Web Design

Implementation Priority

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)

1. Color and contrast. Palette applied, semantic tokens set, WCAG AA contrast met (4.5:1 text, 3:1 UI). Dark mode if needed.
2. Visual hierarchy. Four text levels working (foreground, muted, muted/70, muted/50). Primary action obvious. Squint test passes.
3. Component states. Every interactive element has hover, focus-visible, active, disabled, loading, error, and empty states accounted for.
4. 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)

1. Keyboard and accessibility. Focus styles, tab order, skip links,

   aria

   attributes, touch targets (44px+). Test with keyboard only.
2. Transitions. Hover/active feedback (150ms ease-out), state transitions (200-300ms), correct easing per direction (ease-out for enter, ease-in for exit).
3. 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)

1. Shadows and depth. Layered shadows, shadows-instead-of-borders where appropriate, consistent light source. Dark mode: surface lightness instead of shadows.
2. Optical adjustments. Icon-side button padding, concentric border radii, play button offset, tabular-nums on data, image outlines.
3. Micro-interactions. Contextual icon animation, blur on stagger entrances, copy-to-clipboard feedback, optimistic updates.
4. Defensive CSS.

   min-width: 0

   on flex children,

   overflow-wrap: break-word

   ,

   scrollbar-gutter: stable

   , text truncation, safe-area padding.
5. Final checks. Squint test, grayscale test, swap test, "would a human ship this?" test. No AI slop (gratuitous gradients, identical metric cards, centered everything).

Table of Contents

1. Layout and Spacing
2. Typography
3. Color
4. Shadows and Depth
5. Visual Hierarchy
6. Animation and Motion
7. Components
8. Responsive Design
9. Accessibility
10. Performance
11. UX Psychology
12. Design Tokens
13. Polish and Craft
14. Microcopy and UX Writing
15. AI Slop Prevention
16. Advanced Craft
17. Defensive CSS
18. Modern CSS Reset
19. Predictive Prefetching
20. Audio Feedback and Sound Design

1. Layout and Spacing

Spacing Scale

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

.stack > * + * { margin-block-start: var(--space); }

.cluster { display: flex; flex-wrap: wrap; gap: var(--space); }

.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 { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 250px), 1fr)); gap: var(--space); }

.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

<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>

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

<section className="space-y-6 py-12">
  <h2 className="text-2xl font-semibold tracking-tight">Features</h2>
  <div className="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
    {features.map(f => <FeatureCard key={f.id} {...f} />)}
  </div>
</section>

<div className="rounded-lg border bg-card p-6">      {/* outer: p-6 */}
  <div className="space-y-4">                          {/* inner gap: 4 */}
    <h3 className="font-semibold leading-tight">Title</h3>
    <p className="text-sm text-muted-foreground">Description text here.</p>
  </div>
</div>

2. Typography

Type Scale

Font Size Rules

• Body text minimum: 16px (1rem). This is the browser default. Never go smaller for primary reading content.
• Use

  rem

  for font sizes. This respects both browser zoom and the user's default font size preference. Pixels prevent users from scaling text.
• Use

  rem

  for media queries. When users increase their default font size, rem-based breakpoints trigger mobile layouts on wider screens, giving them more room.
• Use

  px

  for padding, borders, and decorative elements. These shouldn't scale with text size.
• Use

  rem

  for vertical margins. Spacing between paragraphs should grow with text.

Fluid Typography

clamp()

/* Heading: 32px on small screens, 48px on large, fluid between */
font-size: clamp(2rem, 1.5rem + 2vw, 3rem);

Line Height

• Body text: 1.5. This meets WCAG criteria and improves readability for all users.
• Headings: 1.1 - 1.25. Larger text needs tighter leading.
• The bigger the text, the less line-height it needs. Scale inversely.
• Headings and buttons: 1.1 is a good default.

Line Length

• Optimal: 60-75 characters (about 8-10 words per line).
• Maximum: 80 characters. Beyond this, readers lose their place.
• Use

  max-width: 65ch

  on content containers to enforce this.

Letter Spacing

• Large text: reduce letter-spacing. Bigger text needs less space between characters.
• Small text: increase letter-spacing slightly.
• All-caps text: add +0.05 to +0.1em letter-spacing. Uppercase letters crowd each other without extra space.
• Use

  font-variant-numeric: tabular-nums

  in tables and timers so digits maintain consistent width.

Text Wrapping

/* Balanced line breaks for headings */
h1, h2, h3, h4, h5, h6 { text-wrap: balance; }

/* Avoid orphans in paragraphs */
p { text-wrap: pretty; }

/* Prevent overflow from long words/URLs */
p, h1, h2, h3, h4, h5, h6 { overflow-wrap: break-word; }

Font Rendering

body { -webkit-font-smoothing: antialiased; }
html { text-rendering: optimizeLegibility; -webkit-text-size-adjust: 100%; }

Font Weight

• Never use weights below 400 -- they become illegible on most screens.
• Use 500-600 for medium headings.
• Use 700 for strong emphasis.
• Prevent layout shift from weight changes: Use a hidden

  ::after

  pseudo-element with bold text to reserve the bold width, preventing jitter when toggling active states.

