Design

Manage your app's design system through

instructions/design-system.md

- the single source of truth for all UX/UI work.

Choose Your Mode

CREATE → No design system yet, or extracting from existing code MODIFY → Have a design system, need to update it WORK WITHIN → Have a design system, building features that follow it

CREATE Mode

Generate a new

instructions/design-system.md

from one of these entry points:

From URL (Reference App)

Analyze a live app and extract its design patterns.

Tell AI:

Analyze the design system at [URL].
Identify: colors, typography, spacing, component patterns.
Match to recognized framework (shadcn, Material UI, Radix, etc.).
Generate instructions/design-system.md based on this analysis.

Good reference apps:

linear.app (minimal, fast, keyboard-focused)
stripe.com/dashboard (data-heavy, clear hierarchy)
notion.so (flexible, calm)
vercel.com (modern, technical)

From Code (Extract & Audit)

Paste existing source code to extract and document current patterns.

Tell AI:

Analyze this code and extract the design system:
[paste relevant components, styles, or config files]

Document: colors, typography, spacing, component specs.
Identify inconsistencies (e.g., multiple button heights, conflicting colors).
Generate instructions/design-system.md with recommendations to standardize.

What to paste:

Tailwind config or CSS variables
Button/Input/Card components
Theme or design token files
2-3 representative page components

From Screenshot

Upload an image as a visual reference.

Tell AI:

Analyze this screenshot and extract the design system.
Identify: colors, typography, spacing, component patterns.
Match to closest recognized framework.
Generate instructions/design-system.md based on this analysis.

What to screenshot:

Dashboard or main app view
A form or data entry screen
Navigation (sidebar or topnav)

From Scratch

Start fresh with guided decisions.

Tell AI:

Help me create a design system for [app type].
I want it to feel like [reference: minimal/playful/professional/technical].
Primary brand color: [color or "help me choose"].
Generate instructions/design-system.md with sensible defaults.

See LAWSOFUX.md for why certain patterns work better.

MODIFY Mode

Update an existing

instructions/design-system.md

Update Values

Change colors, fonts, or spacing.

Tell AI:

Update instructions/design-system.md:
- Change primary color from [old] to [new]
- Update font from [old] to [new]
Ensure all related values are updated (hover states, etc.).

Add Patterns

Add new component types not yet documented.

Tell AI:

Add a [pricing table / data table / modal] pattern to instructions/design-system.md.
Follow existing design system values (colors, spacing, typography).
Reference: [URL or description of what you want]

See COMPONENTS.md for common SaaS component patterns.

Audit & Reconcile

Compare current code to design system, resolve drift.

Tell AI:

Audit this code against instructions/design-system.md:
[paste code]

Option A: List deviations so I can fix the code
Option B: Update design-system.md to reflect what code actually does

Always identifies:

Inconsistent values (3 different grays, 2 button heights)
Undocumented patterns (components not in design system)
Unused specs (documented but not implemented)

Migrate Framework

Transition from one component library to another.

Tell AI:

Migrate instructions/design-system.md from [Material UI] to [shadcn].
Keep existing colors, typography, and spacing.
Update component specs to match new framework patterns.

WORK WITHIN Mode

Reference existing

instructions/design-system.md

when building:

Build Feature

Follow the system when implementing new UI.

Tell AI:

Build [feature description].
Follow instructions/design-system.md for all design decisions.
Use the documented colors, typography, spacing, and component patterns.

Review Compliance

Check AI-built code against the system.

Tell AI:

Review this code for design system compliance:
[paste code]

Check against instructions/design-system.md.
Flag any deviations from documented patterns.

Answer Questions

Quick design decisions.

Tell AI:

Based on instructions/design-system.md:
- What color should [element] be?
- What spacing between [A] and [B]?
- Which button variant for [action]?

Design-System.md Structure

When CREATE mode generates the file, it follows this structure:

markdown

# Design System

## Reference
- Primary reference: [app name/URL]
- Component library: [shadcn/Material UI/Radix/custom]
- Design philosophy: [minimal/playful/professional/technical]

## Colors

### Brand
- Primary: #XXXXXX
- Primary hover: #XXXXXX

### Gray Scale
- 50: #XXXXXX (backgrounds)
- 100-400: [values]
- 500: #XXXXXX (borders, secondary text)
- 600-800: [values]
- 900: #XXXXXX (primary text)

### Semantic
- Success: #XXXXXX
- Error: #XXXXXX
- Warning: #XXXXXX

## Typography

### Font
- Family: [Inter/SF Pro/etc.]
- Fallback: system-ui, sans-serif

### Scale
- H1: 32px / 1.2 line-height / semibold
- H2: 24px / 1.25 / semibold
- H3: 20px / 1.3 / medium
- Body: 16px / 1.5 / regular
- Small: 14px / 1.5 / regular
- Tiny: 12px / 1.4 / regular

## Spacing

- Base unit: 4px
- Scale: 4, 8, 12, 16, 24, 32, 48, 64
- Component padding: 16px
- Section spacing: 32px
- Card gap: 16px

## Components

### Buttons
| Variant | Background | Text | Height | Padding | Border Radius |
|---------|------------|------|--------|---------|---------------|
| Primary | primary | white | 40px | 16px 24px | 6px |
| Secondary | gray-100 | gray-900 | 40px | 16px 24px | 6px |
| Ghost | transparent | gray-600 | 40px | 16px 24px | 6px |
| Destructive | error | white | 40px | 16px 24px | 6px |

States: hover (darken 10%), active (darken 15%), disabled (opacity 50%)

### Inputs
- Height: 40px
- Border: 1px gray-300
- Border radius: 6px
- Padding: 12px
- Focus: primary border + ring
- Error: error border
- Disabled: gray-100 background

### Cards
- Background: white
- Border: 1px gray-200 OR shadow-sm
- Border radius: 8px
- Padding: 16px or 24px

## Patterns

### Navigation
- Style: [sidebar/topnav/both]
- Width: [if sidebar, e.g., 240px]
- Behavior: [collapsible/fixed/responsive]

### Forms
- Layout: single column, labels above
- Field spacing: 16px
- Button placement: right-aligned
- Validation: inline, on blur

### Tables
- Row height: 48px
- Actions: right side
- Hover: gray-50 background
- Pagination: bottom

## Inconsistencies Found
[If extracted from existing code, list what was found and standardized]
- Example: Found 3 button heights (36px, 40px, 44px) → standardized to 40px

User Override

If you already have a

instructions/design-system.md

file, it takes precedence over any generated recommendations. The skill will work within your documented system.

Common Mistakes

Mistake	Fix
Building UI without design system	CREATE mode first, then build
Inconsistent components	Use MODIFY → Audit & Reconcile
"It looks off but I can't say why"	Check compliance against design-system.md
Reinventing patterns	Reference COMPONENTS.md for proven SaaS patterns
Ignoring UX principles	Reference LAWSOFUX.md for why patterns work

Success Looks Like

✅ Every project has

instructions/design-system.md

✅ AI builds consistent UI without repeated instructions ✅ Design decisions are documented, not guessed ✅ Code audits catch drift before it compounds ✅ New team members/contractors have clear reference

design

NPX Install

Tags

SKILL.md Content

Design

Choose Your Mode

CREATE Mode

From URL (Reference App)

From Code (Extract & Audit)

From Screenshot

From Scratch

MODIFY Mode

Update Values

Add Patterns

Audit & Reconcile

Migrate Framework

WORK WITHIN Mode

Build Feature

Review Compliance

Answer Questions

Design-System.md Structure

User Override

Common Mistakes

Success Looks Like