Interface Kit

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.

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.

Pick a Tone

Choose one and commit fully:

• Brutally minimal — generous whitespace, monospace type, stark contrast, near-zero decoration
• Maximalist chaos — layered textures, clashing type scales, dense information, intentional visual noise
• Retro-futuristic — CRT glow effects, monospace terminals, scan lines, neon on dark
• Organic / natural — earth tones, rounded shapes, paper textures, hand-drawn accents
• Luxury / refined — serif headlines, muted palettes, ample negative space, subtle gold or cream accents
• Editorial / magazine — dramatic type hierarchy, full-bleed imagery, grid-breaking layouts
• Playful / bold — bright primaries, chunky borders, exaggerated shadows, bouncy motion

Match Complexity to Vision

Maximalist design demands elaborate code — layered backgrounds, complex grid structures, multiple font stacks. Minimalist design demands surgical precision — every pixel of spacing matters more when there's nothing to hide behind.

The Ban List (When No DESIGN.md Exists)

When building without an existing design system, avoid these overused defaults that signal "AI-generated":

• Fonts: Inter, Roboto, Arial, system-ui as display fonts, Space Grotesk
• Colors: Purple-to-blue gradients on white backgrounds
• Patterns: Generic hero with centered text + CTA + stock illustration

Vary between light and dark themes, different font pairings, different aesthetic directions. Never converge on the same choices across projects.

Visual Texture

Add depth through: gradient meshes, noise/grain overlays (filter: url(#noise)), layered transparencies, subtle background patterns, duotone image treatments.

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.

Text Wrapping

h1, h2, h3, h4, h5, h6 {
  text-wrap: balance;
}

p, li, dd, blockquote {
  text-wrap: pretty;
}

balance distributes heading lines evenly. pretty avoids orphaned words in body text.

Numeric Display

.data-value, .price, .counter, [data-numeric] {
  font-variant-numeric: tabular-nums;
}

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:

• Headings: 600-700 (semibold to bold)
• Body: 400 (regular)
• Labels / UI: 500 (medium)

Always include font stack fallbacks:

--font-display: "Instrument Serif", "Georgia", serif;
--font-body: "Söhne", "Helvetica Neue", sans-serif;
--font-mono: "JetBrains Mono", "Fira Code", monospace;

5. Color & Theme

HSL Custom Properties (shadcn Pattern)

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 222.2 47.4% 11.2%;
  --primary-foreground: 210 40% 98%;
  --secondary: 210 40% 96.1%;
  --secondary-foreground: 222.2 47.4% 11.2%;
  --muted: 210 40% 96.1%;
  --muted-foreground: 215.4 16.3% 46.9%;
  --accent: 210 40% 96.1%;
  --accent-foreground: 222.2 47.4% 11.2%;
  --destructive: 0 84.2% 60.2%;
  --destructive-foreground: 210 40% 98%;
  --border: 214.3 31.8% 91.4%;
  --ring: 222.2 84% 4.9%;
  --radius: 0.5rem;
}

Define semantic tokens: primary, secondary, destructive, muted, accent, background, foreground. Reference colors by semantic name — never hardcode hex values in components.

Dark Mode

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  /* ... desaturated, lighter tonal variants — NOT simply inverted */
}

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

outer_radius = inner_radius + padding

/* Correct: concentric */
.card        { border-radius: 16px; padding: 8px; }
.card-inner  { border-radius: 8px; }  /* 16 - 8 = 8 */

/* Wrong: same radius on parent and child */
.card        { border-radius: 12px; }
.card-inner  { border-radius: 12px; }  /* Looks bloated */

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:

.elevated {
  box-shadow:
    0 1px 2px rgba(0, 0, 0, 0.04),
    0 2px 4px rgba(0, 0, 0, 0.04),
    0 4px 8px rgba(0, 0, 0, 0.04);
}

Multiple shadows at different spreads mimic how light works. A single hard shadow looks artificial.

Image Outlines

Add a subtle inset outline to images and media for consistent depth against varied backgrounds:

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

Spacing Scale

Use a 4px / 8px base incremental system. Every spacing value should be a multiple of 4:

4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96 / 128

Hit Areas

Minimum 44x44px for all interactive elements. If the visual element is smaller, extend the hit area with a pseudo-element:

.small-button::before {
  content: "";
  position: absolute;
  inset: -8px;
}

Z-Index Scale

Define a layered scale and never use arbitrary values:

--z-base: 0;
--z-dropdown: 10;
--z-sticky: 20;
--z-overlay: 40;
--z-modal: 100;
--z-toast: 1000;

7. Motion & Interaction

The Frequency-Based Decision Framework

This is the most important mental model for animation decisions:

High-frequency animations feel sluggish. Low-frequency animations without motion feel jarring. Match the animation budget to usage frequency.

Custom Easing Curves

Built-in CSS easings (ease, ease-in-out) are too weak. Define custom curves:

:root {
  --ease-out: cubic-bezier(0.23, 1, 0.32, 1);
  --ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);
  --ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);
  --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
}