Using Design Tokens

This guide shows developers how to consume and extend the design–token system shipped with the Astro Performance Starter.

1. Quick recap

Token sources live in tokens/:

File	Purpose
base.json	Atomic design tokens (color, spacing, radii, motion, etc.)
semantic.json	Light/dark semantic aliases (background, border, etc.)
dist/	Build output – do not edit directly

The build script (pnpm run tokens:build) generates:

• tokens/dist/tokens.css – CSS variables (light + .dark). Imported by src/styles/global.css and mapped to Tailwind utilities via @theme inline (Tailwind 4 is CSS-first — there is no tailwind.config.*).
• tokens/dist/tailwind-tokens.json – a JSON export of the token scales for tooling.

2. In templates/components

Tailwind utilities

<div class="bg-background text-foreground p-4 rounded-lg shadow-md transition duration-fast">
  …
</div>

• bg-background / text-foreground – map to the flat semantic tokens (semantic.background, semantic.foreground), exposed as --color-background / --color-foreground via @theme inline.
• shadow-md – from shadow scale.
• duration-fast – motion tokens (--duration-fast/base/slow, plus ease-*); transition itself is Tailwind’s built-in utility.

CSS/SCSS

.card {
  background-color: hsl(var(--color-background));
  color: hsl(var(--color-foreground));
  border-radius: var(--border-radius-lg);
}

• Access any token via CSS custom property – wrap HSL tokens with hsl().
• Dark-mode handled automatically via .dark variables.

3. Adding / updating tokens

1. Edit tokens/base.json or tokens/semantic.json.
2. Run pnpm run tokens:build to regenerate outputs.
3. Commit only the source files — tokens/dist/ is gitignored and regenerated automatically (predev/build).

Tip: keep scales consistent (increments of 4px for spacing, 8ms for durations, etc.).

4. Naming rules

• Atomic tokens: lowercase camelCase (borderRadius.lg).
• Semantic tokens: flat, role-based names (background, surfaceRaised, mutedForeground) — see ADR-047.

5. Dark mode strategies

• System preference: enabled automatically via prefers-color-scheme.
• Manual toggle: add .dark class to html / body.

// Example: toggle
import { useEffect } from "preact/hooks";

useEffect(() => {
  document.documentElement.classList.toggle("dark");
});

6. Lint & validation

• pnpm run design:validate – ensures WCAG-AA contrast for semantic pairs.
• CI fails if new tokens break contrast budgets.

Need help? Check the Design System implementation guide or open an issue.