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 native llms.txt support, allowing AI coding tools (Claude, ChatGPT, Cursor) to index your UI library 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.

REQUIRED SETUP

The ToastProvider and SnackbarProvider are essential for notifications to render properly. They must sit inside the primary BiibaOSProvider.

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-Optimized Coding (llms.txt)

Teach your AI developer tools (Cursor, Claude Projects, Custom GPTs) how to design and build accurately using BiibaUI. Because this library is custom-tailored, feeding the llms.txt file location directly into your agent ensures it knows every import, prop, and styling class perfectly.

1. Copy Location

Your local library definitions are instantly exposed at:

/llms.txt

2. Add to Cursor

Open Cursor, press @ in chat, click Docs > Add new doc, and paste the URL.

3. Claude & GPTs

Download the file from your browser and upload it directly into Claude Projects or Custom GPT knowledge bases.

Agent Prompting Example

Simply paste the URL into your system guidelines or instruct your agent at the start of a conversation to read the API specification:

.cursorrules

Read and analyze the full component specification before building or designing any layouts:
/llms.txt 

Ensure you follow the custom prop types, providers, and themes detailed in this file.

Provider Options

Prop	Type	Default	Description
`theme`	`Partial<BiibaTheme>`	—	Override any design token at provider level
`defaultDark`	`boolean`	undefined	Force initial dark mode on mount
`followSystemTheme`	`boolean`	true	Automatically track OS colour scheme
`motion`	`BiibaMotionProp`	moderate	Configure animation presets or custom platform physics

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
  }}
>

Theming