OpenType Features

font-variant-numeric: tabular-nums

font-variant-numeric: oldstyle-nums

font-variant-numeric: slashed-zero

font-variant-numeric: diagonal-fractions

font-feature-settings: "calt" 1

font-feature-settings: "ss02"

/* Data display: aligned, disambiguated */
.data { font-variant-numeric: tabular-nums slashed-zero; }

/* Prose: numbers that blend with text */
.prose { font-variant-numeric: oldstyle-nums; }

/* Code-adjacent UI */
.code-ui { font-variant-numeric: tabular-nums slashed-zero; font-feature-settings: "ss02"; }

• font-optical-sizing: auto

  -- leave at default. The font adjusts glyph shapes per size (thicker strokes at small sizes, finer details at large).

• font-synthesis: none

  -- disable to prevent the browser from generating faux bold/italic when the font lacks those weights. Forces you to load proper font files.
• Variable fonts accept any weight 100-900, not just standard stops. Use precise values like 450 or 550 for fine-grained hierarchy without loading extra files.

• text-decoration-skip-ink: auto

  is the default and correctly skips descenders. Add

  text-underline-offset: 3px

  to push underlines below descenders for cleaner links.

Typeface Pairing

• Limit to two typefaces. One for headings, one for body. A second typeface should reinforce the design concept.
• A monospace third face for code is acceptable.
• If using a single typeface, differentiate hierarchy through weight, size, and color instead.

In Practice: Next.js + Tailwind Typography

app/layout.tsx

import { Inter, JetBrains_Mono } from "next/font/google"

const sans = Inter({ subsets: ["latin"], variable: "--font-sans" })
const mono = JetBrains_Mono({ subsets: ["latin"], variable: "--font-mono" })

export default function RootLayout({ children }) {
  return (
    <html lang="en" className={`${sans.variable} ${mono.variable}`}>
      <body className="font-sans antialiased">{children}</body>
    </html>
  )
}

{/* Page heading */}
<h1 className="text-3xl font-bold tracking-tight sm:text-4xl">Dashboard</h1>

{/* Section heading */}
<h2 className="text-2xl font-semibold tracking-tight">Recent Activity</h2>

{/* Card title */}
<h3 className="font-semibold leading-tight">Monthly Revenue</h3>

{/* Body text with constrained width */}
<p className="max-w-prose text-muted-foreground">
  Your revenue increased 12% compared to last month.
</p>

{/* Small label */}
<span className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
  Status
</span>

{/* Tabular numbers in a data display */}
<td className="tabular-nums text-right font-medium">$12,450.00</td>

3. Color

Color System Structure

1. Neutrals (Greys): 8-10 shades. Used for text, backgrounds, panels, form controls -- almost everything.
2. Primary Colors: 1-2 colors for primary actions, navigation, and branding. 5-10 shades each.
3. Accent/Semantic Colors: Red (destructive/error), yellow/amber (warning), green/emerald (success), blue (info). 5-10 shades each.

The 9-Shade System

Color Format

• Use OKLCH as the primary color format. It's perceptually uniform (colors at the same lightness actually look equally light), supported in all modern browsers, and used by Tailwind v4 and shadcn/ui. Format:

  oklch(lightness chroma hue)

  .
• HSL remains a solid alternative when OKLCH tooling is unavailable. It's intuitive: adjusting lightness creates shades, adjusting saturation creates tints.
• Store color channels as CSS variables for maximum flexibility:

:root {
  /* OKLCH approach (preferred) */
  --primary: oklch(62% 0.21 260);

  /* HSL approach (alternative) */
  --primary-h: 221;
  --primary-s: 72%;
  --primary-l: 62%;
  --primary-hsl: hsl(var(--primary-h) var(--primary-s) var(--primary-l));
}

Color Rules

