madappgang/design-references

Design References Skill

Overview

This skill provides predefined design system references that the ui agent can use when reviewing designs. Each reference includes design principles, color guidelines, typography rules, spacing patterns, and component patterns.

Available Design Systems

Material Design 3 (Google)

Reference ID: material-3 Official URL: https://m3.material.io/

Design Principles

1. Adaptive & Accessible - Responsive across devices, accessible to all
2. Personal & Customizable - Dynamic color, personalization
3. Expressive - Motion, shape, and color express brand

Color System

• Dynamic Color - Colors derived from user wallpaper or brand
• Tonal Palettes - 13 tones per color (0-100)
• Color Roles:
  • Primary: Main brand color
  • Secondary: Accent elements
  • Tertiary: Contrast and balance
  • Error: Destructive actions
  • Surface: Backgrounds and containers
  • On-*: Text/icon colors on surfaces

Key Metrics:

• Text contrast: 4.5:1 minimum (WCAG AA)
• Large text contrast: 3:1 minimum
• Non-text contrast: 3:1 minimum

Typography

Type Scale (Default): | Role | Size | Weight | Line Height | |------|------|--------|-------------| | Display Large | 57sp | 400 | 64sp | | Display Medium | 45sp | 400 | 52sp | | Display Small | 36sp | 400 | 44sp | | Headline Large | 32sp | 400 | 40sp | | Headline Medium | 28sp | 400 | 36sp | | Headline Small | 24sp | 400 | 32sp | | Title Large | 22sp | 400 | 28sp | | Title Medium | 16sp | 500 | 24sp | | Title Small | 14sp | 500 | 20sp | | Body Large | 16sp | 400 | 24sp | | Body Medium | 14sp | 400 | 20sp | | Body Small | 12sp | 400 | 16sp | | Label Large | 14sp | 500 | 20sp | | Label Medium | 12sp | 500 | 16sp | | Label Small | 11sp | 500 | 16sp |

Font: Roboto (sans-serif)

Spacing

Baseline Grid: 4dp Common Values: 4, 8, 12, 16, 24, 32, 48, 64, 96, 128

Component Patterns

• Buttons: Filled, Outlined, Text, Elevated, Tonal
• Cards: Elevated, Filled, Outlined
• Navigation: Rail, Bar, Drawer
• Inputs: Filled, Outlined
• Dialogs: Basic, Full-screen, Date picker

Review Checklist

• [ ] Dynamic color theming applied correctly
• [ ] Type scale follows M3 specs
• [ ] 4dp baseline grid followed
• [ ] Touch targets minimum 48dp
• [ ] Elevation levels correct (0-5)
• [ ] Shape scale appropriate (Extra small to Extra large)

---

Apple Human Interface Guidelines (iOS/macOS)

Reference ID: apple-hig Official URL: https://developer.apple.com/design/human-interface-guidelines/

Design Principles

1. Clarity - Text readable, icons precise, ornaments subtle
2. Deference - Content over chrome, minimal UI
3. Depth - Visual layers, motion conveys hierarchy

Color System

System Colors: | Color | Light Mode | Dark Mode | Usage | |-------|------------|-----------|-------| | Blue | #007AFF | #0A84FF | Links, interactive elements | | Green | #34C759 | #30D158 | Success, positive actions | | Indigo | #5856D6 | #5E5CE6 | Accent | | Orange | #FF9500 | #FF9F0A | Warnings, attention | | Pink | #FF2D55 | #FF375F | Accent | | Purple | #AF52DE | #BF5AF2 | Accent | | Red | #FF3B30 | #FF453A | Destructive, errors | | Teal | #5AC8FA | #64D2FF | Accent | | Yellow | #FFCC00 | #FFD60A | Warnings |

Semantic Colors:

• Label (Primary, Secondary, Tertiary, Quaternary)
• Fill (Primary through Quaternary)
• Background (Primary, Secondary, Tertiary)
• Separator

Typography

