// Web design reference for building production-grade interfaces. Covers layout, typography, color, spacing, shadows, animation, accessibility, responsive design, components, performance, and UX psychology. Use when building UI, reviewing design quality, choosing design tokens, or making any visual design decision.
Multi-model agent orchestration using specialized agents for planning, coding, research, math/science, visual analysis, and adversarial review. Use when tasks are complex enough to benefit from different models' strengths, when you want adversarial review to catch blind spots, or when coordinating multi-step workflows across agent roles. Triggers on complex projects, multi-step tasks, architecture decisions, or when explicitly requested.
Check color contrast ratios against WCAG AA and AAA accessibility standards. Use when the user wants to verify if their color combinations are accessible, check contrast between text and background colors, or audit a palette for accessibility.
Compare two images pixel-by-pixel and get a visual diff. Use when the user wants to compare their implementation against a design, spot differences between two screenshots, or verify visual regression.
Extract text from images using OCR. Use when the user shares a screenshot and you need to read the text content, copy UI labels, or extract copy from a design mockup.
Extract color palettes from images (screenshots, Figma exports, design mockups) to help implement matching UI. Use when the user shares a screenshot, design image, or asks to "match these colors", "extract colors from this image", "implement this design", or "get the color palette".
| name | web-design |
| description | Web design reference for building production-grade interfaces. Covers layout, typography, color, spacing, shadows, animation, accessibility, responsive design, components, performance, and UX psychology. Use when building UI, reviewing design quality, choosing design tokens, or making any visual design decision. |
| metadata | {"author":"pascalorg","version":"1.0.0"} |
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.
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.
<button>, <nav>, <main>, headings in order). Everything else builds on this.max-w-prose, 12-col grid). Does the page hold together at every viewport?auto-fill grids, clamp(), flex-wrap). No content hidden on small screens without reason.max-width: 65ch), rem units for font sizes.aria attributes, touch targets (44px+). Test with keyboard only.prefers-reduced-motion respected. Spring physics where appropriate.min-width: 0 on flex children, overflow-wrap: break-word, scrollbar-gutter: stable, text truncation, safe-area padding.Rule of thumb: If you're debating a shadow opacity while the layout breaks at 768px, stop and go back to Tier 1.
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 |
These CSS patterns create responsive layouts without media queries:
Stack -- Vertical flow with consistent gaps:
.stack > * + * { margin-block-start: var(--space); }
Cluster -- Horizontal wrapping with gaps:
.cluster { display: flex; flex-wrap: wrap; gap: var(--space); }
Sidebar -- Two columns where one is fixed:
.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:
.grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 250px), 1fr)); gap: var(--space); }
Center -- Constrained width with centering:
.center { max-inline-size: var(--measure); margin-inline: auto; padding-inline: var(--space); }
fr units over percentages in Grid -- fr distributes space after gaps, preventing overflow.gap instead of margins between items.min-width: 0 on flex children to prevent content overflow.align-self: start on sticky sidebar elements inside grid layouts.Page shell with sidebar:
<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:
<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:
<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>
Card with proper spacing hierarchy (outer > inner):
<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>
Use a mathematical ratio to generate harmonious font sizes. Choose the ratio based on context:
| Ratio | Name | Best For |
|---|---|---|
| 1.067 | Minor Second | Dense UI, dashboards |
| 1.125 | Major Second | Compact interfaces |
| 1.200 | Minor Third | General purpose (recommended default) |
| 1.250 | Major Third | Content-heavy sites |
| 1.333 | Perfect Fourth | Marketing, editorial |
| 1.414 | Augmented Fourth | Bold presentation |
| 1.500 | Perfect Fifth | Dramatic hierarchy |
| 1.618 | Golden Ratio | High-impact landing pages |
rem for font sizes. This respects both browser zoom and the user's default font size preference. Pixels prevent users from scaling text.rem for media queries. When users increase their default font size, rem-based breakpoints trigger mobile layouts on wider screens, giving them more room.px for padding, borders, and decorative elements. These shouldn't scale with text size.rem for vertical margins. Spacing between paragraphs should grow with text.Use clamp() for responsive sizing that scales smoothly between breakpoints:
/* Heading: 32px on small screens, 48px on large, fluid between */
font-size: clamp(2rem, 1.5rem + 2vw, 3rem);
Define a small-screen scale (e.g., 1.2x at 320px) and a large-screen scale (e.g., 1.333x at 1500px). The browser interpolates between them.
max-width: 65ch on content containers to enforce this.font-variant-numeric: tabular-nums in tables and timers so digits maintain consistent width./* 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; }
body { -webkit-font-smoothing: antialiased; }
html { text-rendering: optimizeLegibility; -webkit-text-size-adjust: 100%; }
::after pseudo-element with bold text to reserve the bold width, preventing jitter when toggling active states.Modern fonts ship with OpenType features that dramatically improve typographic quality. Enable them intentionally:
| Feature | CSS | Use |
|---|---|---|
| Tabular numbers | font-variant-numeric: tabular-nums | Tables, dashboards, pricing, timers -- equal-width digits align in columns |
| Oldstyle numbers | font-variant-numeric: oldstyle-nums | Body text/prose -- digits with ascenders/descenders blend with lowercase |
| Slashed zero | font-variant-numeric: slashed-zero | Code-adjacent UIs, IDs, error codes -- disambiguate 0 from O |
| Proper fractions | font-variant-numeric: diagonal-fractions | Recipes, specs -- converts 1/2 to typographic fraction |
| Contextual alternates | font-feature-settings: "calt" 1 | Usually on by default -- keep enabled for smart glyph adjustments |
| Disambiguation set | font-feature-settings: "ss02" | Code UIs -- distinguish I/l/1 and 0/O (font-dependent) |
/* 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.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.Font setup in 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>
)
}
Tailwind type scale in use (shadcn conventions):
{/* 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>
A working palette needs three categories:
For each color, define 9 shades numbered 50-900:
| Shade | Use |
|---|---|
| 50 | Subtle tinted backgrounds |
| 100 | Hover backgrounds, light fills |
| 200 | Active backgrounds, badges |
| 300 | Borders, rings |
| 400 | Placeholder text, disabled states |
| 500 | Primary buttons, icons, links |
| 600 | Hover on primary buttons |
| 700 | Active/pressed states |
| 800 | Heading text on light backgrounds |
| 900 | Body text on light backgrounds |
| 950 | Darkest shade for high contrast |
oklch(lightness chroma hue).: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));
}
#0a0a0a / #111 and #fafafa / #f5f5f5 instead.color-mix() for dynamic variations:background: color-mix(in oklch, var(--primary), transparent 95%);
#e5e5e5).prefers-color-scheme as the default. Don't add a theme toggle unless specifically needed.app/globals.css -- semantic color tokens (shadcn/ui pattern):
@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);
}
}
Dark mode toggle with next-themes (only add when users need manual control; system preference is the default):
// 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>
)
}
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);
opacity between two shadow states using pseudo-elements.Subtle layered box-shadow adds depth better than solid borders and adapts to any background through transparency:
/* 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);
0px 0px 0px 1px) acts as the border replacement — a zero-blur spread gives a crisp 1px edge.border-color would clash.box-shadow on hover for interactive lift. Use transition: box-shadow 150ms ease (or Tailwind's transition-shadow).Add a 1px outline to images for consistent visual framing and depth:
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); }
}
This is simpler than the inset ring technique and works on any <img> directly. Use outline-offset: -1px so the outline sits inside the image bounds.
Elevation classes from Tailwind mapped to use cases:
{/* 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">
Shadow instead of border (card with hover lift):
<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>
Image with inset outline (simple approach):
<img
src={src} alt={alt}
className="rounded-lg outline outline-1 -outline-offset-1 outline-black/10 dark:outline-white/10"
/>
Nested border radius (card with inner image):
{/* 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>
<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.Every interface needs exactly four text levels. More creates noise, fewer creates flatness:
{/* 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>
In dark mode, shadows are invisible. Instead, use lightness shifts to create depth. Each elevated layer gets a few percentage points brighter:
{/* 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>
The lightness difference between levels should be subtle (2-5% in OKLCH lightness). Larger jumps fragment the interface into disconnected "worlds."
| Easing | Use For |
|---|---|
ease-out | Elements entering the screen, appearing, expanding. Default choice. |
ease-in-out | Elements moving while already visible on screen. |
ease | Hover effects, color transitions. |
linear | Continuous/looping animations only (spinners, progress fills). |
ease-in | Elements leaving the screen. Never for elements that remain visible. |
Custom curves are strongly preferred over built-in CSS easings. Example production curve: cubic-bezier(0.32, 0.72, 0, 1) (iOS sheet behavior, used at 500ms).
| Context | Duration |
|---|---|
| Hover effects | 100-150ms |
| Button press feedback | ~160ms |
| Tooltip enter/exit | ~125ms |
| Dropdown/select open | ~180ms |
| General UI transitions | 150-300ms |
| Toast notifications | ~400ms |
| Drawer/sheet open | ~500ms |
| Hold-to-confirm (destructive) | 2000ms (safety) |
| Hold release feedback | 200ms |
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.Scale on press: scale(0.97) on :active for instant tactile feedback.
Never scale from 0. Start from scale(0.9) or higher. Even a deflated balloon has a visible shape.
Origin-aware popover: Scale from the trigger point using transform-origin, not center.
Tooltip delay pattern: First tooltip shows with delay. Subsequent tooltips while hovering appear instantly.
Blur as rescue: When easing adjustments still feel off, add filter: blur(2px) during the transition.
Use clip-path for reveals: Hardware-accelerated with no layout shifts. clip-path: inset(0 0 100% 0) to inset(0 0 0 0).
Make animations interruptible. CSS transitions interpolate toward the latest state and can be interrupted mid-action — use them for interactions (hovers, toggles, drags). CSS keyframe animations run a fixed timeline and cannot retarget — use them for staged sequences that play once (page load entrances, celebration effects). Users change intent mid-interaction; interruptible animations feel responsive, non-interruptible ones feel broken.
Animate icons contextually. When icons appear or disappear conditionally (e.g., a checkmark replacing a copy icon), animate opacity, scale, and blur together for a smooth transition instead of an instant swap. Use spring physics or short transitions (150-200ms). This applies to any element that swaps in/out based on state.
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).type: "spring" with stiffness: 300, damping: 20 is a good starting point.transform (translate, rotate, scale) -- GPU-acceleratedopacity -- GPU-acceleratedclip-path -- GPU-acceleratedwidth, height, padding, margin -- triggers layout recalculationtop, left, right, bottom -- triggers layout recalculationbackground-color -- triggers repaint (expensive)requestAnimationFrame (worst -- lags when browser is busy)Always respect 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;
}
}
Button with press feedback (CSS only, Tailwind). Duration matches the ~160ms guideline (Tailwind's closest: 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>
Animated dialog with Framer Motion + shadcn:
"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>
)
}
Staggered list entrance:
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>
)
}
Staggered entrance with blur (CSS-only, higher impact):
@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>
Subtle exit animation (Framer Motion — less motion than entrance):
<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>
Skeleton loading with Tailwind animate-pulse:
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>
)
}
Choose the right timing model based on what drives the motion:
| Motion Type | Use | Why |
|---|---|---|
| User-driven (drag, flick, swipe) | Spring | Survives interruption, preserves velocity |
| System-driven (state change, feedback) | Easing | Clear start/end, predictable timing |
| Time representation (progress, loading) | Linear | 1:1 relationship between time and progress |
| High-frequency (typing, fast toggles) | None | Animation adds noise, feels slower |
| Keyboard-initiated actions | None | Must feel instant and connected to input |
Spring parameter guidance: Start with stiffness: 300, damping: 20 (slight bounce) or stiffness: 500, damping: 30 (snappy, minimal overshoot). Avoid damping < 10 with high stiffness -- creates excessive oscillation. Always pass velocity from drag events to preserve input energy:
onDragEnd={(e, info) => {
animate(target, { x: 0 }, {
type: "spring",
velocity: info.velocity.x,
stiffness: 500,
damping: 30,
});
}}
When an animation feels slow, shorten the duration first -- don't change the easing curve. The duration is almost always the problem.
Animating width or height triggers layout recalculation. Use this pattern instead:
Two-div pattern: Outer div animates (via motion.div), inner div measures (via ref). Never measure and animate the same element -- it creates a feedback loop.
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>
)
}
Measurement hook using ResizeObserver (not getBoundingClientRect which causes layout thrashing):
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]
}
useRef) so the observer attaches when the DOM node is ready.overflow: hidden on the animated container to clip content during transitions.bounds === 0 on initial render -- fall back to "auto" height.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.useIsPresent() and set disabled={!isPresent} or pointer-events: none on elements during their exit animation -- otherwise users click elements that are animating away.propagate prop so parent exit triggers child exits.y: -12px instead of full distance, add blur(4px) to soften).For page-level and cross-document transitions, prefer the native View Transitions API over JS animation libraries:
/* 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);
}
view-transition-name must be unique during a transition (no two elements can share the same name simultaneously).Dialog.Root, Dialog.Trigger, Dialog.Content, Dialog.Title. Each part is independently addressable.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)) }
.button { background: var(--button-bg, var(--primary)); }
See the full token set in Section 3: In Practice. The standard semantic tokens are: --background, --foreground, --card, --primary, --secondary, --muted, --accent, --destructive, --border, --input, --ring, --radius (each with a -foreground counterpart where applicable). Values use OKLCH format.
min-width instead of fixed width to accommodate varying label lengths.label using for/id.fieldset and legend for grouped inputs.input, button, textarea, select { font: inherit; }aria-describedby.autocomplete attributes for familiar fields (name, email, address).:-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);
}
The inset box-shadow covers Chrome's blue background. -webkit-text-fill-color forces your text color (regular color gets overridden). The transition: background-color 5000s delays Chrome's background change indefinitely. Target all four states (base, hover, focus, active) or Chrome re-applies its styles on interaction. Caveat: the 5000s transition delay means autofilled backgrounds won't update on live theme switches (light/dark toggle) — only affects sites with runtime theme toggling.
viewBox: All icons in a set should share the same viewBox (typically 0 0 24 24).display: inline-flex; align-items: center and occasionally a -1px to -2px vertical offset for visual centering.text-muted-foreground color.aria-hidden="true" on decorative icons. Provide aria-label on icon-only buttons.font-variant-numeric: tabular-nums so digits maintain equal width across rows.<table>, <thead>, <tbody>, <th scope="col">, <caption>..table-wrapper { overflow-x: auto; -webkit-overflow-scrolling: touch; }
thead th { position: sticky; top: 0; } for long scrollable tables.animate-pulse), not harsh gradient sweeps.rgba(0,0,0,0.5) or backdrop-filter: blur(4px)).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.isolation: isolate on the app root prevents z-index conflicts with portaled modals.Form with validation (React Hook Form + Zod + shadcn):
"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>
)
}
Empty state component:
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>
)
}
Data table with shadcn (key patterns):
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>
)
}
Loading with delayed spinner (prevents flash):
"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" />
}
Define breakpoints based on content needs, not device names. Use the fewest breakpoints necessary.
| Token | Width | Typical Use |
|---|---|---|
| sm | 640px (40rem) | Phone landscape |
| md | 768px (48rem) | Tablet portrait |
| lg | 1024px (64rem) | Tablet landscape / small laptop |
| xl | 1280px (80rem) | Desktop |
| 2xl | 1536px (96rem) | Large desktop |
rem for breakpoint values so layouts respond to user font size preferences.@container (min-inline-size: 400px) {
.card { flex-direction: row; }
}
auto-fill/auto-fit grids, flex-wrap, and clamp() to create layouts that adapt without media queries.@media (hover: hover) and @media (pointer: coarse) to adapt for touch vs. mouse:@media (pointer: coarse) {
.button { min-height: 48px; }
}
Responsive card layout (mobile stack -> desktop grid):
<div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
{items.map(item => <Card key={item.id} {...item} />)}
</div>
Navigation that adapts (sidebar on desktop, sheet on mobile):
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>
)
}
Container query with Tailwind (component adapts to parent width):
<div className="@container">
<div className="flex flex-col @md:flex-row @md:items-center gap-4">
<img className="w-full @md:w-48 rounded-lg" src={src} alt={alt} />
<div className="space-y-2">
<h3 className="font-semibold">{title}</h3>
<p className="text-sm text-muted-foreground">{description}</p>
</div>
</div>
</div>
| Element | AA Minimum | AAA Minimum |
|---|---|---|
| Normal text | 4.5:1 | 7:1 |
| Large text (18px+ bold, 24px+) | 3:1 | 4.5:1 |
| UI components and icons | 3:1 | -- |
| Input borders | 3:1 | -- |
:focus-visible (not :focus) to show outlines only for keyboard users::focus-visible { outline: 2px solid var(--ring); outline-offset: 2px; }
order to reorder content in a way that breaks keyboard navigation.Escape to close overlays, Enter/Space to activate buttons.<header>, <nav>, <main>, <footer>, <aside>.<h1> per page, no skipped levels.<button> for actions, <a> for navigation.<ul>/<ol> for lists, <table> for tabular data.lang attribute on <html>.<title> for each page.<img> needs an alt attribute. Decorative images get alt="".width and height to images to prevent layout shift.aria-describedby to connect error messages to inputs.aria-busy="true" on the loading region, plus visible status text.aria-describedby, not just visual proximity.prefers-reduced-motion. Reduce or remove non-essential animation./* Small checkbox (20×20) with expanded 44×44 hit area */
.checkbox {
position: relative;
width: 20px;
height: 20px;
}
.checkbox::after {
content: "";
position: absolute;
top: 50%;
left: 50%;
transform: translate(-50%, -50%);
width: 44px;
height: 44px;
}
Tailwind equivalent:
<button class="relative size-5 after:absolute after:top-1/2 after:left-1/2 after:size-11 after:-translate-1/2">
<CheckIcon />
</button>
gap-y-px look separated but should feel continuous — expand hit areas to cover the gaps so there are no dead spots between items.hit-area utilities (bazza.dev/r/hit-area) for a Tailwind-native approach. Install via npx shadcn@latest add https://bazza.dev/r/hit-area. Supports uniform (hit-area-4), directional (hit-area-l-8 hit-area-r-4), axis (hit-area-x-4 hit-area-y-6), and custom (hit-area-[21px]) expansion. Use hit-area-debug to visualize during development.| Metric | Good | Description |
|---|---|---|
| LCP | < 2.5s | Largest Contentful Paint (loading) |
| INP | < 200ms | Interaction to Next Paint (responsiveness) |
| CLS | < 0.1 | Cumulative Layout Shift (visual stability) |
width and height on all images to prevent layout shift.loading="lazy" on below-fold images.max-width: 100% and display: block to all media elements.font-display: swap to prevent invisible text during font loading.transform, opacity, and clip-path for 60fps performance.will-change: transform sparingly to hint GPU acceleration.content-visibility: auto for off-screen content to skip rendering.scrollbar-gutter: stable to prevent layout shift when scrollbars appear.transition: all. Be explicit about which properties animate.getBoundingClientRect() then writing style.left in the same frame causes layout thrashing. Batch all reads before all writes.will-change only during active animation. Add on mouseenter, remove on transitionend. Never leave it on permanently.h-dvh instead of h-screen in Tailwind. dvh accounts for mobile browser chrome (address bar, toolbar). h-screen causes content to be hidden behind browser UI on mobile.srcset and sizes attributes.aspect-ratio: 16/9.object-fit: cover to handle unexpected aspect ratios.Next.js Image component (handles srcset, WebP/AVIF, lazy loading):
import Image from "next/image"
// Replaces <img> — automatically optimized, lazy-loaded, prevents CLS
<Image
src="/hero.jpg"
alt="Product screenshot"
width={1200}
height={630}
className="rounded-lg"
priority // Add for above-fold hero images only
/>
// For fill mode (unknown dimensions):
<div className="relative aspect-video">
<Image src={url} alt={alt} fill className="object-cover rounded-lg" />
</div>
Font optimization in Next.js (automatic subsetting + swap):
// next/font handles subsetting, font-display: swap, and self-hosting automatically
import { Inter } from "next/font/google"
const inter = Inter({ subsets: ["latin"] })
// Generates: font-display: swap, optimal subsetting, no layout shift
Dynamic imports for heavy components:
import dynamic from "next/dynamic"
// Chart library only loads when needed, with skeleton fallback
const Chart = dynamic(() => import("@/components/chart"), {
loading: () => <div className="h-64 animate-pulse rounded-lg bg-muted" />,
ssr: false,
})
Optimistic update pattern (React):
"use client"
import { useOptimistic } from "react"
function TodoList({ todos, addTodo }) {
const [optimisticTodos, addOptimistic] = useOptimistic(
todos,
(state, newTodo) => [...state, { ...newTodo, pending: true }]
)
async function handleAdd(formData) {
const todo = { text: formData.get("text"), id: crypto.randomUUID() }
addOptimistic(todo) // Show immediately
await addTodo(todo) // Server action — rolls back on error
}
return (
<ul className="space-y-1">
{optimisticTodos.map(todo => (
<li key={todo.id} className={todo.pending ? "opacity-50" : ""}>
{todo.text}
</li>
))}
</ul>
)
}
Fitts's Law. The time to reach a target depends on distance and size. Make important actions large and close to the cursor. Reduce distance to common targets. Edge/corner placement in desktop interfaces gives "infinite" dimension along one axis.
Hick's Law. Decision time increases with the number and complexity of choices. Minimize choices at each step. Break complex tasks into smaller decisions. Use progressive disclosure. Recommend defaults.
Miller's Law. Working memory holds roughly 7 (+/-2) items. Chunk information into digestible groups. Don't use this as an excuse to limit UI to 7 items -- use it to inform grouping strategy.
Jakob's Law. Users spend most of their time on other sites. They expect yours to work the same way. Follow platform conventions. Don't innovate on interaction patterns without good reason.
Doherty Threshold. Productivity soars when system response time is under 400ms. Use skeleton screens, optimistic updates, and loading indicators to maintain perceived speed.
Aesthetic-Usability Effect. Users perceive attractive designs as more usable. Invest in visual polish -- it directly affects perceived quality and user patience with issues.
Von Restorff Effect (Isolation Effect). The item that stands out from a group is most remembered. Use visual distinctiveness for the most important element (CTA, key metric).
Peak-End Rule. People judge experiences by the peak moment and the ending, not the average. Invest disproportionately in climactic moments and final impressions.
Zeigarnik Effect. People remember incomplete tasks better than complete ones. Progress bars and step indicators use this to drive completion.
Tesler's Law (Conservation of Complexity). Every system has irreducible complexity. The question is who bears it -- the user or the system. Absorb complexity in the implementation so the interface stays simple.
Postel's Law. Be liberal in what you accept, strict in what you produce. Accept varied input formats. Output clean, consistent formats.
Choice Overload. Too many options overwhelm users and reduce satisfaction. Enable filtering, recommend defaults, break complex decisions into steps.
Goal-Gradient Effect. People accelerate as they approach a goal. Show progress bars, pre-fill partial progress, and keep multi-step processes visible.
Serial Position Effect. Users remember the first and last items in a list best. Place key navigation items at the beginning and end. Put less important items in the middle.
Pareto Principle (80/20). 80% of usage comes from 20% of features. Identify and optimize the critical 20%.
Selective Attention (Banner Blindness). Users ignore anything that looks like an ad. Don't style real content like advertisements.
Organize tokens in layers:
--blue-500: #3b82f6. These are the palette.--color-primary: var(--blue-500). These encode meaning.--button-bg: var(--color-primary). These allow component-level overrides.Color: background, foreground, primary, secondary, muted, accent, destructive, border, input, ring, plus semantic (success, warning, info, error).
Typography: font-family (sans, heading, mono), font sizes (xs through 4xl), font weights (normal, medium, semibold, bold), line heights, letter spacings.
Spacing: Based on 4px grid (see Section 1).
Borders: radius (sm, md, lg, xl, full), width (1px, 2px), color (from color tokens).
Shadows: sm, md, lg, xl, 2xl (see Section 4).
Motion: Duration (fast: 150ms, normal: 250ms, slow: 500ms), easing functions.
Z-index: Layered scale: base(0), dropdown(1000), sticky(1100), modal(1200), popover(1300), toast(1400).
:root {
/* Primitives */
--gray-50: #fafafa;
--gray-900: #171717;
--blue-500: #3b82f6;
/* Semantic */
--background: var(--gray-50);
--foreground: var(--gray-900);
--primary: var(--blue-500);
/* Component */
--button-bg: var(--primary);
--button-text: white;
--card-bg: var(--background);
--card-border: var(--gray-200);
}
.dark {
--background: var(--gray-900);
--foreground: var(--gray-50);
--primary: var(--blue-400);
}
Change token values at breakpoints without touching components:
:root {
--space-section: 2rem;
--text-hero: 2rem;
}
@media (min-width: 768px) {
:root {
--space-section: 4rem;
--text-hero: 3.5rem;
}
}
The difference between amateur and professional design is the accumulation of hundreds of small, intentional decisions. No single detail transforms a product, but their aggregate creates the feeling of quality users describe as "this just feels right."
| Amateur | Professional |
|---|---|
| Arbitrary animation duration | Deliberate durations: 100-300ms range, scaled to trigger size |
| Layout shifts during state changes | Hidden pseudo-elements reserve bold text width |
| Hard borders on images | Inset box-shadow with semi-transparent color |
| Hit targets match visual size exactly | Invisible ::before expands clickable area |
| Neglects error pages, empty states, footers | Every screen is a craft opportunity |
| Hover effects fire on touch devices | @media (hover: hover) isolates hover states |
| CSS transitions fire during theme changes | Disable transitions, apply theme, re-enable one frame later |
| Same animation for all interactions | Minimize motion for frequent actions; reserve it for meaningful state changes |
Dropdowns open on click | Trigger on mousedown for perceived immediacy |
| Waits for server to update UI | Optimistic updates with rollback on error |
::selection for brand consistency (but ensure sufficient contrast).prefers-color-scheme media query inside SVG for adaptive favicons.Accent border card (left-side colored bar):
<div className="rounded-lg border-l-4 border-l-blue-500 bg-card p-4 shadow-sm">
<h3 className="font-semibold">New deployment</h3>
<p className="text-sm text-muted-foreground">Production build completed in 42s.</p>
</div>
Image with natural inset border (no hard edges):
<div className="relative overflow-hidden rounded-lg">
<img src={src} alt={alt} className="w-full" />
<div className="absolute inset-0 rounded-lg ring-1 ring-inset ring-black/5" />
</div>
Hover-only effects isolated from touch (Tailwind):
<button className="rounded-lg bg-secondary px-4 py-2
transition-colors
hover:[@media(hover:hover)]:bg-secondary/80
active:scale-[0.97]">
Action
</button>
Custom selection color in globals.css:
::selection { background-color: oklch(0.8 0.1 250); color: oklch(0.2 0 0); }
Skip link for keyboard users:
<a href="#main" className="sr-only focus:not-sr-only focus:fixed focus:top-4 focus:left-4
focus:z-50 focus:rounded-lg focus:bg-background focus:px-4 focus:py-2 focus:text-sm
focus:shadow-lg focus:ring-2 focus:ring-ring">
Skip to content
</a>
<main id="main">{children}</main>
Responsive SVG favicon with dark mode (app/icon.svg):
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
<style>
circle { fill: #111 }
@media (prefers-color-scheme: dark) { circle { fill: #eee } }
</style>
<circle cx="16" cy="16" r="14" />
</svg>
| Pattern | Example |
|---|---|
| Single-word verbs | Save, Copy, Delete, Join, Share |
| Short phrases | Join waitlist, Get started, Learn more |
| State-changing labels | Copy -> Copied, Save -> Saved, Send -> Sent |
| Directional navigation | Previous / Next, Back / Continue |
Patterns that AI code generators default to that look generic, low-quality, or obviously machine-made. Avoid these.
h-screen. Use h-dvh (dynamic viewport height). h-screen hides content behind mobile browser chrome.z-[9999]. Use the token scale: dropdown(1000), sticky(1100), modal(1200), popover(1300), toast(1400).transition-all. Specify exactly which properties transition.useEffect for render logic. Derived state should be computed during render, not in effects.Before considering UI work done, check:
Techniques that separate polished production interfaces from prototypes.
Tailwind's default shadows use grey. For richer depth, tint shadows with the background's hue:
:root {
--shadow-color: 220deg 60% 50%; /* match your background hue */
}
.card-natural-shadow {
box-shadow:
0 1px 1px hsl(var(--shadow-color) / 0.075),
0 2px 2px hsl(var(--shadow-color) / 0.075),
0 4px 4px hsl(var(--shadow-color) / 0.075),
0 8px 8px hsl(var(--shadow-color) / 0.075);
}
Change --shadow-color per section or theme to keep shadows coherent with their environment. In dark mode, replace shadows with subtle border + lighter surface (bg-card) since shadows lose visual logic on dark backgrounds.
To create color states from a single base color (in HSB/HSL):
{/* Primary button with derived hover/active states */}
<button className="bg-blue-600 hover:bg-blue-700 active:bg-blue-800
text-white transition-colors">
Confirm
</button>
{/* Tinted background from same color family */}
<div className="bg-blue-50 text-blue-700 dark:bg-blue-950 dark:text-blue-300 rounded-lg p-4">
Info message using the same blue family at lower intensity.
</div>
Standard CSS gradients interpolate in sRGB, causing muddy midpoints between saturated colors. Fix by specifying OKLCH interpolation:
/* Muddy (default sRGB interpolation) */
background: linear-gradient(to right, #ff0 , #00f);
/* Clean (perceptually uniform) */
background: linear-gradient(to right in oklch, oklch(0.9 0.4 110), oklch(0.5 0.3 264));
In Tailwind, use arbitrary values:
<div className="bg-[linear-gradient(to_right_in_oklch,oklch(0.8_0.15_200),oklch(0.7_0.2_280))]" />
CSS border-radius creates a circular arc that meets the straight edge at a hard tangent point. iOS uses a superellipse (squircle) that starts curving before the arc, creating a smoother, more organic shape.
CSS-only approach (good enough for most cases): Use larger radii. A border-radius of ~22-28% of the smaller dimension approximates the squircle feel. Tailwind's rounded-2xl (16px) to rounded-3xl (24px) on cards looks close on typical card sizes.
For pixel-perfect iOS fidelity, use a clip-path with an SVG superellipse or the figma-squircle package:
import { getSvgPath } from "figma-squircle"
function Squircle({ width, height, children }) {
const path = getSvgPath({
width, height,
cornerRadius: 20,
cornerSmoothing: 0.6, // 0 = CSS radius, 1 = full squircle
})
return (
<div style={{ clipPath: `path('${path}')`, width, height }}>
{children}
</div>
)
}
When it matters: App icons, hero cards, and premium product images. For standard UI cards, rounded-xl or rounded-2xl is sufficient.
<div className="rounded-xl border border-white/20 bg-white/10 p-6
backdrop-blur-xl shadow-xl">
<h3 className="font-semibold text-white">Glass Card</h3>
</div>
Rules:
backdrop-blur-md (12px) for subtle, backdrop-blur-xl (24px) for strong frosting.bg-white/10 to bg-white/20).border border-white/20 for the glass edge catch.backdrop-filter is GPU-intensive.backdrop-filter support, you get a semi-transparent card (still usable).Flat surfaces can feel sterile. A subtle noise overlay adds organic warmth:
.textured {
position: relative;
}
.textured::after {
content: '';
position: absolute;
inset: 0;
background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.7' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E");
opacity: 0.03;
pointer-events: none;
mix-blend-mode: overlay;
border-radius: inherit;
}
Keep opacity between 0.02-0.05. Higher makes the surface look dirty.
Fade content at scroll container boundaries:
<div className="relative max-h-64 overflow-y-auto
[mask-image:linear-gradient(to_bottom,transparent,black_16px,black_calc(100%-16px),transparent)]">
{/* scrollable content */}
</div>
For image containers and avatar frames, an inset ring looks more natural than a border because it doesn't add to the element's dimensions and blends with the content:
{/* Hard border (adds 2px to dimensions, feels rigid) */}
<img className="rounded-full border-2 border-gray-200" />
{/* Inset ring (no dimension change, blends naturally) */}
<div className="relative rounded-full overflow-hidden">
<img className="rounded-full" src={src} alt={alt} />
<div className="absolute inset-0 rounded-full ring-1 ring-inset ring-black/10" />
</div>
{/* Shorthand for non-image elements */}
<div className="rounded-lg shadow-[inset_0_0_0_1px_rgba(0,0,0,0.06)]">
Use @property to enable animation on custom properties and catch invalid values:
@property --gradient-angle {
syntax: "<angle>";
initial-value: 0deg;
inherits: false;
}
.rotating-border {
--gradient-angle: 0deg;
border-image: conic-gradient(from var(--gradient-angle), #e92a67, #a853ba, #2a8af6, #e92a67) 1;
animation: rotate-gradient 3s linear infinite;
}
@keyframes rotate-gradient {
to { --gradient-angle: 360deg; }
}
Without @property, CSS can't interpolate custom properties -- the animation would snap between values instead of transitioning smoothly.
Polished buttons use six layered techniques working together to mimic real-world light physics:
.button-polished {
/* Subtle gradient for dimension */
background: linear-gradient(
to bottom,
color-mix(in oklch, var(--primary), white 4%),
var(--primary)
);
box-shadow:
/* 1. Outer cut: thin dark edge */
0 0 0 0.5px rgba(0, 0, 0, 0.15),
/* 2. Inner ambient highlight: light from all sides */
inset 0 0 0 1px rgba(255, 255, 255, 0.08),
/* 3. Inner top highlight: primary light from above */
inset 0 1px 0 rgba(255, 255, 255, 0.15),
/* 4-6. Layered depth shadows */
0 1px 2px rgba(0, 0, 0, 0.15),
0 2px 4px rgba(0, 0, 0, 0.1),
0 4px 8px rgba(0, 0, 0, 0.05);
/* Text shadow for contrast */
text-shadow: 0 1px 1px rgba(0, 0, 0, 0.1);
}
This technique replaces flat buttons with physically convincing depth. The gradient adds dimension, the inset shadows simulate environmental and directional light, and the outer shadows create depth.
Use alpha-based border colors instead of hardcoded hex values. Semi-transparent borders adapt automatically to any background:
/* Hardcoded (breaks on different backgrounds) */
border: 1px solid #e5e5e5;
/* Adaptive (works on any background) */
border: 1px solid rgba(0, 0, 0, 0.12);
/* Dark mode equivalent */
border: 1px solid rgba(255, 255, 255, 0.12);
This removes the need for separate light/dark border tokens in many cases.
Native pseudo-elements and selectors that reduce DOM complexity:
::marker for custom list bullets -- replaces background-image hacks:li::marker { color: var(--muted-foreground); font-size: 0.8em; }
::first-line for typographic treatments -- automatically adapts when viewport changes:.article p:first-of-type::first-line {
font-variant-caps: small-caps;
font-weight: 500;
}
::backdrop for dialog/popover overlays -- replaces extra overlay divs:dialog::backdrop { background: rgba(0, 0, 0, 0.5); backdrop-filter: blur(4px); }
::placeholder for input styling (keep at lower contrast than actual input text).Small corrections the eye expects but math doesn't provide:
rounded-full) need slightly more horizontal padding than their border-radius suggests -- add 2-4px extra.leading-none and manually center with padding.Patterns that prevent common layout breakage:
/* Prevent flex items from overflowing */
.flex-child { min-width: 0; overflow-wrap: break-word; }
/* Prevent images from breaking layout */
img { max-width: 100%; display: block; object-fit: cover; }
/* Prevent scroll chaining through modals */
.modal { overscroll-behavior: contain; }
/* Always use auto overflow, not scroll */
.scrollable { overflow-y: auto; }
/* Reserve scrollbar space to prevent layout shift */
.page { scrollbar-gutter: stable; }
/* Use min-height, not height, for variable content */
.hero { min-height: 400px; } /* NOT height: 400px */
/* Use min-width, not width, for buttons */
.button { min-width: 100px; } /* NOT width: 100px */
/* Fallback backgrounds for failed images */
.card-image { background-color: var(--muted); }
/* Fallback for CSS variables */
.element { width: var(--sidebar-width, 250px); }
/* Prevent flex containers from hiding overflow */
.grid-child { min-width: 0; }
/* Use auto-fill to prevent stretching with few items */
grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
/* Sticky elements in grid need align-self */
.sidebar { align-self: start; position: sticky; top: 1rem; }
/* Single-line text truncation */
.truncate { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
/* Multi-line text truncation (e.g., 3 lines) */
.line-clamp-3 {
display: -webkit-box;
-webkit-box-orient: vertical;
-webkit-line-clamp: 3;
overflow: hidden;
}
/* Safe area padding for full-bleed layouts on notched devices */
.safe-area { padding: env(safe-area-inset-top) env(safe-area-inset-right) env(safe-area-inset-bottom) env(safe-area-inset-left); }
/* Never use arbitrary z-index values. Always map to a token layer. */
/* z-base: 0, z-dropdown: 1000, z-sticky: 1100, z-modal: 1200, z-popover: 1300, z-toast: 1400 */
A sensible starting point for any project:
/* 1. Use border-box for everything */
*, *::before, *::after { box-sizing: border-box; }
/* 2. Remove default margins */
* { margin: 0; }
/* 3. Enable smooth keyword animations (respects motion prefs) */
@media (prefers-reduced-motion: no-preference) {
html { interpolate-size: allow-keywords; }
}
/* 4. Accessible body defaults */
body {
line-height: 1.5;
-webkit-font-smoothing: antialiased;
}
/* 5. Responsive media */
img, picture, video, canvas, svg {
display: block;
max-width: 100%;
}
/* 6. Form elements inherit fonts */
input, button, textarea, select { font: inherit; }
/* 7. Prevent text overflow */
p, h1, h2, h3, h4, h5, h6 { overflow-wrap: break-word; }
/* 8. Better text wrapping */
p { text-wrap: pretty; }
h1, h2, h3, h4, h5, h6 { text-wrap: balance; }
/* 9. Root stacking context */
#root, #__next { isolation: isolate; }
Loading content before the user clicks by analyzing cursor trajectory, reducing perceived latency by 100-200ms.
Standard hover-based prefetching (onMouseEnter) waits until the user has stopped moving and is already on the element. Trajectory prediction calculates where the cursor is heading while still in motion, reclaiming the ~100-200ms that hover-based approaches waste.
// Hover-based (too late — fires after the user has arrived)
<Link href="/about" onMouseEnter={() => router.prefetch("/about")}>About</Link>
// Trajectory-based (fires while cursor is still moving toward the element)
const { elementRef } = useForesight({
callback: () => router.prefetch("/about"),
hitSlop: 20, // expand invisible prediction area by 20px
name: "about-link",
})
<Link ref={elementRef} href="/about">About</Link>
hitSlop to start predictions earlier. Expanding the invisible area (e.g., 20px) around elements begins loading sooner without visual changes.touchstart or viewport-based strategies.Reference: ForesightJS
Audio is a UI tool, not decoration. Used correctly, it reinforces actions and creates a sense of physical interaction. Used incorrectly, it annoys.
| Interaction | Sound? | Reason |
|---|---|---|
| Payment success | Yes | Significant confirmation |
| Form submission | Yes | User needs assurance |
| Error state | Yes | Can't be overlooked |
| Notification | Yes | User may not be looking at screen |
| Significant button (e.g., send) | Maybe | Only for milestone actions |
| Typing | No | Too frequent |
| Hover | No | Decorative, no informational value |
| Scroll | No | Too frequent |
| Navigation | No | Keyboard nav would be noisy |
prefers-reduced-motion -- reduce or disable sound alongside motion.// Preload sounds to avoid first-play delay
const sounds = {
success: new Audio("/sounds/success.mp3"),
error: new Audio("/sounds/error.mp3"),
click: new Audio("/sounds/click.mp3"),
}
Object.values(sounds).forEach(a => { a.volume = 0.3; a.load() })
function playSound(name: keyof typeof sounds) {
sounds[name].currentTime = 0 // reset so rapid re-triggering works
sounds[name].play()
}
currentTime = 0 before every play for rapid re-triggering.For UI sounds without audio files -- generate clicks and tones programmatically:
// Singleton AudioContext (never create per sound)
let ctx: AudioContext | null = null
function getCtx() { return ctx ??= new AudioContext() }
// Click sound: filtered noise burst (5-15ms)
function playClick() {
const ctx = getCtx()
if (ctx.state === "suspended") ctx.resume()
const buffer = ctx.createBuffer(1, ctx.sampleRate * 0.008, ctx.sampleRate)
const data = buffer.getChannelData(0)
for (let i = 0; i < data.length; i++) {
data[i] = (Math.random() * 2 - 1) * Math.exp(-i / 50)
}
const source = ctx.createBufferSource()
source.buffer = buffer
const filter = ctx.createBiquadFilter()
filter.type = "bandpass"
filter.frequency.value = 4000 // 3000-6000Hz for crisp clicks
filter.Q.value = 3 // 2-5 for focused but natural
const gain = ctx.createGain()
gain.gain.setValueAtTime(0.3, ctx.currentTime)
gain.gain.exponentialRampToValueAtTime(0.001, ctx.currentTime + 0.05)
source.connect(filter).connect(gain).connect(ctx.destination)
source.start()
source.onended = () => { source.disconnect(); filter.disconnect(); gain.disconnect() }
}
// Tonal sound: oscillator with pitch sweep (confirmations, pops)
function playTone() {
const ctx = getCtx()
if (ctx.state === "suspended") ctx.resume()
const t = ctx.currentTime
const osc = ctx.createOscillator()
osc.frequency.setValueAtTime(400, t)
osc.frequency.exponentialRampToValueAtTime(600, t + 0.04) // upward sweep
const gain = ctx.createGain()
gain.gain.setValueAtTime(0.3, t)
gain.gain.exponentialRampToValueAtTime(0.001, t + 0.08)
osc.connect(gain).connect(ctx.destination)
osc.start(t)
osc.stop(t + 0.08)
osc.onended = () => { osc.disconnect(); gain.disconnect() }
}
Key rules for Web Audio:
AudioContext -- never create per sound (browser limits to ~6).ctx.state === "suspended"). Browsers suspend AudioContext until user interaction.0.001 (not 0 -- exponential ramps can't reach zero).| User Feedback | Fix |
|---|---|
| "too harsh" | Lower filter frequency, reduce Q |
| "too muffled" | Higher filter frequency |
| "too long" | Shorter buffer duration, faster decay |
| "cuts off abruptly" | Use exponential decay instead of linear |
| "more mechanical" | Higher Q, faster decay |
| "softer" | Lower gain, use triangle wave |
| Property | Recommended Default |
|---|---|
| Body font size | 16px (1rem) |
| Body line height | 1.5 |
| Heading line height | 1.1 - 1.25 |
| Max content width | 65ch |
| Spacing base unit | 4px |
| Border radius (sm) | 4px |
| Border radius (md) | 8px |
| Border radius (lg) | 12px |
| Border radius (full) | 9999px |
| Border radius (shadcn default) | 0.625rem (10px) |
| Transition (fast) | 150ms ease-out |
| Transition (normal) | 250ms ease-out |
| Transition (slow) | 500ms ease-out |
| Min touch target | 44px (48px preferred) |
| Min contrast (text) | 4.5:1 |
| Min contrast (large text) | 3:1 |
| Min contrast (UI elements) | 3:1 |
| Max line length | 60-75 characters optimal, 80 max |
| Button/input height | 32-36px (standard), 40px (comfortable) |
| Icon sizes | 16px (dense), 20px (default), 24px (prominent) |
| Button padding ratio | 2x horizontal : 1x vertical |
| Shadow blur ratio | 2x the offset distance |
| Spinner delay | 400ms before showing |
| System response target | < 400ms (Doherty Threshold) |
| Color format | OKLCH (preferred), HSL (alternative) |
| Focus ring | 2px solid, 2px offset |
| Z-index layers | dropdown:1000, sticky:1100, modal:1200, popover:1300, toast:1400 |