Calibrate

Calibrate is a local-first design system compiler for design engineers. It reads your Figma file, builds a structured model of your design system, and uses it to scaffold typed components, design tokens, MDX docs, and AI implementation prompts — all from the terminal or your AI IDE.

No cloud sync. No proprietary lock-in. Your design system lives in git.

What it does

Figma  →  ptb scan  →  ptb generate-components  →  typed React shells
                    →  ptb generate-tokens        →  CSS custom properties
                    →  ptb export context          →  .ptb/context/ + AI.md (commit these)
                    →  ptb mcp                     →  live MCP server for AI IDEs
                    →  ptb implement component     →  AI-written component code
                    →  ptb document component      →  MDX docs + Storybook stories
                    →  ptb verify component        →  pixel diff + AI visual feedback
                    →  ptb status                  →  staleness tracking in CI

When your designer updates a component in Figma, ptb scan picks up the change, ptb diff shows what changed, and ptb status tells you which implementations are stale. The whole team stays in sync through a committed ptb.lock — no external service required.

Once your AI IDE is connected via MCP, you can run scans, generate code, stamp components, and inspect design context entirely from chat — no terminal needed.

Install

Requirements: Node.js ≥ 20 — download here if you don't have it.

Mac / Linux

Run these once to fix npm permissions, then install:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=$HOME/.npm-global/bin:$PATH' >> ~/.zshrc 2>/dev/null || echo 'export PATH=$HOME/.npm-global/bin:$PATH' >> ~/.bash_profile
export PATH=$HOME/.npm-global/bin:$PATH
npm install -g @calibrate-ds/cli
ptb --version

The first three lines only need to be run once — they fix the permission issue permanently. Next time, just npm install -g @calibrate-ds/cli.

Windows

Open PowerShell as Administrator and run:

npm install -g @calibrate-ds/cli
ptb --version

Quickstart

1. Initialize

cd your-project
ptb init

PTB detects whether your repo is fresh or existing:

• Fresh repo — scaffolds packages/ui/ with framework-specific package.json, tsconfig.json, and component/token directories
• Existing repo — writes ptb.config.json and .gitignore entries only, leaves your code untouched

You will be asked to choose:

• Framework (React, Vue, Svelte, React Native)
• Solo or team project
• Figma plan (Organization/Enterprise for direct API, or Pro/Starter for the Calibrate plugin)
• Documentation tool (Storybook, Docusaurus, or plain MDX)

2. Set your Figma token

export FIGMA_ACCESS_TOKEN=your_token_here

Generate a token at Figma → Account Settings → Security → Generate New Token. PTB never stores the token — ptb.config.json only stores the env var name.

To make it persist across terminal sessions, add the export line to ~/.zshrc or ~/.bashrc.

3. Scan your Figma file

Organization / Enterprise — PTB reads directly from the Figma API, no plugin needed:

ptb scan

Pro / Starter / Free — first export your tokens using the plugin:

1. Install CalibrateDS on Figma Community
2. Open your Figma file → Plugins → CalibrateDS → Token Exporter → Export PTB JSON
3. Save the file as imported-tokens.json in your .ptb/ folder (press Cmd+Shift+. on Mac to reveal hidden folders)
4. Then run:

ptb scan

ptb scan fetches your Figma file, normalizes it into a structured model, saves it to .ptb/latest.json, exports component context files to .ptb/context/, and auto-generates AI.md at your package root.

Find your file key in the Figma URL: figma.com/design/<FILE_KEY>/... — paste it into ptb.config.json as designTool.fileKey.

On every update: whenever your designer changes tokens or variables re-run the CalibrateDS plugin export (Pro/Starter/Free) or just ptb scan (Org/Enterprise) to pull the latest.

4. Generate components and tokens

ptb generate-components    # typed React shells in packages/ui/src/components/
ptb generate-tokens        # CSS custom properties in packages/ui/src/tokens/
ptb export context         # write .ptb/context/ files for AI IDEs — commit these

5. Connect your AI IDE (MCP)

PTB runs as an MCP server, exposing your design system as a live data source to any AI IDE that supports the Model Context Protocol: Claude Code, Cursor, Windsurf, Gemini/Antigravity, and others.