SF Pro (San Francisco): | Style | Size | Weight | Leading | |-------|------|--------|---------| | Large Title | 34pt | Bold | 41pt | | Title 1 | 28pt | Regular | 34pt | | Title 2 | 22pt | Regular | 28pt | | Title 3 | 20pt | Regular | 25pt | | Headline | 17pt | Semi-Bold | 22pt | | Body | 17pt | Regular | 22pt | | Callout | 16pt | Regular | 21pt | | Subheadline | 15pt | Regular | 20pt | | Footnote | 13pt | Regular | 18pt | | Caption 1 | 12pt | Regular | 16pt | | Caption 2 | 11pt | Regular | 13pt |

Spacing

iOS Standard Margins: 16pt (compact), 20pt (regular) macOS Standard Margins: 20pt

Component Patterns

• Navigation: Tab Bar, Sidebar, Navigation Bar
• Buttons: System, Custom, Icon-only
• Lists: Plain, Grouped, Inset Grouped
• Forms: Grouped sections with headers

Review Checklist

• [ ] SF Pro or SF Mono fonts used
• [ ] System colors or semantically appropriate custom colors
• [ ] Touch targets minimum 44pt x 44pt
• [ ] Standard margins respected
• [ ] Navigation patterns match platform conventions
• [ ] Dark mode support with proper semantic colors

---

Tailwind UI

Reference ID: tailwind-ui Official URL: https://tailwindui.com/

Design Principles

1. Utility-First - Compose styles from atomic classes
2. Responsive - Mobile-first, breakpoint prefixes
3. Consistent - Design tokens as class names

Color System

Tailwind Colors (50-950 shades):

• Slate, Gray, Zinc, Neutral, Stone (Grays)
• Red, Orange, Amber, Yellow (Warm)
• Lime, Green, Emerald, Teal (Cool greens)
• Cyan, Sky, Blue, Indigo, Violet, Purple, Fuchsia, Pink, Rose

Usage Patterns:

• Primary: blue-600 (buttons, links)
• Secondary: gray-600 (secondary text)
• Success: green-600
• Warning: amber-600
• Error: red-600
• Background: white / gray-50
• Surface: gray-100 / gray-800

Typography

Font Scale: | Class | Size | Line Height | |-------|------|-------------| | text-xs | 12px | 16px | | text-sm | 14px | 20px | | text-base | 16px | 24px | | text-lg | 18px | 28px | | text-xl | 20px | 28px | | text-2xl | 24px | 32px | | text-3xl | 30px | 36px | | text-4xl | 36px | 40px | | text-5xl | 48px | 48px | | text-6xl | 60px | 60px | | text-7xl | 72px | 72px | | text-8xl | 96px | 96px | | text-9xl | 128px | 128px |

Font Weights: thin(100) to black(900)

Spacing Scale

| Class | Value | |-------|-------| | 0 | 0px | | px | 1px | | 0.5 | 2px | | 1 | 4px | | 2 | 8px | | 3 | 12px | | 4 | 16px | | 5 | 20px | | 6 | 24px | | 8 | 32px | | 10 | 40px | | 12 | 48px | | 16 | 64px | | 20 | 80px | | 24 | 96px |

Component Patterns

• Buttons: Primary, Secondary, Soft, Outline
• Forms: Stacked, Inline, with validation states
• Cards: Simple, with header, with footer
• Navigation: Navbar, Sidebar, Tabs

Review Checklist

• [ ] Spacing uses Tailwind scale (4px base)
• [ ] Typography uses Tailwind type scale
• [ ] Colors from Tailwind palette
• [ ] Consistent hover/focus states
• [ ] Responsive breakpoints (sm, md, lg, xl, 2xl)
• [ ] Dark mode with dark: variants

---

Ant Design

Reference ID: ant-design Official URL: https://ant.design/

Design Principles

1. Natural - Align with user mental models
2. Certain - Predictable, consistent behavior
3. Meaningful - Purpose-driven design
4. Growing - Support user skill progression

Color System

Functional Colors: | Role | Hex | Usage | |------|-----|-------| | Primary | #1677ff | Brand, primary actions | | Success | #52c41a | Positive feedback | | Warning | #faad14 | Warnings, attention | | Error | #ff4d4f | Errors, destructive | | Info | #1677ff | Informational |

Neutral Colors: 13 shades of gray (#fff to #000)

Typography

Font Family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue

| Role | Size | Weight | |------|------|--------| | h1 | 38px | 600 | | h2 | 30px | 600 | | h3 | 24px | 600 | | h4 | 20px | 600 | | h5 | 16px | 600 | | Base | 14px | 400 | | Small | 12px | 400 |

Spacing

Base Unit: 4px Scale: 4, 8, 12, 16, 20, 24, 32, 40, 48

Component Patterns

• Forms: Horizontal, Vertical, Inline layouts
• Tables: Sortable, Filterable, Paginated
• Modals: Confirm, Info, with footer
• Data Entry: Extensive input types

Review Checklist

• [ ] 14px base font size
• [ ] 4px spacing base unit
• [ ] Functional colors for feedback
• [ ] Form layouts consistent
• [ ] Table patterns for data display
• [ ] Enterprise-grade density (compact option)

---

Shadcn/ui

Reference ID: shadcn-ui Official URL: https://ui.shadcn.com/

Design Principles

1. Copy-Paste - Components you own, not import
2. Accessible - Built on Radix UI primitives
3. Customizable - CSS variables for theming
4. Composable - Small, focused components

Color System

CSS Variables Based:

--background: 0 0% 100%;
--foreground: 240 10% 3.9%;
--card: 0 0% 100%;
--card-foreground: 240 10% 3.9%;
--popover: 0 0% 100%;
--popover-foreground: 240 10% 3.9%;
--primary: 240 5.9% 10%;
--primary-foreground: 0 0% 98%;
--secondary: 240 4.8% 95.9%;
--secondary-foreground: 240 5.9% 10%;
--muted: 240 4.8% 95.9%;
--muted-foreground: 240 3.8% 46.1%;
--accent: 240 4.8% 95.9%;
--accent-foreground: 240 5.9% 10%;
--destructive: 0 84.2% 60.2%;
--destructive-foreground: 0 0% 98%;
--border: 240 5.9% 90%;
--input: 240 5.9% 90%;
--ring: 240 5.9% 10%;
--radius: 0.5rem;

Typography

Inter (default) or system font stack

| Variant | Size | Weight | Leading | |---------|------|--------|---------| | h1 | 36px | 800 | 40px | | h2 | 30px | 600 | 36px | | h3 | 24px | 600 | 32px | | h4 | 20px | 600 | 28px | | p | 16px | 400 | 28px | | lead | 20px | 400 | 28px | | large | 18px | 600 | 28px | | small | 14px | 500 | 20px | | muted | 14px | 400 | 20px |

Spacing

Tailwind-based: 4px base (matches Tailwind scale)

Component Patterns

• Buttons: Default, Secondary, Destructive, Outline, Ghost, Link
• Forms: Built on Radix primitives
• Dialogs: AlertDialog, Dialog, Sheet
• Data Display: Table, DataTable, Cards

Review Checklist

• [ ] CSS variables for theming
• [ ] Radix UI primitives for accessibility
• [ ] Border radius using --radius variable
• [ ] Focus rings using --ring variable
• [ ] Consistent variant naming
• [ ] Dark mode via class strategy

---

Usage in Reviews

Selecting a Design Reference

The ui agent will check for style in this order:

1. Project Style (.claude/design-style.md) - Highest priority
2. Predefined Reference (via Design Reference: directive or user selection)
3. Auto-detect (if recognizable patterns found)
4. Generic Best Practices (fallback)

Review with Specific Reference

Task: ui

Review this dashboard screenshot against Material Design 3 guidelines.

Design Reference: material-3

Image: screenshots/dashboard.png

Write review to: ${SESSION_PATH}/reviews/design-review/gemini.md

Combining Project Style + Reference

Task: ui

Review using:
- Project Style: .claude/design-style.md (brand colors, custom tokens)
- Base Reference: shadcn-ui (component patterns, accessibility)

Image: screenshots/form.png