Reference

Theming

BiibaOS uses standard CSS custom properties as high-performance design tokens. Pass partial overrides to BiibaOSProvider—which are merged at runtime—allowing you to alter the interface globally without a rebuild.

Interactive Customizer

Test color swatches, roundings, and transitions live on these docs.

Design Tokens

All theme colors, typography definitions, and radius sets map to CSS custom properties on the :root element.

// All tokens resolved as CSS variables on :root
--biiba-primary       /* primary action colour    */
--biiba-primary-fg    /* text on primary bg       */
--biiba-primary-light /* lighter primary helper   */
--biiba-secondary     /* secondary / muted bg     */
--biiba-bg            /* page background          */
--biiba-surface       /* card / input background  */
--biiba-surface-raised
--biiba-text          /* primary text             */
--biiba-text-muted    /* secondary text           */
--biiba-text-subtle   /* placeholder / hint       */
--biiba-border        /* separator / outline      */
--biiba-border-focus  /* focused input ring       */
--biiba-danger        /* error / destructive      */
--biiba-success       /* success / confirmation   */
--biiba-warning       /* warning / caution        */
--biiba-radius-sm / -md / -lg / -full
--biiba-font          /* font-family stack        */

Utility Classes

Apply semantic colors via clean class names. Shades (like `light` and `dark`) are auto-generated from your core swatches using CSS color-mix(), updating instantly at runtime.

.text-primary

.text-success

.text-danger

.text-warning

.text-muted

.bg-primary

.bg-primary-light

.bg-success-light

.bg-danger-light

.bg-warning-light

/* Typography Colors */
<span class="biiba_text-primary">Primary colored text</span>
<span class="biiba_text-success">Success colored text</span>
<span class="biiba_text-danger">Danger colored text</span>
<span class="biiba_text-warning">Warning colored text</span>
<span class="biiba_text-muted">Muted text</span>

/* Background Colors with Shades */
<div class="biiba_bg-primary">Primary background</div>
<div class="biiba_bg-primary-light">Light primary tint</div>
<div class="biiba_bg-primary-dark">Dark primary shade</div>
<div class="biiba_bg-success-light">Light success tint</div>
<div class="biiba_bg-danger-light">Light danger tint</div>

Custom Theme Definition

Deep-merge custom palettes with default tokens. Supplying discrete light and dark options gives you precise color contrast control.

import { BiibaOSProvider } from 'biibaos'

const myTheme = {
  colors: {
    light: {
      primary: '#6366f1',     // indigo
      primaryFg: '#ffffff',
      primaryLight: '#e0e7ff', // light indigo helper
      success: '#10b981',     // emerald
    },
    dark: {
      primary: '#818cf8',
      primaryFg: '#ffffff',
      primaryLight: '#312e81', // dark indigo helper
    },
  },
  radius: {
    md: '6px',   // less rounded
    lg: '10px',
  },
  font: {
    family: "'Geist', sans-serif",
  },
}

export default function App({ children }) {
  return (
    <BiibaOSProvider theme={myTheme} followSystemTheme>
      {children}
    </BiibaOSProvider>
  )
}

Font Configuration

Customize typography by selecting one of our curated high-performance font presets, specifying a custom font family, or inheriting the parent application's typography.

Using Font Presets

Pass a fontPreset name under the font property of your theme configuration. The BiibaOSProvider will automatically load the Google Font stylesheet dynamically, inject it into the document head, and map it to the --biiba-font CSS variable.

import { BiibaOSProvider } from 'biibaos'

const myTheme = {
  font: {
    // Curated Google Fonts preset
    fontPreset: 'inter' // 'inter' | 'geist' | 'plus-jakarta-sans' | 'dm-sans' | 'nunito' | 'outfit' | 'sora' | 'figtree' | 'poppins' | 'manrope' | 'system' | 'inherit'
  }
}

export default function App({ children }) {
  return (
    <BiibaOSProvider theme={myTheme}>
      {children}
    </BiibaOSProvider>
  )
}

Adapting to Your App's Font

If your application already loads its own font (e.g., using next/font in Next.js or a custom webfont stylesheet) and you want Biiba components to adapt to it, configure the provider. Setting fontPreset to 'inherit' sets --biiba-font to inherit. Alternatively, you can supply a custom font family string directly.

import { BiibaOSProvider } from 'biibaos'

// 1. Adapt to your app's existing font (inherited from parent/body)
const inheritTheme = {
  font: {
    fontPreset: 'inherit'
  }
}

// 2. Or override with a custom font-family string directly
const customFamilyTheme = {
  font: {
    family: "'My Custom Font', sans-serif"
  }
}

Per-Variant Typography Overrides

You can fine-tune styling for individual text variants (e.g., display, h1, mono) inside the font.variants map. This allows you to override the font preset, size, weight, line-height, and letter-spacing for specific roles. When variant-specific Google Font presets are requested, the provider automatically fetches and loads them dynamically.

import { BiibaOSProvider } from 'biibaos'

const themeWithOverrides = {
  font: {
    fontPreset: 'inter', // Global default font preset
    variants: {
      display: {
        fontPreset: 'plus-jakarta-sans', // Variant-specific Google Font
        size: '36px',
        weight: 700,
        lineHeight: 1.1,
        letterSpacing: '-0.03em',
      },
      h1: {
        fontPreset: 'geist', // Another Google Font for headings
        size: '28px',
        weight: 600,
      },
      mono: {
        fontPreset: 'system', // Override to use the native system sans/monospace
        size: '13px',
      }
    }
  }
}

export default function App({ children }) {
  return (
    <BiibaOSProvider theme={themeWithOverrides}>
      {children}
    </BiibaOSProvider>
  )
}

Theme Playground

Edit live — changes apply instantly to this site. Export your config when done.

Light Mode

Primary

Background

Text

Dark Mode

Primary

Background

Text

Live PreviewLive

Display

Heading 1

Heading 2

Body text — changes apply here instantly when you update fonts, colors, and radii.

const x = 42;

Buttons

States

SuccessDangerWarningPrimary

Surface

Surface card preview

BiibaOS Design System

Global Component Sizes

You can set a global defaultSize on the BiibaOSProvider to scale your Buttons, Inputs, and Selects across the entire app. Individual components can still override this by passing the size prop directly.

// Scale down all form controls globally
<BiibaOSProvider defaultSize="sm" followSystemTheme>
  <App />
</BiibaOSProvider>

// This button will be "sm" because of the provider
<Button>Save Settings</Button>

// This input will still be "lg"
<Input size="lg" placeholder="Large override" />

Runtime Swapping

Call setTheme() directly from the useBiibaOS hook to change swatches dynamically. This is extremely useful for user-selectable color palettes or white-labeled multi-tenant layouts.

import { useBiibaOS } from 'biibaos'

function BrandSwitcher() {
  const { setTheme } = useBiibaOS()

  return (
    <button onClick={() =>
      setTheme({ colors: { light: { primary: '#ef4444' } } })
    }>
      Switch to Red
    </button>
  )
}

Dark Mode Control

// Automatic (follows OS colors)
<BiibaOSProvider followSystemTheme>

// Force dark layout globally
<BiibaOSProvider defaultDark>

// Manual toggle inside custom headers
const { isDark, toggleDark } = useBiibaOS()
<button onClick={toggleDark}>{isDark ? 'Light' : 'Dark'}</button>

Installation

Components