This is the recommended way to work with PTB — once connected, you can run scans, generate code, inspect components, and stamp implementations entirely from chat.

See the MCP Setup section below for per-IDE instructions.

6. Implement with AI

Once MCP is connected, ask your AI IDE directly:

• "What are the variant axes for the Button component?"
• "Run a scan and generate the Button component"
• "Which components are stale?"

Or use the CLI:

ptb ai setup               # configure Claude or OpenAI once
ptb implement component Button

7. Track freshness

ptb status                 # shows which components are stale vs implemented
ptb stamp component Button # mark Button as implemented against the current design

MCP Server — AI IDE Integration

PTB exposes 22 tools over a stdio MCP server. Your AI IDE can query component design context, run scans, generate code, and manage stamps — all from chat. Everything you can do in the terminal, you can do from chat.

Available tools

Inspection

| Tool | What it does | |---|---| | list_components | List all components with kind, category, variant axes, and Figma node ID | | get_component | Full design context: variant axes, token bindings, state/interaction contracts, render tree | | find_component_by_figma_node | Resolve a Figma node ID to its component | | get_status | Compare stampedHash vs designHash — what is ready, stale, or unimplemented | | what_uses | Which components depend on a given component | | token_impact | Which components are affected by a token change | | list_themes | List all token collections and their modes | | get_token | Resolve a token name to its value and which components reference it |

Pipeline

| Tool | What it does | |---|---| | run | Run a PTB pipeline stage: scan, generate, tokens, context, prune |

Work lifecycle

| Tool | What it does | |---|---| | assign_component | Assign a component to a developer | | start_work | Claim a component and get the full implementation brief (context, deps, acceptance criteria) | | implement_component | Get design context + dependency plan — AI writes code, runs verify, and stamps | | submit_work | Stamp work done — reads report.json, hard-blocks on scaffold/missing report, enforces regression gate | | document_component | Generate MDX documentation and/or Storybook stories |

Governance

| Tool | What it does | |---|---| | run_diff | What changed in Figma, grouped into new / not-implemented / drifted — variant axes, layout, size, typography, text, structure, dependencies, per-variant; every change shown regardless of stamp state. Optional name scopes to one component | | diff_clear | Acknowledge the current design as the diff baseline (reporting-only; never touches ptb.lock) | | my_queue | Components assigned to the current developer, sorted by status |

Verification

| Tool | What it does | |---|---| | run_verify | Pixel-diff the implementation against Figma thumbnails — requires Storybook running locally | | get_verify_report | Last verification report for a component without re-running |

Setup & info

| Tool | What it does | |---|---| | setup_mcp | Configure PTB MCP for additional AI IDEs (Cursor, Windsurf, Antigravity, VS Code) | | get_checklist | Live setup or upgrade checklist with state detection (kind: "setup" or "upgrade") | | whats_new | Per-version upgrade changelog — what to re-run after updating PTB |

Setup: Claude Code (zero config)

ptb init writes .mcp.json at your project root — Claude Code reads this automatically. Just restart Claude Code after running ptb init and PTB tools will appear in chat.

Commit .mcp.json to your repo. Teammates who clone it get PTB tools in Claude Code with no extra steps.

If you're adding PTB to an existing project that already has a ptb.config.json, create .mcp.json manually:

{
  "mcpServers": {
    "ptb": {
      "command": "ptb",
      "args": ["mcp"]
    }
  }
}

Setup: Other IDEs (Cursor, Windsurf, Antigravity, VS Code)

Once PTB is connected in Claude Code, ask in chat:

"set up MCP for cursor"

The setup_mcp tool writes the correct config file for the requested IDE and tells you what to restart. No terminal needed.

Or run from the terminal to configure all detected IDEs in one step:

ptb mcp setup             # auto-detects and configures all installed IDEs
ptb mcp setup cursor      # configure a specific IDE
ptb mcp setup antigravity
ptb mcp setup windsurf
ptb mcp setup vscode

What gets written:

