Meridian — design DNA

Meridian is the design language for ui.byronwade.com. One philosophy, four surfaces, built on shadcn/ui.

Agents: obey design.md first. This file is the human-readable deep DNA.
Architecture: architecture.md. Ranked influences + specs: influences.md · /system.

Soft warm neutrals (never pure white/black). One deep accent (--brand). Full-bleed cinema. Structured reading. Density follows the task. The website is a theme showcase for AI authors — not a custom component catalog.

This DNA is distilled from what leading product designers and design-system practitioners publish — not from aesthetic collage. Sources and what we took: docs/sources.md.

Controlled principles

Six binding rules. Prefer these over vibe, trend, or naming other brands in the UI.

1. Obsess over usefulness

Solve real operator problems. Make the useful path effortless. Every control earns its place by helping someone finish a task — not by decorating the screen.

Source: Vercel Design Engineer Principles — “Obsess over usefulness.”

2. Assign meaning

Color, icon, and depth carry role — never decoration. Danger is destructive. Caution is warning. Go / primary / selected resolve to --brand. Agent activity pastels encode what the agent is doing, not accent fashion. If removing a visual doesn’t hurt scanning or trust, remove it.

Source: Shopify Polaris — Pro design language — “Assign meaning.”

3. Density follows the task

High density for data-rich indexes and long sessions. Lower density for focused detail, forms, and marketing presence. Surfaces remap control/row heights via data-surface; don’t invent a new component kit per platform. Space groups related information; hierarchy comes from size, tracking, and weight — not chrome volume.

Source: Polaris Pro — “Increase density”; Linear UI refresh — hierarchy and chrome clarity (Linear Now).

4. Predictable, then juicy

Visually similar things behave the same. Interactions give clear feedback (hover quiet, press felt) without novelty motion. No scroll choreography. Honor prefers-reduced-motion.

Source: Polaris Pro — “Make it predictable” / “Craft juicy interactions”; Vercel — own every state and edge case.

5. Parts and wholes together

Tokens are subatomic decisions (globals.css). Atoms live in components/ui/ (shadcn). Wholes are surfaces and the workbench — prove the system in real product frames, not isolated pattern grids. Don’t ship a Frankenstein kit of labeled influences; compose one calm product.

Source: Brad Frost — Atomic Design and The Part and The Whole; tokens as subatomic particles (Extending Atomic Design).

6. Progressive disclosure

Make complexity available, not required. Application default is cool paper and compact controls. Theater, AI rails, and deep tooling appear when the object or task needs them — never as floating spectacle or chatbot cliché.

Source: Vercel — “Build for everyone”; ChatGPT / OpenAI product craft — product as hero, hide complexity until needed.

Foundation

Everything builds on shadcn. Primitives live in components/ui/. Meridian is tokens + surface contracts + composition — not a parallel component library.

npx shadcn@latest add [component]

Canonical composition (part + whole): components/surfaces/workbench.tsx.

Surface matrix

Four surfaces. Same tokens. Different density, chrome, and theater rules — driven by task, not aesthetics.

Surface rules

1. Never fork components per surface — one Button/Card/Table; density via data-surface and size props.
2. Web Application is the default lane — when unsure, design for app paper.
3. Marketing may use theater; apps almost never do.
4. Native lanes borrow OS grammar, not OS skins — safe areas, 44px touch, compact desktop toolbars — still Meridian tokens.
5. Reduce chrome noise — align labels/icons; soften borders; limit brand tint in chrome (Linear refresh discipline).

What we take (discipline, not labels)

Do not name other brands in UI chrome or marketing headlines. Encode the discipline:

Cinema — styling, not spectacle

• Media owns the frame — full-bleed, not inset marketing cards
• One idea per frame
• No scroll choreography, SVG grain, mix-blend on fixed chrome, or content-visibility size placeholders
• Hero height uses svh, never dvh — dynamic viewport resizes on mobile chrome show/hide and jerks reverse-scroll
• Demo shells: overflow-hidden, not nested overflow-auto (nested scrollports steal the wheel on direction change)
• Simple motion only — honor prefers-reduced-motion
• Theater when earned — marketing presence; not app chrome
• No overlay stickers on media

Shared laws (all surfaces)

1. Tokens only — no raw hex in components
2. One accent — --brand drives primary, ring, selected; success follows brand so one variable re-skins the system
3. Status is semantic — destructive / warning keep fixed meaning (Polaris “assign meaning”)
4. Hierarchy from size + tracking — not bold display weight
5. Mono for data — IDs, counts, timestamps, prices, model/tool names
6. Depth defaults to none — edge first; depth-soft / depth-raised sparingly
7. Shape vocabulary — controls rounded-lg; panels rounded-2xl; marketing CTAs may rounded-full; shells rounded-3xl
8. Object-bound AI — provenance + activity tokens; attach to a product object
9. Fewer decisions — prefer shared scales over one-off exceptions

Density scale

Reading lanes

Where things go