Design System Generator Skill

Design System Generator

Overview

This skill generates a project-specific DESIGN_SYSTEM.md that enforces consistent UI/UX across:

SPAs (React/Vue/Svelte/Angular)
Traditional server-rendered sites (Laravel, Rails, Django, WordPress, etc.)
Hybrid systems (admin + marketing + docs)

The design system must be component-based, portable, and practical for real implementation.

Run this skill in the main conversation. Do not spawn subagents, agent teams, or delegated parallel workers unless the user explicitly approves the proposed count and scope after being told that doing so can increase usage. Ask again before expanding an approved scope.

Interactive Workflow

Required Questions

Ask these questions before generating the document:

1. Project type: SPA / Traditional / Hybrid

2. Primary framework(s): React/Vue/Svelte/Angular/None + backend/framework

3. Existing UI/template/design system already in use? (yes/no)

4. CSS approach preference:
   a) Tailwind/utility-first
   b) SCSS/SASS
   c) CSS Modules
   d) styled-components/emotion
   e) Component library (MUI/Ant/etc.)

5. Do you need light mode only, light+dark, or multi-theme?

6. Accessibility target (recommend WCAG AA) and keyboard support expectations

7. Browser/device support constraints

8. i18n/RTL requirements (if any)

9. Do you want design tokens exported? (CSS vars / JSON / both)

Reply examples:
- Short: `1a 2b 3no 4a 5b 6aa 7modern 8no 9both`
- Detailed: `SPA with Vue 3, no existing design system, using Tailwind, light+dark theme, WCAG AA, modern browsers only, no RTL, export both CSS vars and JSON`

Optional Questions (ask only if relevant)

Figma link or brand guide?
Multi-tenant theming?
Mobile app alignment?

Decision Policy

Rule 1: Prefer existing stack

If the project already uses a template or styling system, adapt to it.

Rule 2: Choose one best-fit direction

Do not provide 3-5 "options" unless the user requests comparison. Pick one approach and commit.

Rule 3: Source of truth before invention

Before generating or updating DESIGN_SYSTEM.md, inspect existing UI source of truth:

project instructions (AGENTS.md, CLAUDE.md, equivalent)
existing design docs, screenshots, prototypes, brand notes, and component docs
shared components, wrappers, layouts, forms, tables, modals, navigation, and state components
theme config, Tailwind config, CSS variables, global CSS, tokens, custom classes, animations, and transitions

Do not invent tokens, classes, wrappers, animation rules, or component architecture when a project-owned source already defines them.

Safe Defaults

React SPA: TailwindCSS + shadcn/ui (Radix primitives) + CSS variables tokens
Vue SPA: TailwindCSS + headless components + CSS variables tokens
Angular: Angular Material OR Tailwind + CDK (based on preference)
Traditional: SCSS or PostCSS layered architecture (tokens/base/components/utilities), optional bundler

Output Files

Primary

DESIGN_SYSTEM.md

Optional (only if user wants)

design-tokens.json
tokens.css
Sample component snippets

Non-Negotiables (must appear in DESIGN_SYSTEM.md)

Accessibility

Visible focus states
Keyboard navigation for interactive elements
Contrast targets (WCAG AA recommended)
Reduced motion support
Semantic HTML first; ARIA only when necessary

Performance / Production

Hashed asset filenames + manifest mapping (cache busting)
Minify CSS/JS for production
Image optimization pipeline (including SVG optimization)
Font loading strategy (font-display: swap, limit weights)

Source of Truth / Reuse

Reusable component and wrapper rules
Token ownership and generated-token policy
Animation, transition, and custom class policy
No one-off visual styles when a token, utility, wrapper, or component exists

UI Verification

Playwright/browser screenshot workflow
Element or region screenshots before full-page screenshots
Before/after screenshot comparison when visual output changes
Ambiguous user images require labeled annotated copies before coding

Document Style

DESIGN_SYSTEM.md is a team artifact:

Do not mention "AI", "assistant", "model", or "prompt"
Use clear "Do/Don't" guidance
Keep readable in ~10-15 minutes

DESIGN_SYSTEM.md Required Structure

Generate a tailored document using this structure:

Scope
Design principles (3-5 bullet max)
Supported platforms & constraints
Design tokens
- Color system
- Typography
- Spacing/layout
- Radius/borders/shadows
- Motion
UI foundations
- Base styles/reset
- Focus/interaction states
- Iconography
Component architecture
- Portability across SPA + Traditional
- Naming + folder conventions
- Required states (hover/focus/disabled/loading/error)
Component inventory (minimum viable list)
CSS strategy & tooling
- SPA path vs Traditional path
Production build & asset strategy
- dist structure
- Manifest requirement
- Optimization checklist
Accessibility checklist (ship gate)
Visual QA and screenshot workflow
Examples (token usage + one component example)

SPA vs Traditional Guidance

SPA guidance must include:

Recommended bundler (Vite/Webpack/Rollup) aligned with stack
CSS strategy (Tailwind/CSS Modules/SCSS)
Component library decision (if any)
Theming mechanism (CSS variables recommended)

Traditional guidance must include:

SCSS/PostCSS architecture:
- tokens layer
- base layer
- components layer
- utilities layer
Recommendation for bundling (optional but encouraged)
Manifest strategy so server templates reference hashed assets

Required Manifest Guidance (Cache Busting)

Include an explicit section stating:

Build output must produce a manifest mapping logical asset names to hashed filenames
Server must read manifest to include assets
Avoid stale browser caches in production

Agent-Doc Patch Snippet (Required Output)

After generating DESIGN_SYSTEM.md, also output a short patch snippet to add to AGENTS.md and/or CLAUDE.md:

## Design System
All UI components and pages must follow `DESIGN_SYSTEM.md`:
- Use design tokens (no hardcoded colors/sizes).
- Reuse shared components, wrappers, utilities, and motion rules before creating new ones.
- Implement component states (hover/focus/disabled/loading/error).
- For UI changes, capture the target element/region before full-page screenshots.
- Meet accessibility and performance requirements.

Reference Files

Before generating DESIGN_SYSTEM.md, read these reference files:

Template: TEMPLATE_DESIGN_SYSTEM.md - Use this as the base structure for generation
Example CSS tokens: examples/tokens.css - Reference for CSS variable token format
Example JSON tokens: examples/design-tokens.json - Reference for JSON token export format
Example manifest: examples/manifest.example.json - Reference for asset manifest structure
AGENTS.md patch: examples/AGENTS.patch.md - The exact snippet to add to AGENTS.md/CLAUDE.md

Acceptance Criteria

DESIGN_SYSTEM.md is tailored to the user's stack and constraints
Contains token rules, component state rules, accessibility gates, and production/manifest rules
Contains source-of-truth, reusable component, custom class, animation, transition, and visual QA rules
Avoids "AI" language entirely in the generated docs
Recommends a single coherent approach (unless user asked for alternatives)
Includes an AGENTS.md / CLAUDE.md patch snippet referencing DESIGN_SYSTEM.md

This skill is part of the awesome-ai-agent-skills community library.

Agent Skills: Design System Generator

Install this agent skill to your local

Skill Files