| IDE | Config file | |---|---| | Claude Code (user-level) | ~/.claude/mcp.json | | Cursor | ~/.cursor/mcp.json | | Windsurf | ~/.codeium/windsurf/mcp_config.json | | Gemini / Antigravity | ~/.gemini/antigravity/mcp_config.json | | VS Code (GitHub Copilot) | .vscode/mcp.json at project root |

Existing entries in these files are preserved — only the ptb entry is added or updated.

Why --cwd is required for non-Claude-Code IDEs

Most AI IDEs spawn the MCP server from their own install directory, not your project root. Without --cwd, PTB can't find your ptb.config.json. The setup_mcp tool and ptb mcp setup set --cwd to your project root automatically.

Figma token and the MCP server

The MCP server is a separate process from your terminal — it does not inherit your shell exports. If run({ stage: "scan" }) tells you FIGMA_ACCESS_TOKEN is not set in the MCP server environment, that is why.

Never put your token directly in the MCP config file. That file can end up in a dotfiles repo, get synced, or be shared — treat it like a .env file.

Option 1 — Launch your IDE from the terminal (recommended):

First, add the token to your shell profile so it's always set:

# Add to ~/.zshrc or ~/.bashrc, then open a new terminal tab
export FIGMA_ACCESS_TOKEN=your_token_here

Then always open your IDE from the terminal, not the dock:

cursor .    # Cursor
code .      # VS Code

The IDE inherits the terminal's environment, so the MCP server gets the token automatically.

Option 2 — IDE launched from the dock (Mac):

Use launchctl to set the variable at the OS session level so all GUI apps inherit it:

launchctl setenv FIGMA_ACCESS_TOKEN your_token_here

Fully quit and relaunch your IDE. This persists until you log out — re-run it after each restart or add it to a login script.

Option 3 — Last resort, env block in MCP config:

Some IDEs support an env block in the MCP config file. The token is stored in plain text on disk, which is acceptable as long as the file is never committed to git:

echo "mcp.json" >> ~/.gitignore   # gitignore the config file first

Then add the block to your MCP config — but prefer options 1 or 2 to keep credentials out of config files entirely.

After upgrading PTB

1. Update the CLI: npm install -g @calibrate-ds/cli
2. Restart your IDE's MCP server (the IDE needs to re-spawn the process)
3. Ask your AI IDE: "whats_new" to see what to re-run
4. Run ptb scan (or ask your IDE to run({ stage: "scan" })) to pick up any scanner changes

Symbol Bridge

PTB maintains a ptb-bridge.json file that maps Figma node IDs to your exported component symbols. This lets the find_component_by_figma_node MCP tool tell your AI IDE exactly which file and export name corresponds to a Figma component — enabling design-to-code navigation.

The bridge is automatically updated whenever you run ptb generate-components. To add entries manually:

ptb bridge add <nodeId> <ComponentName> <relative/path/to/Component.tsx>
ptb bridge list    # show all entries

Commit ptb-bridge.json alongside your other PTB files.

Configuration

ptb init creates ptb.config.json at your project root. All fields:

{
  "designTool": {
    "provider": "figma",
    "fileKey": "YOUR_FIGMA_FILE_KEY",
    "accessTokenEnv": "FIGMA_ACCESS_TOKEN"
  },
  "project": {
    "rootDir": "."
  },
  "output": {
    "componentsDir": "packages/ui/src/components",
    "tokensDir": "packages/ui/src/tokens",
    "metadataDir": ".ptb"
  },
  "framework": {
    "name": "react",
    "typescript": true,
    "styling": "css-modules"
  },
  "generation": {
    "stories": true,
    "tests": false,
    "types": true,
    "indexFiles": true,
    "cssFiles": true
  },
  "naming": {
    "componentCase": "PascalCase",
    "folderCase": "kebab-case",
    "tokenCase": "camelCase"
  },
  "classification": {
    "treatComponentSetsAsCanonical": true,
    "treatStandaloneComponentsAsCanonical": true,
    "treatNestedInstancesAsReferences": true
  },
  "docs": {
    "tool": "storybook",
    "format": "both"
  },
  "ai": {
    "active": "claude",
    "providers": {
      "claude": {
        "model": "claude-sonnet-4-6",
        "accessTokenEnv": "ANTHROPIC_API_KEY"
      }
    }
  }
}

