web-design

What this skill does

# Web Design

A practitioner-sourced reference for building web interfaces well. Synthesized from Refactoring UI, Tailwind CSS, shadcn/ui, Laws of UX, animations.dev, detail.design, Every Layout, Web Interface Guidelines, jakub.kr, userinterface.wiki (Raphael Salaja), and other authoritative sources.

Use this skill whenever you are building, reviewing, or improving a web interface.

## Implementation Priority

When building or reviewing a UI, work through these tiers in order. Each tier depends on the ones above it — fixing a shadow detail is wasted effort if the layout is broken.

### Tier 1: Structure (get this right first)

1. **Semantic HTML.** Correct elements (`<button>`, `<nav>`, `<main>`, headings in order). Everything else builds on this.
2. **Layout.** Grid/flex structure, spacing scale, content width constraints (`max-w-prose`, 12-col grid). Does the page hold together at every viewport?
3. **Responsive behavior.** Mobile-first, intrinsic sizing (`auto-fill` grids, `clamp()`, `flex-wrap`). No content hidden on small screens without reason.
4. **Typography fundamentals.** Type scale, line height (1.5 body, 1.1-1.25 headings), line length (`max-width: 65ch`), `rem` units for font sizes.

### Tier 2: Visual System (the design backbone)

5. **Color and contrast.** Palette applied, semantic tokens set, WCAG AA contrast met (4.5:1 text, 3:1 UI). Dark mode if needed.
6. **Visual hierarchy.** Four text levels working (foreground, muted, muted/70, muted/50). Primary action obvious. Squint test passes.
7. **Component states.** Every interactive element has hover, focus-visible, active, disabled, loading, error, and empty states accounted for.
8. **Spacing and proportion.** Outer padding >= inner padding. No ambiguous gaps. Button padding ratio (2x horizontal : 1x vertical). Input heights match button heights.

### Tier 3: Interaction and Motion (make it feel alive)

9. **Keyboard and accessibility.** Focus styles, tab order, skip links, `aria` attributes, touch targets (44px+). Test with keyboard only.
10. **Transitions.** Hover/active feedback (150ms ease-out), state transitions (200-300ms), correct easing per direction (ease-out for enter, ease-in for exit).
11. **Animation.** Stagger entrances, subtle exits, interruptible transitions, `prefers-reduced-motion` respected. Spring physics where appropriate.

### Tier 4: Polish (the last 10% that makes it feel crafted)

12. **Shadows and depth.** Layered shadows, shadows-instead-of-borders where appropriate, consistent light source. Dark mode: surface lightness instead of shadows.
13. **Optical adjustments.** Icon-side button padding, concentric border radii, play button offset, tabular-nums on data, image outlines.
14. **Micro-interactions.** Contextual icon animation, blur on stagger entrances, copy-to-clipboard feedback, optimistic updates.
15. **Defensive CSS.** `min-width: 0` on flex children, `overflow-wrap: break-word`, `scrollbar-gutter: stable`, text truncation, safe-area padding.
16. **Final checks.** Squint test, grayscale test, swap test, "would a human ship this?" test. No AI slop (gratuitous gradients, identical metric cards, centered everything).

**Rule of thumb:** If you're debating a shadow opacity while the layout breaks at 768px, stop and go back to Tier 1.

## Table of Contents

