ui-design

# UI Design Fundamentals

The definitive guide for building production-grade web interfaces. Covers the full stack of design decisions from layout to motion.

## WHEN To Use

- Designing new UI components or pages
- Building landing pages, dashboards, or applications
- Reviewing code for design quality
- Creating distinctive interfaces that avoid generic aesthetics
- Implementing accessibility requirements

## KEYWORDS

ui design, web design, layout, typography, color palette, spacing, visual hierarchy, responsive design, accessibility, motion design, component design, design tokens, frontend, css, tailwind


## Installation

### OpenClaw / Moltbot / Clawbot

```bash
npx clawhub@latest install ui-design
```


---

## Design Philosophy

### The 80/20 of Design Quality

| Factor | Impact | Time Investment |
|--------|--------|-----------------|
| **Typography** | 40% | Choose 1-2 fonts well |
| **Spacing** | 25% | Use consistent scale |
| **Color** | 20% | Limit palette, ensure contrast |
| **Everything else** | 15% | Shadows, borders, motion |

Focus on typography and spacing first. They're 65% of perceived quality.

### Commit to a Direction

Mediocrity is forgettable. Pick an extreme:

| Direction | Characteristics | Use When |
|-----------|-----------------|----------|
| **Brutally Minimal** | Stark, essential, nothing extra | Developer tools, productivity |
| **Luxury/Refined** | Premium, subtle elegance | High-end products, fashion |
| **Playful** | Fun, bright, approachable | Consumer apps, games |
| **Editorial** | Type-forward, grid-based | Content sites, magazines |
| **Industrial** | Function-forward, robust | B2B, enterprise |

---

## Layout

### Grid vs Flexbox Decision

| Layout Need | Tool | Why |
|-------------|------|-----|
| Page-level structure | CSS Grid (`grid-template-areas`) | Named regions, explicit control |
| Navigation bars | Flexbox | Single-axis, `gap` spacing |
| Card grids | Grid (`auto-fill`/`auto-fit`) | Responsive without media queries |
| Centering | Grid (`place-items: center`) | Shortest, most reliable |
| Sidebar + content | Grid (`250px 1fr`) | Fixed + fluid |
| Stacking/overlaps | Grid + `grid-area: 1/1` | No `position: absolute` needed |

### Container Strategy

```css
/* Standard content width */
.container {
  width: 100%;
  max-width: 1280px;
  margin-inline: auto;
  padding-inline: clamp(1rem, 5vw, 3rem);
}

/* Full-bleed with contained content */
.full-bleed {
  width: 100vw;
  margin-left: calc(50% - 50vw);
}
```

### Common Layout Mistakes

| Mistake | Problem | Fix |
|---------|---------|-----|
| Mixing container widths | Inconsistent alignment | Use single `max-w-*` value |
| Content behind fixed navbar | Hidden content | Add `pt-[navbar-height]` |
| No mobile padding | Edge-to-edge text | Add `px-4` minimum |
| Centered everything | Weak hierarchy | Left-align body text |

---

## Typography

Typography carries 90% of a design's personality.

### Font Pairing by Context

| Context | Display Font | Body Font | Example |
|---------|--------------|-----------|---------|
| Editorial | High-contrast serif | Neutral humanist | Playfair + Source Sans |
| SaaS | Geometric sans | Matching sans | DM Sans + DM Mono |
| Luxury | Thin modern serif | Elegant sans | Cormorant + Jost |
| Developer | Monospace display | Monospace body | JetBrains Mono + IBM Plex |
| Playful | Rounded/quirky | Clean readable | Nunito + Outfit |

### Type Scale (1.25 ratio)

```css
--text-xs: 0.64rem;   /* 10px - captions */
--text-sm: 0.8rem;    /* 13px - secondary */
--text-base: 1rem;    /* 16px - body */
--text-lg: 1.25rem;   /* 20px - lead */
--text-xl: 1.563rem;  /* 25px - h4 */
--text-2xl: 1.953rem; /* 31px - h3 */
--text-3xl: 2.441rem; /* 39px - h2 */
--text-4xl: 3.052rem; /* 49px - h1 */
```

### Typography Rules

| Rule | Value | Why |
|------|-------|-----|
| Minimum body size | 16px | Below is hard to read |
| Body line-height | 1.5-1.75 | Improves readability |
| Heading line-height | 1.1-1.2 | Tighter for large text |
| Line length | 60-75 characters | Optimal reading |
| Paragraph spacing | 1.5em | Clear separation |

### Typography Mistakes

| Mistake | Problem | Fix |
|---------|---------|-----|
| System fonts only | Generic look | Use Google Fonts or variable fonts |
| Too many fonts | Visual chaos | Max 2 families |
| Weak weight contrast | Poor hierarchy | Bold headings (600+), regular body |
| Long lines | Hard to read | Add `max-w-prose` (65ch) |

---

## Color

### Building a Palette

Every palette needs five functional roles:

| Role | Purpose | Usage |
|------|---------|-------|
| **Primary** | Brand identity | Buttons, links, active states |
| **Neutral** | Text, backgrounds | Body text, cards, dividers |
| **Accent** | Secondary actions | Tags, badges, highlights |
| **Semantic** | Feedback | Success/warning/error states |
| **Surface** | Layered backgrounds | Cards, modals, overlays |

### Surface Layering (Dark Mode)

Create depth through lightness, not shadows:

```css
:root {
  --surface-0: hsl(220 15% 8%);   /* page background */
  --surface-1: hsl(220 15% 12%);  /* card */
  --surface-2: hsl(220 15% 16%);  /* raised element */
  --surface-3: hsl(220 15% 20%);  /* popover/modal */
}
```

### Contrast Requirements (WCAG)

| Text Size | Minimum Ratio | Enhanced (AAA) |
|-----------|---------------|----------------|
| Normal text (<18px) | 4.5:1 | 7:1 |
| Large text (≥18px bold, ≥24px) | 3:1 | 4.5:1 |
| UI components | 3:1 | — |

### Color Mistakes

| Mistake | Problem | Fix |
|---------|---------|-----|
| Purple gradient on white | "AI aesthetic" cliché | Use intentional brand colors |
| Low contrast text | Accessibility fail | Test with contrast checker |
| Color-only indicators | Colorblind users excluded | Add icons/text |
| Too many colors | Visual noise | 3-5 colors maximum |
| Light gray text on white | Unreadable | `slate-600` minimum |

---

## Spacing

### 8px Base Unit Scale

```css
--space-1: 0.25rem;  /* 4px - tight gaps */
--space-2: 0.5rem;   /* 8px - input padding */
--space-3: 0.75rem;  /* 12px - button padding */
--space-4: 1rem;     /* 16px - default spacing */
--space-6: 1.5rem;   /* 24px - section padding */
--space-8: 2rem;     /* 32px - section gaps */
--space-12: 3rem;    /* 48px - major breaks */
--space-16: 4rem;    /* 64px - page rhythm */
```

### Spacing Rules

| Rule | Implementation |
|------|----------------|
| Use `gap` not margins | `display: flex; gap: var(--space-4)` |
| Consistent padding | Same values on all cards/sections |
| More space between groups | Less space within groups (Gestalt) |
| No arbitrary values | Only use scale tokens |

### Spacing Mistakes

| Mistake | Problem | Fix |
|---------|---------|-----|
| Arbitrary pixel values | Inconsistent rhythm | Use spacing scale only |
| Margin on children | Margin collapse bugs | Use `gap` on parent |
| Equal spacing everywhere | No visual grouping | More between, less within |
| Tight mobile padding | Cramped feeling | Minimum `p-4` on mobile |

---

## Visual Hierarchy

Guide the eye through deliberate contrast.

### Hierarchy Techniques

| Technique | How | Impact |
|-----------|-----|--------|
| **Size** | Hero 3-4x body | Immediate focal point |
| **Weight** | Bold headings, regular body | Scannability |
| **Color** | Primary vs muted | Information layers |
| **Space** | Isolation creates emphasis | Draws attention |
| **Position** | Top-left anchors reading | Natural flow |

### Card Hierarchy Pattern

```
Eyebrow  ← xs, uppercase, muted color
Title    ← xl, semibold, primary color
Body     ← base, secondary color, 1.6 line-height
Action   ← spaced apart, mt-4 minimum
```

---

## Responsive Design

### Breakpoint Strategy

| Breakpoint | Target | Key Changes |
|------------|--------|-------------|
| < 640px | Mobile | Single column, stacked nav, 44px touch targets |
| 640-1024px | Tablet | Two columns, collapsible sidebars |
| 1024-1440px | Desktop | Full layout, hover enabled |
| > 1440px | Wide | Max-width container, prevent ultra-wide lines |

### Fluid Techniques

```css
/* Fluid typography */
h1 { font-size: clamp(2rem, 1.5rem + 2.5vw, 3.5rem); }

/* Fluid spacing */
section { padding-block: clamp(2rem, 1rem + 4vw, 6rem); }

/* Intrinsic grid */
.grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(100%, 20rem), 1fr));
  gap: var(--space-6);
}
```

### Responsive Mistakes

| Mistake | Problem | Fix |
|---------|---------|-----|
| No viewport meta | Broken mobile | Add `width=device-width` |
| Fixed widths | Overflow on mobile | Use `max-w-*` and `%` |
| Tiny touch targets | Frustrating taps | Minimum 44x44px |
| Hidden horizontal scroll | Broken layout | Test at 375px width |

---

## Accessibility

Accessibility is not optional.

### Critical Requirements

| Requirement | Implementation | Standard |
|-------------|----------------|----------|
| Color contrast | 4.5:1 normal, 3:1 large | WCAG 2.1 AA |
| Keyboard navigation | Tab order matches visual | WCAG 2.1.1 |
| Focus indicators | Visible `:focus-visible` ring | WCAG 2.4.7 |
| Semantic HTML | `<button>`, `<nav>`, `<main>` | WCAG 1.3.1 |
| Alt text | Descriptive for images | WCAG 1.1.1 |
| Motion safety | `prefers-reduced-motion` | WCAG 2.3.3 |
| Touch targets | 44×44px minimum | WCAG 2.5.8 |