• Use near-black and near-white, not pure. Pure black (#000) on pure white (#fff) creates uncomfortable contrast. Use

  #0a0a0a

  /

  #111

  and

  #fafafa

  /

  #f5f5f5

  instead.
• Saturate your neutrals. Add a hint of your primary hue to grey tones (keep saturation under 5% in HSB). This creates palette cohesion.
• Maintain consistent color temperature. Use either warm or cool tinted neutrals, not both.
• Colors must differ in brightness, not just hue. Two colors at the same lightness compete visually. Vary brightness to create distinction.
• Rotate hue for vibrant variants. When creating lighter shades, rotate hue toward a brighter anchor (yellow, cyan). For darker shades, rotate toward a deeper anchor (blue, violet). This prevents washed-out pastels.
• Don't rely on color alone to convey meaning. Always pair color with text, icons, or patterns for accessibility.
• Use

  color-mix()

  for dynamic variations:

background: color-mix(in oklch, var(--primary), transparent 95%);

Dark Mode

• Swap light and dark values (900 becomes foreground, 50 becomes background).
• Don't just invert -- dark backgrounds need reduced contrast. Container brightness should differ from background by max 12%.
• Avoid pure white text on dark backgrounds. Use near-white (e.g.,

  #e5e5e5

  ).
• Shadows are ineffective in dark mode -- use subtle borders or lighter elevated surfaces instead.
• Respect

  prefers-color-scheme

  as the default. Don't add a theme toggle unless specifically needed.

In Practice: shadcn/ui Theming

app/globals.css

@layer base {
  :root {
    --background: oklch(1 0 0);
    --foreground: oklch(0.145 0 0);
    --card: oklch(1 0 0);
    --card-foreground: oklch(0.145 0 0);
    --primary: oklch(0.205 0 0);
    --primary-foreground: oklch(0.985 0 0);
    --secondary: oklch(0.965 0 0);
    --secondary-foreground: oklch(0.205 0 0);
    --muted: oklch(0.965 0 0);
    --muted-foreground: oklch(0.556 0 0);
    --accent: oklch(0.965 0 0);
    --accent-foreground: oklch(0.205 0 0);
    --destructive: oklch(0.577 0.245 27.325);
    --border: oklch(0.922 0 0);
    --input: oklch(0.922 0 0);
    --ring: oklch(0.708 0 0);
    --radius: 0.625rem;
  }
  .dark {
    --background: oklch(0.145 0 0);
    --foreground: oklch(0.985 0 0);
    --card: oklch(0.205 0 0);
    --card-foreground: oklch(0.985 0 0);
    --primary: oklch(0.985 0 0);
    --primary-foreground: oklch(0.205 0 0);
    --muted: oklch(0.269 0 0);
    --muted-foreground: oklch(0.708 0 0);
    --border: oklch(0.269 0 0);
  }
}

next-themes

// app/layout.tsx
import { ThemeProvider } from "next-themes"

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}

// components/theme-toggle.tsx
"use client"
import { useTheme } from "next-themes"
import { Button } from "@/components/ui/button"
import { Moon, Sun } from "lucide-react"

export function ThemeToggle() {
  const { setTheme, theme } = useTheme()
  return (
    <Button variant="ghost" size="icon"
      onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
      <Sun className="h-4 w-4 rotate-0 scale-100 transition-[transform,opacity] dark:-rotate-90 dark:scale-0" />
      <Moon className="absolute h-4 w-4 rotate-90 scale-0 transition-[transform,opacity] dark:rotate-0 dark:scale-100" />
      <span className="sr-only">Toggle theme</span>
    </Button>
  )
}

4. Shadows and Depth

Shadow Principles

• Single consistent light source. All shadows should share the same angle ratio (typically above and slightly left). Every shadow on the page must use the same offset ratio.
• Elevation mapping. As elements rise: offset increases, blur grows, opacity decreases. This mimics physical light behavior.
• Layer multiple shadows for realism. A single

  box-shadow

  looks flat. Stack 2-5 layers with geometrically increasing values. (Shadow color uses HSL below for readability; any color format works.)

/* Low elevation */
box-shadow: 0 1px 2px hsl(var(--shadow-color) / 0.3);

/* Medium elevation */
box-shadow:
  0 1px 2px hsl(var(--shadow-color) / 0.2),
  0 2px 4px hsl(var(--shadow-color) / 0.2),
  0 4px 8px hsl(var(--shadow-color) / 0.2);

/* High elevation */
box-shadow:
  0 1px 2px hsl(var(--shadow-color) / 0.12),
  0 2px 4px hsl(var(--shadow-color) / 0.12),
  0 4px 8px hsl(var(--shadow-color) / 0.12),
  0 8px 16px hsl(var(--shadow-color) / 0.12),
  0 16px 32px hsl(var(--shadow-color) / 0.12);

• Match shadow color to the environment. Don't use pure black/grey shadows -- tint them with the background's hue for vibrant, natural depth.
• Shadow blur = 2x shadow distance. A 4px vertical offset pairs with 8px blur.
• Elements closer to the user appear lighter. Mimic real-world light: surfaces near the light source are brighter.
• Avoid shadows in dark interfaces. They lack visual logic. Use subtle borders or surface lightness variation instead.
• Don't mix depth techniques. Pick one approach (shadows, borders, or surface lightness) and use it consistently.
• Never animate layered shadows directly. It's too expensive. Instead, animate

  opacity

  between two shadow states using pseudo-elements.

Border Radius

• Nest corner radii correctly. Inner radius = outer radius - gap between elements. If outer is 12px and padding is 8px, inner should be 4px.
• Container borders need dual contrast. They must be distinguishable from both the container's background and the page background.

Shadows Instead of Borders

box-shadow

/* Multi-shadow composition — replaces border with soft depth */
box-shadow:
  0px 0px 0px 1px rgba(0, 0, 0, 0.06),
  0px 1px 2px -1px rgba(0, 0, 0, 0.06),
  0px 2px 4px 0px rgba(0, 0, 0, 0.04);

/* Hover: slightly increase opacity for lift effect */
box-shadow:
  0px 0px 0px 1px rgba(0, 0, 0, 0.08),
  0px 1px 2px -1px rgba(0, 0, 0, 0.08),
  0px 2px 4px 0px rgba(0, 0, 0, 0.06);

• The first layer (

  0px 0px 0px 1px

  ) acts as the border replacement — a zero-blur spread gives a crisp 1px edge.