designTool.accessTokenEnv stores the name of the env var, never the token itself. PTB validates that this value is SCREAMING_SNAKE_CASE on startup.

AI setup

ptb ai setup        # interactive: choose provider, set env var name, pick model
ptb ai list         # show all configured providers
ptb ai use claude   # switch active provider
ptb ai model        # change model for active provider

Supported providers: Claude (Anthropic), OpenAI. Local models via OpenAI-compatible baseUrl are also supported.

# Claude
export ANTHROPIC_API_KEY=sk-ant-...
ptb ai setup   # choose "claude"

# OpenAI
export OPENAI_API_KEY=sk-...
ptb ai setup   # choose "openai"

Recommended models

| Provider | Recommended model | |---|---| | Anthropic | claude-opus-4-7 or claude-sonnet-4-6 | | OpenAI | gpt-4o or o3 |

Weaker models will produce code that compiles but misses design intent — wrong spacing, ignored variants, missing accessibility attributes.

Using your AI IDE with PTB context files (no ptb implement)

ptb implement is useful for batch generation. For interactive development, skip it entirely and let your AI IDE read PTB's context files directly.

PTB extracts everything from Figma into structured JSON. Your AI IDE doesn't need a live Figma connection — .ptb/context/ files contain variant axes, token bindings, state contracts, layout, render trees, and interaction contracts.

Workflow:

1. Run ptb export context after each scan (or use run({ stage: "context" }) via MCP)
2. ptb scan auto-generates AI.md at your package root — most AI IDEs pick this up automatically
3. Connect the MCP server — then ask your IDE: "get_component Button" for full design context
4. Let the AI write the component — it has full design intent without needing Figma access

Team workflow

PTB tracks design-to-implementation freshness through a committed ptb.lock file. No server required.

Setup

ptb init          # scaffolds project, registers you as lead, creates ptb.lock
ptb join          # teammates register themselves (they join as members)
git add ptb.lock ptb-team.json

Roles

• The person who runs ptb init is automatically the lead
• All subsequent ptb join calls give the member role
• Leads can assign components to anyone, reassign, and stamp any component
• Members can only self-assign and stamp components assigned to them
• The last lead cannot be demoted

ptb team                          # show roster with roles
ptb team role @alice lead         # promote alice to lead
ptb team role @bob member         # demote to member

Assigning work

ptb assign Button                  # self-assign to yourself
ptb assign Button @alice           # assign to alice (leads only)
ptb assign . @alice                # assign all unimplemented to alice (leads only)
ptb assign Button --clear          # unassign
ptb status --team                  # workload by assignee
ptb status --mine                  # only your assignments

Stamping implementations

ptb stamp component Button
ptb stamp component Button -m "implemented with new focus ring per design v2"
ptb stamp component .              # stamp all

Or ask your AI IDE: "submit_work Button" — no terminal needed.

Viewing history

ptb log     # design changes and stamps from git history
ptb diff    # unstamped design changes since last scan

CI integration

ptb ci setup      # leads only

Generates .github/workflows/ptb.yml — a GitHub Actions workflow that runs ptb status --fail-on-stale on every push and PR.

For CI to work without a Figma token, commit your context files after each scan:

ptb export context
git add .ptb/context/ ptb.lock
git commit -m "chore: update design system context"

Documentation

ptb document component Button          # single component: MDX + stories
ptb document component .               # all components
ptb document component Button --force  # overwrite existing
ptb document component Button --no-ai  # deterministic tables only, no AI prose
ptb document system                    # generate AI.md and components.md

AI.md is also auto-generated on every ptb scan — you only need ptb document system to regenerate components.md or get AI-enhanced intent descriptions.

Context and prompts

ptb export context                    # export all context to .ptb/context/
ptb context component Button          # display rich context in terminal
ptb context component Button --json   # machine-readable JSON
ptb prompt component Button           # print AI implementation prompt
ptb prompt component . --format json  # write all prompts to .ptb/prompts/

Context files in .ptb/context/ are designed to be committed and read by AI tools. They contain the full component model: variant axes, token bindings, state contracts, layout, render tree, and interaction contracts.

