Design System Generator

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:

1. Scope
2. Design principles (3-5 bullet max)
3. Supported platforms & constraints
4. Design tokens
   • Color system
   • Typography
   • Spacing/layout
   • Radius/borders/shadows
   • Motion
5. UI foundations
   • Base styles/reset
   • Focus/interaction states
   • Iconography
6. Component architecture
   • Portability across SPA + Traditional
   • Naming + folder conventions
   • Required states (hover/focus/disabled/loading/error)
7. Component inventory (minimum viable list)
8. CSS strategy & tooling
   • SPA path vs Traditional path
9. Production build & asset strategy
   • dist structure
   • Manifest requirement
   • Optimization checklist
10. Accessibility checklist (ship gate)
11. Visual QA and screenshot workflow
12. 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.