UI Craft

"All those unseen details combine to produce something that's just stunning, like a thousand barely audible voices all singing in tune."

Quick Start: Top 10

1. Ask before assuming — never default accent color, font, or design style without analyzing the existing project or asking the user. Blue is not everyone's brand.
2. Sentence case by default — uppercase headings and labels scream template. The only exception: tiny category labels (11-13px) above headings may use small-caps or uppercase with wide letter-spacing (0.04-0.08em)
3. 90%+ neutral colors, one accent — most of the page should be black, white, and gray; a single brand color does all the heavy lifting — detect the accent from existing code or ask the user. NEVER default to blue without asking.
4. Vary border-radius by element size — 4px on inputs, 8px on cards, 12px on modals; uniform radii look stamped out
5. Use real SVG icons, not emoji — Lucide, Heroicons, or Phosphor; emoji in feature lists is an instant AI tell
6. Tight letter-spacing on large headings —

   tracking-tight

   or

   -0.02em

   + on anything above 24px; default spacing looks loose and generic
7. One font family for body, optionally a second for display — never mix three; Inter, Geist, or DM Sans are safe defaults
8. Layered shadows over flat borders — two-layer box-shadow (ambient + direct light) adds depth without the "card outline" look
9. Exit animations faster than enter — dismiss at ~75% of entrance duration
10. Plain secondary text for comparisons, not colored pills — "+12.5% from last month" in muted text, not a green badge
11. Accent color budget: 3-5 places per viewport — primary CTA, one key metric, active states, maybe a section label. If the accent appears in 10+ places, it loses its power
12. Every section earns its space — if a section doesn't answer a clear question or drive action, cut it
13. One signature detail per UI — a subtle motif, an unexpected layout break, a clever SVG pattern, a distinctive card treatment. This is what makes it feel designed rather than templated. Examples: angled section dividers, a branded icon style, custom list markers, a unique hover reveal

Before writing ANY code: Run Stack Detection + Discovery Phase. Analyze the project for existing design tokens (CSS variables, Tailwind config, font imports). If the project already has a design system, use it. If preferences are missing and not in the prompt, ask the user. Never assume defaults.

Routing

Before routing to any mode, run the Discovery Phase. Analyze the project for existing design tokens. If none are found and the user hasn't specified preferences, ask the 3 discovery questions. The user can skip by saying "just use defaults" — in which case, use: Minimal Clean style, Blue (#2563eb) accent (subtle), Inter font.

Stack Detection (Always Run First)

tailwind.config.*

@tailwind

class="flex items-center"

tracking-tight

letter-spacing: -0.01em

@apply

[cubic-bezier(0.23,1,0.32,1)]

*.module.css

styles.container

.module.css

styled(Component)

css\

css

*.styles.ts

style={{ }}

<style>

<style scoped>

<style lang="scss">

<style>

.css

• Never fight the project's stack. If the project uses Tailwind, write Tailwind. If it uses CSS Modules, write CSS Modules. Never mix approaches.
• All design knowledge applies regardless of stack. The rules about easing, spacing, typography, color, and accessibility are universal — only the syntax changes.
• Reference files are CSS-first. Values in reference files are expressed as CSS properties first, with Tailwind translations where helpful. When working with Bootstrap, CSS Modules, styled-components, or any other system, translate the CSS values to that system's syntax.
• When in doubt, read existing code. Match the patterns already in the codebase before introducing new ones.

Tailwind-Specific Craft

/* Design rule → Tailwind equivalent */
letter-spacing: -0.03em        → tracking-tighter or tracking-[-0.03em]
font-variant-numeric: tabular   → tabular-nums (built-in utility)
text-wrap: balance              → text-balance (Tailwind v3.4+)
prefers-reduced-motion          → motion-reduce:... / motion-safe:...
ease-out: cubic-bezier(0.23,1,0.32,1) → ease-[cubic-bezier(0.23,1,0.32,1)]
focus-visible outline           → focus-visible:ring-2 focus-visible:ring-blue-500
touch-action: manipulation      → touch-manipulation
44px touch targets              → min-h-11 min-w-11 (44px = 2.75rem)