• Works on image backgrounds and color backgrounds where solid

  border-color

  would clash.
• Transition

  box-shadow

  on hover for interactive lift. Use

  transition: box-shadow 150ms ease

  (or Tailwind's

  transition-shadow

  ).

Image Outlines

img {
  outline: 1px solid rgba(0, 0, 0, 0.1);
  outline-offset: -1px;
}

/* Dark mode */
@media (prefers-color-scheme: dark) {
  img { outline-color: rgba(255, 255, 255, 0.1); }
}

<img>

outline-offset: -1px

In Practice: Tailwind Shadow and Depth

{/* Flat surface — default cards */}
<div className="rounded-lg border bg-card shadow-sm">

{/* Raised — hover state, dropdown trigger */}
<div className="rounded-lg border bg-card shadow-md hover:shadow-lg transition-shadow">

{/* Floating — dropdowns, popovers, command palette */}
<div className="rounded-xl border bg-popover shadow-xl">

{/* Dialog/modal backdrop + elevated panel */}
<div className="fixed inset-0 bg-black/50 backdrop-blur-sm">
  <div className="rounded-xl border bg-card shadow-2xl">

<div className="rounded-lg bg-card p-4
  shadow-[0px_0px_0px_1px_rgba(0,0,0,0.06),0px_1px_2px_-1px_rgba(0,0,0,0.06),0px_2px_4px_0px_rgba(0,0,0,0.04)]
  hover:shadow-[0px_0px_0px_1px_rgba(0,0,0,0.08),0px_1px_2px_-1px_rgba(0,0,0,0.08),0px_2px_4px_0px_rgba(0,0,0,0.06)]
  transition-shadow">
  <h3 className="font-semibold">No border needed</h3>
  <p className="text-sm text-muted-foreground">Shadow provides the edge.</p>
</div>

<img
  src={src} alt={alt}
  className="rounded-lg outline outline-1 -outline-offset-1 outline-black/10 dark:outline-white/10"
/>

{/* Outer: rounded-xl (12px), padding: p-2 (8px), so inner = 12-8 = 4px = rounded-sm */}
<div className="rounded-xl border bg-card p-2">
  <img className="rounded-sm w-full" src={src} alt={alt} />
  <div className="p-3">
    <h3 className="font-semibold">Title</h3>
  </div>
</div>

5. Visual Hierarchy

Core Principles

• Size, weight, and color communicate importance. Primary content is larger, bolder, and higher contrast. Secondary content is smaller, lighter, and lower contrast.
• De-emphasize secondary content instead of over-emphasizing primary content. It's more effective to make supporting elements quieter than to make everything louder.
• Semantic hierarchy != visual hierarchy. An

  <h2>

  doesn't always need to look like a big heading. Style for the role the content plays in the layout, not its HTML tag.
• Reduce label reliance. When context makes meaning clear, labels are redundant. "john@example.com" doesn't need an "Email:" label -- the format itself communicates.
• Use weight and contrast as separate levers. Bold dark text and regular grey text occupy different hierarchy levels. Combining size + weight + color gives you three independent hierarchy controls.
• High contrast for important elements, low contrast for structural elements. Draw attention to actions and content, not chrome and borders.

Visual Weight Ordering

• Arrange series of elements in descending visual weight. The heaviest element sits at the outer edge.
• Use fewer borders. Replace borders with spacing, background color differences, or shadows for cleaner separation.
• Accent borders (3-5px) on one edge of a card or callout add visual interest and hierarchy without heavy separation.

Alignment

• Align everything with something. Alignment shows that elements are related and that placement is intentional.
• Prefer optical alignment over mathematical. Triangular shapes (play buttons, arrows) have visual centers that differ from their geometric centers. Trust your eyes.
• Measure spacing between high-contrast points. Eyes find element edges based on contrast, not bounding boxes.

Four-Level Text Hierarchy

{/* Level 1: Primary — the main content the user came to see */}
<p className="text-foreground">Invoice #1234 — $2,400.00</p>

{/* Level 2: Secondary — supporting info that adds context */}
<p className="text-muted-foreground">Due March 15, 2026</p>

{/* Level 3: Tertiary — metadata, timestamps, IDs */}
<span className="text-xs text-muted-foreground/70">Created 2 days ago</span>

{/* Level 4: Muted — disabled, placeholder, non-essential */}
<span className="text-xs text-muted-foreground/50">Optional</span>

Surface Elevation (Dark Mode Depth)

{/* Level 0: Page background */}
<div className="bg-background">                        {/* darkest */}
  {/* Level 1: Card surface */}
  <div className="bg-card">                             {/* slightly lighter */}
    {/* Level 2: Dropdown / popover on top of card */}
    <div className="bg-popover">                         {/* lighter still */}
    </div>
  </div>
</div>

Quality Checks

• Squint test. Blur your eyes and look at the page. Hierarchy should still be visible -- headings distinct from body, primary actions distinct from secondary.
• Swap test. If you replaced the typeface with a system font, would the design still hold? If not, the hierarchy depends on the font, not the structure.
• Grayscale test. Convert to grayscale. If elements that were distinct now merge, you're relying on hue alone (an accessibility failure).

