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 */
  --zen-font-family: 'Inter', sans-serif;
}

/* Override only in light mode */
[data-theme="light"] {
  --zen-surface: #fafafa;
  --zen-fg: #1a1a1a;
}

/* Override only in dark mode */
[data-theme="dark"] {
  --zen-surface: #0a0a0a;
  --zen-fg: #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 */
  --zen-primary: oklch(0.55 0.2 250);
  --zen-primary-fg: #ffffff;
  --zen-focus-ring: oklch(0.7 0.15 250);
}

[data-theme="dark"] {
  /* Lighter primary for dark mode */
  --zen-primary: oklch(0.7 0.15 250);
  --zen-primary-fg: oklch(0.2 0 0);
  --zen-focus-ring: var(--zen-primary);
}

CSS variable reference#

Primary#

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

Surfaces#

Background colors for different elevation levels.

Text#

Text colors for different emphasis levels.

Borders#

Border colors for different emphasis levels.

Interactive states#

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

Focus#

Focus ring styles for accessibility.

Status colors#

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

Typography#

Font family variables.

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

Token naming#

All Zen tokens use the --zen- prefix. Unsuffixed names represent the default value; variants add a suffix, such as --zen-border-muted. Foreground colors use fg, and background qualifiers use bg. The --zen-palette-50 through --zen-palette-950 tokens provide the selected neutral, slate, gray, zinc, or stone shades used by semantic colors.

Migrating token names#

Update custom overrides and utility classes to the names below. Token values and light/dark palette definitions are unchanged. The old names are no longer provided.

The surface color prop value also changes: use backgroundColor="surface" instead of backgroundColor="surface-base". Responsive values and hover/focus/active variants use the same new names. border-edge and ring-offset-focus-offset remain unchanged.

The package's Tailwind preset and its own build now share one configuration, including the correct --zen- variable references.