@qiiqa/bob-ui-react-themes

The theming and customization layer for Qiiqa React applications.

Concept: Themes vs Variants

Bob UI separates appearance into two distinct concerns:

Theme (Developer's choice)

A theme defines the structural UX style of your app — border rendering, shadow depth, density, and can include custom fonts, background images, and icon styles. The developer picks one theme for their entire app and it stays fixed.

Bob UI ships two built-in themes:

• clean — Minimal, modern. Interactive elements have no visible borders by default; only the active state shows a bottom underline.
• pragmatic — Traditional, clear. All buttons and tabs always show a 1px border.

Developers can also supply a fully custom theme — a CSS file with their own fonts, images, and --q-* variable overrides.

Variant (User's choice)

A variant is a color palette and light/dark mood that the end user can switch between at runtime. Each variant is a CSS file setting --q-* color variables (primaries, backgrounds, text, etc.).

Bob UI ships these built-in variants: moonlit, ocean, dark, green, light.

Users can also create and save their own custom variants via BobVariantDesigner.

Features

• Two-tier separation: Developer chooses the theme; users choose their variant.
• Dynamic variant loading: Variant CSS files are fetched at runtime — no bundle-time coupling.
• System-aware: Can auto-detect OS dark/light preference via BobThemeProvider.
• Persistent: Remembers user variant choices in localStorage.
• Custom variants: Users can create, save, and delete their own color variants via BobVariantDesigner.

⚠️ Required: Copy Variant CSS Files to Your Public Folder

The provider loads variant CSS files dynamically from browser-accessible URLs. These files ship with this package under themes/, but must be served as static files by your app.

Copy from:

node_modules/@qiiqa/bob-ui-react-themes/themes/

To your app's public/themes/ folder:

your-app/public/themes/
  ├── theme-moonlit.css    ← "moonlit" color variant
  ├── theme-ocean.css      ← "ocean" color variant
  ├── theme-dark.css       ← "dark" color variant
  ├── theme-green.css      ← "green" color variant
  └── theme-original.css   ← "original" color variant

Without this step, variant switching will silently fail with no visual error.

Usage

Prefer using @qiiqa/bob-ui-react (the aggregate package). It re-exports everything from this package, so you rarely need to import directly from @qiiqa/bob-ui-react-themes.

BobThemeProvider

Wrap your application root. The themes array uses the format '{variant} {theme}':

import { BobThemeProvider } from '@qiiqa/bob-ui-react';

const App = () => (
    <BobThemeProvider
        themes={[
            // '{variant} {theme}' — variant = color palette, theme = clean or pragmatic
            { name: 'moonlit clean',     label: 'Moonlit',      url: '/themes/theme-moonlit.css' },
            { name: 'moonlit pragmatic', label: 'Moonlit Pro',  url: '/themes/theme-moonlit.css' },
            { name: 'ocean clean',       label: 'Ocean',        url: '/themes/theme-ocean.css' },
            { name: 'ocean pragmatic',   label: 'Ocean Pro',    url: '/themes/theme-ocean.css' },
            { name: 'dark clean',        label: 'Dark',         url: '/themes/theme-dark.css' },
            { name: 'dark pragmatic',    label: 'Dark Pro',     url: '/themes/theme-dark.css' },
        ]}
        defaultLight="moonlit clean"
        defaultDark="dark pragmatic"
    >
        <YourApp />
    </BobThemeProvider>
);

BobVariantSelector

A compact two-dropdown selector for users to pick their preferred variant at runtime. Place it in a header or toolbar:

import { BobVariantSelector } from '@qiiqa/bob-ui-react';

function Header() {
    return (
        <header>
            <h1>My App</h1>
            <BobVariantSelector />
        </header>
    );
}

• First dropdown → Theme (clean / pragmatic) — the structural style
• Second dropdown → Variant (moonlit, ocean, etc.) — the color palette

BobThemeSelector

Identical to BobVariantSelector but uses BobBoxSelect for visual consistency with the Bob component system:

import { BobThemeSelector } from '@qiiqa/bob-ui-react';
<BobThemeSelector />

BobVariantDesigner

A full design panel for users/admins to live-edit CSS color variables and save named custom variants:

import { BobVariantDesigner, BobDialogBase } from '@qiiqa/bob-ui-react';
import { useState } from 'react';

const [open, setOpen] = useState(false);

<BobDialogBase id="variant-designer" isOpen={open} onClose={() => setOpen(false)}>
    {open && <BobVariantDesigner onClose={() => setOpen(false)} />}
</BobDialogBase>

useBobTheme

Hook to read or control the current selection:

import { useBobTheme } from '@qiiqa/bob-ui-react';

const { currentTheme, setTheme, isAuto, setAuto } = useBobTheme();
// currentTheme: e.g. 'moonlit clean'

Built-in Variants

| Variant name | Mood | CSS file | |---|---|---| | moonlit | Dark blue | theme-moonlit.css | | ocean | Deep navy | theme-ocean.css | | dark | Pure dark | theme-dark.css | | green | Dark green | theme-green.css | | light | Light | theme-light.css |

Each can be combined with clean or pragmatic in the themes array.

See apps/bob-ui-demo for live visual verification of all themes and variants.