System · Harbor

Architecture

Layers, pipeline, frozen vs creative, extension.

architecture.md

Meridian — architecture.md

System layers for humans and agents. Influences: influences.md.
Contracts: ../design.md · ../agents.md. Specs: layout · ux · animations · color · typography · density · ai-surfaces.

1. What Meridian is

An AI design contract — strict guidelines + typed grammar so agents under extreme constraints always produce good UI. Showcased on a cinematic website. Surfaces are proofs, not the product. See north-star.md.

Is	Is not
Tokens + grammar + fail-closed laws	Parallel component library
shadcn primitives + typeset rhythm	Forked Button/Card twins / shell zoo
Frozen material + creative composition	Freeform vibe coding
Agent-readable contracts + lint	Prompt-only hope

2. Research → system (why each layer exists)

Finding	Source	Response
Agents fabricate tokens / drift mid-session	Superdesign	Closed unions in `lib/design/grammar.ts`
Docs ≠ code ≠ components	Pandya	One grammar imported by UI + `check:design`
Creativity dies if everything locked	Internal model	Frozen vs creative zones in `recipes.ts`
Productivity apps need quiet dense chrome	Cursor app, Linear	Shell rhythm + workbench proofs
Material needs control vs layer + stroke	Fluent 2	`materialLaws`, `radiusFor`, `edge`
Meaning-bearing color + task density	Polaris Pro	Status semantics, `data-surface`
HTML/markdown type soup repeats	shadcn/typeset	Owned `typeset.css` + frozen presets
Cinema staging	Apple-class film patterns	`cinematicLaws`, `defineCinemaFrame`
Parts without wholes fail	Brad Frost	Surfaces validate atoms in product frames
Compose don’t invent	shadcn / schema UI gen	`npx shadcn@latest add`

3. North star pipeline

docs/north-star.md             ← product = AI contract
docs/platform.md               ← shared architecture (all contracts)
        ↓
lib/platform/skeleton.ts       ← MCP · filenames · routes · JSON keys (SSOT)
lib/contracts/dna/{id}.ts      ← aesthetic DNA only (may differ)
        ↓
influences.md (ranked absorb)
        ↓
design.md + agents.md          ← contracts (MUST / load order / platform parity)
        ↓
lib/design/{grammar,recipes,typeset,shell,contrast,cx,knobs}.ts
        ↓
app/globals.css + typeset.css  ← OKLCH tokens + typeset rhythm
        ↓
