State Tracking Commands
These commands read the ptb.lock file to help you track Design Drift — the gap between the current Figma design and your implementation.
| Command | What it does |
|---|---|
ptb status | Three-column freshness table: Design (hash drift vs Figma), Code (contextHash drift in generated files), Visual (pixel diff score from last verify). |
ptb diff | Shows exactly what changed in Figma since your last stamp — variant axes added, tokens changed, layout shifts. |
ptb diff clear | Clears diff history after you've reviewed and addressed the changes. |
ptb log | Prints the git-style history of design changes and developer stamps. |
ptb stamp component <name> | Marks a component as implemented against the current design snapshot. Use . for all components. |
ptb assign <name> [person] | Assigns a component to a developer. Leads can assign anyone; members can only self-assign. |
ptb verify component <name> | Pixel-diffs your implementation against the Figma thumbnail. Requires Storybook running on localhost:6006. |
ptb what-uses <name> | Blast-radius analysis: every component that depends on the given one. See Change Management. |
ptb token-impact <token> | Every component using a specific token — run before changing a token value. |
ptb plan / ptb apply | Preview, then safely regenerate, only the generated files a design change affects. See Change Management. |
The three-column status table
Component Design Code Visual
BtnWeb ✔ in sync ✔ in sync ~ 87%
Notification ✔ in sync ✗ stale —
Toggle ~ drift ✔ in sync ✔ 99%
| Column | What it checks |
|---|---|
| Design | designHash vs stampedHash in ptb.lock — did Figma change since you last stamped? |
| Code | contextHash in the generated file header vs current design — is the file up to date? |
| Visual | Score from the last ptb verify run. — until you run verify at least once. |
ptb status --fail-on-stale exits with code 1 when any component is stale or visual score < 90%. Used in CI.
Verify before stamping
The recommended workflow is to run verification before stamping a component as done:
ptb verify component Button # score must be ≥ 0.90 to pass
ptb stamp component Button # once verify passes
Or from your AI IDE: the AI calls run_verify automatically after implement_component, adjusts styles if the score is below threshold, then calls submit_work.
The verify score is a composite — token content, DOM structure, and pixel similarity are each checked in priority order. A component with correct text content and structure can pass even if pixel alignment is slightly off. See Visual Verification for a detailed guide.
Next Steps
Review the AI Commands reference.