@zentrades-ui/tokens

Design tokens for the Zen UI design system.

Installation

pnpm add @zentrades-ui/tokens

Usage

Import the default tokens:

import { defaultTokens } from "@zentrades-ui/tokens";

// Access token values
console.log(defaultTokens.color.themed.contentPrimary.light); // "#1a1a1a"
console.log(defaultTokens.spacing.units["8"]); // "8px"

Token Structure

Colors

Primitive Palette

Raw color values organized by hue:

defaultTokens.color.palette.brand     // Brand colors (25-900)
defaultTokens.color.palette.grey      // Grey scale
defaultTokens.color.palette.blue      // Blue tones
defaultTokens.color.palette.red       // Red tones
defaultTokens.color.palette.green     // Green tones
// ... and more

Themed Colors

Colors with light/dark mode variants:

// Content colors
defaultTokens.color.themed.contentPrimary    // { light: "...", dark: "..." }
defaultTokens.color.themed.contentSecondary
defaultTokens.color.themed.contentTertiary
defaultTokens.color.themed.contentBrand

// Background colors
defaultTokens.color.themed.backgroundPrimary
defaultTokens.color.themed.backgroundSecondary
defaultTokens.color.themed.backgroundBrand

// Border colors
defaultTokens.color.themed.borderPrimary
defaultTokens.color.themed.borderSecondary

// Surface levels (L0-L6)
defaultTokens.color.themed.surfaceL0
defaultTokens.color.themed.surfaceL1
// ... up to surfaceL6

Spacing

// Named tokens
defaultTokens.spacing.tokens.xs   // 4px
defaultTokens.spacing.tokens.s    // 8px
defaultTokens.spacing.tokens.m    // 16px
defaultTokens.spacing.tokens.l    // 24px
defaultTokens.spacing.tokens.xl   // 32px

// Numeric scale
defaultTokens.spacing.units["1"]  // 1px
defaultTokens.spacing.units["2"]  // 2px
defaultTokens.spacing.units["4"]  // 4px
defaultTokens.spacing.units["8"]  // 8px
// ... and more

Typography

// Font families
defaultTokens.typography.fontFamilies.geist  // "Geist, -apple-system, ..."
defaultTokens.typography.fontFamilies.mono   // "Geist Mono, monospace, ..."

// Font sizes
defaultTokens.typography.fontSizes.xs   // 0.625rem
defaultTokens.typography.fontSizes.s    // 0.75rem
defaultTokens.typography.fontSizes.m    // 0.875rem
defaultTokens.typography.fontSizes.l    // 1rem
// ... up to 8xl

// Font weights
defaultTokens.typography.fontWeights.regular   // 400
defaultTokens.typography.fontWeights.medium    // 500
defaultTokens.typography.fontWeights.semibold  // 600
defaultTokens.typography.fontWeights.bold      // 700

// Line heights
defaultTokens.typography.lineHeights.xs  // matching font sizes
defaultTokens.typography.lineHeights.s
// ...

Border

// Border radius
defaultTokens.border.radius.xs      // 0.25rem
defaultTokens.border.radius.sm      // 0.375rem
defaultTokens.border.radius.md      // 0.5rem
defaultTokens.border.radius.lg      // 0.75rem
defaultTokens.border.radius.xl      // 1rem
defaultTokens.border.radius.pill    // 62.4375rem
defaultTokens.border.radius.circle  // 50%

// Border width
defaultTokens.border.width.none  // 0rem
defaultTokens.border.width.xs    // 0.0625rem (1px)
defaultTokens.border.width.s     // 0.09375rem (1.5px)
defaultTokens.border.width.m     // 0.125rem (2px)
defaultTokens.border.width.l     // 0.1875rem (3px)
defaultTokens.border.width.xl    // 0.25rem (4px)

Shadows

defaultTokens.shadow.layers.L0  // No shadow
defaultTokens.shadow.layers.L1  // Subtle elevation
defaultTokens.shadow.layers.L2  // Light elevation
// ... up to L7

TypeScript Types

Import types for type-safe token access:

import type { Tokens, ThemedColorVar, TokenScale } from "@zentrades-ui/tokens";

// Tokens is the full token object type
const myTokens: Tokens = { ... };

// ThemedColorVar is for light/dark color pairs
const color: ThemedColorVar = { light: "#fff", dark: "#000" };

Using with @zentrades-ui/theme

Pass tokens to the ThemeProvider to generate CSS variables:

import { ThemeProvider } from "@zentrades-ui/theme";
import { defaultTokens } from "@zentrades-ui/tokens";

<ThemeProvider mode="light" tokens={defaultTokens}>
  <App />
</ThemeProvider>

The theme provider converts tokens to CSS variables:

• contentPrimary → --zen-color-contentprimary
• backgroundBrand → --zen-color-backgroundbrand
• spacing 8 → --zen-space-8

Custom Tokens

Create custom tokens by extending or overriding defaults:

import { defaultTokens, Tokens } from "@zentrades-ui/tokens";

const customTokens: Tokens = {
  ...defaultTokens,
  color: {
    ...defaultTokens.color,
    themed: {
      ...defaultTokens.color.themed,
      contentBrand: {
        light: "#0066ff",
        dark: "#3399ff",
      },
    },
  },
};