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 (React, Vue, Svelte), workflow type, and documentation tool.

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 22 tools.