6. Animation and Motion

When to Animate

• Feedback: Confirm that the system recognized an action (button press, form submit, toggle).
• State transitions: Signal changes between interface modes or views.
• Spatial navigation: Help users understand their position in a hierarchy (zoom = depth, slide = lateral movement).
• Signifiers: Show how to interact with an element (drag direction, swipeable area).

When NOT to Animate

• High-frequency interactions. Actions performed many times daily should feel instant -- no animation.
• Keyboard-initiated actions. These should be immediate and feel connected to the input.
• When performance suffers. A janky animation is worse than no animation. 60fps or nothing.
• Repetitive daily-use elements. Animations seen repeatedly throughout the day become annoying.
• Gratuitous motion. If it doesn't clarify interaction or explain functionality, remove it.

Easing Functions

ease-out

ease-in-out

ease

linear

ease-in

cubic-bezier(0.32, 0.72, 0, 1)

Duration Guidelines

• Asymmetric timing for safety: Slow, predictable timing for destructive actions paired with fast release feedback.
• Entry != exit. Differentiate enter vs. exit animations. Entry should feel decisive; exit should feel natural.
• Exit animations should be subtler than entrances. Use less movement on exit — a fixed small value (e.g.,

  y: -12px

  ) instead of the full distance (e.g.,

  y: calc(-100% - 4px)

  ). The exiting element needs just enough motion for directional indication, not a full departure animation. Add a light

  blur(4px)

  on exit to soften the disappearance.

Animation Techniques

scale(0.97)

:active

scale(0.9)

transform-origin

filter: blur(2px)

clip-path

clip-path: inset(0 0 100% 0)

inset(0 0 0 0)

opacity

scale

blur

