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 | 1