frontend-design

Great interfaces are a collection of small, intentional details that compound. Apply this doctrine when building or reviewing any UI.

DESIGN.md wins. If this repo has a DESIGN.md, its fonts, tokens, budgets, and recipes override everything below — this skill covers the craft layer underneath any design language. Express every change in the styling system the project already uses (Tailwind, CSS Modules, styled-components, plain CSS); never introduce a second one for a fix.

Direction

Before coding a new surface, commit to a clear aesthetic point of view — the repo's DESIGN.md if one exists, otherwise a deliberate choice for the context. Intentionality matters more than intensity: refined minimalism and bold maximalism both work; timid, evenly-distributed defaults do not. Never ship generic AI aesthetics: stock font stacks chosen by habit, purple-gradient-on-white, cookie-cutter card grids with no context-specific character. Match implementation effort to the vision — maximalist designs need elaborate effects, minimal ones need precision in spacing and type.

Typography

Good typography is mostly restraint: a sensible scale, comfortable spacing, enough contrast.

Few fonts, few weights. Rarely more than two or three families. Pair for contrast (display vs body), not similarity. Hierarchy comes from size and weight used sparingly.
Scale, not one-offs. Sizes come from the project's type scale. Heading sizes descend with level — pick the tag from the document outline, control size with CSS, never skip levels.
Line-height by role. Headings ~1.1, body 1.5–1.6, always unitless.
Letter-spacing by size. Slightly negative on large headings, slightly positive on small uppercase labels, neither on body.
Cap the measure. Long-form text at 60–75 characters per line (max-w-2xl at 16px body, or 65ch).
Wrap deliberately. text-wrap: balance on headings, text-wrap: pretty on descriptions; neither in long-form text.
Tabular numbers on anything that changes. tabular-nums on timers, counters, prices, table columns.
Natural case in copy. Store text in sentence case; uppercase via text-transform only where the design language sanctions it.
Mechanics. .woff2 for web fonts. CSS properties over raw tags (font-weight: 650, font-variant-numeric: tabular-nums — not font-variation-settings/font-feature-settings). font-synthesis: none so missing weights fail visibly. antialiased once on the root layout. Inputs ≥ 16px on mobile (text-base sm:text-sm) or iOS zooms. Body ≥ 16px; contrast ≥ 4.5:1 (3:1 for large text).

Surfaces

Concentric radius. When nesting rounded elements: outer = inner + padding. Matching radii on parent and child is the most common thing that makes UI feel subtly off. Derive radii from the project's radius token where one exists.
Shadows over borders. Layered transparent box-shadow (1px ring + tight lift + soft ambient) adapts to any background and animates smoothly; flat borders do neither. Use the project's shadow utility if it has one; otherwise:

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)] dark:shadow-[0px_0px_0px_1px_rgba(255,255,255,0.06),0px_1px_2px_-1px_rgba(255,255,255,0.03),0px_2px_4px_0px_rgba(0,0,0,0.2)]

Strengthen the same layers for hover/selected. Extract a shared component after the third repetition, with transition-shadow duration-200.

Image outlines. Inset 1px outline on images/media for separation: pure black at 10% in light mode, pure white at 10% in dark — never a tinted neutral, which reads as dirt on the edge. [outline:1px_solid_rgba(0,0,0,0.1)] [outline-offset:-1px].
Optical alignment. When geometric centering looks off (icon+text buttons, play triangles), nudge until it looks centered; the best fix is the SVG viewBox itself.
Hit areas. ≥ 44×44px for touch, ≥ 40×40px on desktop. Extend with a pseudo-element if the visible control is smaller; never overlap two hit areas.

Motion

Interruptible by default. CSS transitions and springs retarget mid-flight; keyframes don't. Transitions/springs for interactive states (hover, toggle, dismiss), keyframes only for one-shot sequences (page load). With a motion library, prefer type: "spring", bounce: 0.
Split and stagger enters. Don't animate one container — break content into semantic chunks with ~60–100ms stagger, combining opacity, small translateY, and blur:

@keyframes enter {
  from { opacity: 0; transform: translateY(8px); filter: blur(4px); }
}
.animate-enter {
  animation: enter 600ms cubic-bezier(0.2, 0, 0, 1) both;
  animation-delay: calc(80ms * var(--stagger, 0));
}

Exits subtler than enters. Small fixed translateY (~-12px) + blur + fade — never a full reversal of the enter path, never zero motion.
Icon swaps. Cross-fade in place with opacity/scale/blur (scale 0.25→1, blur 4px→0); AnimatePresence mode="popLayout" with a spring, or an absolute-positioned CSS cross-fade without a library.
Press feedback. active:scale-[0.96] on buttons — never below 0.95.
No animation on first paint for default-state elements: initial={false} on AnimatePresence.
Name transition properties. Never transition: all — list exact properties. will-change only for transform/opacity/filter, only after observing first-frame stutter.
Respect prefers-reduced-motion on every entrance and press effect.

Review checklist

Fonts, tokens, and budgets match DESIGN.md (if present)
Sizes from the type scale; headings descend with level; line-height unitless by role
balance on headings, pretty on descriptions, measure capped on long-form
tabular-nums on changing numbers; antialiased on root; inputs ≥ 16px on mobile
Concentric radii on nested surfaces
Layered shadows (or the project's shadow utility) instead of flat borders
Images have the 1px untinted outline
Icon+text pairs optically aligned; hit areas ≥ 40/44px
Enters split and staggered; exits subtler; interactive motion interruptible
active:scale-[0.96] on primary press targets; reduced-motion honored
No transition: all; will-change rare and specific