Design Tokens

Why OKLCH

OKLCH (Oklab Lightness–Chroma–Hue) is a perceptually uniform color space. Two colors with the same lightness value look equally bright to the human eye, eliminating the uneven contrast jumps common in HSL ramps. Each shade step carries predictable contrast, accessible pairings are easier to verify, and new theme hues can be generated by rotating the hue channel while preserving the same lightness–chroma curve.

All primitives below are currently defined in HEX and will be progressively converted to OKLCH. A HEX fallback will be provided for browsers that don't support oklch():

.element {
  /* Fallback for older browsers */
  background: #006AFF;
  /* OKLCH for modern browsers */
  background: oklch(0.55 0.24 264);
}

ThemeProvider

Wrap your application with ThemeProvider to enable theming. It injects all color tokens and static tokens as CSS custom properties.

import { ThemeProvider } from "madagent";
import "madagent/styles";

function App() {
  return (
    <ThemeProvider theme="blue" mode="light">
      {/* All components have access to theme tokens */}
    </ThemeProvider>
  );
}

The provider renders a div with data-md-theme and data-md-mode attributes, which you can use for mode-specific CSS overrides.

useTheme Hook

Access the current theme and switch themes at runtime:

import { useTheme, themes } from "madagent";

function ThemeToggle() {
  const { theme, setTheme } = useTheme();
  const isDark = theme.mode === "dark";

  return (
    <button onClick={() =>
      setTheme(isDark ? themes.blue("light") : themes.blue("dark"))
    }>
      Switch to {isDark ? "light" : "dark"} mode
    </button>
  );
}

Primitives

Raw color palettes with 9 stops each (100–900). In light mode, 100 is the lightest and 900 the darkest. In dark mode, the ramp is inverted. Values are currently HEX and will be converted to OKLCH.

Alpha

Absolute

Semantic Tokens

Semantic tokens map primitives to UI roles. Components consume these instead of referencing primitives directly. Grouped into three categories: surface (backgrounds), content (text/icons), and border (strokes/dividers).

Surface

Colors for backgrounds and fills. Use var(--md-surface-*) in CSS.

Content

Colors for text and icons. Use var(--md-content-*) in CSS.

Border

Colors for strokes and dividers. Use var(--md-border-*) in CSS.

Spacing

Spacing tokens are not theme-dependent. Available as --md-spacing-* CSS custom properties.

Typography

Font Families

Font Sizes

Font Weights

Line Heights

Borders & Radii

Border Widths

Border Radii

Shadows