UX/UI design principles

Heuristics, laws, layout, type, states, forms, feedback, accessibility (WCAG 2.2 AA) and design tokens, as a checklist for building and reviewing interfaces. Palettes and contrast math live in Color theory; the CSS side is in CSS.

Usability heuristics

Jakob Nielsen's 10 heuristics (NN/g). Use them for heuristic evaluation: 3–5 reviewers each walk the UI alone, then merge findings and rate severity.

Severity scale: 0 not a problem, 1 cosmetic, 2 minor, 3 major (fix before release), 4 catastrophe.

Laws of UX

Gestalt & visual hierarchy

Gestalt principles

Hierarchy levers

Rank each screen's content (primary, secondary, tertiary), then use the fewest levers that make the ranking obvious. The squint test: blur the screen and check that the primary thing still wins.

Buttons follow the same rule: one solid primary, outline or tonal secondary, text-only tertiary. Destructive actions are only red when they are the primary action of that view.

<style>
  .card { max-width: 320px; padding: 16px;
    border: 1px solid var(--chip); border-radius: 8px; }
  .eyebrow { font-size: 12px; color: var(--muted);
    text-transform: uppercase; letter-spacing: 0.06em; }
  h3 { margin: 4px 0; font-size: 20px; font-weight: 700; }
  .body { margin: 0 0 12px; color: var(--muted); }
  .cta { font: inherit; font-weight: 600; border: 0;
    padding: 6px 12px; border-radius: 6px; color: white;
    background: oklch(0.55 0.2 260); }
</style>
<div class="card">
  <div class="eyebrow">Invoice 1042</div>
  <h3>€1,240 due Friday</h3>
  <p class="body">Paid by the card on file.</p>
  <button class="cta">Review invoice</button>
</div>

Size and weight make the amount primary, muted color demotes the eyebrow and body, and the only saturated element is the one action.

Layout, spacing & responsive

4/8 pt grid

Every size and space is a multiple of 4 px (fine steps) or 8 px (most layout). It keeps rhythm consistent and maps well to 1x/1.5x/2x/3x screens.

Start with too much whitespace and remove it. Internal spacing (padding) should be smaller than external spacing (margin to the next group), otherwise proximity lies.

:root {
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-3: 0.75rem;
  --space-4: 1rem;
  --space-6: 1.5rem;
  --space-8: 2rem;
  --space-12: 3rem;
  --space-16: 4rem;
}
 
.stack > * + * { margin-block-start: var(--space-4); }
.cluster {
  display: flex;
  flex-wrap: wrap;
  gap: var(--space-2);
}

Layout rules

Pick breakpoints where your content breaks, not per device. Tailwind's defaults match the table: see Tailwind.

Typography

Type scale

Multiply a base size (usually 16 px) by a ratio per step.

<style>
  :root { --r: 1.25; --s0: 16px;
    --s1: calc(var(--s0) * var(--r));
    --s2: calc(var(--s1) * var(--r));
    --s3: calc(var(--s2) * var(--r));
    --s4: calc(var(--s3) * var(--r)); }
  p { margin: 0 0 4px; line-height: 1.2; }
</style>
<p style="font-size: var(--s4)">Step 4 · 39 px</p>
<p style="font-size: var(--s3)">Step 3 · 31 px</p>
<p style="font-size: var(--s2)">Step 2 · 25 px</p>
<p style="font-size: var(--s1)">Step 1 · 20 px</p>
<p style="font-size: var(--s0)">Step 0 · 16 px body</p>

Use a tighter ratio on mobile and a larger one on desktop, or interpolate with clamp() (see Recipes). In practice, many systems hand-tune a fixed list (12, 14, 16, 18, 20, 24, 30, 36, 48).

Readability

Pairing

Limit to two families and three or four weights. Load variable fonts to get every weight in one file.

Components & states

State matrix

Every interactive component needs a design for each state that applies.

The five pointer and keyboard states side by side; the real :hover, :focus-visible and :active rules also work on the first button.

