detections/.cursor/skills/ui-design/references/design-vocabulary.md

# Design Vocabulary

Use this reference when writing DESIGN.md files and constructing generation prompts. Replace vague descriptors with specific, actionable terms.

## Atmosphere Descriptors

Use these instead of "clean and modern":

| Atmosphere | Characteristics | Font Direction | Color Direction | Spacing |
|------------|----------------|---------------|-----------------|---------|
| **Airy & Spacious** | Generous whitespace, light backgrounds, floating elements, subtle shadows | Thin/light weights, generous letter-spacing | Soft pastels, whites, muted accents | Large margins, open padding |
| **Dense & Data-Rich** | Compact spacing, information-heavy, efficient use of space | Medium weights, tighter line-heights, smaller sizes | Neutral grays, high-contrast data colors | Tight but consistent padding |
| **Warm & Approachable** | Rounded corners, friendly illustrations, organic shapes | Rounded/humanist typefaces, comfortable sizes | Earth tones, warm neutrals, amber/coral accents | Medium spacing, generous touch targets |
| **Sharp & Technical** | Crisp edges, precise alignment, monospace elements, dark themes | Geometric or monospace, precise sizing | Cool grays, electric blues/greens, dark backgrounds | Grid-strict, mathematical spacing |
| **Luxurious & Premium** | Generous space, refined details, serif accents, subtle animations | Serif or elegant sans-serif, generous sizing | Deep darks, gold/champagne accents, rich jewel tones | Expansive whitespace, dramatic padding |
| **Playful & Creative** | Asymmetric layouts, bold colors, hand-drawn elements, motion | Display fonts, variable weights, expressive sizing | Bright saturated colors, unexpected combinations | Dynamic, deliberately uneven |
| **Corporate & Enterprise** | Structured grids, predictable patterns, dense but organized | System fonts or conservative sans-serif | Brand blues/grays, accent for status indicators | Systematic, spec-driven |
| **Editorial & Content** | Typography-forward, reading-focused, long-form layout | Serif for body text, sans for UI elements | Near-monochrome, sparse accent color | Generous line-height, wide columns |

## Style-Specific Vocabulary

### When user says... → Use these terms in DESIGN.md

| Vague Input | Professional Translation |
|-------------|------------------------|
| "clean" | Restrained palette, generous whitespace, consistent alignment grid |
| "modern" | Current design patterns (2024-2026), subtle depth, micro-interactions |
| "minimal" | Single accent color, maximum negative space, typography-driven hierarchy |
| "professional" | Structured grid, conservative palette, system fonts, clear navigation |
| "fun" | Saturated palette, rounded elements, playful illustrations, motion |
| "elegant" | Serif typography, muted palette, generous spacing, refined details |
| "techy" | Dark theme, monospace accents, neon highlights, sharp corners |
| "bold" | High contrast, large type, strong color blocks, dramatic layout |
| "friendly" | Rounded corners (12-16px), humanist fonts, warm colors, illustrations |
| "corporate" | Blue-gray palette, structured grid, conventional layout, data tables |

## Color Mood Palettes

### Cool Blues & Grays
- Background: #f8fafc → #f1f5f9
- Surface: #ffffff
- Text: #0f172a → #475569
- Accent: #2563eb (blue-600)
- Pairs well with: Airy, Sharp, Corporate atmospheres

### Warm Earth Tones
- Background: #faf8f5 → #f5f0eb
- Surface: #ffffff
- Text: #292524 → #78716c
- Accent: #c2410c (orange-700) or #b45309 (amber-700)
- Pairs well with: Warm, Editorial atmospheres

### Bold & Vibrant
- Background: #fafafa → #f5f5f5
- Surface: #ffffff
- Text: #171717 → #525252
- Accent: #dc2626 (red-600) or #7c3aed (violet-600) or #059669 (emerald-600)
- Pairs well with: Playful, Creative atmospheres