Staging and Choreography (from Disney's 12 Principles)

• One focal point at a time. Only one element should animate prominently. If two things move simultaneously, the eye doesn't know where to look.
• Context menus animate on exit only, not entrance. They should appear instantly and animate away.
• Squash and stretch range: 0.95-1.05 scale. Anything beyond looks cartoonish in UI.
• Stagger delays: max 50ms per item. Longer stagger feels sluggish. For a 5-item list: 0ms, 50ms, 100ms, 150ms, 200ms.
• Split and stagger for impact. Instead of animating an entire block at once, break it into smaller chunks (sections, lines, even words) and animate each individually. Combine

  opacity

  ,

  blur(4-5px)

  , and

  translateY(6-8px)

  for the initial state. Use CSS custom properties for clean stagger control:

  animation-delay: calc(var(--stagger-delay, 80ms) * var(--stagger-index, 0))

  . Three tiers of granularity: container-level (simple), section-level (balanced), word-level (dramatic).
• Dim backgrounds on overlays. Darkened backdrops direct focus to the foreground element.
• Use spring physics for bounce-and-settle effects. Don't fake it with easing curves. Framer Motion

  type: "spring"

  with

  stiffness: 300, damping: 20

  is a good starting point.

Properties Safe to Animate

• transform

  (translate, rotate, scale) -- GPU-accelerated

• opacity

  -- GPU-accelerated

• clip-path

  -- GPU-accelerated

Properties to Avoid Animating

• width

  ,

  height

  ,

  padding

  ,

  margin

  -- triggers layout recalculation

• top

  ,

  left

  ,

  right

  ,

  bottom

  -- triggers layout recalculation

• background-color

  -- triggers repaint (expensive)

Performance Ranking

1. CSS Animations/Transitions (best -- runs off main thread)
2. Web Animations API (good -- survives main-thread congestion)
3. JavaScript

   requestAnimationFrame

   (worst -- lags when browser is busy)

Accessibility

prefers-reduced-motion

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

In Practice: Tailwind + Framer Motion

duration-150

<button className="rounded-lg bg-primary px-4 py-2 text-sm font-medium text-primary-foreground
  transition-[background-color,transform] duration-150 ease-out
  hover:bg-primary/90
  active:scale-[0.97]">
  Save Changes
</button>

"use client"
import { motion, AnimatePresence } from "motion/react"
import { Dialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog"

export function AnimatedDialog({ open, onOpenChange, children }) {
  return (
    <Dialog open={open} onOpenChange={onOpenChange}>
      <AnimatePresence>
        {open && (
          <DialogContent forceMount asChild>
            <motion.div
              initial={{ opacity: 0, scale: 0.95 }}
              animate={{ opacity: 1, scale: 1 }}
              exit={{ opacity: 0, scale: 0.95 }}
              transition={{ duration: 0.2, ease: [0.32, 0.72, 0, 1] }}
            >
              {children}
            </motion.div>
          </DialogContent>
        )}
      </AnimatePresence>
    </Dialog>
  )
}

import { motion } from "motion/react"

export function StaggeredList({ items }) {
  return (
    <ul className="space-y-2">
      {items.map((item, i) => (
        <motion.li key={item.id}
          initial={{ opacity: 0, y: 8 }}
          animate={{ opacity: 1, y: 0 }}
          transition={{ delay: i * 0.05, duration: 0.25, ease: "easeOut" }}
          className="rounded-lg border bg-card p-4"
        >
          {item.label}
        </motion.li>
      ))}
    </ul>
  )
}

@keyframes stagger-in {
  from {
    opacity: 0;
    filter: blur(5px);
    transform: translateY(8px);
  }
}

.stagger-item {
  animation: stagger-in 800ms cubic-bezier(0.25, 0.46, 0.45, 0.94) both;
  animation-delay: calc(var(--stagger-index, 0) * 80ms);
}

{/* Assign --stagger-index per element */}
<div className="stagger-item" style={{ "--stagger-index": 0 } as React.CSSProperties}>Section 1</div>
<div className="stagger-item" style={{ "--stagger-index": 1 } as React.CSSProperties}>Section 2</div>
<div className="stagger-item" style={{ "--stagger-index": 2 } as React.CSSProperties}>Section 3</div>

<AnimatePresence>
  {show && (
    <motion.div
      initial={{ opacity: 0, y: 8, filter: "blur(4px)" }}
      animate={{ opacity: 1, y: 0, filter: "blur(0px)" }}
      exit={{ opacity: 0, y: -12, filter: "blur(4px)" }}
      transition={{ type: "spring", duration: 0.45, bounce: 0 }}
    >
      {children}
    </motion.div>
  )}
</AnimatePresence>

function CardSkeleton() {
  return (
    <div className="rounded-lg border bg-card p-6 space-y-4">
      <div className="h-4 w-2/3 animate-pulse rounded bg-muted" />
      <div className="h-3 w-full animate-pulse rounded bg-muted" />
      <div className="h-3 w-4/5 animate-pulse rounded bg-muted" />
    </div>
  )
}

Spring Physics vs Easing Decision Framework

stiffness: 300, damping: 20

stiffness: 500, damping: 30

damping < 10

velocity

onDragEnd={(e, info) => {
  animate(target, { x: 0 }, {
    type: "spring",
    velocity: info.velocity.x,
    stiffness: 500,
    damping: 30,
  });
}}

Container Bounds Animation

width

height

motion.div

function AnimatedContainer({ children }) {
  const [ref, bounds] = useMeasure()
  return (
    <motion.div
      animate={{ height: bounds.height }}
      transition={{ duration: 0.2, delay: 0.05 }}
      style={{ overflow: "hidden" }}>
      <div ref={ref}>{children}</div>
    </motion.div>
  )
}

getBoundingClientRect

function useMeasure() {
  const [element, setElement] = useState(null)
  const [bounds, setBounds] = useState({ width: 0, height: 0 })
  const ref = useCallback((node) => setElement(node), [])

  useEffect(() => {
    if (!element) return
    const observer = new ResizeObserver(([entry]) => {
      setBounds({ width: entry.contentRect.width, height: entry.contentRect.height })
    })
    observer.observe(element)
    return () => observer.disconnect()
  }, [element])

  return [ref, bounds]
}

• Use callback ref (not

  useRef

  ) so the observer attaches when the DOM node is ready.
• Set

  overflow: hidden

  on the animated container to clip content during transitions.
• Guard

  bounds === 0

  on initial render -- fall back to

  "auto"

  height.
• Use sparingly: buttons, accordions, expandable sections. Not every container.

AnimatePresence Deep Patterns

• mode="wait"

  doubles perceived duration because exit completes before enter starts. Halve your timing values when using it.

• mode="sync"

  causes layout conflicts -- entering and exiting elements coexist briefly. Use

  popLayout

  for list reordering instead.
• Disable interactions on exiting elements. Use

  useIsPresent()

  and set

  disabled={!isPresent}

  or

  pointer-events: none

  on elements during their exit animation -- otherwise users click elements that are animating away.
• Nested AnimatePresence needs the

  propagate

  prop so parent exit triggers child exits.
• Exit should mirror initial for symmetric feel, but use less motion on exit (fixed small

  y: -12px

  instead of full distance, add

  blur(4px)

  to soften).

View Transitions API

/* 1. Assign unique transition names to elements that persist across views */
.hero-image { view-transition-name: hero; }
.page-title { view-transition-name: title; }

/* 2. Style the transition pseudo-elements */
::view-transition-group(hero) {
  animation-duration: 300ms;
  animation-timing-function: cubic-bezier(0.32, 0.72, 0, 1);
}

• Every

  view-transition-name

  must be unique during a transition (no two elements can share the same name simultaneously).
• Clean up transition names after completion if they were dynamically assigned.
• Falls back gracefully in unsupported browsers -- the page just navigates without animation.

7. Components

Component Philosophy

• Copy and own, don't install. The shadcn/ui model: components are source code you paste into your project and customize, not opaque npm packages. You own the code.
• Build on accessible primitives. Use headless UI libraries (Radix, Base UI, React Aria) for behavior, then style with your own design tokens.
• Compound component pattern. Break complex components into composable parts:

  Dialog.Root

  ,

  Dialog.Trigger

  ,

  Dialog.Content

  ,

  Dialog.Title

  . Each part is independently addressable.
• Use

  cn()

  for class logic. The

  clsx

  +

  tailwind-merge

  utility is standard in the shadcn/ui ecosystem for conditionally merging Tailwind classes:

// lib/utils.ts
import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"
export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) }

