ContractsMeridian

For agents

Built so models stay true.

UX + DX first. Strict load order. Compose shadcn under frozen laws — creativity stays in the story, not the tokens.

agents.md

RawInstallGolden pathUXDXProofs

Design contract install

Install into any project

Agent stack: law book + verified skills + CI gates are required. Contract MCP is optional. shadcn MCP / CLI installs atoms; Meridian keeps agents inside closed tokens via docs, skills, and npm run validate.

0. Agent loop (golden path)
Fail-closed order — gates are the bailiff, not a skipped tool call.
  1. 01Load /meridian/design.md + /meridian/agents.md (REQUIRED FIRST)
  2. 02Open meridian-* skill (compose / specialty) — verified cookbook
  3. 03Pick a task recipe — list-resource / object-detail / agent-rail / …
  4. 04list_primitives + shadcn add — compose approved atoms only; never twin kits
  5. 05npm run validate — REQUIRED BEFORE DONE (check:design · platform · contrast)
  6. 06Optional MCP: get_contract → validate_ui when the session is tool-wired
1. Skills (required cookbook)
Native Meridian skill pack — theme, compose, specialty.

all skills

npx skills add byronwade/ui.byronwade.com

Meridian theme skill

npx skills add byronwade/ui.byronwade.com --skill meridian-theme
2. Law book + gates
Machine markdown + npm run validate.

done gate

npm run validate
3. Compose with shadcn
Install atoms, then stay inside the contract.

shadcn init

npx shadcn@latest init -d --base radix

add primitives

npx shadcn@latest add button card input table tabs dialog
4. Contract API (JSON)
Slim consistency kit — mandate, tokens, primitives, recipes.

curl

curl -sS https://ui.byronwade.com/r/meridian.contract.json

/r/meridian.contract.json

5. Optional — contract MCP
Accelerator for tool-calling agents. Not a substitute for gates.

npx (any project)

CONTRACT_ID=meridian CONTRACT_SITE=https://ui.byronwade.com npx -y --package=github:byronwade/ui.byronwade.com contract-mcp

.cursor/mcp.json

{
  "mcpServers": {
    "meridian-contract": {
      "command": "npx",
      "args": [
        "-y",
        "--package=github:byronwade/ui.byronwade.com",
        "contract-mcp"
      ],
      "env": {
        "CONTRACT_ID": "meridian",
        "CONTRACT_SITE": "https://ui.byronwade.com"
      }
    },
    "shadcn": {
      "command": "npx",
      "args": [
        "shadcn@latest",
        "mcp"
      ]
    }
  }
}
get_contractresolve_tokenvalidate_uilist_primitivesget_recipeapply_prefs

shadcn MCP/CLI installs atoms. Law book + skills + npm run validate enforce the system. Contract MCP is optional.

Contributor checkout: CONTRACT_ID=meridian node packages/contract-mcp/server.mjs

Next: explore UI primitives, app shells, theme, and design.md — all styled with Meridian tokens on this route.

DX · Always tier

Golden path

Compose shadcn + frozen presets. Depth loads on Ask — don’t dump every skill into the first prompt.

import { Button } from "@/components/ui/button"
import { typesetClass, 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>
  )
}
  1. 1 · data-surface
  2. 2 · shadcn atoms only
  3. 3 · typesetClass

DX · closed atoms

Primitive contracts

Required states + ARIA for shipped shadcn atoms. Prefer a rule over a new component — see dx.md.

  • button

    button

    components/ui/button.tsx

    States

    rest · hover · pressed · focusVisible · disabled · destructive

    Must

    • Use Button from @/components/ui/button
    • motion-press for juicy press
    • focus-visible ring (not fill alone)
    • Icon-only: aria-label required

  • input

    input

    components/ui/input.tsx

    States

    rest · hover · focusVisible · disabled · invalid

    Must

    • radiusIntent control (rounded-lg)
    • focus ring via ring-ring
    • Label every field

  • badge

    badge

    components/ui/badge.tsx

    States

    rest

    Must

    • Semantic status ≠ brand decoration
    • Mono for tool/activity names

  • card

    card

    components/ui/card.tsx

    States

    rest

    Must

    • edge or depth-* — never Tailwind shadow-*
    • rounded-2xl panel radius

  • separator

    separator

    components/ui/separator.tsx

    States

    rest

    Must

    • Stroke before shadow for separation

Prove every skill

The website exercises the full loop — 5 skills, each with a live proof.

  1. 01 · ThemeTheme grammar
  2. 02 · SurfaceSurface gallery
  3. 03 · ComposeLive proofs
  4. 04 · CinematicContract film
  5. 05 · A11yContrast audit

Start here

Frozen vs creative

frozen
Locked
Color, radius, depth, surfaces, bans, cinema laws, contrast.
  • colorRoles
  • radii
  • depths
  • surfaces
  • themeKnobs
  • activityRoles
  • banned
  • cinematicLaws
  • materialLaws
  • designInfluences
  • shellRhythm
  • shellLaws
  • controlScale
  • spaceScale
  • brandPresets
  • radiusPresets
  • paperPresets
  • interactiveProofStates
  • laneLaws
  • motionLaws
  • typesetPresets
  • typesetLaws
  • typesetRhythm
  • uxLaws
  • dxLaws
  • dxLoadTiers
  • requiredUiStates
  • interactionStateRecipe
  • interactionClasses
  • resourceProofStates
  • primitiveContracts
  • primitiveLaws
creative
Free
Copy, IA, domain objects, frame sequence, shadcn composition.
  • copy
  • informationArchitecture
  • domainObjects
  • frameSequence
  • whichShadcnPrimitives
  • whichTypesetPreset
  • narrativeWithinOneIdea
  • whichInteractiveProof
  • whichDisclosureLevel

Load order

  1. 1.design.md — contract
  2. 2.lib/design/ — grammar, recipes, contrast
  3. 3./system — research specs when composing space/motion/AI
  4. 4.Matching skill under skills/ (see /skills + prove links)
  5. 5.Compose via Workbench / ComposerShell proofs on /surfaces#proofs
  6. 6.npm run check:design && npm run check:contrast

Skills

Canonical under skills/ — browse the full index or copy a file.

All skills

Agents

Author implements; reviewer audits cinema laws, bans, and contrast.

  • agent
    meridian-author
    Implement under design.md + lib/design
  • agent
    meridian-reviewer
    Audit MUST / banned / cinema / contrast
Raw