AgentSkillsCN

design-tokens

运用 Tailwind CSS 4 的 @theme 指令，践行设计令牌模式：CSS 变量、语义化命名、色彩体系、字体比例尺、间距规范以及暗黑模式。适用于 UI 系统设计、设计一致性评审，或品牌规范的制定与落地。结合前端设计技能，助力美学层面的精准呈现。

SKILL.md
--- frontmatter
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."