Colors

Semantic color roles, and when to use each.

Appica UI's palette is organized by role, not by hue. Instead of blue-500, you use primary or info-emphasis. This keeps components meaningful and lets a single token override retheme the whole system. Every color is defined in oklch and is overridable - see Theming.

Each color is exposed as a Tailwind utility (bg-*, text-*, border-*) and as a raw CSS variable named after the role - var(--primary), var(--foreground), and so on. See Theming.

Base colors

The grayscale foundation of every layout: backgrounds, text, and borders. Each family is a scale from subtle to intense.

Foreground (text & icons)

Token	Use for
`foreground`	Default body text
`foreground-muted`	Secondary text, descriptions
`foreground-subtle`	Placeholders, disabled labels, markers
`foreground-strong`	Emphasized text
`foreground-emphasis`	Stronger emphasis
`foreground-intense`	Headings, highest-contrast text
`foreground-inverse`	Text on an inverted surface

Background (surfaces)

Token	Use for
`background`	The base page surface
`background-subtle`	Slightly raised areas, cards
`background-muted`	Hover fills, inset panels
`background-strong`	More prominent fills
`background-inverse`	Inverted surfaces (e.g. tooltips)

Border

Token	Use for
`border`	Default borders and dividers
`border-muted`	Faint separators
`border-strong`	Higher-contrast borders
`border-emphasis`	Emphasized outlines
`border-intense`	Strongest outlines
`border-inverse`	Borders on inverted surfaces

Accent palettes

Six semantic accents share an identical scale, so they're interchangeable by intent. primary and secondary carry your brand; error, success, warning, and info carry status. primary is the one exception: it has no -emphasis or -intense step, and its default values are achromatic. See The primary scale.

Step	Role
`*-subtle`	Translucent tint - soft background wash
`*-soft`	Slightly stronger translucent fill
`*-muted`	Muted solid
`*` (base)	The default accent fill
`*-strong`	Stronger, for hover/active
`*-emphasis`	The vivid, on-brand value
`*-intense`	The boldest value
`*-foreground`	Text/icon color that sits legibly on the accent

For example, an info alert pairs bg-info-subtle (surface), bg-info-soft (border), with text-info-foreground; a solid primary button pairs bg-primary with text-primary-foreground.

The primary scale

Out of the box the primary family is achromatic: every token is a shade of the neutral base rather than a color, which is why the default primary inverts with the theme, near-black on white in light and white on near-black in dark.

Give primary a color and it switches to a different recipe, not just different values. Both are shade picks out of an 11-stop palette (50 through 950), written below as light / dark:

Token	Achromatic (default)	Chromatic
`--primary`	900 / white	500
`--primary-subtle`	100 / 900	500 at 10%
`--primary-soft`	200 / 800	500 at 20%
`--primary-muted`	700 / 200	400
`--primary-strong`	950 / white	600
`--primary-foreground`	white / 900	white
`--focus-ring-primary`	300 / 700	500 at 30% / 50%

The row that matters is subtle and soft. In the achromatic recipe they are solid neutral stops, and they need a separate dark value. In the chromatic recipe they are alpha tints of the 500, identical in both themes, because a translucent fill composites over whatever surface it lands on.

That difference is why no formula turns the default primary into a branded one: the two recipes don't hold the same kind of value in the same slot. The palette is the unit of customization, not the individual token. Supply a color, get eleven stops, and the recipe picks out of those. See Custom brand colors.

Focus rings

Focus styling has its own token set so the ring can differ from borders. Each maps to a matching role, and components apply them automatically on :focus-visible - see Accessibility.

Token	Use for
`ring`	Default focus ring, neutral controls
`ring-input`	Inputs and form fields
`ring-primary`	Primary controls
`ring-secondary`	Secondary controls
`ring-error`	Error / invalid controls
`ring-success`	Success controls
`ring-warning`	Warning controls
`ring-info`	Info controls
`ring-light`	Controls on inverted / dark surfaces

Overriding the palette

Any token can be redefined after the stylesheet import, separately per theme:

:root {
  --secondary: oklch(0.827 0.119 306.383);
}
.dark {
  --secondary: oklch(0.714 0.203 305.504);
}

These are plain custom properties, so any CSS color format works: hex, rgb(), hsl(), a named color. The library writes oklch because its lightness is perceptually even across hues, which is what keeps a palette's steps evenly spaced and its tints predictable. Nothing reads the format back, so you can paste whatever your brand guide gives you:

:root {
  --secondary: #c084fc;
}
.dark {
  --secondary: rgb(168 85 247);
}

The one thing to carry over is opacity. The *-subtle and *-soft steps are translucent by design, so they composite over whatever surface they sit on. Replace one with an opaque color and it stops adapting: keep the alpha, in whichever format you're writing (#c084fc1a, rgb(168 85 247 / 10%)).

To retheme a whole accent family from a single brand color rather than token by token, see Custom brand colors.

Head to Theming for the raw-vs-theme token model and the non-color tokens (radius, shadows, typography).

Getting Started

Guides

Utilities