Health checks

ptb doctor                       # system check: config, token, snapshot age
ptb doctor component Button      # deep audit: 10-point score
ptb doctor component .           # scorecard for all components
ptb doctor tokens                # token resolution coverage
ptb doctor context Button        # AI context quality score
ptb doctor build                 # run tsc --noEmit to catch generation-time type errors

A low doctor score means your Figma components lack the data PTB needs (Auto Layout, token bindings, variant axes, descriptions). Fix in Figma, re-scan, score improves.

What gets committed to git

ptb.config.json        # your PTB configuration — commit this
ptb.lock               # design hash tracking — commit this
ptb-team.json          # team roster — commit this
ptb-bridge.json        # Symbol Bridge (Figma node → code symbol) — commit this
.ptb/context/          # component context files — commit after ptb export context
.ptb/manifest.json     # generated file tracking — commit this
.github/workflows/     # CI workflow — commit this
AI.md                  # auto-generated on every scan — commit this

.ptb/latest.json       # gitignored — large Figma snapshot
.ptb/history/          # gitignored — snapshot history
.ptb/.meta.json        # gitignored — upgrade notice state
*.ptb-meta.json        # gitignored — inline metadata

ptb init writes the correct .gitignore entries automatically.

Telemetry

PTB collects anonymous usage data to help understand which commands are used and improve the tool. A one-time notice is printed on first run. No personal data is ever collected.

Tracked: command names, PTB version, OS, Node.js version.

Never tracked: Figma file keys, token values, component names, file contents, IP addresses, or any project-specific data. Each installation gets a random anonymous UUID stored locally — not linked to any identity.

ptb telemetry off     # disable
ptb telemetry on      # re-enable
ptb telemetry         # check status

Telemetry state lives at ~/Library/Application Support/calibrate-ds/telemetry.json (macOS) or ~/.config/calibrate-ds/telemetry.json (Linux). See the privacy policy for full details.

Getting help

ptb --help                  # full command list
ptb <command> --help        # flags for one command
ptb guide                   # list all topic guides
ptb guide <topic>           # focused reference for a feature area
ptb learn                   # interactive onboarding walkthrough

Available guide topics: setup · context · implement · document · status · team · ai · doctor · ci

Command reference

Setup & scanning

| Command | What it does | |---|---| | ptb init | Initialize PTB, scaffold fresh repos, write config | | ptb scan | Fetch Figma file, save snapshot, export context, regenerate AI.md | | ptb generate-components [name] | Scaffold typed component shells, update Symbol Bridge, auto-generate stories (if generation.stories: true) | | ptb generate-tokens | Scaffold CSS token files | | ptb import-tokens <path> | Import a CalibrateDS plugin token export |

MCP server

| Command | What it does | |---|---| | ptb mcp | Start MCP stdio server for AI IDEs | | ptb mcp --cwd <path> | Start server with an explicit workspace path (required in most IDE configs) | | ptb mcp setup | Configure MCP for all detected AI IDEs automatically | | ptb mcp setup <ide> | Configure a specific IDE: claude-code, cursor, windsurf, antigravity, vscode |

Symbol Bridge

| Command | What it does | |---|---| | ptb bridge add <nodeId> <name> <path> | Manually register a Figma node → component mapping | | ptb bridge list | Show all Symbol Bridge entries |

Context & prompts

| Command | What it does | |---|---| | ptb export context | Export component context files for AI tools | | ptb context component <name> | Display rich component context | | ptb prompt component <name> | Print AI implementation prompt |

AI implementation

| Command | What it does | |---|---| | ptb implement component <name> | AI-generate component implementation, auto-start Storybook, verify, and stamp when score ≥ 90% | | ptb implement component <name> --no-verify | Skip verify gate and stamp immediately | | ptb plan | Show which files are affected by the latest diff | | ptb apply | Regenerate only the files affected by design changes | | ptb prune | Remove stale component folders no longer in Figma |

ptb implement now closes the loop automatically: after writing files it checks whether Storybook is running (ports 6006–6020), starts it if not, runs ptb verify against the Figma thumbnail, and only stamps the component when pixel match ≥ 90%. If the score falls short, it prints the diff score and tells you what to fix before re-running. Pass --no-verify to bypass the gate.