<style>
  .btn { font: inherit; padding: 6px 12px; border: 0;
    border-radius: 6px; color: white;
    background: oklch(0.55 0.2 260); }
  @media (hover: hover) {
    .btn:hover { background: oklch(0.49 0.2 260); } }
  .hover { background: oklch(0.49 0.2 260); }
  .btn:focus-visible, .focus {
    outline: 2px solid var(--fg); outline-offset: 2px; }
  .btn:active, .active {
    background: oklch(0.43 0.2 260); scale: 0.97; }
  .btn:disabled {
    background: oklch(0.55 0.05 260 / 45%);
    cursor: not-allowed; }
  .row { display: flex; gap: 10px; flex-wrap: wrap; }
</style>
<div class="row">
  <button class="btn">Default</button>
  <button class="btn hover">Hover</button>
  <button class="btn focus">Focus</button>
  <button class="btn active">Active</button>
  <button class="btn" disabled>Disabled</button>
</div>

Disabled controls are exempt from contrast rules but still need to be recognizable. Don't disable a submit button to signal invalid input: let the user press it and show what's missing.

Empty, error & onboarding states

Onboarding: prefer contextual hints and a short checklist (goal-gradient, Zeigarnik) over a multi-screen tour. Delay sign-up until the user has seen value, and let them skip and resume later.

Forms

Validation timing

Error messages

<label for="email">Email</label>
<p id="email-hint">We'll send the receipt here.</p>
<input id="email" type="email" autocomplete="email"
  required aria-describedby="email-hint email-error">
<p id="email-error" aria-live="polite"></p>

More on the DOM side in Forms.

Feedback & latency

Web targets (Core Web Vitals, 75th percentile): INP ≤ 200 ms, LCP ≤ 2.5 s, CLS ≤ 0.1.

Loading patterns

Other feedback rules: acknowledge every input within 100 ms (pressed state), confirm success unobtrusively (toast, inline tick), and prefer undo over confirmation dialogs for reversible actions. Data-fetching patterns in TanStack Query.

Navigation & IA

Rules: show "you are here" (aria-current="page"), keep the URL in sync with view state (filters, tabs, pagination) so Back and sharing work, label with the user's words (validate with card sorting and tree testing), and prefer broad-and-shallow over narrow-and-deep hierarchies.

UX writing

Write the empty state, error and success copy with the design, not after. Keep UI strings out of code so they can be translated; leave ~30% extra room for longer languages like German.

Accessibility & touch

WCAG 2.2 AA essentials

Also: one h1, logical heading levels, a skip link, lang on html, visible labels that match accessible names (2.5.3), and semantic HTML before ARIA. Automated tools (axe, Lighthouse) catch only part of the issues; test with a keyboard and a screen reader (VoiceOver, NVDA).

Text needs 4.5:1 (1.4.3); borders, icons and focus rings need 3:1 (1.4.11), the same bar as large text, so read the "large" grade for them:

Touch targets

Put primary mobile actions in the thumb zone (bottom half), avoid hover-only affordances, and use @media (pointer: coarse) to enlarge controls on touch devices.

Design systems, tokens & dark mode

Token tiers

Components use semantic tokens only. Themes swap the semantic layer; primitives stay the same.

tokens/├── primitives/│   ├── color.tokens.json  # blue.50 to blue.950, gray, red│   ├── space.tokens.json  # 4 px scale│   └── type.tokens.json   # families, sizes, weights├── semantic/│   ├── light.tokens.json  # aliases: bg, fg, border, accent│   └── dark.tokens.json├── components/│   └── button.tokens.json├── build.ts               # Style Dictionary / Terrazzo├── dist/│   ├── tokens.css         # generated custom properties│   └── tokens.ts          # generated typed constants└── package.json

Tokens use the W3C Design Tokens Community Group format (first stable version 2025.10): every token has a $value and optional $type, and {path.to.token} makes an alias.

{
  "color": {
    "bg": {
      "accent": {
        "$type": "color",
        "$value": "{color.blue.600}"
      }
    }
  }
}

export const space = {
  0: "0",
  1: "0.25rem",
  2: "0.5rem",
  3: "0.75rem",
  4: "1rem",
  6: "1.5rem",
  8: "2rem",
  12: "3rem",
  16: "4rem",
} as const;
 
