Customization

Theming

oks-ui uses a CSS-variable-driven design system. Every color, space, radius, shadow, font, and z-index is controlled by --oks-* custom properties. Override anything from your own stylesheet.

Token Categories

Colors

7 semantic roles (default, primary, secondary, info, success, warning, danger) × 9 shades (50–900). Plus surface, border, text, and overlay tokens.

Palette

60 named palette colors (slate, gray, zinc, neutral, stone, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose) × 9 shades.

Spacing

0.25rem–4rem scale (4 steps: 1–4) — used for padding, margin, gap, and inset in all components.

Radii

Rounded corners: xs (2px), sm (4px), md (6px), lg (8px), xl (12px), full (9999px).

Shadows

6 shadow levels (xs–2xl) for surface elevation. Separated by light/dark mode.

Fonts

Sans, mono, and size scale (xs–3xl). The sans font uses system font stack by default.

CSS Variable Tokens

Override any token from your app. Tokens are in kebab-case following the pattern --oks-{category}-{name}. Component styles use OKLCH color space for consistent perceptual brightness.

/* Color tokens */
--oks-color-primary-500: #7c3aed; /* violet-500 */
--oks-color-primary-600: #6d28d9; /* hover states */
--oks-color-primary-50: #faf5ff; /* light backgrounds */

/* Surface tokens */
--oks-color-surface: #ffffff;
--oks-color-surface-elevated: #fafafa;
--oks-color-border: oklch(0.928 0.006 264);

/* Spacing & Radii */
--oks-space-4: 1rem;
--oks-radius-lg: 8px;

Dark Mode

oks-ui uses prefers-color-scheme by default — no class toggling needed. Override tokens inside [data-theme="dark"] to lock to dark mode. All component tokens are already adapted for both themes.

/* Automatic: respects system preference */
@media (prefers-color-scheme: dark) {
  --oks-color-surface: #0a0a0a;
  --oks-color-border: oklch(0.269 0.015 264);
  --oks-color-text: #ededed;
}

/* Manual: toggle with data attribute */
[data-theme="dark"] {
  --oks-color-surface: #0a0a0a;
}

Create a Custom Theme

To build a complete brand theme, map semantic colors to your palette and adjust surface tokens:

:root {
  /* Map semantic roles to palette */
  --oks-color-primary-500: var(--oks-palette-violet-500);
  --oks-color-success-500: var(--oks-palette-emerald-500);
  --oks-color-warning-500: var(--oks-palette-amber-500);
  --oks-color-danger-500: var(--oks-palette-rose-500);

  /* Surface colors */
  --oks-color-surface: #ffffff;
  --oks-color-surface-elevated: #f8f9fa;

  /* Border and text */
  --oks-color-border: #e2e8f0;
  --oks-color-text: #0f172a;
  --oks-color-text-muted: #64748b;
}