Playground

| Command | What it does | |---|---| | ptb dev | Start the local component playground (hot-reloads on manifest changes) |

The playground renders every implemented component live at http://localhost:4321. Each component page has three view modes:

• Live — live React render with variant controls
• Design — Figma scan thumbnail (the visual ground truth from ptb scan)
• Overlay — Figma thumbnail and live render stacked, with a slider to cross-fade between them (left = design, right = implementation)

The Overlay mode makes visual drift immediately visible without leaving the browser. It only appears when a thumbnail exists (i.e. ptb scan was run).

Documentation

| Command | What it does | |---|---| | ptb document component <name> | Generate MDX docs and Storybook stories | | ptb document system | Generate AI.md and components.md |

Status & tracking

| Command | What it does | |---|---| | ptb status | Check implementation freshness | | ptb diff | Show unstamped design changes since last scan | | ptb log | Show design change and stamp history | | ptb stamp component <name> | Mark a component as implemented | | ptb assign <name> [person] | Assign a component to a developer |

Team

| Command | What it does | |---|---| | ptb join | Register yourself in the team roster | | ptb team | Show team roster and workload | | ptb team role <handle> <role> | Promote or demote a team member (leads only) |

AI providers

| Command | What it does | |---|---| | ptb ai setup | Configure AI provider | | ptb ai list | List saved providers and active one | | ptb ai use <provider> | Switch active provider | | ptb ai model [id] | Change model for active provider |

Visual verification

| Command | What it does | |---|---| | ptb verify component <name> | Compare Figma design thumbnail vs Storybook render, pixel-diff, get AI feedback |

Options: --storybook-url <url> · --impl-screenshot <path> · --no-ai · --fresh-figma · --story <storyId>

By default the Figma reference is the thumbnail captured at scan time — no Figma token needed. Pass --fresh-figma to force a live screenshot from the Figma API.

Story resolution reads Storybook's index.json at runtime (tries /index.json, /stories.json, then storybook-static/index.json for static builds) and matches by component importPath — no title convention to maintain. Use --story <id> to override. If the story can't be resolved or renders an error page, verify hard-fails with a non-zero exit and explains what to fix.

Output written to .ptb/verify/<slug>/ — figma.png, impl.png, diff.png, report.json.

Health & CI

| Command | What it does | |---|---| | ptb doctor | System and component health audit | | ptb doctor build | Run tsc --noEmit against the DS package | | ptb ci setup | Generate GitHub Actions freshness workflow (leads only) | | ptb remove | Remove all PTB config and metadata from this project |

Help & onboarding

| Command | What it does | |---|---| | ptb guide [topic] | Focused workflow reference per feature area | | ptb learn | Interactive onboarding walkthrough | | ptb flow direct | Checklist for direct Figma API workflow | | ptb flow plugin | Checklist for CalibrateDS plugin workflow |

Supported frameworks

| Framework | Scan & Track | Generate Components | Storybook | |---|---|---|---| | React | ✓ | ✓ | ✓ | | Vue 3 | ✓ | coming soon | ✓ (Vite) | | Svelte | ✓ | coming soon | ✓ (Vite) | | React Native | ✓ | coming soon | — |

All frameworks support the full governance workflow (scan, diff, status, stamp, assign, CI) and documentation generation. Code generation is React-first for v1.

Roadmap

| Milestone | What shipped | |---|---| | M1 | Scan → generate → governance → team workflow | | M2 | ptb verify — visual diff + AI feedback | | M3 | ptb mcp — live MCP server + Symbol Bridge | | M4 | ptb dev playground + three-column ptb status | | M5 | Verify-gated implement loop, story index resolution, playground overlay | | M5.5–M5.6 | 44-gap audit — CSS emission, naming, lifecycle integrity, scaffold guard, real verify gate (0.1.55 → 0.1.66) |

Contributing

See PTB.md for architecture, type definitions, the generator interface, and internal conventions.

pnpm install
pnpm build
pnpm test            # 528 tests across core, generator, and CLI
node apps/cli/dist/index.js --help