export type Space = keyof typeof space;   // 0 | 1 | 2 | ...
 
export const pad = (n: Space) => `var(--space-${n})`;
pad(4);
// @ts-expect-error 5 is not on the scale
pad(5);

Dark mode considerations

Dark mode is a second semantic theme, not filter: invert(). Palette-building details in Color theory.

Research & testing

Metrics: task success rate, time on task, error rate, SUS (System Usability Scale; ~68 is average), and single ease question (SEQ). Five users per round finds most problems in one flow; run several small rounds rather than one big one.

Design review checklist

• One clear primary action per screen; hierarchy survives the squint test
• Spacing and sizes come from the scale; related items are closer than unrelated ones
• Type uses the scale, body text is at least 16 px, lines at most ~75 characters
• Every interactive element has hover, focus-visible, active, disabled and loading states
• Empty, error, loading, offline and no-permission states are designed
• Text contrast is at least 4.5:1 (3:1 large); UI and focus indicators at least 3:1
• Color is never the only signal (icons, text, patterns too)
• Full keyboard path works, focus is visible and never hidden under sticky UI
• Targets are at least 24 px (44–48 px on touch), with space between them
• Forms have visible labels, helpful errors, autocomplete, and allow paste
• Copy uses verbs on buttons, one term per concept, sentence case
• Works at 320 px wide and 200% zoom; content, not devices, sets breakpoints
• Dark mode checked separately, prefers-reduced-motion respected
• Uses existing components and tokens; new ones are documented

Recipes

Focus ring that works everywhere