• Expose component APIs via CSS variables. Components accept customization through CSS custom properties, not endless prop variants:

.button { background: var(--button-bg, var(--primary)); }

Component Design Tokens (shadcn/ui model)

--background

--foreground

--card

--primary

--secondary

--muted

--accent

--destructive

--border

--input

--ring

--radius

-foreground

Button Patterns

• Horizontal padding = 2x vertical padding. This creates the recognizable button shape.
• Default height: 32-36px for standard density. 40px for comfortable.
• Use

  min-width

  instead of fixed

  width

  to accommodate varying label lengths.
• Labels describe outcomes, not processes. "Save" not "Click to save your changes."
• Primary, Secondary, Ghost, Destructive -- four variants cover nearly all cases.

Form Patterns

• Associate every input with a

  label

  using

  for

  /

  id

  .
• Use

  fieldset

  and

  legend

  for grouped inputs.
• Input heights must match button heights. When buttons and inputs appear side by side in inline forms, they must align perfectly. Use the same height token (32-36px default).
• Form elements must inherit font:

  input, button, textarea, select { font: inherit; }

• Display errors inline near the field, not in distant toasts. Connect error messages to inputs with

  aria-describedby

  .
• Prevent errors rather than reporting them. Use constraints, good defaults, and real-time validation.
• Placeholder is not a label. Placeholders disappear on focus. Use floating labels or persistent labels above the field.
• Apply

  autocomplete

  attributes for familiar fields (name, email, address).
• Tame Chrome's autofill styling. Chrome forces a blue background and overrides text color on autofilled inputs via

  :-webkit-autofill

  with

  !important

  at the user-agent level. Tailwind's

  autofill:

  variant alone can't override it. Use this global rule:

input:-webkit-autofill,
input:-webkit-autofill:hover,
input:-webkit-autofill:focus,
input:-webkit-autofill:active {
  -webkit-box-shadow: 0 0 0px 1000px var(--background) inset !important;
  -webkit-text-fill-color: var(--foreground) !important;
  border-color: var(--input) !important;
  transition: background-color 5000s ease-in-out 0s;
  caret-color: var(--foreground);
}

-webkit-text-fill-color

color

transition: background-color 5000s

Icons

• Standard sizes: 16px (inline/dense), 20px (default), 24px (prominent). Decorative icons in empty states or hero sections can be larger (32-48px).
• Stroke width: 1.5px-2px. Match the visual weight of your text.
• Consistent

  viewBox

  : All icons in a set should share the same viewBox (typically

  0 0 24 24

  ).
• Optical alignment with text: Use

  display: inline-flex; align-items: center

  and occasionally a -1px to -2px vertical offset for visual centering.
• Lower icon contrast when paired with text. Icons appear visually heavier than text at the same color. Reduce icon opacity or use

  text-muted-foreground

  color.
• Use

  aria-hidden="true"

  on decorative icons. Provide

  aria-label

  on icon-only buttons.

Tables and Data Display

• Right-align numbers and currency. Left-align text. This keeps decimal points aligned for scannability.
• Use

  font-variant-numeric: tabular-nums

  so digits maintain equal width across rows.
• Use semantic markup:

  <table>

  ,

  <thead>

  ,

  <tbody>

  ,

  <th scope="col">

  ,

  <caption>

  .
• Responsive pattern: Wrap tables in a horizontally scrollable container on small screens:

.table-wrapper { overflow-x: auto; -webkit-overflow-scrolling: touch; }

• Zebra striping (alternating row backgrounds) or horizontal dividers improve readability on wide tables.
• Sticky headers:

  thead th { position: sticky; top: 0; }

  for long scrollable tables.

Loading States

• Delay spinners by 400ms. If the operation completes faster, the user never sees loading UI. This prevents flash-of-loading.
• Skeleton screens over spinners for content-heavy layouts. Animate with subtle pulsing opacity (

  animate-pulse

  ), not harsh gradient sweeps.
• Skeletons must match the layout of the content they replace to prevent layout shift.
• Optimistic updates: Show the expected result immediately, roll back on error. This is the gold standard for perceived performance.
• Progress indicators for operations over 2-3 seconds. Provide determinate progress when possible (percentage), indeterminate when not.

Modals and Overlays

• Backdrop: Semi-transparent overlay (

  rgba(0,0,0,0.5)

  or

  backdrop-filter: blur(4px)

  ).
• Focus trapping: Tab key must cycle within the modal. Focus the first interactive element on open, restore focus to the trigger on close.
• Prevent body scroll: Use

  overflow: hidden

  on

  <body>

  or

  overscroll-behavior: contain

  on the modal. Note:

  overscroll-behavior: contain

  also prevents pull-to-refresh on mobile -- test this trade-off.
• Escape to close: Always support keyboard dismissal.

• isolation: isolate

  on the app root prevents z-index conflicts with portaled modals.

Empty States

• Treat empty states as design opportunities, not afterthoughts.
• Provide clear guidance on what to do next.
• Use illustration or subtle animation to make the state feel intentional.

Error Pages

