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:

# 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

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

What You Decide vs. What AI Implements

Rule: You define the goal of each screen. AI handles the pixels.

Priority Order: What to Get Right First

Tier 1: Gets You 80% of the Way

1. One primary action per screen — If you can’t name it, the page is broken.
2. Visual hierarchy — Size, weight, and contrast guide the eye. Most important = biggest.
3. Consistent spacing — Use your component library’s defaults. Don’t manually tweak pixels.
4. Design states — Every screen needs: empty, loading, error, success, and overflow states.

Tier 2: After Launch

5. Mobile responsiveness — Test core flows on mobile. 50%+ of traffic may be mobile.
6. Micro-interactions — Loading spinners, success checkmarks, smooth transitions.
7. Keyboard navigation — Tab through every form. Escape closes every modal.

Screen-by-Screen Guidance

Dashboard

Tell AI:

Design a SaaS dashboard that shows:
- 3-4 key metric cards at the top (e.g., MRR, active users, signups this week)
- A recent activity feed or table below
- A primary CTA: "Create [your main object]"
- Empty state for new users with onboarding guidance
Use [component library]. Mobile-responsive.

Settings Page

Tell AI:

Create a settings page with tabs:
- Profile (name, email, avatar)
- Billing (current plan, usage, manage subscription link)
- Notifications (email preferences with toggles)
- [Team/API/other sections you need]
Each tab has its own save button. Show success toast on save.

Data Tables

Tell AI:

Build a data table for [items — users, projects, invoices]:
- Columns: [list your columns]
- Sortable by [which columns]
- Search/filter bar above the table
- Row actions: edit, delete (with confirmation dialog)
- Pagination for 20+ items
- Empty state: "No [items] yet. Create your first one."

Forms

Tell AI:

Create a [create/edit] form for [object]:
- Fields: [list fields with types — text, email, select, etc.]
- Validate on blur (not on every keystroke)
- Show inline errors below each field
- Submit button disabled until form is valid
- Show loading state on submit, success toast on completion

Component Selection Guide

Visual Hierarchy Checklist

For every screen, verify:

• The primary action is the most visually prominent element
• Only ONE primary button per section (others are secondary or ghost)
• Headings use size + weight to create clear hierarchy (h1 > h2 > h3)
• Related items are grouped with consistent spacing
• Labels are above inputs (not placeholder-only)
• Color is not the only way to convey meaning (add icons or text)

Common UI Mistakes