Quickstart

This guide walks you through the full workflow: initialize PTB, connect to Figma, generate your design system, and have your AI IDE implement your first component.

1. Initialize your project

Navigate to your project directory and run:

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 your framework, workflow type, and documentation tool.

Beta note: component code generation is React (+ TypeScript, CSS Modules) only for now — Vue and Svelte generators are in progress. Scan, diff, status, and governance work regardless of framework. See Beta Scope & Limitations.

2. Add your Figma file key

Open ptb.config.json and replace "YOUR_FIGMA_FILE_KEY" with your actual file key. Find it in the Figma URL:

figma.com/design/<FILE_KEY>/your-file-name

Edit the fileKey field:

"designTool": {
  "fileKey": "AbCdEfGhIjKlMnOp"
}

3. Store your Figma token

ptb token set your_figma_token_here

Generate a token at Figma → Account Settings → Security → Generate New Token.

PTB stores the token in ~/.config/calibrate-ds/credentials.json — not in ptb.config.json. This single command works for both the CLI and the MCP server in your IDE. No shell profile edits, no restart required.

CI / server environments: use export FIGMA_ACCESS_TOKEN=your_token_here instead. PTB checks the env var first, so it always wins.

4. 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 Figma plugin:

1. Install CalibrateDS on Figma Community
2. Open your Figma file → Plugins → CalibrateDS → Token Exporter → Export PTB JSON
3. Save as imported-tokens.json in your .ptb/ folder
4. Then run ptb scan

ptb scan fetches your Figma file, normalizes it into a structured model, saves it to .ptb/latest.json, and exports component context to .ptb/context/.

5. 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 — commit these

6. Connect your AI IDE via MCP

ptb mcp setup

PTB auto-detects your installed AI IDEs (Claude Code, Cursor, Windsurf, VS Code) and writes the correct config for each. Restart your IDE once to pick it up.

Then open a chat and ask: "Run the PTB setup checklist" — your AI will respond with a live status report confirming the connection.

MCP is the recommended way to work with PTB. Once connected, you can scan, generate, implement, verify, and stamp components entirely from chat — no terminal needed.

See MCP Setup for manual IDE configs and troubleshooting.

7. Implement with AI

From your IDE chat:

"Implement the Button component"

Your AI calls implement_component, reads the full design context (variant axes, token bindings, state contracts), writes the component files, then calls run_verify to pixel-diff the result against the Figma thumbnail.

Or from the terminal:

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

ptb ai setup is required before ptb implement component — the command calls an AI provider to write code.

8. Preview in the playground

ptb dev

Starts a live Vite playground at http://localhost:4321. Every implemented component appears automatically — variant controls are sourced directly from your Figma model, no stories to write.

After every ptb implement, the CLI prints a direct link:

→ Preview: http://localhost:4321/component/button

9. Track freshness

ptb status                     # three-column table: Design / Code / Visual
ptb stamp component Button     # mark Button as implemented against current design

ptb status shows three signals per component:

Or from your IDE chat: "What components are stale? Stamp Button as done."

Next Steps

MCP is the primary way to use PTB — dive into the MCP Overview to see all 23 tools.