| name | design-references |
| description | Provides design system references — Material 3, Apple HIG, Tailwind UI, Ant Design, Shadcn/ui. Use when reviewing UI against an established design system. |
| user-invocable | false |
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
- Adaptive & Accessible - Responsive across devices, accessible to all
- Personal & Customizable - Dynamic color, personalization
- 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
Apple Human Interface Guidelines (iOS/macOS)
Reference ID: apple-hig
Official URL: https://developer.apple.com/design/human-interface-guidelines/
Design Principles
- Clarity - Text readable, icons precise, ornaments subtle
- Deference - Content over chrome, minimal UI
- 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
Tailwind UI
Reference ID: tailwind-ui
Official URL: https://tailwindui.com/
Design Principles
- Utility-First - Compose styles from atomic classes
- Responsive - Mobile-first, breakpoint prefixes
- 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
Ant Design
Reference ID: ant-design
Official URL: https://ant.design/
Design Principles
- Natural - Align with user mental models
- Certain - Predictable, consistent behavior
- Meaningful - Purpose-driven design
- 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
Shadcn/ui
Reference ID: shadcn-ui
Official URL: https://ui.shadcn.com/
Design Principles
- Copy-Paste - Components you own, not import
- Accessible - Built on Radix UI primitives
- Customizable - CSS variables for theming
- 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% ;
: ;
: ;
: ;
: ;
: ;
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
Usage in Reviews
Selecting a Design Reference
The ui agent will check for style in this order:
- Project Style (
.claude/design-style.md) - Highest priority
- Predefined Reference (via
Design Reference: directive or user selection)
- Auto-detect (if recognizable patterns found)
- 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
