Getting Started

Installation

BiibaOS is a premium, platform-adaptive UI component library designed for high-performance React and Next.js applications. Build seamless user interfaces with standard-based CSS variables, native spring physics, and robust theme switches.

Unified Design System

Coherent tokens, spacing, and typography that scale consistently across every viewport.

Platform-Adaptive

Components automatically feel native — desktop gets hover precision, mobile gets touch targets and spring physics.

Runtime Theming

CSS variable tokens update globally at runtime. No rebuild required for dark mode or branding changes.

AI-Optimized Integration

Ships with a modular llms.txt doc set — index + per-component pages — so AI coding tools (Claude, ChatGPT, Cursor) fetch exactly the props they need, instantly.

Package Installation

Install the package from npm. The library ships as ESM + CJS with full TypeScript types.

npm install biibaos

Providers Setup

Create a Providers.tsx wrapper component. You must include 'use client' at the top of the file when using Next.js App Router.

components/Providers.tsx
'use client'

import { BiibaOSProvider, ToastProvider, SnackbarProvider } from 'biibaos'
import 'biibaos/styles'

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <BiibaOSProvider followSystemTheme>
      <SnackbarProvider>
        <ToastProvider position="top-right">
          {children}
        </ToastProvider>
      </SnackbarProvider>
    </BiibaOSProvider>
  )
}

Finally, wrap your root layout with this Providers component.

app/layout.tsx
import { Providers } from '@/components/Providers'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

AI Setup Guide

BiibaOS ships its own llms.txt documentation set so AI tools (Cursor, Claude, ChatGPT, Windsurf, Copilot) generate code with the exact current props — instead of guessing from training data or mixing in patterns from other UI libraries.

1. The doc structure

Every URL below is public and always reflects the installed version (biibaos Sierra 2026.1.0).

/llms.txtStart here

The index. Lists every component with a one-line summary and a link to its page. Small enough to paste anywhere.

/llms/00-setup.mdFetch second, always

BiibaOSProvider props, theming, the shared base props (className/style/platform), and shared tokens (BiibaSize, BiibaVariant…) that every other page assumes you already know.

/llms/<Component>.mdFetch per component, on demand

One focused file per component (Button.md, Modal.md, DynamicIsland.md…) with its exact, current prop table. Only fetch the ones actually used in the task.

/llms-full.txtFallback for single-file tools

Every page above concatenated into one document — for tools that only accept one URL or one uploaded file (no per-page fetching).

2. Connect it to your AI tool

Pick whichever you use — each one takes under a minute.

  1. Open Cursor Settings → Indexing & Docs → Add Doc.
  2. Paste /llms.txt and name it "BiibaOS".
  3. In chat, type @Docs and select it whenever you build UI.

Or, skip the manual step and make it automatic project-wide:

.cursor/rules/biibaos.mdc
---
description: BiibaOS component usage rules
globs: ["**/*.tsx"]
alwaysApply: true
---

Before writing or editing any UI, fetch /llms.txt to see which
components exist, then fetch the specific /llms/<Component>.md
page(s) you need. Also fetch /llms/00-setup.md before using any
component for the first time in this session — it defines shared base
props and tokens that aren't repeated on each component page.

Never invent a prop that isn't in the fetched page. Import everything
from 'biibaos' — there are no deep imports.

3. The prompt that actually works

Vague instructions ("read the docs") make agents skim once and start guessing. Be explicit about what to fetch, when, and what not to do — this is the prompt we use internally, drop it into a system prompt, .cursorrules, or the first message of a chat:

ai-instructions.md
You are building UI with BiibaOS (biibaos, Sierra 2026.1.0) —
not a generic component library. Do not use props, imports, or patterns
from memory; this library is custom and versioned independently.

Before writing any component:
1. Fetch /llms.txt — it's an index of every component with a link
   to its own doc page. Use it to find what exists.
2. Fetch /llms/00-setup.md once per session, before your first
   component — it covers BiibaOSProvider, shared base props
   (className/style/platform), and shared tokens (BiibaSize, BiibaVariant,
   BiibaRadius) that are NOT repeated on individual component pages.
3. For every component you plan to use, fetch its own page —
   /llms/<Component>.md — and use only the props listed there.
4. If you can't browse URLs at all, ask me to paste /llms-full.txt
   instead, and treat it as the full reference.

Hard rules:
- Never invent a prop. If it's not documented on that component's page,
  don't use it — ask, or pick a documented alternative.
- Import everything from 'biibaos' — there are no deep
  imports like 'biibaos/Button'.