### Focus Styles

```css
:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
}

/* Remove default only if custom exists */
:focus:not(:focus-visible) {
  outline: none;
}
```

### Motion Safety

```css
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}
```

---

## Motion & Animation

Use motion to communicate, not decorate.

### Timing Guidelines

| Interaction | Duration | Easing |
|-------------|----------|--------|
| Button hover | 150ms | ease-out |
| Modal open | 250ms | ease-out |
| Modal close | 200ms | ease-in |
| Page transition | 300ms | ease-in-out |
| Stagger delay | 50-80ms per item | — |
| Micro-feedback | 100ms | ease-out |

### Staggered Entrance

```css
.item {
  opacity: 0;
  translate: 0 1rem;
  animation: reveal 0.5s ease-out forwards;
}
.item:nth-child(1) { animation-delay: 0ms; }
.item:nth-child(2) { animation-delay: 60ms; }
.item:nth-child(3) { animation-delay: 120ms; }

@keyframes reveal {
  to { opacity: 1; translate: 0 0; }
}
```

### Motion Mistakes

| Mistake | Problem | Fix |
|---------|---------|-----|
| Animating width/height | Performance hit | Use `transform` only |
| > 500ms duration | Feels sluggish | 150-300ms for most |
| Motion everywhere | Overwhelming | Focus on entrances/exits |
| No reduced-motion | Accessibility fail | Always check preference |

---

## Component States

Every interactive element needs clear states.

| State | Visual Treatment |
|-------|------------------|
| **Default** | Base styling |
| **Hover** | Subtle background/shadow shift |
| **Active/Pressed** | Slight inset, reduced shadow |
| **Focus** | High-visibility ring |
| **Disabled** | 50% opacity, `not-allowed` cursor |
| **Loading** | Spinner or skeleton |

### Button Example

```css
.btn {
  transition: all 150ms ease-out;
}
.btn:hover {
  background: var(--color-primary-600);
}
.btn:active {
  transform: scale(0.98);
}
.btn:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
}
.btn:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}
```

---

## Design Tokens Architecture

Structure tokens in three layers:

```css
/* Layer 1: Primitives */
--blue-500: oklch(0.55 0.2 250);
--gray-100: oklch(0.95 0.005 250);
--radius-md: 0.5rem;

/* Layer 2: Semantic */
--color-primary: var(--blue-500);
--color-surface: var(--gray-100);
--radius-button: var(--radius-md);

/* Layer 3: Component */
--btn-bg: var(--color-primary);
--btn-radius: var(--radius-button);
--btn-padding: var(--space-2) var(--space-4);
```

This allows theme switching by remapping Layer 2 only.

---

## Pre-Delivery Checklist

### Typography
- [ ] Intentional font pairing (not system defaults)
- [ ] Consistent type scale
- [ ] Line length ≤ 75 characters
- [ ] 16px minimum body text

### Color
- [ ] Cohesive palette (3-5 colors)
- [ ] WCAG contrast met (4.5:1 normal, 3:1 large)
- [ ] Semantic colors defined
- [ ] Dark mode tested (if applicable)

### Spacing
- [ ] Consistent rhythm using scale
- [ ] No arbitrary pixel values
- [ ] Proper mobile padding

### Hierarchy
- [ ] Clear visual flow
- [ ] Primary action obvious
- [ ] Information layered by importance

### Responsive
- [ ] Mobile tested (375px)
- [ ] No horizontal overflow
- [ ] Touch targets ≥ 44px

### Accessibility
- [ ] Keyboard navigable
- [ ] Focus visible
- [ ] Screen reader tested
- [ ] Motion-safe

### States
- [ ] Hover on all interactive elements
- [ ] Focus-visible on all focusable
- [ ] Loading states for async
- [ ] Error states for forms

### Performance
- [ ] Images optimized (WebP, srcset)
- [ ] Fonts subset
- [ ] Animations use `transform`/`opacity`

---

## NEVER Do

1. **NEVER skip contrast checking** — Test every text/background combination
2. **NEVER use color alone** — Always pair with icons/text for meaning
3. **NEVER remove focus outlines** — Unless replacing with visible alternative
4. **NEVER use arbitrary spacing** — Stick to the scale
5. **NEVER animate layout properties** — Only `transform` and `opacity`
6. **NEVER ignore reduced-motion** — Always check the preference
7. **NEVER center everything** — Left-align body text
8. **NEVER use tiny touch targets** — 44px minimum
9. **NEVER use low-contrast text** — `slate-600` minimum on white
10. **NEVER use generic system fonts** — Choose intentional typography

---

## Related Skills

- `ui-ux-pro-max` — Searchable design databases with CLI
- `frontend-design` — Creative aesthetics, avoiding "AI slop"
- `theme-factory` — Applying themes to artifacts
- `design-system-patterns` — Token architecture and theming