Visible for keyboard users only, and outline survives Windows forced-colors mode (box-shadow doesn't).

:where(a, button, input, select, textarea,
  summary, [tabindex]):focus-visible {
  outline: 2px solid var(--color-focus, Highlight);
  outline-offset: 2px;
}
 
/* keep focused items clear of a sticky header */
html { scroll-padding-block-start: 5rem; }

Press Tab inside the result: the ring appears for keyboard focus, not for clicks. The third button has it permanently so you can see it.

<style>
  :root { --color-focus: var(--graph-0); }
  :where(a, button, input):focus-visible,
  .show-ring {
    outline: 2px solid var(--color-focus, Highlight);
    outline-offset: 2px;
  }
  button, input { font: inherit; padding: 4px 10px; }
</style>
<button>Tab to me</button>
<input placeholder="then me" size="8">
<button class="show-ring">Ring shown</button>

Motion only for those who want it

Opt in to animation instead of stripping it out afterward. See Animation.

.card { transition: none; }
 
@media (prefers-reduced-motion: no-preference) {
  .card {
    transition: transform 200ms ease-out,
      box-shadow 200ms ease-out;
  }
  .card:hover { transform: translateY(-2px); }
}

<style>
  .card { padding: 16px; border-radius: 8px;
    background: var(--chip); transition: none; }
  @media (prefers-reduced-motion: no-preference) {
    .card { transition: transform 200ms ease-out,
      box-shadow 200ms ease-out; }
    .card:hover { transform: translateY(-2px);
      box-shadow: 0 6px 16px rgb(0 0 0 / 25%); }
  }
</style>
<div class="card">Hover me (still if motion is reduced)</div>

Bigger hit area, same visual size

When a small icon button must meet 44 px on touch without looking bigger.

.icon-btn {
  position: relative;
  inline-size: 1.25rem;
  block-size: 1.25rem;
}
 
/* 20 px icon + 12 px each side = 44 px target */
.icon-btn::after {
  content: "";
  position: absolute;
  inset: -12px;
}

The dashed outline marks the invisible target; hover anywhere inside it.

<style>
  .icon-btn { position: relative; margin: 20px;
    inline-size: 1.25rem; block-size: 1.25rem;
    padding: 0; border: 0; border-radius: 4px;
    background: var(--graph-0); }
  /* 20 px icon + 12 px each side = 44 px target */
  .icon-btn::after { content: ""; position: absolute;
    inset: -12px; outline: 1px dashed var(--muted); }
  .icon-btn:hover::after { background: color-mix(
    in srgb, var(--graph-0) 20%, transparent); }
</style>
<button class="icon-btn" aria-label="Close"></button>

Fluid type scale

Headings that grow with the viewport but still respond to zoom, because the rem term keeps scaling.

:root {
  --step-0: clamp(1rem, 0.95rem + 0.25vw, 1.125rem);
  --step-1: clamp(1.2rem, 1.1rem + 0.5vw, 1.5rem);
  --step-2: clamp(1.44rem, 1.25rem + 0.9vw, 2rem);
  --step-3: clamp(1.73rem, 1.4rem + 1.6vw, 2.67rem);
}
 
h1 { font-size: var(--step-3); line-height: 1.1; }
p { font-size: var(--step-0); max-inline-size: 65ch; }

Spinner that doesn't flash

Show loading only if work takes longer than delayMs, then keep it up for minMs to avoid flicker.

const wait = (ms: number) =>
  new Promise<void>((r) => setTimeout(r, ms));
 
export async function withSpinner<T>(
  work: Promise<T>,
  show: (visible: boolean) => void,
  delayMs = 300,
  minMs = 500,
): Promise<T> {
  const started = { at: -1 };
  const timer = setTimeout(() => {
    started.at = performance.now();
    show(true);
  }, delayMs);
  try {
    return await work;
  } finally {
    clearTimeout(timer);
    if (started.at >= 0) {
      const shown = performance.now() - started.at;
      await wait(Math.max(0, minMs - shown));
      show(false);
    }
  }
}

Validate on blur, then live

The validation timing from Forms: no errors while typing the first time.

type Validator = (value: string) => string | null;
 
export function wireField(
  input: HTMLInputElement,
  validate: Validator,
): void {
  const error = document.getElementById(`${input.id}-error`);
  const state = { touched: false };
 
  const run = () => {
    const msg = validate(input.value);
    input.setAttribute("aria-invalid", String(msg !== null));
    if (error) error.textContent = msg ?? "";
  };
 
  input.addEventListener("blur", () => {
    state.touched = true;
    run();
  });
  input.addEventListener("input", () => {
    if (state.touched) run();
  });
}

Optimistic update with rollback

For likes, toggles and renames that almost always succeed. In React, see useOptimistic in TypeScript + React.

type Store<S> = { get: () => S; set: (next: S) => void };
 
export async function optimistic<S>(
  store: Store<S>,
  update: (prev: S) => S,
  commit: () => Promise<void>,
): Promise<void> {
  const before = store.get();
  store.set(update(before));          // paint the result now
  try {
    await commit();
  } catch (err) {
    store.set(before);                // roll back
    throw new Error("Could not save", { cause: err });
  }
}
 
// optimistic(post, (p) => ({ ...p, likes: p.likes + 1 }),
//   () => api.like("p1"));

References

• MDN: Accessibility (opens in a new tab), Understanding WCAG (opens in a new tab), :focus-visible (opens in a new tab), prefers-reduced-motion (opens in a new tab), prefers-color-scheme (opens in a new tab), color-scheme (opens in a new tab), autocomplete (opens in a new tab), text-wrap (opens in a new tab), clamp() (opens in a new tab)
• W3C: WCAG 2.2 (opens in a new tab), What's new in WCAG 2.2 (opens in a new tab), Design Tokens Format Module (opens in a new tab)
• Nielsen Norman Group: 10 usability heuristics (opens in a new tab), Response time limits (opens in a new tab), Why you only need to test with 5 users (opens in a new tab)
• Laws of UX (opens in a new tab): one page per law with sources
• Apple Human Interface Guidelines (opens in a new tab) and Material Design 3 (opens in a new tab): platform conventions, target sizes, components
• Refactoring UI (opens in a new tab): hierarchy, spacing and color for developers
• web.dev: Web Vitals (opens in a new tab): INP, LCP, CLS thresholds
• GOV.UK Design System (opens in a new tab): tested patterns for forms, errors and validation
• Butterick's Practical Typography (opens in a new tab): line length, spacing, font choice