- Always wrap the app in <BiibaOSProvider>. Add <ToastProvider> /
  <SnackbarProvider> only if useToast() / useSnackbar() are actually used.
- If a prop you expect seems missing, re-fetch the page rather than
  assuming it exists — pages change between releases.

Provider Options

PropTypeDefaultDescription
themePartial<BiibaTheme>—Override any design token at provider level
defaultDarkbooleanundefinedForce initial dark mode on mount
followSystemThemebooleantrueAutomatically track OS colour scheme
motionBiibaMotionPropmoderateConfigure animation presets or custom platform physics
spatialDepthbooleanfalseEnable Pillar 2 iOS-style tilt-parallax globally (requires sensor permission)
spatialIntensityBiibaTiltIntensitymoderateConfigure spatial parallax tilt intensity ('subtle' | 'moderate' | 'expressive')
capabilitiesPartial<BiibaSierraCapabilities>—Toggle animations/features globally (entrance, choreography, throwGestures, tiltParallax, ambientContrast, chartPhysics)
componentOverridesBiibaComponentOverrideMap—Granular capability and motion override per component name (e.g. { Toast: { entrance: false } })

Dark Mode

// Automatic — follows OS preference
<BiibaProvider followSystemTheme>

// Force dark on load
<BiibaProvider defaultDark>

// Manual control via hook
const { isDark, toggleDark, setDark } = useBiiba()
<button onClick={toggleDark}>{isDark ? 'Light Mode' : 'Dark Mode'}</button>

Motion System

BiibaOS comes with a comprehensive, platform-adaptive physics-based motion system. By default, it automatically adjusts spring stiffness, damping, and transition times based on the user's device (Mobile vs Desktop) to ensure native-feeling interactions.

// Simplest — use a global preset
<BiibaProvider motion="expressive">

// Advanced — Different feel per platform
<BiibaProvider
  motion={{
    desktop: {
      preset: 'subtle', // Fast, less bouncy for mouse
      spring: { stiffness: 400, damping: 35, mass: 0.8 },
    },
    mobile: {
      preset: 'expressive', // Slower, more bouncy for touch
      spring: { stiffness: 220, damping: 18, mass: 1.2 },
    },
    reducedMotion: undefined, // Follows OS accessibility settings automatically
  }}
>

// Disable animations entirely on a specific platform
<BiibaProvider
  motion={{
    desktop: { preset: 'none' }, // No animations on desktop
    mobile: { preset: 'moderate' }, // Normal animations on mobile
  }}
>

Sierra Overrides & Capabilities

Sierra introduces a powerful, multi-level capability override chain. This system lets you turn specific motion features on or off globally, target individual component classes, or customize a specific element instance.

Capabilities Schema

FieldTypeDefaultDescription
entrancebooleantrueAllows components to slide/fade on mount.
choreographybooleantrueSequenced sub-component animations (icon → title → body → footer).
throwGesturesbooleantrueEnable velocity-based throw dismissals.
tiltParallaxbooleanfalseEnable iOS-style glass layers shifting on phone tilt.
ambientContrastbooleanfalseDynamic contrast alpha-nudge theme adjustments.
chartPhysicsbooleantrueSpring staggered entrances and draw paths for Recharts.

The Override Chain (Priority Order)

Settings resolve dynamically starting from instance properties down to global preferences:

  1. Instance Props: prop overrides defined directly on a component (e.g. <Card choreography={false} />)
  2. Component Overrides: componentOverrides defined on the Provider (e.g. Toast: { entrance: false })
  3. Global Capabilities: capabilities toggle defined on the Provider (e.g. capabilities={{ throwGestures: false }})
  4. Global Preset: standard motion preset selection (e.g. motion="snappy")
  5. Platform Default: standard desktop/mobile timing configuration from `motion.ts`
  6. Reduced Motion Preference: prefers-reduced-motion media query always wins and disables motion.
components/Providers.tsx
import { BiibaOSProvider } from 'biibaos'

export function Providers({ children }) {
  return (
    <BiibaOSProvider
      motion="moderate"
      spatialDepth={true}            // Opt-in to spatial depth (Pillar 2)
      spatialIntensity="subtle"
      capabilities={{
        tiltParallax: true,          // Turn tilt parallax on globally
        ambientContrast: false,      // Leave dynamic contrast opt-in
      }}
      componentOverrides={{
        Toast: { entrance: false },  // Disable toast mount animations globally
        ActionSheet: { throwGestures: false }
      }}
    >
      {children}
    </BiibaOSProvider>
  )
}

Next

Theming