components/ui/*                ← shadcn atoms (compose only)
        ↓
components/surfaces/*          ← proofs (validation only)
components/cinematic/*         ← film stages
        ↓
check:platform · design · shell · proofs · typeset · contrast

Agents invent stories and compositions. They do not invent colors, shadows, radii, or type scales.
They also do not invent Meridian-only MCP tools or machine filenames — see platform.md.

4. Frozen vs creative

FROZEN                              CREATIVE
──────────────────────────────      ─────────────────────────────
colorRoles / OKLCH                  copy / voice
radii / depths / strokeFor          information architecture
surfaces / shell rhythm             domain objects
typeset presets / laws              which typeset preset
themeKnobs / activity               frame sequence (ideas: 1)
cinematicLaws / materialLaws        which shadcn wholes
banned / designInfluences           narrative within one idea
contrast pairs

5. Layer catalog

Layer	Path	Owner
North star	`docs/north-star.md`	Product
Ranked influences	`docs/influences.md`	Research
Spatial system	`docs/layout.md`	Research
Interaction / UX	`docs/ux.md`	Research
Motion	`docs/animations.md`	Research
Color	`docs/color.md`	Research
Type + typeset	`docs/typography.md`	Research
Density	`docs/density.md`	Research
Operator UX	`docs/ux.md`	Pillar
Developer / agent DX	`docs/dx.md`	Pillar
AI UI	`docs/ai-surfaces.md`	Research
Human DNA	`docs/meridian.md`	DNA
Source ledger	`docs/sources.md`	DNA
AI contract	`design.md`	Contract
Agent OS manual	`agents.md`	Contract
Typed grammar	`lib/design/grammar.ts`	Code
Recipes / laws	`lib/design/recipes.ts`	Code
Typeset presets	`lib/design/typeset.ts`	Code
Shell rhythm	`lib/design/shell.ts`	Code
Contrast pairs	`lib/design/contrast.ts`	Code
Class helpers	`lib/design/cx.ts`	Code
Drift lint	`scripts/check-*.mjs`	CI
Tokens	`app/globals.css`	Theme
Typeset CSS	`app/typeset.css`	Theme
Primitives	`components/ui/*`	shadcn
Proofs	`components/surfaces/*`	Validation
Film	`components/cinematic/*`	Marketing
Skills	`skills/*/SKILL.md`	Agents
Agents	`.cursor/agents/*`	Agents

6. Typed grammar surface

Import @/lib/design — never ad-hoc fabrication.

Export	Job
`colorRoles`	Closed semantic colors
`radii` / `radiusFor`	Control vs layer vs shell
`depths` / `depthFor`	edge → soft → raised
`strokeFor`	thin edge / focus ring
`surfaces`	application · marketing · mobile · desktop
`activityRoles`	thinking · search · read · edit
`provenanceRoles`	user · assistant · tool · …
`banned`	Drift patterns
`typesetClass` / `typesetLaws`	Frozen HTML/markdown rhythm
`uxLaws` / `dxLaws`	Twin pillars — operator + agent/dev experience
`shellRhythm` / `shellLaws`	Surface density contract
`cinematicLaws`	Film contract
`materialLaws`	Fluent-shaped material
`designInfluences`	Absorb / reject lists
`defineCinemaFrame`	Typed one-idea frames
`defineInteractiveProof`	Proof recipe (validation)
`contrastPairs`	WCAG AA audit data

7. Runtime architecture (Next.js)

app/
  page.tsx                 home film
  globals.css              tokens
  typeset.css              shadcn/typeset (owned)
  theme/                   grammar showcase
  surfaces/                proof gallery (validation)
  for-agents/              designed agents guide
  architecture/            designed architecture
  system/                  research docs index + [slug]
  design.md/route.ts       negotiated contract
  agents.md/route.ts
  architecture.md/route.ts
  *.md/route.ts            other negotiated docs
components/
  ui/                      shadcn (compose only)
  surfaces/                proofs — not a shell product
  cinematic/               stages
  home/                    film beats
  docs/                    DocShell, MarkdownBody (typeset)
lib/design/                typed law
scripts/check-*.mjs        gates

Content negotiation: browsers → designed HTML; agents → raw markdown (Accept or ?raw=1).

8. Toolchain roles

Kind	Role	Examples
Contract	Always-on law	`design.md`, `agents.md`, `north-star.md`
Research spec	Deep merge rules	`docs/layout.md`, `typography.md`, …
Skill	Task workflow	`meridian-compose`
Agent	Author / reviewer	`meridian-author`
Lint	Fail closed	`check:design`, `shell`, `proofs`, `typeset`, `contrast`

9. Website routes

Route	Job
`/`	Cinematic positioning
`/design` · `/meridian/design.md`	Contract
`/meridian/for-agents` · `/meridian/agents.md`	Agent OS
`/meridian/architecture` · `/meridian/architecture.md`	This file
`/system` · `/meridian/system/[slug]`	Research specs (influences, layout, ux, …)
`/meridian/theme` · `/meridian/surfaces` · `/skills`	Showcase
`/llms` · `/meridian/llms.txt`	Discovery

10. Extension protocol

New token role → grammar.ts + globals.css + cx.ts + contrast if text/bg (same PR).
New ban → banned + check-design.mjs rule.
New influence win → update influences.md merge matrix + encode in recipes/CSS.
New skill when a workflow repeats three times.
Keep MUST lists short — raise the floor, don’t write a novel in the contract; put depth in docs/*.

11. Dependency rules

docs/research  →  informs  →  design.md / recipes
recipes        →  imported by  →  UI / theme pages
UI             →  may import  →  @/lib/design, @/components/ui, @/lib/icons
UI             ✗  must not    →  invent hex, shadow-*, lucide direct

12. Done definition (architectural)

Change sits in the correct layer
Frozen vocabulary unchanged unless intentional + tests/lint updated
Influence merge matrix still true (or updated)
Gates green

Sources

Raw