ContractsAtlas

For agents

Keep Atlas coherent

Load the contract, compose shadcn under frozen laws, validate before done. Install paths below — same tools on every system.

Full installcontract.json

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

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; Atlas 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 /atlas/design.md + /atlas/agents.md (REQUIRED FIRST)
  2. 02Open atlas-* 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 Atlas skill pack — theme, compose, specialty.

all skills

npx skills add byronwade/ui.byronwade.com

Atlas theme skill

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

/r/atlas.contract.json

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

npx (any project)

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

.cursor/mcp.json

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

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