Theming

Appica UI is themed entirely through CSS custom properties — design tokens. There are no theme objects to import and no JavaScript config: you override a few CSS variables and every component updates. This is what @appica/ui-react/styles.css brings in.

How tokens are structured

Tokens live in two layers, and understanding the split is the key to customizing safely.

1. Raw value tokens hold the actual values, defined per theme. :root (and .light) hold the light values; .dark holds the dark ones.

:root,
.light {
  --primary: oklch(0.21 0.034 264.665);
  --background: oklch(1 0 0);
  --radius: 0.875rem;
}

.dark {
  --primary: oklch(1 0 0);
  --background: oklch(0.13 0.028 261.692);
}

2. Theme tokens alias those raw values inside Tailwind's @theme inline block, which is what generates the utility classes.

@theme inline {
  --color-primary: var(--primary);
  --color-background: var(--background);
  --radius-lg: calc(var(--radius) + 0.125rem);
}

The inline keyword matters: it tells Tailwind to inline the raw token into each utility instead of pointing it at a --color-* variable. So bg-primary compiles to background-color: var(--primary) — not var(--color-primary). The upshot is that bg-primary and text-foreground resolve to the right value and flip automatically between light and dark, because the raw layer changes underneath. There's no --color-primary custom property to reference at runtime, though — when you need a token in plain CSS, reach for the raw token (var(--primary)).

Recoloring

Redefine any raw token after the import. To change the brand color:

@import 'tailwindcss';
@import '@appica/ui-react/styles.css';

@source '@appica/ui-react';

:root {
  --primary: oklch(0.62 0.21 28); /* a warm red */
}

.dark {
  --primary: oklch(0.7 0.18 28);
}

Colors use oklch for perceptually uniform lightness, which keeps tints and shades consistent across hues. See Colors for the full palette and the semantic roles each token plays.

Radius

A single base token, --radius, drives the entire corner-radius scale. Every step (--radius-xs through --radius-4xl) is derived from it with calc(), so changing one value rescales every component at once.

:root {
  --radius: 0.5rem; /* sharper corners everywhere */
}

Use the scale through Tailwind utilities (rounded-lg, rounded-2xl) or the variables directly (var(--radius-md)).

Other token groups

The same pattern covers the rest of the design language:

Override any of them the same way — redefine the raw token after the import.

Using tokens in your own UI

Because the tokens are plain CSS variables, your own components can share the exact look of Appica UI. Reach for the Tailwind utilities, or reference the raw tokens directly — var(--primary) in CSS, or the (--token) shorthand in a utility (text-(--primary), not text-(--color-primary)):

<div className="bg-background-subtle text-foreground border-border rounded-lg border p-4">
  Matches the system automatically — including in dark mode.
</div>

// Same token, referenced directly through the raw variable.
<div className="text-(--primary)">Brand-colored text</div>

Next steps

• Colors — every palette and semantic role.
• Dark Mode — switch and persist themes.