import { Meta } from '@storybook/addon-docs/blocks';

Design Tokens

<p className="excerpt">Shade's design tokens are implemented through CSS-first Tailwind v4 tokens (`@theme` + CSS variables). This document outlines our token system and how to use it effectively.</p>

Color System

Base Colors

Our color system includes semantic colors and a comprehensive neutral palette:

css

@theme {
    // Base colors
    --color-transparent: transparent;
    --color-current: currentColor;
    --color-ghostaccent: var(--accent-color, #ff0095);
    --color-white: #FFF;
    --color-black: #15171A;

    // Gray scale (note: we use 'gray', not 'grey')
    --color-gray-50: #FAFAFB;
    --color-gray-100: #F4F5F6;
    // ... more shades
    --color-gray-900: #394047;
    --color-gray: #ABB4BE;

    // Brand colors
    --color-green-100: #E1F9E4;
    --color-green-400: #58DA67;
    --color-green-500: #30CF43;
    --color-green-600: #2AB23A;
    --color-green: #30CF43;
    // ... more colors
}

⚠️ Note: While both grey and gray token aliases exist for legacy compatibility, use gray for new components following TailwindCSS conventions.

Semantic Tokens

Theme-aware colors using CSS variables:

css

@theme {
    --color-background: var(--background);
    --color-foreground: var(--foreground);
    --color-primary: var(--primary);
    --color-primary-foreground: var(--primary-foreground);
    // ... more semantic colors
}

Semantic Contract

The semantic visual rules and guarantees are defined in:

theme-variables.css (runtime values + dark mode overrides)
tailwind.theme.css (Tailwind aliases)

Current semantic families:

Surface: surface-page, surface-panel, surface-elevated, surface-overlay, surface-inverse
Text: text-primary, text-secondary, text-tertiary, text-inverse
Border/focus: border-subtle, border-default, border-strong, focus-ring
State: state-info, state-success, state-warning, state-danger

Semantic typography/radius/motion families:

Typography: font-body, font-heading, font-code, text-body-{sm|md|lg}, leading-{body|heading}
Sizing: --control-height (shared medium control height, currently 34px)
Radius: radius-control, radius-surface, radius-badge, radius-pill
Motion: duration-{fast|base|slow}, ease-{standard|emphasized}

Typography

Font Families

css

@theme {
    --font-sans: Inter, -apple-system, ...;  /* Default UI font */
    --font-serif: Georgia, serif;            /* Editorial content */
    --font-mono: Consolas, ...;              /* Code */
    // Additional web fonts available
}

Font Sizes

A comprehensive scale from 2xs to 9xl:

css

@theme {
    --text-2xs: 1.0rem;
    --text-base: 1.4rem;
    --text-xs: 1.2rem;
    // ... more sizes
    --text-9xl: 12.8rem;
    --text-9xl--line-height: 1;
}

Line Heights

css

@theme {
    --leading-base: 1.5em;
    --leading-tight: 1.35em;
    --leading-tighter: 1.25em;
    --leading-supertight: 1.1em;
}

Spacing

Our spacing system uses a 0.4rem (4px) base unit:

css

@theme {
    --spacing: 0.4rem; /* Base unit */
    // Utilities are derived as calc(var(--spacing) * n)
}

Breakpoints

css

@theme {
    --breakpoint-sm: 480px;
    --breakpoint-md: 640px;
    --breakpoint-sidebar: 800px;
    --breakpoint-lg: 1024px;
    --breakpoint-sidebarlg: 1240px;
    --breakpoint-xl: 1320px;
    --breakpoint-xxl: 1440px;
    --breakpoint-xxxl: 1600px;
    --breakpoint-tablet: 860px;
}

Shadows

css

@theme {
    --shadow: 0 0 1px rgba(0,0,0,.05), 0 5px 18px rgba(0,0,0,.08);
    --shadow-xs: 0 0 1px rgba(0,0,0,0.04), ...;
    // ... more shadow values
}

Border Radius

css

@theme {
    --radius: 0.4rem;
    --radius-sm: 0.4rem;
    --radius-md: 0.6rem;
    --radius-lg: 0.8rem;
    // ... more radius values
}

Animations

Pre-defined animations for common interactions:

css

@theme {
    --animate-toaster-in: toasterIn 0.8s cubic-bezier(...);
    --animate-fade-in: fadeIn 0.15s ease forwards;
    // ... more animations
}

Usage Guidelines

Best Practices

Use Semantic Tokens

// ✅ Good
className="bg-background text-foreground"

// ❌ Avoid
className="bg-white text-black"

Spacing Consistency

// ✅ Good
className="p-4 gap-2"

// ❌ Avoid
style={{padding: '16px', gap: '8px'}}

Typography Scale

// ✅ Good
className="text-2xl font-sans"

// ❌ Avoid
style={{fontSize: '22px'}}

Dark Mode

Dark mode uses a CSS custom variant:

css

@custom-variant dark (&:is(.dark *):not(.light *));

CSS Reset

Shade uses a scoped CSS reset:

css

@import "./preflight.css"; /* Custom scoped reset provided */

</div>