CSS Variables
Every theme pack emits a runtime <style> block of CSS custom properties
into your document. Tailwind utilities, your own CSS, and djust's
shipped components all resolve through those variables — so swapping
packs at runtime recolors the entire site without a rebuild.
The naming follows shadcn/ui conventions, with djust extensions for
states (success, warning, info), media (link, code,
selection), and structural surfaces (surface_1 / _2 / _3).
The HSL triplet convention
Every color token is emitted as an HSL triplet with no hsl(...)
wrapper:
--background: 40 30% 7%; /* not hsl(40 30% 7%) */
--primary: 28 85% 55%;
You wrap with hsl(...) at the consumption site. The win: opacity
composes naturally:
background: hsl(var(--primary));
border: 1px solid hsl(var(--primary) / 0.5); /* 50% opacity */
box-shadow: 0 0 0 4px hsl(var(--ring) / 0.2);
The full token list
Base surfaces
| Token | What it paints |
|---|---|
--background | The page background. |
--foreground | Body text on --background. |
--card | Slightly lifted surface (cards, panels, modals). |
--card-foreground | Text inside a card. |
--popover | Popover / dropdown / tooltip background. |
--popover-foreground | Text inside a popover. |
Action
| Token | What it paints |
|---|---|
--primary | The dominant action color (CTA buttons, focused inputs, link). |
--primary-foreground | Text on a --primary background. |
--secondary | Subdued action (cancel buttons, alternate fills). |
--secondary-foreground | Text on --secondary. |
--accent | Highlights (active nav, selected row). Often equals --primary. |
--accent-foreground | Text on --accent. |
--muted | Muted background (disabled fills, subtle dividers). |
--muted-foreground | Subdued text — captions, secondary labels. |
--destructive | Red for delete confirms, error states. |
--destructive-foreground | Text on --destructive. |
Status (djust extensions)
| Token | What it paints |
|---|---|
--success | Green for confirmations, success toasts. |
--success-foreground | Text on --success. |
--warning | Amber/orange for warnings. |
--warning-foreground | Text on --warning. |
--info | Blue for informational callouts. |
--info-foreground | Text on --info. |
Media (djust extensions)
| Token | What it paints |
|---|---|
--link | Inline link color. |
--link-hover | Link color on hover. |
--code | <code> background tint. |
--code-foreground | <code> text color. |
--selection | ::selection background. |
--selection-foreground | ::selection text. |
--brand | Distinctive identity color, often more saturated than --primary (Dracula Pink, Nord Frost, Catppuccin Rosewater). Set to match --primary if your pack has no separate brand color. |
--brand-foreground | Text on --brand. |
UI elements
| Token | What it paints |
|---|---|
--border | Default border color (cards, inputs, dividers). |
--input | Input field border (often equals --border). |
--ring | Focus ring (often equals --primary). |
Surfaces (djust extensions for landing-page layering)
For complex dark layouts that need three distinct elevation levels:
| Token | What it paints |
|---|---|
--surface-1 | Darkest — ultra-dark base background. |
--surface-2 | Mid — panels, navbars. |
--surface-3 | Elevated — cards, modals. |
A simple light-mode pack can leave these all equal to --background
and --card. Dark editorial / dashboard packs typically use them to
build depth without shadows.
Geometry
| Token | What it paints |
|---|---|
--radius | Border-radius multiplier in rem (e.g. --radius: 0.5rem). Components like buttons and cards multiply this. |
Light vs. dark
Every shipped pack defines a LIGHT and a DARK set of these tokens.
The active mode determines which set goes into :root. The mode-switcher
flips :root (or a .dark class, depending on pack config) and the
whole site recolors immediately — no JS needed for the recoloring
itself, only for storing the user's choice.
Where to find the canonical list
Source of truth is the
ThemeTokens
dataclass. Every shipped pack populates the same field set — you can
copy the closest pack and tweak.
See also
- Settings — how to choose which pack emits these tokens at request time.
- Tailwind — declaring brand aliases that resolve through these tokens.
extra_css_vars— for project-specific variables outside this token set.