bg-gradient-to-r from-purple-500 to-cyan-500

animate-bounce

shadow-[0_0_30px_rgba(59,130,246,0.5)]

├── Analyze project for existing design tokens
├── If design tokens found → note them, work within existing system
├── If no design tokens and user provided preferences in prompt → use those
├── If no design tokens and no preferences → ask user the 3 discovery questions
└── Proceed to build with the resolved design decisions

Discovery Phase (Always Run First)

Step 1: Project Analysis

Scan for existing design tokens:
├── CSS variables (--color-*, --font-*, --accent-*, --brand-*)
├── Tailwind config (theme.extend.colors, theme.extend.fontFamily)
├── globals.css / global styles (font imports, color definitions)
├── Layout files (font loading, Google Fonts, next/font)
├── Component library theme (shadcn theme, MUI theme, Bootstrap variables, etc.)
└── Design system tokens file (tokens.css, design-tokens.ts)

• Accent color(s) in use
• Font families loaded/configured
• Border radius patterns
• Shadow patterns
• Color palette structure
• Design style signals (rounded vs sharp, minimal vs rich, etc.)

Step 2: Ask the User

#2563eb

#4f46e5

#7c3aed

#e11d48

#ea580c

#059669

#0d9488

#d97706

system-ui, sans-serif

Step 3: Apply Decisions

Design Style Implementation Guide

border-radius

rgba(0,0,0,0.06)

rgba(255,255,255,0.08)

Core Rules (Always Apply)

The Anti-Slop Test

• Identical card grids (icon + heading + text, repeated 3-6x) — monotonous layout signals zero design thought
• ALL CAPS on headings, labels, table headers, nav, buttons — screams template. Exception: tiny (11-13px) section category labels with wide letter-spacing
• Purple/cyan gradient everything — instant AI tell, lacks brand identity
• Emoji as feature icons — use proper SVG icon components (Lucide, Heroicons)
• Bounce/elastic easing curves — cartoonish motion undermines credibility
• Glassmorphism on dark backgrounds with neon accents — "made by prompt"

• Colored pills/badges on trend percentages — plain secondary text: "+12.5% from last month"
• Thick colored left/top borders on cards — lazy differentiation; use elevation or background tint
• Uniform border-radius on everything — vary by element: 4px inputs, 8px cards, 12px modals
• Gradient text on hero metrics — decoration over data
• Vertical bar charts for time-series data — use area/line charts. Horizontal bars ARE fine for categorical comparison

• transition: all

  — list specific properties;

  all

  animates unintended things
• Decorative glow effects as primary affordances — glow is not a button state
• Soft blurry gradient blobs/orbs in backgrounds — use intentional flat or subtle backgrounds
• Generic CTAs ("Learn more", "Click here", "Get started") — be specific: "Start for free", "Deploy now", "View changelog"
• Walls of text in any section — no section on a landing page should exceed 2-3 sentences. Copy is ruthlessly concise

• No

  font-variant-numeric: tabular-nums

  on data
• Missing

  text-wrap: balance

  on headings
• Straight quotes instead of curly (" " and ' ')
• No non-breaking spaces in brand names
• Hero metric layouts (big number + gradient) without adjacent context
• Overly minimal results that look "empty" rather than "designed"
• Testimonial cards with 5-star ratings — use quotes with name/role/company

The Craft Test (What TO Do)

• One accent color, 3-5 placements per viewport — primary CTA, one key metric, active states, a section label. Never two accent colors competing. If accent appears 10+ times, it loses power.
• White backgrounds with barely-there borders —

  1px solid oklch(92% 0.005 250)

  or whitespace to separate sections