### Monochrome
- Background: #fafafa → #f5f5f5
- Surface: #ffffff
- Text: #171717 → #737373
- Accent: #171717 (black) with #e5e5e5 borders
- Pairs well with: Minimal, Luxurious, Editorial atmospheres

### Dark Mode
- Background: #09090b → #18181b
- Surface: #27272a → #3f3f46
- Text: #fafafa → #a1a1aa
- Accent: #3b82f6 (blue-500) or #22d3ee (cyan-400)
- Pairs well with: Sharp, Technical, Dense atmospheres

## Typography Mood Mapping

### Geometric (Modern, Clean)
Fonts: DM Sans, Plus Jakarta Sans, Outfit, General Sans, Satoshi
- Characteristics: even stroke weight, circular letter forms, precise geometry
- Best for: SaaS, tech products, dashboards, landing pages

### Humanist (Friendly, Readable)
Fonts: Source Sans 3, Nunito, Lato, Open Sans, Noto Sans
- Characteristics: organic curves, varying stroke, warm feel
- Best for: consumer apps, health/wellness, education, community platforms

### Monospace (Technical, Code-Like)
Fonts: JetBrains Mono, Fira Code, IBM Plex Mono, Space Mono
- Characteristics: fixed-width, technical aesthetic, raw precision
- Best for: developer tools, terminals, data displays, documentation

### Serif (Editorial, Premium)
Fonts: Playfair Display, Lora, Merriweather, Crimson Pro, Libre Baskerville
- Characteristics: traditional elegance, reading comfort, authority
- Best for: blogs, magazines, luxury brands, portfolio sites

### Display (Expressive, Bold)
Fonts: Cabinet Grotesk, Clash Display, Archivo Black, Space Grotesk
- Characteristics: high impact, personality-driven, attention-grabbing
- Best for: hero sections, headlines, creative portfolios, marketing pages
- Use for headings only; pair with a readable body font

## Shape & Depth Vocabulary

### Border Radius Scale
| Term | Value | Use for |
|------|-------|---------|
| Sharp | 0-2px | Technical, enterprise, data-heavy |
| Subtle | 4-6px | Professional, balanced |
| Rounded | 8-12px | Friendly, modern SaaS |
| Pill | 16-24px or full | Playful, badges, tags |
| Circle | 50% | Avatars, icon buttons |

### Shadow Scale
| Term | Value | Use for |
|------|-------|---------|
| None | none | Flat design, minimal |
| Whisper | 0 1px 2px rgba(0,0,0,0.05) | Subtle elevation, cards |
| Soft | 0 4px 6px rgba(0,0,0,0.07) | Standard cards, dropdowns |
| Medium | 0 10px 15px rgba(0,0,0,0.1) | Elevated elements, modals |
| Strong | 0 20px 25px rgba(0,0,0,0.15) | Floating elements, popovers |

### Surface Hierarchy
1. **Background** — deepest layer, covers viewport
2. **Surface** — content containers (cards, panels) sitting on background
3. **Elevated** — elements above surface (modals, dropdowns, tooltips)
4. **Overlay** — dimming layer between surface and elevated elements

## Layout Pattern Names

| Pattern | Description | Best for |
|---------|-------------|----------|
| **Holy grail** | Header + sidebar + main + footer | Admin dashboards, apps |
| **Magazine** | Multi-column with varied widths | Content sites, blogs |
| **Single column** | Centered narrow content | Landing pages, articles, forms |
| **Split screen** | Two equal or 60/40 halves | Comparison pages, sign-up flows |
| **Card grid** | Uniform grid of cards | Product listings, portfolios |
| **Asymmetric** | Deliberately unequal columns | Creative, editorial layouts |
| **Full bleed** | Edge-to-edge sections, no max-width | Marketing pages, portfolios |
| **Dashboard** | Stat cards + charts + tables in grid | Analytics, admin panels |