• Treat 404 and error pages as craft opportunities.
• Maintain the site's personality and navigation.
• Provide helpful next steps (search, popular pages, home link).

In Practice: shadcn/ui Component Patterns

"use client"
import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import { z } from "zod"
import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

const schema = z.object({
  email: z.string().email("Enter a valid email"),
  name: z.string().min(2, "Name must be at least 2 characters"),
})

export function SignupForm() {
  const { register, handleSubmit, formState: { errors } } = useForm({
    resolver: zodResolver(schema),
  })

  return (
    <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
      <div className="space-y-2">
        <Label htmlFor="name">Name</Label>
        <Input id="name" {...register("name")} />
        {errors.name && (
          <p className="text-sm text-destructive">{errors.name.message}</p>
        )}
      </div>
      <div className="space-y-2">
        <Label htmlFor="email">Email</Label>
        <Input id="email" type="email" autoComplete="email" {...register("email")} />
        {errors.email && (
          <p className="text-sm text-destructive">{errors.email.message}</p>
        )}
      </div>
      <Button type="submit" className="w-full">Create account</Button>
    </form>
  )
}

import { Inbox } from "lucide-react"
import { Button } from "@/components/ui/button"

export function EmptyState({ title, description, action, onAction }) {
  return (
    <div className="flex flex-col items-center justify-center rounded-lg border border-dashed p-8 text-center">
      <Inbox className="h-10 w-10 text-muted-foreground/50" />
      <h3 className="mt-4 font-semibold">{title}</h3>
      <p className="mt-2 text-sm text-muted-foreground max-w-sm">{description}</p>
      {action && (
        <Button onClick={onAction} className="mt-4" size="sm">{action}</Button>
      )}
    </div>
  )
}

import {
  Table, TableBody, TableCell, TableHead,
  TableHeader, TableRow,
} from "@/components/ui/table"

export function InvoiceTable({ invoices }) {
  return (
    <div className="rounded-lg border">
      <Table>
        <TableHeader>
          <TableRow>
            <TableHead>Invoice</TableHead>
            <TableHead>Status</TableHead>
            <TableHead className="text-right">Amount</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {invoices.map(inv => (
            <TableRow key={inv.id}>
              <TableCell className="font-medium">{inv.id}</TableCell>
              <TableCell>
                <span className="inline-flex items-center rounded-full bg-emerald-50 px-2 py-0.5
                  text-xs font-medium text-emerald-700 dark:bg-emerald-950 dark:text-emerald-300">
                  {inv.status}
                </span>
              </TableCell>
              <TableCell className="text-right tabular-nums">{inv.amount}</TableCell>
            </TableRow>
          ))}
        </TableBody>
      </Table>
    </div>
  )
}

"use client"
import { useEffect, useState } from "react"
import { Loader2 } from "lucide-react"

export function DelayedSpinner({ delay = 400 }) {
  const [show, setShow] = useState(false)
  useEffect(() => {
    const timer = setTimeout(() => setShow(true), delay)
    return () => clearTimeout(timer)
  }, [delay])

  if (!show) return null
  return <Loader2 className="h-5 w-5 animate-spin text-muted-foreground" />
}

8. Responsive Design

Breakpoint Strategy

Responsive Rules

• Design mobile-first. Start with the smallest layout and expand.
• Use

  rem

  for breakpoint values so layouts respond to user font size preferences.
• Use container queries for component-level responsiveness. Components should adapt to their container, not the viewport:

@container (min-inline-size: 400px) {
  .card { flex-direction: row; }
}

• Prefer intrinsic sizing over breakpoints. Use

  auto-fill

  /

  auto-fit

  grids,

  flex-wrap

  , and

  clamp()

  to create layouts that adapt without media queries.
• Never hide content solely because the screen is small. Small screens don't mean users need less information.
• Optimize line length. Add breakpoints when text exceeds 75 characters per line.
• Test for text readability at 200% zoom (WCAG requirement).
• Check interaction modes. Use

  @media (hover: hover)

  and

  @media (pointer: coarse)

  to adapt for touch vs. mouse:

@media (pointer: coarse) {
  .button { min-height: 48px; }
}

In Practice: Tailwind Responsive Patterns

<div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
  {items.map(item => <Card key={item.id} {...item} />)}
</div>

import { Sheet, SheetContent, SheetTrigger } from "@/components/ui/sheet"
import { Button } from "@/components/ui/button"
import { Menu } from "lucide-react"

export function AppShell({ nav, children }) {
  return (
    <div className="flex min-h-screen">
      {/* Desktop sidebar */}
      <aside className="hidden lg:flex w-64 flex-col border-r p-4">{nav}</aside>

      {/* Mobile sheet */}
      <Sheet>
        <SheetTrigger asChild>
          <Button variant="ghost" size="icon" className="lg:hidden fixed top-4 left-4 z-40">
            <Menu className="h-5 w-5" />
          </Button>
        </SheetTrigger>
        <SheetContent side="left" className="w-64 p-4">{nav}</SheetContent>
      </Sheet>

      <main className="flex-1 p-6 lg:p-8">{children}</main>
    </div>
  )
}