• Numbers: large, black, undecorated —

  font-weight: 600-700

  ,

  tabular-nums

  , no gradients. The number speaks for itself
• Comparison is plain secondary text — "+12.5% from last month" in secondary color. Never pills, never colored badges
• One chart color, not rainbow — single accent hue at different opacities. Area fill fades from ~15% at line to 0% at bottom
• Functional color only — small dots (6-8px) for status, flags for countries. Color serves data, never decoration
• Real content, not placeholders — actual company names, real metrics. "Lorem ipsum" feels generated

• Hero — left-aligned or asymmetric. One headline (48-72px, tight tracking), one paragraph, dual CTAs (solid primary + ghost secondary). Social proof below CTAs (avatars + count, or logos). Never center everything.
• Product proof — show a screenshot/mockup with real data. Frame in a subtle container. Replaces abstract illustrations.
• Logo strip — "Trusted by teams at" + 5-7 logos. Choose plausible brands (Lattice > Stripe for believability).
• Features — 2-3 asymmetric rows (text + visual, alternating sides). Each feature gets a real visual (chart, timeline, funnel), not just an icon. NEVER a uniform 3-column or 6-card icon grid.
• Metrics band — 3-4 stats on tinted/dark background. First metric in accent, rest in primary text. Numbers 48px+, descriptions small.
• Testimonials — 3 cards with specific metrics. Name + role + company. First card can be accent-tinted. No star ratings, no thick side borders.
• Pricing — 3 tiers, middle featured (elevation or accent border). Price splits weight. Feature lists with SVG checkmarks.
• Sections breathe — 120-200px between majors. Varied spacing creates rhythm.
• Tab-based feature sections — use tabs or toggles to let users explore features interactively. Each tab reveals different content (screenshot, demo, description). Never present all features as identical static cards. See inspiration.md for examples from dub.co, vercel.com.
• Velocity/changelog section — prove the product ships fast. Show recent changelog entries with dates, or a "We ship fast" section. This builds confidence that the product is actively maintained.
• Specific metrics in social proof — "Build times went from 7m to 40s" next to a customer logo. Quantify the transformation instead of vague praise. One concrete metric beats "trusted by thousands."

• Sidebar navigation — subtle bg tint, NOT full dark. Dark sidebar is a common AI pattern. Active item uses accent bg at low opacity.
• Metric card hierarchy — primary card gets accent tint or solid bg; others stay neutral white. All cards include sparklines (32px polyline SVG). NEVER put the same colored top border on all cards.
• At least 3 content types visible — metric cards + chart + table/list is the minimum. Never 4+ identical cards in a row.
• Chart type by data story — area for trends, horizontal bar for categories, donut sparingly for part-of-whole, sparkline for inline trends. Never pie charts or 3D.
• Data tables with row context — avatars, status dots (not badges), proportion bars. Headers in sentence case, never uppercase.
• Filter toolbar — ghost buttons, active state with accent bg. Date range selector gets prominence.

Animation Decision Rules

1. Justify every animation — motion must communicate something (hierarchy, state change, spatial relationship). Decorative motion is noise.
2. Frequency determines budget — actions performed 100+ times/day get zero animation. Occasional actions (modals, drawers) get standard treatment. First-time experiences can delight.
3. Speed communicates confidence — UI that responds in under 200ms feels instant. 300ms+ starts feeling sluggish.
4. Respect the user's system —

   prefers-reduced-motion

   is not optional. Provide meaningful fallbacks, not just

   animation: none

   .
5. GPU-only properties — stick to

   transform

   and

   opacity

   . Animating

   width

   ,

   height

   ,

   top

   ,

   left

   causes layout thrashing.
6. List properties explicitly —

   transition: all

   animates things you didn't intend. Be precise about what moves and why.

Interaction Rules

• Full keyboard support per WAI-ARIA APG patterns
• Visible focus rings via

  :focus-visible

  ; group with

  :focus-within

