Humphrey Design System

Design strategy and component architecture for evolving the Humphrey dashboard from a generic AI-generated aesthetic to a distinctive, premium product. Based on research conducted April 2026 (see Humphrey UI Overhaul Research).

Three-Layer Architecture

The recommended approach layers three independent systems:

Layer 1 — Component Primitives (shadcn/ui + Radix UI): Copy-paste component system where code lives in components/ui/. Radix provides bulletproof accessibility (keyboard navigation, screen readers, focus management) without visual opinions. Components are fully editable, no vendor lock-in. CSS variable theming by default — maps directly to Humphrey’s tokens.css. Incremental adoption: migrate component by component, not big-bang.

Layer 2 — Semantic Token System (tokens.css): Humphrey’s existing tokens.css expanded into a comprehensive semantic token system covering colour, spacing, typography, shadows, and animation timing. Single source of truth for all visual values. Light and dark mode variants via [data-theme="dark"] selector. Integrated with Tailwind v4 via @theme inline.

Layer 3 — Motion Design: Two animation systems working in tandem. Next.js 16 View Transitions API (via React <ViewTransition> component) handles route-level page transitions. Motion (Framer Motion) handles component-level micro-interactions — KPI count-ups, chart data transitions, hover effects, loading skeletons.

Aesthetic Direction: “Theatrical Dark”

Evolution from synthwave/neon glow to a premium dark palette. Retains the dark-first approach and brand colour palette (Hot Pink FF86B7, Periwinkle 7B8AD4, Coral FFAC74) but replaces glow effects with restrained accents. Think Stripe dark mode or Mercury banking interface, not retro arcade.

Specific changes:

• Replace CSS box-shadow glow effects with subtle single-colour border accents
• Brand colours at reduced saturation for backgrounds; full saturation reserved for interactive elements and status indicators
• Five dark surface levels for depth and layering: #0C0A2F (base) → #141232 → #1C1A3D → #252349 → #2D2B55 (elevated)
• Geist Mono with tabular-nums retained for financial data; increased contrast between data labels and values
• Geist Sans headings pushed to 700 weight, labels to 400 at reduced opacity

Typography System

Typefaces: Geist Sans (UI) + Geist Mono (financial data) — Vercel’s dashboard typeface family.

Scale: 1.25x modular scale at 14px base. clamp() for fluid scaling between mobile and desktop rather than breakpoint jumps. tabular-nums and lining-nums on all financial data (already implemented).

Hierarchy: Weight and line-height drive hierarchy, not colour or decoration. Headings at tight line-height (1.1–1.2), body at generous line-height (1.5+). Follows patterns observed in Linear, Stripe, and Vercel dashboards.

Spacing System

8px base grid with a deliberate spacing scale (4, 8, 12, 16, 24, 32, 48, 64px). Semantic assignment:

• --space-within (tight) — within a component
• --space-between (medium) — between related components
• --space-section (large) — between page sections

Key principle: spacing between related items tighter than spacing between groups. AI-generated dashboards typically space everything identically — rhythmic variation is the differentiator.

Motion Design System

Three timing presets with spring physics (not linear easing):

Preset	Duration	Use Cases
Fast	100–150ms	Micro-interactions: hover states, tooltip/popover, button feedback
Normal	200–300ms	Transitions: tab switch, sidebar collapse, skeleton → content
Slow	400–600ms	Page-level: KPI count-up, chart data series (staggered 150ms per series)

All animations must include prefers-reduced-motion fallbacks. The single biggest tell of AI-generated UI is zero micro-interactions — purposeful motion is the fastest path to “designed” feel.

Migration Approach

Hub-by-hub migration over 8–12 weeks (one developer, part-time):

1. Weeks 1–2: Expand tokens.css into comprehensive semantic token system. Map every visual value to a named token. Create light/dark mode variants.
2. Weeks 3–4: Install shadcn/ui, generate core primitives. Create wrapper components matching existing Humphrey APIs. Migrate shared components (header, sidebar, navigation tabs).
3. Weeks 5–8: Migrate pages hub by hub, starting with most-used. Replace custom components with restyled shadcn equivalents. Add Motion micro-interactions progressively.
4. Weeks 9–10: Add View Transitions for page navigation. Refine chart theming (Recharts v3 accepts CSS custom properties). Polish empty states, loading states, error states with brand personality.

Information Architecture Principles

Drawn from Linear, Stripe, and Vercel dashboard analysis:

• Each of the 8 navigation hubs has a clear purpose statement
• Landing view shows curated summary (3–5 key metrics) with drill-down paths, not walls of charts
• Every number has context: period comparison, trend indicator, plain-language annotation
• Progressive disclosure: summary first, detail on demand
• Empty states reference the venue: “No events scheduled this week. Time to book the next big night?”
• Error messages with warmth: “We couldn’t fetch tonight’s rostering data. Our systems might need a coffee too.”

Tools Evaluated and Not Selected

• Google Stitch: HTML/CSS only output, generic aesthetics, experimental Google Labs product, cannot import existing design systems
• Material Design 3: Recognisable “Google/Material” look, very high migration effort, complete paradigm shift
• Aceternity UI / Magic UI: Recognisable template aesthetics becoming associated with “AI startup” look. Cherry-pick 2–3 animation patterns only; do not adopt colour palettes or default styling.
• Lovable / Bolt: Designed for greenfield, not migration. “Vibe coded” aesthetic.
• Premium template approach: Faster start but risk of “template smell” and fighting template opinions. Not recommended as primary strategy.

Related Pages

• Humphrey Intelligence App — the product this design system serves
• Tech Stack — underlying platform (Next.js 16, Tailwind v4, React 19)
• Humphrey UI Overhaul Research — source research informing this page