arcadia-admin/app/components/layout/THEME_CONTRACT.md

Theme contract

Every Crema theme (lib-theme-*) must declare these CSS variables so the shell, AI surfaces, and shadcn primitives render correctly. Missing a variable won't crash anything — it'll just look wrong (transparent backgrounds, missing borders, broken focus rings, etc.).

A theme is a single CSS file that declares variables under :root for light mode and under .dark for dark mode. Themes may also @import url(...) font packages at the top of the file — they ship self-contained.

The shell expects the theme to be the first import in the consuming app's entry CSS, so any embedded font URLs land at the top of the resolved output (CSS spec requires @import before any other rules).

Required tokens

Surfaces

Token	Used for
--background	Page background
--foreground	Default text color
--card	Card surfaces, inputs, dropdowns
--card-foreground	Text on cards
--popover	Popover/menu surfaces
--popover-foreground	Text on popovers
--muted	Subtle backgrounds (hover states, toolbars, code blocks)
--muted-foreground	Subtle text (timestamps, hints, labels)
--accent	Hover/focus highlight on items
--accent-foreground	Text on accent backgrounds

Brand & status

Token	Used for
--primary	Brand color, primary buttons, active nav, ripple
--primary-foreground	Text on primary surfaces
--secondary	Secondary buttons
--secondary-foreground	Text on secondary
--destructive	Errors, sign-out, destructive menu items
--success	Confirmations
--success-foreground	Text on success surfaces

Borders, inputs, focus

Token	Used for
--border	Dividers, default borders
--input	Input field borders
--ring	Focus rings

Sidebar (rail)

Token	Used for
--sidebar	Rail background
--sidebar-foreground	Rail text
--sidebar-primary	Active nav background
--sidebar-primary-foreground	Active nav text
--sidebar-accent	Rail hover
--sidebar-accent-foreground	Text on rail hover
--sidebar-border	Rail borders
--sidebar-ring	Rail focus ring

Charts & syntax (optional but recommended)

Token	Used for
--chart-1 … --chart-5	Chart series colors; --chart-3 doubles as warning amber
--syntax-keyword, --syntax-string, --syntax-number, --syntax-comment, --syntax-function, --syntax-type	Code-block highlighting

Typography

Token	Used for
--font-heading	Heading font stack
--font-sans	Default UI font stack
--font-ai-prose	Assistant prose (the AI surface uses this for replies)
--font-mono	Code, tabular numbers

Type scale

Each pair declares a size and matching line height:

• --text-display-size / --text-display-lh
• --text-headline-size / --text-headline-lh
• --text-title-size / --text-title-lh
• --text-body-size / --text-body-lh
• --text-label-size / --text-label-lh
• --text-caption-size / --text-caption-lh

Motion

Token	Used for
--duration-fast, --duration-base, --duration-slow, --duration-slower, --duration-spring	Animation lengths
--ease-standard, --ease-emphasized, --ease-decelerate, --ease-accelerate	Standard easing curves
--ease-spring-gentle, --ease-spring-snappy, --ease-spring-bouncy	Spring curves

Radii & elevation

Token	Used for
--radius	Base radius (sm/md/lg/xl/2xl computed from this in app.css)
--elevation-0 … --elevation-5	Shadow scale
--border-width-thin, --border-width-base, --border-width-thick, --border-width-heavy	Stroke widths

Scoping conventions

• :root { … } — theme defaults (light mode).
• .dark { … } — dark-mode overrides.
• [data-theme="<name>"] { … } — alternate-scoped theme. Only needed if a theme should coexist with another on the same page (e.g. an AI surface uses a different theme than the rest of the app). Single-theme apps don't need this scope.

Adding a new theme

1. Clone any existing theme as a starting point — lib-theme-mightypix is a good reference because it's complete.
2. Edit tokens (and font @import url if changing fonts).
3. Update the consuming app's app.css:

   @import "../../lib-theme-<your-name>/theme.css";   /* CREMA:THEME */
   @import "tailwindcss";
   ...
   

4. Done. Components automatically pick up the new look — no changes needed in any TSX file.

Multi-theme apps (e.g. mightypix on AI surfaces only)

If a theme defines [data-theme="<name>"] instead of (or in addition to) :root, you can switch surfaces per route via the shell's theme prop:

<AppShell title="Assistant" theme="mightypix">…</AppShell>

The shell wraps itself in data-theme={theme} so the alt theme's tokens cascade through that subtree only.