• Hit targets ≥ 24px (mobile ≥ 44px); expand with pseudo-elements if visual < 24px
• URL reflects state — deep-link filters, tabs, pagination, expanded panels
• Navigation elements use proper anchor tags — support Cmd/Ctrl+click, middle-click
• Optimistic UI — update immediately, reconcile on response, rollback on failure
• Confirm destructive actions or provide Undo window

• overscroll-behavior: contain

  in modals/drawers

• touch-action: manipulation

  on controls to prevent double-tap zoom

Component Craft

• Interactive elements have three states minimum — rest, hover/focus, active/pressed. If it looks the same when you click it, it feels broken.
• Button hierarchy guides action — primary = solid, secondary = outline/ghost, destructive = red outline. Only ONE primary per view section.
• Feedback must be visual, not just color — swap icon to checkmark, show inline confirmation, animate the state change. Color alone fails for colorblind users and subtle shifts go unnoticed.
• Metric cards vary treatment — if showing 3+ cards with same structure, differentiate the primary one (heavier type weight, slightly larger number, or subtle background tint — never thick colored borders).
• Price typography splits weight — dollar sign lighter/smaller than the number, period label (e.g. "/month") in secondary color.
• Prevent native image drag on interactive overlays —

  user-drag: none; -webkit-user-drag: none; pointer-events: none

  on images inside sliders/carousels.
• Placeholders are visual, not text — skeleton bars, subtle grid lines, or a muted pattern. "Chart would render here" looks unfinished.

@media (hover: hover) and (pointer: fine)

• Cards:

  transform: translateY(-1px)

  + shadow increase —

  transition: transform 200ms ease-out, box-shadow 200ms ease-out

  / Tailwind:

  hover:-translate-y-px hover:shadow-md transition-[transform,box-shadow] duration-200

• Buttons: slight background darkening, not a full color swap —

  transition: background 150ms ease-out

  / Tailwind:

  hover:bg-accent/90 transition-colors duration-150

• Table rows: subtle background —

  hover:bg-gray-50

  / Tailwind:

  hover:bg-slate-50/50

• Links:

  text-underline-offset: 2px; text-decoration-skip-ink: auto

  / Tailwind:

  underline-offset-2 decoration-skip-ink-auto

• Active/pressed:

  transform: scale(0.98)

  on buttons for tactile feedback

Forms (Non-negotiable)

• Never block paste in inputs
• Enter submits focused input; ⌘/Ctrl+Enter in multi-line fields
• Keep submit enabled until request starts; then disable with spinner and keep label
• Accept free text, validate after — don't block typing
• Errors inline next to fields; on submit, focus first error
• Set

  autocomplete

  + meaningful

  name

  ; correct

  type

  and

  inputmode

• Warn on unsaved changes before navigation
• Trim values to handle trailing whitespace from text expansion
• Mobile input font-size ≥ 16px to prevent iOS zoom

Typography Essentials

• text-wrap: balance

  for headings;

  text-wrap: pretty

  for body

• font-variant-numeric: tabular-nums

  for data/numbers
• Truncation handling for dense UI; flex children need

  min-w-0

• Smart punctuation: curly quotes (

  “

  ”

  ), apostrophes (

  ’

  ), ellipsis (

  …

  ), em-dash (

  —

  )
• Non-breaking spaces:

  10 MB

  ,

  ⌘ K

  , brand names,

  $ 79/month

system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif

Layout Essentials

• Optical alignment — adjust ±1px when perception beats geometry
• Deliberate alignment to grid/baseline/edges — no accidental placement
• Respect safe areas:

  env(safe-area-inset-*)

• No unwanted scrollbars — fix overflows
• CSS layout over JS measurement
• Nested radii: child ≤ parent, concentric
• Layered shadows: ambient + direct light, at least two layers
• Fixed z-index scale: dropdown → sticky → modal-backdrop → modal → toast → tooltip

