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

design-tokens skill

safe

This skill helps you apply design token patterns using Tailwind CSS 4 @theme with semantic naming, OKLCH colors, and dark mode for cohesive UI systems.

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."
effort: high
---

# 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 token system. It focuses on semantic naming, OKLCH color usage, brand-tinted neutrals, scalable typography, an 8-point spacing system, and built-in dark mode support. Use it to establish a single source of truth for design decisions and to integrate tokens directly into the stylesheet workflow.

How this skill works

The skill generates and organizes CSS variables inside an @theme block so tokens are available natively to Tailwind without a JavaScript config. It prefers semantic names (for example --color-primary) and perceptually uniform OKLCH color values, including a single brand-hue variable to tint neutrals. Dark mode is handled by overriding token values in a prefers-color-scheme media query, and component-level tokens can be composed from base tokens.

When to use it

When creating or migrating a UI system to Tailwind CSS 4 and you want CSS-native tokens
When you need a single source of truth for colors, type, spacing, and radii
When you want perceptually consistent color behavior across light and dark modes
When reviewing design consistency or establishing brand guidelines
When integrating tokens with aesthetic direction from a frontend-design workflow

Best practices

Define tokens in CSS @theme, not in JavaScript config
Use semantic names (e.g., --color-primary, --spacing-md) instead of implementation hues
Choose OKLCH colors and tint neutral grays with a subtle brand hue (chroma 0.005–0.02)
Adopt an 8‑point spacing scale and derive component tokens from base tokens
Support dark mode from the start by inverting lightness, keeping the same brand hue
Keep the initial token set focused—expand component tokens as patterns stabilize

Example use cases

Bootstrapping a brand system: define --brand-hue then derive colors, neutrals, and typography
Migrating from Tailwind 3: remove tailwind config and move tokens to @theme for native CSS variables
Implementing dark mode: override token lightness in prefers-color-scheme media queries
Design reviews: use semantic tokens to verify color/spacing consistency across components
Component libraries: create component-specific tokens (button, input, card) that reference base tokens

FAQ

Why use OKLCH instead of RGB or HSL?

OKLCH is perceptually uniform, so lightness and chroma adjustments behave predictably across colors, improving accessible contrast and consistent theming.

How do I tint neutrals without making them obviously colored?

Use a very low chroma value (0.005–0.02) combined with your brand hue so neutrals retain gray appearance while subtly aligning with the brand.