using-bridge

name	using-bridge
description	Use when any Bridge command is invoked (make, fix, done, setup, drop, status) or any Figma / design-system / compiler / Bridge workflow topic is raised. Sets command priorities and iron laws (compiler-only, semantic tokens only, verification-before-ship).

Using Bridge

Bridge is a compiler-driven design workflow for generating Figma designs and maintaining a design system via Claude Code. The compiler (at lib/compiler/compile.ts) enforces all 26 Figma Plugin API rules, so Claude NEVER writes raw Plugin API code and NEVER hardcodes primitive values.

This skill is force-loaded at every SessionStart via hooks/session-start. Its job is to establish the discipline before any action skill runs. It is deliberately small (~400 tokens) to keep the fixed per-session cost low.

---

Command Map

User intent (keywords)	Route to
"make", "design", "create", "build", "generate", "new component", "new screen"	generating-figma-design
"fix", "correct", "learn", "diff", "what changed", "I adjusted"	learning-from-corrections
"done", "ship", "ship it", "finish", "complete"	shipping-and-archiving
"setup", "setup bridge", "extract", "extract DS", "onboard", "initialize", "bootstrap"	extracting-design-system
"drop", "abandon", "cancel"	inline Drop Procedure (this skill)
"status", "what's next", "workflow"	inline status logic (this skill)

---

Drop Procedure (inline)

drop is handled inline here — it is small enough not to warrant its own skill. Invoke when the user says "drop", "abandon", or "cancel".

1. Confirm. Ask: "Sure you want to drop {name}?"
2. Capture learnings. If a snapshot exists, offer to run fix first to capture corrections before archiving.
3. Document drop reason. Append a drop: block to the CSpec with date, reason, and learnings.
4. Archive. Move specs/active/{name}.cspec.yaml → specs/dropped/{name}.cspec.yaml. Move the snapshot JSON too if it exists.
5. Update history. Append {ISO date} | {name} | DROPPED | {reason} to specs/history.log.
6. Cleanup. Remove /tmp/bridge-scene-{name}.json if present.

Output template:

## Dropped: {name}

Reason: {reason}
CSpec archived: specs/dropped/{name}.cspec.yaml
Learnings: {captured | skipped}

Ready for the next design. Run: `make <description>`.

---

Skill Priority

1. Process first, then action. For exploratory or ambiguous requests, brainstorm the intent first before implementing. For a clear directive that maps to a command in the table above, route directly.
2. Verification before completion. No "done" without evidence (see Iron Laws below).
3. Minimal context. Load only the references needed for the current action. See each action skill's ## Verification section.

---

Iron Laws (non-negotiable)

NEVER write raw Figma Plugin API code. All scene graph JSON must pass through `lib/compiler/compile.ts`. Violations require explicit human approval before any execution to Figma. NEVER use hardcoded primitive values. Only semantic DS tokens (`$color/...`, `$spacing/...`, `$text/...`, `$comp/...`). The compiler emits `RESOLVE_TOKEN_NOT_FOUND` for any unresolved reference. NEVER claim "done" without: (a) compiler exit 0, (b) screenshot taken in this turn, (c) user confirmation of visual correctness. "Looks right" / "should pass" / "I'm confident" are forbidden — show the evidence. NEVER read `figma-api-rules.md`. The compiler enforces all 26 rules. This file does not exist in v6. NEVER reuse a Figma `nodeId` from a previous session. Node IDs are session-scoped — re-search.

---

Red Flags — Rationalization → Reality

Rationalization	Reality
"I'll just hardcode this hex once"	Always use a semantic token. No exceptions.
"The compiler is overkill for this tiny thing"	The compiler is the only path.
"Skip the screenshot, it's obviously right"	'Looks right' ≠ 'is right'.
"I remember this nodeId from my last session"	Node IDs are session-scoped. Re-search.
"I'll use figma-api-rules.md for context"	That file is forbidden. Compiler owns all rules.
"The user approved, I can skip the compile exit code check"	Compile exit 0 is Gate A. Independent of user approval.
"Let me write a small inline Plugin API script for this fix"	No inline scripts. Scene graph → compiler → execute.

---

References

• Compiler reference: references/compiler-reference.md (repo-root)
• Transport adapter: references/transport-adapter.md (repo-root)
• Verification gates: references/verification-gates.md (repo-root)
• Red Flags catalog: references/red-flags-catalog.md (repo-root)

---

Conversation Language Rule

• Conversation with the user: their language (detect from context).
• All generated artifacts (KB files, CSpecs, guides, learnings, recipes, scene graphs, docs, specs, plans): English only. This rule is non-negotiable per Bridge's artifact policy.