designing-systems_skill

Overview

This skill guides creation of robust design systems: color tokens, typography scales, spacing, and Tailwind v4 theming. It enforces OKLCH color usage, semantic CSS variables, dark-mode parity, and a CSS-first @theme workflow for predictable theming. Use it to standardize visual systems and prevent mixed color spaces or banned fonts.

How this skill works

Before any implementation, spawn three agents to map the codebase and verify standards: one to scan existing CSS variables and Tailwind config, one to confirm OKLCH and Tailwind v4 patterns, and one to validate @theme syntax. The skill prescribes token files (colors, typography, spacing) and a single app entry that imports tokens and applies @theme. After changes, run an automated validation agent to check tokens, dark mode parity, and forbidden assets.

When to use it

• When building or refactoring a design system across a codebase
• When migrating color tokens to OKLCH for wide-gamut support
• When adopting Tailwind v4 with a CSS-first @theme setup
• When introducing semantic tokens for theming and dark mode
• When enforcing font and token usage rules across teams

Best practices

• Always analyze the existing system first—document variables and Tailwind config
• Use OKLCH exclusively for color tokens; never hard-code hex or RGB
• Define semantic tokens (e.g., --color-primary, --color-success) and avoid presentational names
• Create light and dark token sets in tandem; maintain parity for each token
• Keep tokens in dedicated files (colors.css, typography.css, spacing.css) and import from a single app stylesheet
• Ban specified fonts and use only approved typefaces from the typography palette

Example use cases

• Convert an existing hex-based palette to OKLCH tokens and update components to use CSS variables
• Set up Tailwind v4 @theme to map CSS tokens into utility classes for consistent theming
• Design a typography scale and token file, then wire fonts into the @theme block
• Implement 60-30-10 color distribution for a new product theme with dark-mode counterparts
• Run the validation agent after a release to ensure no forbidden fonts or hard-coded colors were introduced