Design System — master router + shared foundations

Researched 2026 baseline for every web UI. Confidence per claim: ✅ = verified from a primary/teardown source; ◐ = well-sourced design judgment (strong default, not dogma).

Always do this first: (1) classify the project type → load the matching skill below; (2) load layout-interaction-design for any non-trivial interactive/multi-screen build (spacing, button placement, navigation, states); (3) apply the shared foundations + premium-feel checklist from THIS skill on top. Division of labor: the per-type skill owns its layout/UX; layout-interaction-design owns spacing mechanics, action hierarchy, routing & states; THIS skill owns tokens, type, a11y, motion, components, and the overall look.

1. Router — pick the project type

For EVERY type (the behavioral layer): also load layout-interaction-design — spacing/padding/ margin/gap mechanics, button & action placement (incl. the cross-platform order disagreement), navigation & routing (Next.js App Router: Link/prefetch, layouts, loading.tsx, modal routes, active link), and the full interaction-state set (loading/empty/error, focus management, feedback latency).

If two could apply (e.g. a dashboard that's also a marketing page), load both and let the dominant surface win.

2. House stack & non-negotiables ✅◐

• Stack: Next.js (App Router) + Tailwind v4 (CSS-first, no tailwind.config.js) + shadcn/ui (init with Base UI primitives in 2026: npx shadcn@latest init --base-ui) + Lucide icons + Recharts for data. Motion via CSS first, motion (ex-Framer) only when needed (§5).
• Never ship system-ui as the brand font. Pick a real font pair per type (see the per-type skill or §4). This single change separates the "product" tier from the "templated" tier.
• Token-first. Define semantic CSS variables once; reference them everywhere; never hardcode hex in components or charts.
• Dark vs light: dashboards & trading = dark-first; tools & docs = either; marketing & editorial = often light-first but support both. Never auto-invert semantic colors — re-map them.

3. Token layer — paste-ready (shadcn + Tailwind v4) ◐

Premium rules baked in: one saturated accent, everything else neutral; never pure #000/#fff for text/bg; 8px spacing grid; small consistent radii. Swap --accent per project; keep the rest.

/* globals.css */
@import "tailwindcss";

@theme inline {
  --color-bg: var(--bg);            --color-surface: var(--surface);
  --color-surface-2: var(--surface-2); --color-elevated: var(--elevated);
  --color-ink: var(--ink);          --color-ink-2: var(--ink-2);
  --color-ink-muted: var(--ink-muted); --color-border: var(--border);
  --color-accent: var(--accent);    --color-accent-hover: var(--accent-hover);
  --color-ring: var(--accent);
  --color-pos: var(--pos); --color-neg: var(--neg); --color-warn: var(--warn);
  --radius-sm: 4px; --radius-md: 6px; --radius-lg: 8px; --radius-pill: 9999px;
  --ease-out: cubic-bezier(.16,1,.3,1); --ease-standard: cubic-bezier(.2,0,0,1);
  --dur-fast: 120ms; --dur-base: 200ms; --dur-slow: 320ms;
}

:root {                                  /* LIGHT — never pure white/black */
  --bg:#FFFFFF; --surface:#F6F8FA; --surface-2:#EDF0F3; --elevated:#FFFFFF;
  --ink:#0A1628; --ink-2:#3A4452; --ink-muted:#6B7280; --border:rgba(10,22,40,.10);
  --accent:#635BFF; --accent-hover:#5147E6;      /* ← change per project */
  --pos:#0E9F6E; --neg:#E02424; --warn:#C2700A;
}
.dark {                                  /* DARK — never pure black */
  --bg:#0D0D0F; --surface:#131317; --surface-2:#1A1A20; --elevated:#222229;
  --ink:#F0F0F5; --ink-2:#B0B0BF; --ink-muted:#84848F; --border:rgba(255,255,255,.08); /* ink-muted ≥4.5:1 on dark surfaces */
  --accent:#7C83FF; --accent-hover:#9AA0FF;
  --pos:#22C97A; --neg:#F04F5A; --warn:#E0A800;
}

• Spacing: 8px grid → 4 · 8 · 12 · 16 · 24 · 32 · 48 · 64 · 96 · 128. Section padding ≥24–32px; let dense content sit inside roomy chrome.
• Borders: hairlines, not <hr> — 1px at low alpha (--border). Shadows: minimal; none on flat marketing surfaces; soft layered shadow only for true elevation (cards/popovers/modals).
• Radii: small + consistent (4/6/8). Reserve pill for marketing CTAs, not product chrome.
• For dense dark dashboards, dataviz-design §2 has the deeper surface/ink ladder, CVD-safe diverging P&L, and heatmap ramps — use those there.

4. Typography ◐ (full detail: per-type skill + research)

• One modular ratio: UI/dashboards 1.2; marketing/editorial 1.25–1.333. Use clamp() fluid type, keep a rem term so browser zoom works, body ≥16px.
• Measure: body max-width: 60–70ch (66 ideal); line-height 1.5–1.65 body, 1.05–1.2 headings.
• Tracking: negative on large headings only (-0.02 to -0.03em ≥24px); 0 body; +0.05em on caps.
• Numerics: font-variant-numeric: tabular-nums on every figure (prices, %, P&L, dates) so digits don't jitter. Set on the container, not per cell.
• Variable fonts + font-optical-sizing: auto on opsz families (Fraunces, Newsreader, Source Serif 4).
• Default pairs (all via next/font/google): dashboards/tools → Geist + Geist Mono or Inter + IBM Plex Mono; marketing → Bricolage Grotesque / Fraunces display + Geist/Inter body; editorial → Newsreader / Source Serif 4 body + Inter UI; docs → Inter/Geist + JetBrains Mono.

5. A11y, components, motion, responsive ✅◐

A11y — WCAG 2.2 AA baseline (always):

• Contrast: body ≥4.5:1, large/UI ≥3:1 (check both themes). Targets ≥24px (44px primary touch).
• Visible :focus-visible ring; never bare outline:none. Logical tab order; one <h1>/page; landmarks.
• Color is never the only signal — pair P&L color with ▲▼/sign. Honor prefers-reduced-motion globally.
• Live updates (price/signal ticks) → aria-live="polite" / role="status".

:where(a,button,input,select,textarea,[tabindex]):focus-visible{
  outline:2px solid var(--accent); outline-offset:2px; border-radius:4px; }
@media (prefers-reduced-motion: reduce){
  *,*::before,*::after{ animation-duration:.01ms!important; animation-iteration-count:1!important;
    transition-duration:.01ms!important; scroll-behavior:auto!important; } }

Components: shadcn/ui (own the code; components/ui/* IS your design system). Compose with cva variants + cn(). Tailwind v4 gotchas: theme in @theme (no config.js), OKLCH tokens, [data-slot] styling hooks. Every interactive element ships 6 states: default, hover, focus, active, disabled, loading.

Motion: CSS transitions for the 90% (hover ~120ms, base ~200ms, slow ~320ms cap, ease-out). motion only for spring/gesture/layout/AnimatePresence exit orchestration. View Transitions API (Baseline Oct 2025) for route transitions. Asymmetric: enter ~instant/200ms, exit ~150ms opacity. Spatial/origin-aware (popovers scale from trigger). No transitions on long lists/tables.

Responsive: mobile-first viewport breakpoints for page layout; Tailwind v4 built-in container queries (@container) for component layout. Data-dense surfaces get a compact data-density mode (tighter spacing, ≤32px rows) but never below the 24px target floor.

6. Style picker — name the look, then prompt it ✅◐

Build the bones in a credible style, then add one texture accent in a hero/scorecard. Reserve bold styles for side-projects.

Fintech-safe core (use freely): Swiss/International (grid, sans, typography-as-hero — trust), Minimalism (whitespace, restraint — premium calm), Editorial/Magazine (serif display + pull quotes — authority), Bento grid (modular tiles — organized, "keynote"), Flat/Material (safe default), Glassmorphism ◐ (frosted cards — the premium surface accent, use lightly).

Use sparingly / side-projects only: ◐ Neumorphism, Claymorphism, Skeuomorphism, Neo-Brutalism, Brutalism, Maximalism, Aurora/mesh, Y2K, Synthwave, Memphis, Japandi.

7. Premium-feel checklist — apply to every build ✅

Distilled from Stripe, Vercel/Geist, Linear, Robinhood, Apple, Mercury, Arc. If a generic Tailwind UI feels "templated," it's usually failing these:

1. One saturated accent, everything else neutral — links/primary/active/focus only.
2. Never pure black/white for text or bg — deep slate (#0A1628) / near-black (#0D0D0F); #000/#fff are only the extreme anchors.
3. 8px spacing grid; generous section padding; dense content inside roomy chrome.
4. 4–6 size type ramp, one family; negative tracking on large headings; tabular-nums on all figures.
5. Semantic color = meaning (green=up, red=down) applied consistently — never decoration.
6. Transitions 100–250ms ease-out, asymmetric (enter ~instant, exit ~150ms), spatial/origin-aware, none on long lists.
7. 6 states per interactive element; visible keyboard focus.
8. Hairline 1px borders at low alpha; minimal/zero shadows except true elevation.
9. Small consistent radii (4/6/8); pill only for marketing CTAs.
10. Whitespace = hierarchy — let content lead, chrome recede.
11. Constrained gradients ◐ — ≤3 complementary stops, accents/hero only, never body.
12. Hard numbers as design — specific figures over adjectives; data is the decoration in finance UI.
13. State via environment — subtle bg tint to signal mode (live/paused, open/closed).
14. Skeletons over spinners; instructional empty states (say what's missing + the next action).

8. Upgrading a ChatGPT/Grok-built project

1. Classify the project type (§1) → load that skill + this one.
2. Audit against §7. The usual offenders: system-ui font, no token layer, flat-gray everything, no focus states, default Tailwind blue everywhere, spinners, cramped or inconsistent spacing.
3. Apply in order: fonts (§4) → token layer (§3) → spacing/grid → components to shadcn → motion → a11y. Fonts + tokens alone usually deliver ~70% of the perceived lift.
4. Verify live on Vercel + run the §5 a11y checklist before calling it done.

Sources

Stripe/Vercel/Linear/Robinhood/Apple/Mercury/Arc teardowns; UX Planet "50 Design Styles"; WCAG 2.2 (w3.org); shadcn/Base UI vs Radix (2026); Motion.dev; Tailwind v4 docs; Typewolf/Google Fonts; utopia.fyi fluid type. Full per-track notes + URLs synthesized into this skill and the per-type skills. Treat ◐ as strong defaults; verify palettes with a contrast + CVD checker before shipping.