design-system

Design System Generator

Analyze the user's provided design references (images, screenshots, PDFs, links, text descriptions, or existing code) and generate a comprehensive 3-file design system documentation.

Inputs

Accept ANY combination of:

• Images: Screenshots of UIs, mockups, design tool exports
• PDFs: Brand guidelines, style guides, design specs
• Links: URLs to design system documentation, component libraries, or live websites
• Text descriptions: Written descriptions of the design language
• Existing code: CSS files, theme configs, Tailwind configs, design tokens

If the user provides a link, use WebFetch to retrieve the content. If they provide a file path, read the file.

Output

Generate exactly 3 markdown files in the user's working directory (or a specified path):

1. design.md — Token Reference
2. design-guidelines.md — Accessibility & Do's/Don'ts
3. design-components.md — Component Specs

File Specifications

design.md — Token Reference

# [System Name] Design System — Token Reference

> Always read this file first. For component specs see [design-components.md](design-components.md). For accessibility and do's/don'ts see [design-guidelines.md](design-guidelines.md).

[1-2 sentence intro: design language, core architecture, primary typeface, base spacing unit, platform coverage]

Required sections:

Colors

Group by semantic role using H3 subsections (e.g., ### Accent — Primary, ### Surface & Neutral, ### Semantic/Status).

| Role | Hex | Usage | |------|-----|-------| | primary | #6442d6 | High-emphasis fills, text, icons | | on-primary | #ffffff | Text/icons on primary |

Include light/dark hex where detectable.

Typography

Default font family + fallback chain.

| Style | Size | Weight | Line Height | Spacing | |-------|------|--------|-------------|---------| | Display Large | 57sp | 400 | 64sp | -0.25sp | | Body Medium | 14sp | 400 | 20sp | 0.25sp |

List all scale levels (Display, Headline, Title, Body, Label or equivalent).

Shape

| Token | Radius | Components | |-------|--------|------------| | Small | 8dp | Chips, snackbars | | Medium | 12dp | Cards | | Full | 50% | Buttons, search bars |

Elevation

| Level | dp | CSS Shadow | Usage | |-------|-----|-----------|-------| | 0 | 0 | none | Base surface | | 1 | 1 | 0 1px 2px rgb(0 0 0/.3), 0 1px 3px 1px rgb(0 0 0/.15) | Cards |

Interaction States

| State | Layer Opacity | Notes | |-------|-------------|-------| | Enabled | 0% | Resting | | Hover | 8% | Cursor over | | Focus | 10% | Keyboard focus | | Pressed | 10% | Tap/click | | Disabled | 38% content, 12% container | Inoperable |

Layout

| Class | Width | Panes | Navigation | |-------|-------|-------|------------| | Compact | < 600dp | 1 | Nav bar | | Medium | 600–839dp | 1–2 | Nav rail or bar | | Expanded | 840–1199dp | 1–2 | Nav rail or drawer |

Motion

Easing curves (CSS cubic-bezier values), duration tokens (short/medium/long), transition types.

Icons

Icon system specs: style, sizes, grid, stroke weight. Omit if not detectable.

Design Tokens

Naming convention format (e.g., md.sys.color.primary).

design-guidelines.md — Accessibility & Do's/Don'ts

# [System Name] Guidelines — Accessibility & Do's/Don'ts

> See [design.md](design.md) for token values. See [design-components.md](design-components.md) for component specs.

Required sections:

Accessibility

• Contrast Requirements: Table with Requirement | Ratio, then Component | 3:1 Against
• Touch Targets: Minimum sizes, spacing rules, density constraints
• Keyboard Navigation: Table with Key | Action
• Assistive Technology: Screen reader rules, labels, roles

Gestures

Table with Gesture | Use (Tap, Double tap, Long press, Scroll, Swipe, Drag, Pinch).

Content Design

Writing rules: tone, capitalization, line length, label constraints.

Do's and Don'ts

Organize by category with H3 subsections: Color, Shape, Elevation, Interaction, Layout, Typography, Motion, Components.

Format:

• Do use primary for the single most important action
• Don't apply primary fill to multiple buttons in a group

design-components.md — Component Specs

# [System Name] Components

> Full specifications for all [N] components. Grouped by workflow.
> For tokens see [design.md](design.md). For rules & accessibility see [design-guidelines.md](design-guidelines.md).

Find ALL components detectable from the provided references. Do not limit to a fixed list.

Organize by workflow category using H2 headings:

• ## Actions
• ## Input
• ## Navigation
• ## Containment
• ## Data Display
• ## Feedback

Each component as an H3 section:

### Button

**Types:** Filled (primary) > Tonal (secondary) > Elevated > Outlined > Text.
Height 40dp. Target 48dp. Label: 14sp/500. Sentence case.

| Property | Value |
|---|---|
| Contrast | 4.5:1 text, 3:1 icons/borders |
| States | Rest, Hover, Pressed, Focus, Disabled |
| Touch target | 48x48dp min |

**Do:** Use sentence case; keep labels concise (1-3 words).
**Don't:** Use "Click here"; end with punctuation.

---

Typical components to cover:

• Actions: Button, Icon Button, FAB, Toolbar, Link
• Input: Text Field, Checkbox, Radio, Switch, Slider, Dropdown/Select, Combobox, Picker, Textarea
• Navigation: Navigation Bar/Rail/Drawer, Tabs, Breadcrumb, Menu, Search, App Bar
• Containment: Card, Dialog, Bottom Sheet, Drawer, Popover, Accordion, Divider
• Data Display: Avatar, Badge, List, Carousel, Icon, Image, Tag/Chip, Skeleton, Tooltip
• Feedback: Progress Indicator, Spinner, Snackbar/Toast, Message Bar

General Rules

• Be specific: measurements in dp/sp/px, hex colors, CSS box-shadow values
• If a value cannot be determined from references, make a reasonable inference based on the design language and note it with "(inferred)"
• Use tables over prose — keep scannable
• Aim for 150–400 lines per file
• Each file must cross-reference the other two in its opening blockquote
• Separate components with horizontal rules (---)
• Use consistent markdown formatting throughout

Workflow

1. Gather all reference materials from the user (read files, fetch URLs)
2. Analyze the design language: identify colors, typography, spacing patterns, component inventory
3. Generate all 3 files
4. Write each file to the specified directory
5. Summarize what was generated: system name, token count, component count