Skip to Content
DocumentationDesignCustomization

Customization

Zen uses CSS custom properties (variables) for all design tokens, making it easy to customize the look and feel of your application. You can override these variables to match your brand or create entirely custom themes.

Overriding variables

To customize Zen, override the CSS variables in your stylesheet. Variables defined on :root apply globally, while scoped selectors can target specific themes.

:root {
  /* Override for both light and dark themes */
  --font-family: 'Inter', sans-serif;
}
 
/* Override only in light mode */
[data-theme="light"] {
  --surface-base: #fafafa;
  --text-primary: #1a1a1a;
}
 
/* Override only in dark mode */
[data-theme="dark"] {
  --surface-base: #0a0a0a;
  --text-primary: #fafafa;
}

Creating a branded theme

Here’s an example of creating a custom branded theme with a blue accent:

[data-theme="light"] {
  /* Primary button and accent color */
  --primary: oklch(0.55 0.2 250);
  --primary-foreground: #ffffff;
  --focus-ring: oklch(0.7 0.15 250);
}
 
[data-theme="dark"] {
  /* Lighter primary for dark mode */
  --primary: oklch(0.7 0.15 250);
  --primary-foreground: oklch(0.2 0 0);
  --focus-ring: var(--primary);
}

CSS variable reference

Primary

The primary accent color used for primary buttons and branded elements.

VariableDescription
--primaryPrimary/brand accent color (button backgrounds)
--primary-foregroundText color on primary backgrounds

Surfaces

Background colors for different elevation levels.

VariableDescription
--surface-basePrimary background (page level)
--surface-raisedElevated surfaces (cards, modals)
--surface-sunkenRecessed areas (inputs, wells)
--surface-overlayOverlays (dropdowns, popovers)
--surface-invertedInverted background (tooltips)
--surface-disabledDisabled element background

Text

Text colors for different emphasis levels.

VariableDescription
--text-primaryPrimary text (headings, body)
--text-mutedMuted text (labels, placeholders, hints)
--text-disabledDisabled text

Borders

Border colors for different emphasis levels.

VariableDescription
--border-defaultDefault border (inputs, cards)
--border-mutedSubtle borders (dividers)
--border-strongEmphasized borders (focus, active)

Interactive states

Colors for interactive elements like buttons, checkboxes, and list items.

VariableDescription
--interactive-bgDefault interactive background
--interactive-bg-hoverHover state background
--interactive-bg-pressedPressed/active state background

Focus

Focus ring styles for accessibility.

VariableDescription
--focus-ringFocus ring color
--focus-ring-offsetFocus ring offset color (gap)

Status colors

Colors for feedback states (info, success, warning, error).

VariableDescription
--status-infoInfo accent color
--status-info-bgInfo background
--status-info-textInfo text color
--status-successSuccess accent color
--status-success-bgSuccess background
--status-success-textSuccess text color
--status-warningWarning accent color
--status-warning-bgWarning background
--status-warning-textWarning text color
--status-errorError accent color
--status-error-bgError background
--status-error-textError text color

Typography

Font family variables.

VariableDescription
--font-familyDefault font stack
--font-family-monoMonospace font stack

Using OKLCH colors

Zen uses OKLCH color values for better color manipulation and perceptual uniformity. OKLCH colors are defined as oklch(lightness chroma hue):

  • Lightness: 0 (black) to 1 (white)
  • Chroma: 0 (gray) to ~0.4 (vivid)
  • Hue: 0-360 degrees (color wheel)
:root {
  /* A vibrant blue */
  --brand-color: oklch(0.6 0.2 250);
 
  /* A muted green */
  --subtle-green: oklch(0.7 0.1 150);
 
  /* With transparency */
  --overlay-bg: oklch(0.2 0 0 / 0.5);
}

Tips

  • Always provide both light and dark theme overrides for a consistent experience
  • Use OKLCH for colors to maintain perceptual consistency across themes
  • Test your customizations in both themes to ensure adequate contrast
  • Use browser DevTools to inspect and experiment with CSS variables in real-time
ThemesBox