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.

When to use this skill:

• Setting up UI consistency rules for a new project
• Standardizing component patterns across teams
• Establishing design tokens (colors, typography, spacing)
• Defining accessibility and performance requirements

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.

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)

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. 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).
- Implement component states (hover/focus/disabled/loading/error).
- 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
• 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.

Design System

All UI components and pages must follow DESIGN_SYSTEM.md:

• Use design tokens (no hardcoded colors/sizes).
• Implement component states (hover/focus/disabled/loading/error).
• Meet accessibility and performance requirements.

design-system-generator

Generates a project-specific DESIGN_SYSTEM.md so UI/UX stays consistent across pages, components, and teams.

What this skill produces

• DESIGN_SYSTEM.md (primary output)
• Optional:
• tokens.css (CSS variables)
• design-tokens.json (token export)
• Example manifest snippet / guidance (cache-busting)

What this skill optimizes for

• Component-based design that works in:
• SPAs (React/Vue/Svelte/Angular)
• Traditional server-rendered sites (Laravel/Rails/Django/WordPress)
• Hybrid setups
• Accessibility defaults (focus, keyboard, contrast, reduced motion)
• Production readiness (hashed assets + manifest, minification, image optimization)

Where to place outputs

• DESIGN_SYSTEM.md → repo root
• Optional token files:
• styles/tokens.css
• styles/design-tokens.json

Integration requirement

AGENTS.md and/or CLAUDE.md must reference DESIGN_SYSTEM.md with the required snippet:

## Design System
All UI components and pages must follow `DESIGN_SYSTEM.md`:
- Use design tokens (no hardcoded colors/sizes).
- Implement component states (hover/focus/disabled/loading/error).
- Meet accessibility and performance requirements.

Related skills

• agents-md-generator - Generates AGENTS.md/CLAUDE.md and can delegate to this skill for Design System generation

DESIGN_SYSTEM.md

0. Scope

• Product surfaces covered:
• Out of scope:

1. Design principles

• Clarity over cleverness
• Consistency over variety
• Accessibility is default
• Performance is a feature

2. Supported platforms & constraints

• App type: (SPA / Traditional / Hybrid)
• Frameworks:
• Browser support:
• i18n/RTL:
• Theming: (Light / Light+Dark / Multi-theme)

3. Design tokens

3.1 Token sources

• Source of truth: (CSS variables / JSON tokens / both)
• Files:
• styles/tokens.css
• styles/design-tokens.json (optional)

3.2 Color system

• Brand colors:
• Neutral palette:
• Semantic colors:
• --color-success
• --color-warning
• --color-danger
• --color-info

Rules:

• Never hardcode hex in components; use tokens.
• Ensure contrast meets WCAG AA.

3.3 Typography

• Font families:
• Type scale (sizes + line-height):
• Font weights:
• Rules (headings/body/captions):

3.4 Spacing & layout

• Spacing scale:
• Grid/container rules:
• Responsive breakpoints:

3.5 Radius, borders, shadows

• Radius scale:
• Border rules:
• Shadow scale:

3.6 Motion

• Duration scale:
• Easing:
• Reduced motion policy:

4. UI foundations

4.1 Base styles / reset

• Reset/base approach:
• Defaults (body, links, headings):

4.2 Focus & interaction states

• Focus ring standard:
• Hover/active behavior:
• Disabled behavior:

4.3 Iconography

• Icon set:
• Sizing rules:
• Stroke/fill rules:

5. Component architecture

5.1 Portability

Components must be implementable in:

• SPA components
• server-rendered templates

5.2 Naming & structure

• Naming conventions:
• Folder conventions:

5.3 Required component states

All interactive components define:

• default, hover, active, focus, disabled
• loading (if async)
• error (if validation)

6. Component inventory (minimum)

• Button (primary/secondary/ghost/destructive)
• Input, Textarea, Select
• Checkbox, Radio, Switch
• Badge
• Card
• Modal/Dialog
• Toast/Notification
• Table (empty/loading states)
• Navigation primitives (header/sidebar/tabs)

7. CSS strategy & tooling

7.1 SPA

• Bundler:
• CSS strategy:
• Theming approach:

7.2 Traditional server-rendered

• CSS tooling:
• Architecture layers:
• tokens
• base
• components
• utilities
• Bundler recommendation:

8. Production build & asset strategy

8.1 Output folders

• dist/ structure:
• Public assets:

8.2 Manifest & cache busting (required)

Build outputs a manifest mapping logical to hashed filenames.

8.3 Optimization

• CSS/JS minify:
• Image optimization:
• SVG optimization:
• Font strategy:

9. Accessibility checklist (ship gate)

• Keyboard navigation verified
• Focus visible
• Contrast AA
• Reduced motion supported
• Semantic HTML first

10. Examples

10.1 Token usage (CSS variables)

:root {
  --color-bg: #ffffff;
  --color-fg: #0b0f17;
  --radius-md: 12px;
  --space-4: 16px;
}

10.2 Component example

<button class="btn btn-primary">
  Submit
</button>