Design contract · preview

Vellum

Reading-first docs & help — typeset lanes, measured prose.

Reading lanes and typeset presets — not dashboard card grids. Measure stays honest at ~65ch.

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; Vellum 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.

01Load /vellum/design.md + /vellum/agents.md (REQUIRED FIRST)
02Open vellum-* skill (compose / specialty) — verified cookbook
03Pick a task recipe — list-resource / object-detail / agent-rail / …
04list_primitives + shadcn add — compose approved atoms only; never twin kits
05npm run validate — REQUIRED BEFORE DONE (check:design · platform · contrast)
06Optional MCP: get_contract → validate_ui when the session is tool-wired

1. Skills (required cookbook)

Native Vellum skill pack — theme, compose, specialty.

all skills

npx skills add byronwade/ui.byronwade.com

Vellum theme skill

npx skills add byronwade/ui.byronwade.com --skill vellum-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/vellum.contract.json

/r/vellum.contract.json

5. Optional — contract MCP

Accelerator for tool-calling agents. Not a substitute for gates.

npx (any project)

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

.cursor/mcp.json

{
  "mcpServers": {
    "vellum-contract": {
      "command": "npx",
      "args": [
        "-y",
        "--package=github:byronwade/ui.byronwade.com",
        "contract-mcp"
      ],
      "env": {
        "CONTRACT_ID": "vellum",
        "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=vellum node packages/contract-mcp/server.mjs

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

UI gallery

Shared shadcn — Vellum skin

One component set under components/ui. This route applies the DNA; we do not fork controls per contract.

Open full UI page →

Buttons & badges

Primary, outline, ghost, destructive — brand comes from this contract's --brand.

DefaultSecondaryOutline

App shells

Workbench & composer proofs

Product chrome — same shells as Meridian, restyled by Vellum.

Open surfaces →

Surface studio

Switch density lanes in one chrome

Workbench, composer, marketing, mobile, desktop — same tokens, remapped hit targets.

Surface studio

Try the lanes

application · agent

⌘K

empty via search

ID	Title	Meta
ISS-1842	Tighten selected-state contrast	2h
ISS-1839	Ship help drawer reading lane	48m
ISS-1831	Map activity to agent timeline	—
ISS-1820	Align edge depth on panels	1d

Application workbench

Object list + detail + agent rail — compose shadcn, don't twin shells.

⌘K

empty via search

ID	Title	Meta
ISS-1842	Tighten selected-state contrast	2h
ISS-1839	Ship help drawer reading lane	48m
ISS-1831	Map activity to agent timeline	—
ISS-1820	Align edge depth on panels	1d

Composer shell

Bound AI next to the object — provenance and activity stay readable.

01 export function IssueRow() {

02 return (

03 <tr className="bg-brand/10">

04 …

05 </tr>

06 )

07 }