ui-design

name	ui-design
description	This skill should be used when the user asks to "design a component", "pick colors", "improve typography", "fix spacing", "choose a layout", or discusses visual design, CSS, styling decisions, or responsive interfaces. Provides patterns for typography scales, color systems, spacing, and production-grade UI design.
user-invocable	false
allowed-tools	Read, Grep, Glob
activation	{"file-patterns":["**/*.tsx","**/*.jsx","**/*.css","**/*.scss","**/tailwind.config.*"],"exclude":["node_modules/**","**/*.test.*","**/*.spec.*"]}

UI Design Patterns

Reference for intentional visual design. Every choice must be justified. Sources in references/sources.md.

Iron Law

AESTHETICS MUST HAVE INTENT [4][11]

Every visual choice must be justified. Default styles, copied gradients, and "looks modern" are not justifications. If you cannot explain why a specific font, color, or animation exists, it's design debt. Good design is invisible because it serves purpose — it satisfies mental models, not trends. — Don Norman, The Design of Everyday Things [11]; Laws of UX [4]

When This Skill Activates

• Creating/styling UI components; reviewing CSS, Tailwind, or styled-components
• Discussing typography, color schemes, layouts, or design systems

---

1. Typography [6][7][10][19]

Font choice must match product personality: developer tools → monospace (precision), documentation → serif (readability), marketing → distinctive display. [6][7][27]

Use a mathematical type scale (1.25 major third ratio). All sizes relate harmonically. [10] Line length: 45–75 characters for body text; line-height: 1.7 for prose, 1.2 for headings. [6][7]

Heading levels must differ in weight, tracking, and size — not size alone. [7][15] See references/patterns.md for scale values, font pairs, and heading styles.

---

2. Color System [1][9][12][14]

Three-layer token architecture (Material Design 3 [1] + W3C Design Tokens spec [9]):

:root {
  --blue-600: #2563eb;                      /* Layer 1: Primitive */
  --color-primary: var(--blue-600);         /* Layer 2: Semantic  */
  --button-primary-bg: var(--color-primary);/* Layer 3: Component */
}

Dark mode: swap semantic tokens only — never invert or filter. [23] Elevation in dark mode is expressed via lightness, not shadows. [1][12]

Contrast: 4.5:1 for normal text, 3:1 for large text and UI components. [14][26]

See references/patterns.md for dark surface hierarchy and accessible contrast examples.

---

3. Spacing [1][13][15]

4px/8px base grid — from Müller-Brockmann grid mathematics [13], adopted by Material Design [1]. All padding/margin values must come from the scale: --space-1 (4px) through --space-24 (96px).

Gestalt proximity: larger gaps between sections, smaller gaps within — whitespace creates grouping. [5]

Violation: padding: 18px 22px — magic number, off-grid. [15]

See references/patterns.md for full scale and component spacing hierarchy.

---

4. Motion [4][11][24]

Animation must communicate state, not decorate. Fitts's Law: every interaction needs tactile feedback. [4][11]

Define a timing system (--duration-fast: 100ms, --duration-normal: 200ms, --duration-slow: 300ms). [1] Never animate all — specify properties. Transitions over 500ms feel sluggish for UI. [4]

Required: @media (prefers-reduced-motion: reduce) — WCAG 2.2 and vestibular accessibility. [24][26]

---

5. Component Hierarchy [1][3][5][15]

Atomic Design [3]: atoms → molecules → organisms. Components reference tokens; organisms compose molecules.

Elevation table — radius and shadow signal interactivity, not decoration: [1][11][15]

Element	Radius	Shadow
Badge/tag	4px (--radius-sm)	none
Button/input	6px (--radius-md)	none
Card (static)	8px (--radius-lg)	shadow-sm
Dropdown	8px	shadow-lg
Modal	12px (--radius-xl)	shadow-xl

---

AI Slop Detection [4][11][15]

Pattern	Problem
Purple-to-pink gradient	No brand justification; copied template [15]
font-family: Inter without rationale	Default, not intentional [6]
Everything centered	No reading flow; violates hierarchy [30]
rounded-xl everywhere	Radius must vary by component scale [1][15]
Shadows on everything	Elevation loses meaning when ubiquitous [11]
animate-pulse on buttons	Hick's Law: noise slows decisions [4]
Glassmorphism everywhere	Trend, not purpose [15]

---

Extended References

• references/sources.md — Full bibliography (30 sources)
• references/patterns.md — Extended correct patterns with citations
• references/violations.md — Extended violation examples with citations
• references/detection.md — Grep patterns for finding issues

---

Checklist

• Typography scale is mathematical; font choice has documented rationale [6][10]
• Color system uses 3-layer tokens (primitives → semantic → component) [1][9]
• All text meets WCAG contrast minimums (4.5:1 / 3:1) [14][26]
• Dark mode designed intentionally — no invert filter [23]
• Spacing follows 4px/8px base grid — no magic numbers [1][13]
• Animations communicate state; prefers-reduced-motion respected [24]
• Component elevation (shadow, radius) signals interactivity level [1][11]
• No AI slop patterns present [4][15]
• Visual hierarchy via whitespace and spacing — not lines or boxes [5][30]