Meridian — north star
What we are building. Read this before inventing surfaces or shells.
The product
Meridian is an AI design contract — a ground-up rule system so that an agent under extreme constraints always produces on-brand, high-quality UI with excellent user experience and developer/agent experience.
It is one contract in a platform family (Harbor, Atlas, Vellum, …). Design DNA may differ; architecture must not. Structural change lands once in platform.md / lib/platform/skeleton.ts and regenerates every contract.
It is not:
- a custom component library
- a zoo of app shells to re-create
- a marketing collage kit
- a place to invent second Buttons / Cards / Workbenches
- a place to invent Meridian-only MCP tools or filenames
It is:
| Layer | Job |
|---|---|
lib/platform/skeleton.ts | Shared MCP / routes / filenames / JSON keys for all contracts |
lib/contracts/dna/{id}.ts | Per-contract aesthetic DNA (may differ) |
design.md / agents.md | Fail-closed MUST / MUST NOT (+ platform consistency) |
lib/design/* | Typed closed unions (tokens, UX/DX laws, shells, typeset, cinema) |
app/globals.css + typeset.css | OKLCH theme + shadcn/typeset rhythm |
components/ui/* | shadcn primitives — compose, don’t fork |
Proofs (surfaces/*) | Validation only — prove rules work; not the product |
check:platform + check:* | CI that agents cannot skip — including cross-contract parity |
Twin pillars (biggest features)
UX — operator experience DX — human + AI developer experience
──────────────────────────── ────────────────────────────────────
usefulness, meaning, status progressive complexity
predictable → juicy press closed token API
quiet chrome, loud content Always / Ask / Never load tiers
empty / loading / error owned self-verification via check:*
object-bound AI, outcome→trace golden path: surface + typeset + shadcn
keyboard parity + a11y rules over widgets
Visual grammar (color, radius, cinema) exists to serve these pillars — not the other way around.
Typed: uxLaws · dxLaws in lib/design/experience.ts.
Prose: ux.md · dx.md.
The AI model
FROZEN (cannot invent) CREATIVE (must invent well)
──────────────────────────── ─────────────────────────────
colors / radii / depth copy & voice
shell rhythm (space/size/type) information architecture
typeset presets (docs/chat/…) which shadcn wholes to compose
theme knobs (closed presets) domain objects & workflows
uxLaws + dxLaws which states/disclosure to emphasize
cinematic + material + lane laws one-idea frame sequence
bans + contrast pairs narrative inside the laws
Agents invent stories and compositions.
They do not invent tokens, shadows, radii, typography scales, or interaction physics.
Primitives policy
- shadcn/ui owns atoms (
Button,Card,Input, …) —npx shadcn@latest add. - shadcn/typeset owns rendered HTML/markdown rhythm —
typeset+ frozen presets. - Meridian owns rules (especially UX + DX) that force those primitives into one coherent system.
- New “components” are almost always wrong — prefer a rule, a preset, or a composed proof.
Success criteria
An AI with only Meridian contracts + shadcn, under pressure, still ships:
- UX — useful controls, visible status, owned empty/error, keyboard path, object-bound AI
- DX — closed grammar, golden path, self-verified gates, no twin kits
- one accent, OKLCH, AA contrast
- shell-correct density without
h-[37px] - typeset-correct reading without per-tag class soup
- cinema with
ideas: 1, no stickers
If a change doesn’t make UX or DX more reliable for agents, it’s out of scope.