Design Rules

• Layered shadows mimic ambient + direct light
• Crisp borders: semi-transparent borders + shadows for edge clarity
• Hue consistency: tint borders/shadows/text toward background hue on non-neutral surfaces
• APCA contrast over WCAG 2 for perceptual accuracy
• Interactions increase contrast:

  :hover

  /

  :active

  /

  :focus

  more contrast than rest

• color-scheme

  on

  <html>

  —

  light

  for light themes,

  dark

  for dark. Ensures native controls, scrollbars match.
• Theme color meta tag matches page background
• Use perceptually uniform color spaces (like OKLCH) for harmonious scales

Performance Rules

• Virtualize large lists (>50 items)
• Preload above-fold images; lazy-load the rest
• Explicit image dimensions to prevent CLS
• Preconnect to CDN domains
• Track re-renders — minimize and make them cheap
• Batch layout reads/writes — never interleave
• Mutations target <500ms
• Prefer CSS > Web Animations API > JS libraries for animations

Content & States

• Design all states: empty, sparse, dense, error, loading, success
• Skeletons mirror final content exactly — prevent layout shift
• No dead ends — always offer next step or recovery
• Empty states guide toward action, not just "nothing here"
• Accessible names exist even when visuals omit labels
• Resilient to user-generated content: short, average, very long

Polish Pass (The Compound Details)

• Brand names use

   

  — prevent "UI" on one line and "Craft" on the next
• Confirmation feedback is visual, not just color — swap icon to checkmark, not just green tint
• One visual anchor per text-heavy page — a code block, screenshot, or diagram breaks monotony
• Headings sit closer to their content than to the previous section — unequal spacing creates grouping
• Footer earns its space or disappears — generic "Built by Name" adds nothing; either add value or simplify
• Test on mobile before declaring done — drag interactions, overflow, label overlap, touch targets
• Secondary actions don't compete with primary — outline/ghost buttons for secondary, solid for primary
• Data-heavy content uses monospace or tabular-nums — even in casual contexts
• Images inside interactive containers can't be natively dragged — kills slider/carousel UX
• Every

  <section>

  on a landing page answers one question — if it answers two, split it

Common Issues (What We See in Real Projects)

Review Format (Required)

transition: all 300ms

transition: opacity 200ms ease-out

all

focus-visible:ring-2 ring-offset-2

color: gray

opacity: 0.5

cursor: not-allowed

1. Critical — blocks usability or accessibility (missing focus states, broken keyboard nav, no reduced-motion support)
2. High-impact — immediately noticeable quality issues (wrong font, default blue, identical card grids, no hover states)
3. Quick wins — small changes, big polish (add tabular-nums, fix letter-spacing, curly quotes, non-breaking spaces)

Quick Decision Frameworks

Should This Animate?

Motion Budget

Accessibility Checklist

• prefers-reduced-motion

  respected on every animation — with meaningful fallbacks:
  • Fade+slide entrance → just appear instantly (

    opacity: 1

    , no transform)
  • Spring/bounce → simple opacity fade (

    200ms ease

    )
  • Parallax scroll → static positioning
  • Color transitions and opacity changes are fine to keep — they don't cause motion sickness

• @media (hover: hover) and (pointer: fine)

  gates hover animations
• All interactive elements keyboard-reachable with visible focus
• Icon-only buttons have

  aria-label

  ; decorative icons are

  aria-hidden

• Focus trapped in modals; restored to trigger on close
• Color is never the sole status indicator
• Touch targets ≥ 44px (use pseudo-element expansion)
• Native elements (

  button

  ,

  a

  ,

  label

  ) before ARIA roles
• Form errors linked via

  aria-describedby

  , invalid fields use

  aria-invalid

• Skip-to-content link; hierarchical

  <h1>

  –

  <h6>

Reference Files

@starting-style