Design Tokens Skill

One config. Consistent design. Zero guessing.

Purpose

Foundation layer for all UI. Every visual property comes from here.

Output

tokens_generated: true
tailwind_config: "tailwind.config.mjs"
css_variables: "src/styles/tokens.css"
design_token_verdict: PASS | WARN | FAIL

Single Source of Truth

This skill is the ONLY source for visual tokens. All UI skills consume from here. No local overrides.

Cross-references:

section-skeleton → uses spacing/colors
astro-components → uses all tokens
frontend-design → uses all tokens

Token Categories

Type	Tokens	Usage
Semantic	`primary-`, `accent`, `neutral-`	Use in components
Utility	`spacing.`, `font-`, `shadow-*`	Internal mapping only

Rule: Components use semantic tokens. Utility for internal only.

Token Usage Scope

Token	Allowed	Forbidden
`accent`	CTAs, links, highlights	Body text, backgrounds
`primary-900`	Headlines, body text	Buttons
`primary-100`	Section backgrounds	Text
`neutral-200`	Borders, dividers	CTAs

Wrong scope = WARN.

Forbidden Raw Values

Type	Forbidden	Use Instead
Colors	`#FF6B35`, `rgb()`	`bg-accent`, `text-primary-900`
Spacing	`mt-[23px]`	`mt-6`
Font sizes	`text-[18px]`	`text-lg`
Shadows	`shadow-[...]`	`shadow-card`
Radius	`rounded-[12px]`	`rounded-lg`

Any raw value in component = FAIL.

A11y Contrast Requirements

Combination	Min Ratio	Standard
Body text on white	4.5:1	AA
Body text on primary-100	4.5:1	AA
Large text (≥18px)	3:1	AA
CTA text on accent	4.5:1	AA
UI components	3:1	AA

Contrast fail = FAIL.

Color System

Required

Color	Tokens	Purpose
Primary	50-950 scale	Brand, text, backgrounds
Accent	DEFAULT, hover, light	CTAs, links
Neutral	50-900 scale	Borders, backgrounds
Semantic	success, error, warning	Feedback

Usage

Token	Use For
`primary-900`	Headlines, body
`primary-700`	Secondary text
`primary-100`	Light section bg
`accent`	CTAs, links
`accent-hover`	Button hover

Typography (Fluid Scale)

Token	Range	Use
`text-base`	16-18px	Body
`text-lg`	18-20px	Lead
`text-2xl`	24-32px	H3
`text-3xl`	30-40px	H2
`text-4xl/5xl`	36-64px	H1

Font: Inter → system-ui → sans-serif

Spacing (8px Grid)

Token	Value	Use
`py-12 md:py-20`	48/80px	Section padding Y
`px-4 md:px-8`	16/32px	Section padding X
`gap-6 md:gap-8`	24/32px	Component gap
`p-4 md:p-6`	16/24px	Card padding

Design Token Verdict

design_token_verdict: PASS | WARN | FAIL
issues: []

Condition	Verdict
Raw value in component	FAIL
Contrast fail	FAIL
Missing required token	FAIL
Wrong token scope	WARN
Missing shade in scale	WARN
All rules pass	PASS

FAIL States

Condition
Hardcoded hex in component
Arbitrary spacing `[Xpx]`
Contrast ratio below AA
Missing primary scale
Missing accent colors

WARN States

Condition
Token used in wrong scope
Missing optional shades
Non-standard font loaded

Brand Intake

brand_intake:
  primary_color: "#XXXXXX"
  accent_color: "#XXXXXX"
  font: Inter | Poppins | System
  style: Modern | Classic | Playful
  industry: removals | cleaning | trades | legal

References

tailwind-config.md — Full config
color-generator.md — Shade generation
tokens-css.md — CSS variables

design-tokens

Safety Notice

Copy this and send it to your AI assistant to learn