ui-design

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]