Meridian — dx.md

Developer experience for humans and AI agents. Twin pillar with ux.md.
North star: north-star.md. Typed: uxLaws / dxLaws in lib/design/experience.ts.

1. Why DX is a product feature

Meridian’s primary consumer is an agent under pressure (and a human guiding it).
If the contract is hard to load, ambiguous, or unverifiable, the system fails — even when tokens are perfect.

2. Golden path — into any project

Live install: /meridian/install.
Stack doctrine (law book · skills · gates · optional MCP): /stack · stack.md.

This product is a fail-closed design contract, not DESIGN.md vibes alone and not shadcn MCP (which installs components).

Agent loop:

1. Load law book (required first)
2. Open matching skill + recipe when it fits
3. npx shadcn@latest add … (or shadcn MCP) for atoms
4. Compose under closed tokens
5. npm run validate (required before done)
6. Optional MCP tools when the session is tool-wired

In-repo compose proof

Live on /meridian/for-agents. When working inside this monorepo:

import { Button } from "@/components/ui/button"
import { typesetClass, bg, radiusIntent } from "@/lib/design"

export function Panel() {
  return (
    <section data-surface="application" className="shell-pad shell-stack">
      <h2 className="type-section">Issues</h2>
      <Button className={radiusIntent("control")}>New</Button>
      <div className={typesetClass("docs")}>{/* help HTML */}</div>
    </section>
  )
}

That’s enough for a correct first surface. Depth (cinema, knobs, proofs) loads on demand.

3. Load tiers (Always / Ask / Never)

Typed as dxLoadTiers — keep agents.md aligned.

4. Layers of abstraction (escape without ejecting)

From least flexible → most flexible (Capozzi / progressive disclosure):

1. Presets — typesetClass("docs"), data-surface="application", knob presets
2. Grammar helpers — bg(), radiusIntent(), defineInteractiveProof()
3. shadcn atoms — compose Button / Card / Input
4. Owned CSS — globals.css / typeset.css variables (theme owners only)
5. New frozen law — last resort; update design.md + lint in the same change

Never jump from (1) to inventing a parallel component kit.

5. Verification loop (mandatory DX)

npm run check:design && npm run check:shell && npm run check:proofs \
  && npm run check:typeset && npm run check:experience && npm run check:contrast

After implementing, agents must:

1. Run the gates
2. List any unmet MUST from design.md / uxLaws / dxLaws
3. Fix or explicitly call out blockers

Hope is not a DX strategy — audit is (Pandya).

6. Machine-readable surface

Docs for humans and agents must stay one grammar — not three drifting stories.

7. Anti-patterns (DX)

8. Agent checklist

• Followed Always load tier
• Used closed grammar / presets (no invented scales)
• Owned loading / empty / error if building a resource surface
• Ran check:experience + sibling gates
• Did not invent a twin component or shell

Sources

• Vercel Design Engineer Principles
• Progressive disclosure of complexity (Rauch / Refactoring)
• Building systems in layers (Capozzi)
• Expose your design system to LLMs (Pandya)
• What is DESIGN.md (Superdesign)
• How to write a good spec for AI agents (Osmani)
• Linear UI redesign