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 '../node_modules/@appica/ui-react/dist';

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

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

The library writes colors in oklch for perceptually uniform lightness, which keeps tints and shades consistent across hues, but an override can be in any CSS color format. See Colors for the full palette, the semantic roles each token plays, and how the formats mix.

Custom brand colors

A brand color isn't one token. --primary has five siblings, and they don't follow from it: --primary-subtle and --primary-soft are translucent tints of a different step. Set one by hand and you get a color that looks right on a button and wrong everywhere else.

The theme customizer fills in the whole family for you:

1. Open Settings in the site header.
2. Under Primary Color or Secondary Color, choose Custom.
3. Pick a color in the panel, or paste a hex into the field below it.
4. Press Get CSS Code and copy what it gives you.

The site recolors as you pick, so what you see is what the CSS will do. Your color becomes the middle step of an 11-step palette generated around it, and each --primary-* token is a step out of that palette. That is why one color is enough to fill the family, and it's the same machinery the built-in palettes run through.

Paste the result into your stylesheet, after the import:

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

@source '../node_modules/@appica/ui-react/dist';

:root,
.light {
  --primary: oklch(62.31% 0.188 259.81);
  --primary-subtle: oklch(62.31% 0.188 259.81 / 10%);
  --primary-soft: oklch(62.31% 0.188 259.81 / 20%);
  --primary-muted: oklch(70.86% 0.1652 259.81);
  --primary-strong: oklch(55.07% 0.1846 259.81);
  --focus-ring-primary: oklch(62.31% 0.188 259.81 / 30%);
  --secondary: oklch(84.88% 0.1039 160.44);
  --secondary-subtle: oklch(70.19% 0.1577 160.44 / 10%);
  --secondary-soft: oklch(70.19% 0.1577 160.44 / 20%);
  --secondary-muted: oklch(90.96% 0.0629 160.44);
  --secondary-strong: oklch(76.83% 0.1425 160.44);
  --secondary-emphasis: oklch(70.19% 0.1577 160.44);
  --secondary-intense: oklch(61.29% 0.1548 160.44);
  --focus-ring-secondary: oklch(70.19% 0.1577 160.44 / 30%);
}

.dark {
  --primary: oklch(62.31% 0.188 259.81);
  --primary-subtle: oklch(62.31% 0.188 259.81 / 10%);
  --primary-soft: oklch(62.31% 0.188 259.81 / 20%);
  --primary-muted: oklch(70.86% 0.1652 259.81);
  --primary-strong: oklch(55.07% 0.1846 259.81);
  --primary-foreground: oklch(1 0 0);
  --focus-ring-primary: oklch(62.31% 0.188 259.81 / 50%);
  --secondary: oklch(76.83% 0.1425 160.44);
  --secondary-subtle: oklch(70.19% 0.1577 160.44 / 10%);
  --secondary-soft: oklch(70.19% 0.1577 160.44 / 20%);
  --secondary-muted: oklch(84.88% 0.1039 160.44);
  --secondary-strong: oklch(76.83% 0.1425 160.44);
  --secondary-emphasis: oklch(70.19% 0.1577 160.44);
  --secondary-intense: oklch(61.29% 0.1548 160.44);
  --focus-ring-secondary: oklch(70.19% 0.1577 160.44 / 50%);
}

That's two colors picked and both families filled, per theme. Only what actually changed is written out, so the block stays as small as your customization.

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.