home / skills / phrazzld / claude-config / design-tokens

design-tokens skill

safe

This skill helps you implement design tokens with Tailwind CSS 4 @theme for semantic, brand-tinted colors, typography, and dark mode.

npx playbooks add skill phrazzld/claude-config --skill design-tokens

Review the files below or copy the command above to add this skill to your agents.

Files (6)

SKILL.md

2.8 KB

---
name: design-tokens
description: "Apply design token patterns using Tailwind CSS 4 @theme directive: CSS variables, semantic naming, color systems, typography scales, spacing, dark mode. Use when designing UI systems, reviewing design consistency, or establishing brand guidelines. Integrates with frontend-design skill for aesthetic execution."
---

# Design Tokens

**Design tokens are the single source of truth for design decisions.**

## Philosophy

- **CSS-first**: Define tokens in CSS `@theme`, not JavaScript config
- **Semantic naming**: `--color-primary` not `--color-blue-500`
- **Brand-tinted neutrals**: Add imperceptible brand hue (chroma 0.005-0.02), not pure gray
- **OKLCH colors**: Perceptually uniform, better than RGB/HSL

## Why Tailwind CSS 4 @theme

- CSS-native (no build step overhead)
- Type-safe auto-completion
- CSS variable integration (`var(--color-primary)`)
- Dark mode built-in

**Migration from Tailwind 3**: Delete `tailwind.config.js`, move to CSS `@theme`.

## Basic @theme Structure

```css
@import "tailwindcss";

@theme {
  /* Brand hue - single source of truth */
  --brand-hue: 250;

  /* Colors - OKLCH with semantic names */
  --color-primary: oklch(0.6 0.2 var(--brand-hue));
  --color-background: oklch(0.995 0.005 var(--brand-hue));  /* Brand-tinted */
  --color-foreground: oklch(0.15 0.02 var(--brand-hue));

  /* Typography */
  --font-sans: "Inter Variable", system-ui, sans-serif;
  --font-size-base: 1rem;

  /* Spacing (8-point grid) */
  --spacing-md: 1rem;
  --radius-md: 0.5rem;
}
```

## Best Practices

### Do
- Use semantic names (`--color-primary`)
- Use OKLCH colors
- Tint neutrals with brand hue
- Follow 8-point spacing grid
- Support dark mode from start
- Create component tokens

### Don't
- Hardcode values
- Use pure grays (chroma 0)
- Use generic fonts (Inter/Roboto)
- Skip dark mode
- Create too many tokens initially

## Dark Mode Pattern

Same brand hue, inverted lightness:

```css
@theme {
  --brand-hue: 250;
  --color-background: oklch(0.995 0.005 var(--brand-hue));

  @media (prefers-color-scheme: dark) {
    --color-background: oklch(0.12 0.015 var(--brand-hue));
  }
}
```

## References

Detailed patterns:
- `references/color-system.md` — OKLCH, semantic colors, brand-tinted neutrals
- `references/typography.md` — Type scale, font pairings, font loading
- `references/spacing.md` — 8-point grid, radius, shadows, breakpoints, z-index
- `references/dark-mode.md` — System preference, manual toggle, component
- `references/component-tokens.md` — Button, input, card, animation, WebGL

## Integration

**Design tokens provide the foundation; frontend-design provides aesthetic direction.**

1. Load design-tokens for the system
2. Load frontend-design for aesthetic execution
3. Result: Consistent system + distinctive design

**"Design tokens are contracts between design and development."**

Overview

This skill applies design token patterns using Tailwind CSS 4's @theme directive to create a CSS-first, semantic token system. It focuses on CSS variables, OKLCH color definitions, brand-tinted neutrals, typography scales, spacing on an 8-point grid, and built-in dark mode support. Use it to establish a single source of truth for design decisions and to integrate with aesthetic guidance from a frontend-design workflow.

How this skill works

The skill defines tokens directly inside a CSS @theme block so tokens live as CSS variables (e.g. --color-primary) rather than JavaScript config. It standardizes color using OKLCH for perceptual uniformity, applies a subtle brand tint to neutrals, and provides responsive dark mode overrides via media queries. Typography, spacing, and component-level tokens are expressed as variables so UI components consume the same values across the system.

When to use it

When creating or migrating a design system to Tailwind CSS 4 and preferring CSS-native tokens
When you need perceptually consistent color outcomes across light and dark modes
When establishing brand guidelines that require semantic, reusable variables
When reviewing UI consistency across components and teams
When integrating with frontend-design for visual styling and component work

Best practices

Use semantic token names (e.g. --color-primary, --spacing-md) instead of implementation details
Prefer OKLCH color values for perceptual uniformity and consistent color operations
Tint neutral values slightly with the brand hue (chroma 0.005–0.02) instead of pure grays
Follow an 8-point spacing grid and express sizes as tokens to keep rhythm consistent
Define dark mode variations from the start using the same brand hue and inverted lightness
Create component-specific tokens (buttons, inputs, cards) rather than hardcoding values in components

Example use cases

Migrating from Tailwind 3: remove tailwind.config.js and move tokens into @theme CSS blocks
Defining a brand color system where primary, background, and foreground are semantic OKLCH tokens
Implementing dark mode by overriding token lightness within prefers-color-scheme: dark
Establishing a typography scale and font variables for consistent type across products
Creating component token sets (button radius, input spacing, card elevation) consumed by UI components

FAQ

Why define tokens in CSS @theme instead of tailwind.config.js?

Defining tokens in @theme keeps them CSS-native, enables direct var() usage, and removes an extra build/config layer while still providing type-safe autocomplete in editors.

Why use OKLCH instead of hex or HSL?

OKLCH is perceptually uniform, so lightness and chroma changes produce predictable visual results, improving accessible contrast and design consistency.