Authoritative guide for implementing stunning, accessible, performant UI. Synthesizes
design engineering philosophy, accessibility standards, animation principles, spatial design,
typography, color systems, and component craft into a single actionable reference.
Complements the design-system skill (which covers DESIGN.md spec writing) by covering
the HOW of implementation.
Trigger phrases: "build UI", "create component", "landing page", "make it look good",
"frontend", "design", "polish UI", "implement design", "make it beautiful",
"UI implementation", "component styling", "animation", "accessibility"
Interface Kit: Implementation Guide for Exceptional Interfaces
If a DESIGN.md exists at the project root, its tokens and specifications override all defaults in this skill. This skill provides sensible defaults for when no design system exists, and implementation guidance that applies regardless.
For deep dives on any section, see the reference files in this skill's references/ directory.
1. Core Philosophy
Taste is trained, not innate. Study why great interfaces feel right. Deconstruct apps you admire — the spacing, the timing, the weight of a shadow. The gap between "fine" and "exceptional" is built from hundreds of micro-decisions that users feel but never consciously notice.
Unseen details compound. A single rounded corner, a single eased transition, a single well-chosen shadow — none of these matter alone. Together they become "a thousand barely audible voices singing in tune." The cumulative effect is what separates craft from output.
Beauty is leverage. Polish is not vanity. Good defaults, considered typography, and intentional motion are real differentiators. Users trust interfaces that feel cared for. Investors notice. Competitors can't easily replicate taste.
Intentionality over intensity. Both bold maximalism and refined minimalism work — what fails is the absence of a clear point of view. Every visual decision should trace back to a deliberate conceptual direction. If you can't articulate WHY a choice was made, reconsider it.
Choose a direction and execute with precision. Don't hedge between styles. A brutalist page committed fully will always outperform a page that's "a little bit of everything." Commit, then refine.
NEVER produce generic "AI slop" aesthetics. No gratuitous gradients on white backgrounds. No cookie-cutter hero sections with stock illustrations. No safe, forgettable layouts that could belong to any product. Every interface should have a point of view that makes it recognizable.
2. The Priority Stack
When implementing UI, work through these priorities in order. Higher priorities are non-negotiable; lower priorities are polish that compounds quality.
Layered shadows over borders, press feedback on buttons, staggered enter animations.
Never skip a CRITICAL/HIGH item to chase a LOW item. A beautifully animated button that fails keyboard navigation is a net negative.
3. Aesthetic Direction
Before writing a single line of CSS, commit to a bold aesthetic direction. The most common failure mode in AI-generated UI is convergence on the same safe, forgettable look.
DESIGN.md overrides this entire section. If DESIGN.md specifies Inter, use Inter. If it specifies purple gradients, use them. The ban list only applies when no design system exists and you're making aesthetic choices from scratch.
4. Typography Essentials
Typography is the single highest-leverage design element. Get it right and mediocre layouts still feel good. Get it wrong and nothing else saves it.
Root Setup
html {
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
text-rendering: optimizeLegibility;
}
Apply font smoothing to the root layout. On macOS, the default sub-pixel rendering makes text appear heavier than the designer intended.
Use tabular-nums for any number that updates dynamically — prices, counters, table columns. Without it, layout shifts as digit widths change.
Scale and Rhythm
Base size: 16px minimum for body text. Never go below 14px for any readable content.
Line height: 1.5-1.75 for body text, 1.1-1.3 for large headings.
Max line length: max-width: 65ch for body text. Long lines destroy readability.
Type scale: Pick a consistent scale and stick to it: 12 / 14 / 16 / 18 / 24 / 32 / 48 / 64.
Font Pairing
Pair a distinctive display font with a refined body font. The display font carries personality; the body font carries readability. Use font-weight for hierarchy within a family:
Dark mode is not "invert colors." Use desaturated, lighter tonal variants. Backgrounds go dark but not pure black (#000). Text goes light but not pure white (#fff). Test contrast separately for dark mode — what passes in light may fail in dark.
Contrast Requirements
WCAG AA minimum: 4.5:1 for normal text, 3:1 for large text (18px+ bold or 24px+ regular)
Never convey information by color alone — always pair with an icon, label, or pattern
Test with browser devtools contrast checker or axe-core
Color Confidence
Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Pick one or two hero colors and let the rest of the palette recede. A confident palette has clear hierarchy; an uncertain palette spreads color evenly and feels flat.
6. Spatial Design
Concentric Border Radius
This is the single most common thing that makes nested UI elements feel "off":
When geometric centering looks off, align optically. Play/pause icons, dropdown carets, and asymmetric glyphs often need 1-2px manual nudges to look centered.
Shadows Over Borders
Layer multiple transparent box-shadow values for natural depth instead of using borders:
Never animate from scale(0). Start from scale(0.9) or higher, combined with opacity:
@keyframes scaleIn {
from { opacity: 0; transform: scale(0.95); }
to { opacity: 1; transform: scale(1); }
}
Press Feedback
Every pressable element should scale down slightly on :active:
button:active {
transform: scale(0.97);
}
Interruptibility
Use CSS transitions (not keyframe animations) for interactive state changes. Transitions can be interrupted mid-way; keyframes cannot. This matters for hover states, toggles, and any element the user might interact with rapidly.
Popover Origin
Make popovers transform-origin aware — they should grow from their trigger element, not from center. Exception: modals always originate from center.
Tooltip Hover Delay
Skip the tooltip delay on subsequent hovers. If the user has already waited for one tooltip, show the next one immediately.
Focus trap (keyboard cannot escape to elements behind)
ESC to close, click outside overlay to close
transform-origin: center, fade + scale enter animation
aria-modal="true", role="dialog", aria-labelledby
Form
Visible labels always — never placeholder-only inputs
Error messages near the field with aria-live="polite" for screen readers
Progressive disclosure: show advanced fields only when needed
Use React Hook Form + Zod for validation
Theming
Use shadcn CSS variable pattern (HSL format) for all component colors. Wrap client-interactive components in server components for Next.js App Router compatibility.
Reference references/component-patterns.md for the full component catalog with copy-paste implementations.
9. Accessibility Essentials
Semantic HTML First
Use <button>, <nav>, <main>, <header>, <footer>, <article>, <section> before reaching for ARIA. A <button> gives you keyboard handling, focus management, and screen reader semantics for free. A <div onClick> gives you none of that.
Keyboard Navigation
Tab / Shift+Tab: move between focusable elements
Enter / Space: activate buttons and links
Arrow keys: navigate within lists, menus, tabs, radio groups
Escape: close modals, popovers, dropdowns
Home / End: jump to first/last item in lists
Focus Management
Visible focus rings on all interactive elements — NEVER use outline: none without a replacement
Trap focus inside modals (Tab wraps within the modal, not behind it)
Restore focus to the trigger element when a modal/popover closes
Use focus-visible to show rings only for keyboard users, not mouse clicks:
