Design System Specification Skill: Tokens and WCAG

​

Best for

• Designing the visual system and style guide for a new web application
• Establishing a consistent design language across multiple sub-brands or pages
• Creating a robust utility system (CSS custom properties) for developers and AI coding agents
• Standardizing typography, spacing rules, and WCAG accessibility targets
• Defining iconography, motion design, and responsive component behavior

​

What it produces

1. Design system overview — brand personality, design principles (Atomic hierarchy, 8px grid, dark mode parity, accessibility)
2. Design token architecture — three-layer model: primitive tokens → semantic tokens → component tokens; theming mechanism (CSS class / data attribute / media query)
3. Color palette — brand colors table (light + dark mode values, contrast ratio, semantic purpose), neutral scale (9–11 grays), utility colors (info/warning/success/error)
4. Typography — font family choices, font loading strategy (font-display, preloading, fallback stacks), fluid type scale using clamp() (Display H1 through Code), line length, modular scale ratio
5. Spacing system — 8px grid scale as CSS custom properties (--space-1 through --space-16), component spacing table
6. Border radius and shadows — radius scale (sm/md/lg/pill), shadow scales for light and dark mode
7. z-index system — named layers (--z-base through --z-toast: 700), isolation: isolate guidance
8. Iconography — icon set selection (e.g., Lucide, Phosphor, Heroicons), sizing grid (8/16/24/32px), stroke width consistency, SVG vs. icon font decision
9. Imagery guidelines — photography style, illustration style, placeholder/empty-state image patterns
10. Motion design — timing curves (ease-out, ease-in, ease-in-out as cubic-bezier values), duration scale, micro-interactions per element, loading animation patterns, prefers-reduced-motion fallbacks
11. UI component library — 13 required components: Buttons, Form Inputs, Cards, Badges, Tables, Modals, Navigation, Dropdowns, Tooltips, Tabs, Accordion, Alerts, Toast Notifications; each with all interactive states and responsive behavior
12. Component state matrix — Default, Hover, Active, Focus-Visible, Disabled, Error, Loading — for every interactive component
13. Layout, responsive, and accessibility rules — grid system, breakpoints (mobile/tablet/desktop/wide), responsive component behavior per breakpoint, WCAG 2.2 checklist
14. Component state reference — per data-fetching component: Loading state, Empty state, Error state
15. Alternatives considered

​

How to invoke it

claude "Design the visual identity and design system for our new checkout portal" --skill design-system-specification

gemini "Create a style guide for a developer-focused analytics dashboard" --skill design-system-specification

npx engineering-docs design-system-specification "Build a full component library spec with tables, modals, navigation, and tooltips"

​

Example scenarios

​

Key concepts

--space-1:  4px;   /* Minor adjustment */
--space-2:  8px;   /* Tiny spacing */
--space-3:  12px;  /* Compact */
--space-4:  16px;  /* Standard increment */
--space-6:  24px;  /* Medium card padding */
--space-8:  32px;  /* Section spacing */
--space-12: 48px;  /* Large container margins */
--space-16: 64px;  /* Hero element margins */

--ease-out:     cubic-bezier(0.0, 0.0, 0.2, 1);    /* Entrances */
--ease-in:      cubic-bezier(0.4, 0.0, 1, 1);        /* Exits */
--ease-in-out:  cubic-bezier(0.4, 0, 0.2, 1);        /* State changes */

--duration-fast:   100ms;  /* Micro-interactions */
--duration-normal: 200ms;  /* Hover states */
--duration-slow:   300ms;  /* Modal open/close */

​

Interview process

​

Output structure

1.  Design System Overview (brand identity + design principles)
2.  Design Token Architecture (3-layer model + theming mechanism)
3.  Color Palette (brand colors, neutral scale, utility colors)
4.  Typography (font families, loading strategy, fluid type scale)
5.  Spacing System (8px grid scale, component spacing table)
6.  Border Radius and Shadows (light + dark mode shadow scales)
7.  z-index System (named layers)
8.  Iconography (library, sizing grid, color rules)
9.  Imagery Guidelines (photography, illustration, placeholders)
10. Motion Design (timing curves, duration scale, micro-interactions, reduced motion)
11. UI Component Library (all 13 components, all states)
12. Layout, Responsive, and Accessibility Rules
13. Component State Reference (loading/empty/error per data component)
14. Alternatives Considered

​

Handoff

​

Quality gate

• Every color token has both light and dark mode values defined, and contrast ratios are verified for all text-bearing tokens
• All spacing, padding, and margin values align to the 8px grid (or documented 4px sub-grid for fine adjustments)
• Every interactive component specifies all states: Default, Hover, Active, Focus-Visible, Disabled, Error, and Loading
• Focus indicator styles are defined for all interactive elements with sufficient contrast in both light and dark backgrounds
• The typography scale is complete with size, weight, line height, and semantic purpose for each level
• Icon set is selected, sizing grid defined (8/16/24/32px), and stroke width is consistent
• z-index scale is defined with named layers and no raw numeric values in any component
• Font loading strategy is documented (font-display, preloading, fallback stacks)
• Every data-fetching component has Loading, Empty, and Error states defined
• Responsive behavior is documented for tables, navigation, modals, and multi-column layouts
• Motion design tokens are defined with prefers-reduced-motion fallbacks for every animation
• Design token architecture is layered (primitive → semantic → component) with documented inheritance