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

<Meta title="Tokens / Tokens Guide" /> <div className="sb-doc">

Tokens

<p className="excerpt">Tokens are Shade's visual atoms — colours, type sizes, spacing, radii, shadows, motion. Every primitive, component, and pattern resolves down to these. Browse the live galleries in the sidebar; the rules for using them are short.</p>

The galleries

• Colors — surface, text, border, state, chart, and the raw palette.
• Typography — font families, size ramp, line-heights.
• Spacing — the 0.4rem base unit and the semantic gap scale primitives use.
• Radius — numeric and semantic radii (radius-control, radius-surface, radius-pill).
• Shadows — elevation tokens for cards, popovers, and modals.
• Motion — durations, easings, and named animations.
• Breakpoints — responsive cut-offs backing Tailwind's md: / lg: variants.

Toggle light/dark from the Storybook toolbar to see semantic tokens flip.

Two flavours

Semantic tokens are named by purpose — --background, --text-primary, --border-default, --surface-elevated. They flip between light and dark mode automatically. Reach for these by default.

Raw tokens are concrete values — --color-gray-500, --text-base, --spacing. They never change between modes. Use only when no semantic token fits (chart series, brand assets, illustrations).

Source files

• apps/shade/theme-variables.css — semantic tokens + dark-mode overrides.
• apps/shade/tailwind.theme.css — Tailwind @theme block: raw catalogue and bindings.
• Semantic color variables should resolve directly to raw --color-* tokens, not to another semantic token. For example, prefer --text-primary: var(--color-black) over --text-primary: var(--foreground).

Rules of consumption

• Prefer Tailwind utilities — bg-background, text-foreground, rounded-md — over inline styles.
• Never hard-code hex or hsl() values for UI chrome. They don't theme and don't dark-mode. Chart tokens are the current exception until the chart palette has its own raw scale.
• Inside stylesheets, use var(--token) directly. Don't wrap variables in color functions.
• Don't write dark: variants for colour. The tokens do that. (Exceptions: assets like logos and illustrations.)

</div>