1. [Layout and Spacing](#1-layout-and-spacing)
2. [Typography](#2-typography)
3. [Color](#3-color)
4. [Shadows and Depth](#4-shadows-and-depth)
5. [Visual Hierarchy](#5-visual-hierarchy)
6. [Animation and Motion](#6-animation-and-motion)
7. [Components](#7-components)
8. [Responsive Design](#8-responsive-design)
9. [Accessibility](#9-accessibility)
10. [Performance](#10-performance)
11. [UX Psychology](#11-ux-psychology)
12. [Design Tokens](#12-design-tokens)
13. [Polish and Craft](#13-polish-and-craft)
14. [Microcopy and UX Writing](#14-microcopy-and-ux-writing)
15. [AI Slop Prevention](#15-ai-slop-prevention)
16. [Advanced Craft](#16-advanced-craft)
17. [Defensive CSS](#17-defensive-css)
18. [Modern CSS Reset](#18-modern-css-reset)
19. [Predictive Prefetching](#19-predictive-prefetching)
20. [Audio Feedback and Sound Design](#20-audio-feedback-and-sound-design)

---

## 1. Layout and Spacing

### Spacing Scale

Use a consistent mathematical scale rooted in a base unit. The standard base is **4px** (0.25rem). Every spacing value should be a multiple of this base.

| Token | Value | Use |
|-------|-------|-----|
| 0.5 | 2px | Hairline gaps, icon padding |
| 1 | 4px | Tight inline spacing |
| 1.5 | 6px | Small component internal padding |
| 2 | 8px | Default gap between related items |
| 3 | 12px | Compact card padding |
| 4 | 16px | Standard card/section padding |
| 5 | 20px | Comfortable padding |
| 6 | 24px | Section padding |
| 8 | 32px | Section gaps |
| 10 | 40px | Large section gaps |
| 12 | 48px | Page section spacing |
| 16 | 64px | Major page divisions |
| 20 | 80px | Hero spacing |
| 24 | 96px | Large hero spacing |

### Spacing Rules

- **Outer padding >= inner padding.** A card's outer margin must equal or exceed its internal padding. Interior elements relate more closely to each other than to external elements.
- **Proximity signals relationship.** Elements closer together are perceived as related (Gestalt Law of Proximity). Use spacing deliberately to group or separate.
- **Eliminate ambiguous spacing.** If the gap between two elements could belong to either, it's ambiguous. Make relationships clear through asymmetric spacing.
- **Eliminate dead zones.** Use padding on child elements instead of margins on containers. Every pixel between interactive items should be clickable.
- **Use consistent increments.** Don't pick arbitrary values. Constrain to the scale. Three similar spacings (14px, 16px, 18px) look like mistakes -- pick one.

### Layout Primitives

These CSS patterns create responsive layouts without media queries:

**Stack** -- Vertical flow with consistent gaps:
```css
.stack > * + * { margin-block-start: var(--space); }
```

**Cluster** -- Horizontal wrapping with gaps:
```css
.cluster { display: flex; flex-wrap: wrap; gap: var(--space); }
```

**Sidebar** -- Two columns where one is fixed:
```css
.sidebar { display: flex; flex-wrap: wrap; gap: var(--space); }
.sidebar > :first-child { flex-basis: 20rem; flex-grow: 1; }
.sidebar > :last-child { flex-basis: 0; flex-grow: 999; min-inline-size: 60%; }
```

**Grid (auto-fill)** -- Responsive columns without breakpoints:
```css
.grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 250px), 1fr)); gap: var(--space); }
```

**Center** -- Constrained width with centering:
```css
.center { max-inline-size: var(--measure); margin-inline: auto; padding-inline: var(--space); }
```

### Grid and Flex Guidance

- Use **CSS Grid** for two-dimensional layouts (rows and columns together).
- Use **Flexbox** for one-dimensional layouts (single row or column).
- Prefer `fr` units over percentages in Grid -- `fr` distributes space after gaps, preventing overflow.
- Use `gap` instead of margins between items.
- A **12-column grid** provides maximum flexibility (divisible by 1, 2, 3, 4, 6).
- Set `min-width: 0` on flex children to prevent content overflow.
- Use `align-self: start` on sticky sidebar elements inside grid layouts.

### In Practice: Tailwind Layout Patterns

**Page shell with sidebar:**
```tsx
<div className="flex min-h-screen">
  <aside className="hidden lg:flex w-64 flex-col border-r bg-muted/40 p-4">
    <nav className="flex flex-col gap-1">{/* nav items */}</nav>
  </aside>
  <main className="flex-1 p-6">
    <div className="mx-auto max-w-4xl space-y-8">{children}</div>
  </main>
</div>
```

**Card grid that adapts without breakpoints:**
```tsx
<div className="grid grid-cols-[repeat(auto-fill,minmax(min(100%,280px),1fr))] gap-4">
  {items.map(item => <Card key={item.id} {...item} />)}
</div>
```

**Content section with consistent vertical rhythm:**
```tsx
<section className="space-y-6 py-12">
  <h2 className