designRFC005 — Figma kit + token sync pipeline

*tatus* v0.1.0 — Draft. Decision required to unblock Figma kit v0 (sample: Button + Card + Empty State per ticket #157).

R1 — Problem

KDS today has no official Figma kit. Designers work from:

• Screenshots of kds.koder.dev.
• Hand-rebuilt components in their own Figma files.
• Color tokens copied by eye from the Verge token table.

Result: structural drift between Figma designs and production code. Every release lands with "the prototype showed #1a2762, but production ships #1f3a93" surprises.

A Figma kit (per ticket #157) needs a sync mechanism so token changes in internal/kinds/verge.go propagate automatically to the Figma side, not in a separate manual step.

R2 — Options evaluated

Option A — Tokens Studio plugin (formerly Figma Tokens)

Most popular Figma token-sync plugin. Reads / writes JSON in the Tokens Studio Format. Sync via GitHub URL or local file.

*ros*

• Mature, well-known, large community.
• Designers can edit tokens IN Figma, push back to Git.
• Plugin handles token-set composition (light / dark / responsive).

*ons*

• Token format is NOT DTCG-spec — slight transformation needed

  from our DTCG-aligned dist/tokens/tokens.json.

• Twoway sync invites designerside edits to conflict with code-

  side edits; conflict resolution is manual.

• Adds a thirdparty dependency to the designside toolchain (each

  designer installs the plugin).

Option B — Specify CLI

Token-sync CLI tool that pulls from Git / GitHub and pushes to Figma via the Figma REST API. One-way: code → Figma.

*ros*

• One-way sync matches the intended direction (code is source of

  truth; Figma reflects).

• No designer-side plugin required.
• DTCG-spec native.

*ons*

• SaaS — Specify hosts the sync runner (conflicts with

  policies/self-hosted-first.kmd G1).

• Free tier limits; commercial pricing for larger teams.
• Adds a thirdpartycontrolled step in the release pipeline.

Option C — Custom Figma plugin reading from dist/tokens/tokens.json

Build a small Figma plugin (~200 lines TypeScript) that fetches https://kds.koder.dev/api/v1/tokens.json on open, applies the colors / fonts as Figma local styles (color styles + text styles).

*ros*

• Zero external SaaS — fetches from kds.koder.dev which we own.
• 100% selfhosted; aligns with `policies/selfhosted-first.kmd`.
• Reuses the alreadyemitted tokens.json (designgen #059).
• One-way enforcement (Figma reflects code; designer can't drift

  without intentional override).

• Plugin can be published to the Figma Community for any designer to

  install.

*ons*

• Need to author + maintain the plugin (TypeScript + Figma API).
• Designers can't propose token changes from Figma — they raise a

  spec PR in internal/kinds/verge.go like everyone else (arguably a feature: token changes are governance events, not designer-led).

• Initial dev cost ~3 days; ongoing maintenance light.

R3 — Decision criteria (per policies/self-hosted-first.kmd)

R4 — Recommendation

*dopt Option C (custom Figma plugin)*for v0.

Rationale:

1. The token export pipeline already exists (dist/tokens/tokens.json

   per design-gen #059). The plugin is the missing piece.

2. One-way enforcement is the right direction philosophically — token

   changes are governance events ratified in verge.kmd, not designer- side experiments.

3. Selfhostedfirst gates favor C cleanly.
4. Re-evaluation if designer experience plateaus — promotion to

   Tokens Studio (Option A) is a reversible follow-up if designers demand in-Figma token editing.

R5 — Implementation tickets

Sub-tickets to open after ratification (in a new tools/figma-bridge/ module under tools/ or as part of design-gen):

1. tools/figma-bridge#001 — Plugin scaffolding (manifest.json,

   TypeScript build, Figma plugin API setup).

2. tools/figma-bridge#002 — Token-fetch loop (fetch tokens.json on

   plugin open + on user-click "Sync Tokens").

3. tools/figma-bridge#003 — Color-styles writer (creates Figma local

   styles for each Verge color token).

4. tools/figma-bridge#004 — Text-styles writer (Verge typography

   roles → Figma text styles using Inter + JetBrains Mono families).

5. tools/figma-bridge#005 — Drift detector (compares current Figma

   styles to fetched tokens; flags drift in a side-panel).

6. tools/figma-bridge#006 — CI gate: workflow that fails the

   koder-stack release wave if Figma kit token export drifts from tokens.json checksum.

Plus, separate from the plugin:

• meta/brand/figma-kit#001..N — author the 3 sample components

  (Button, Card, Empty State) in Figma using the plugin-applied styles.

R6 — Cross-references

• Coordinates with tools/design-gen#059 — already emits

  tokens.json in DTCG-aligned shape; plugin consumes it.

• Coordinates with projects/koder-stack#156 — Storybook RFC chose

  Koder-native HTMX sandbox for live previews; Figma is the design source, not a code preview replacement.

• Coordinates with projects/koder-stack#158 — token distribution

  RFC (separate vertical: how product code consumes tokens; this RFC is how design tool consumes tokens).

R7 — Risk mitigation

Risks of Option C and how to mitigate:

• *igma API changes*breaking the plugin → plugin manifest pins

  the API version; bump deliberately with each Figma quarterly release.

• *lugin install friction for designers*→ publish to Figma

  Community + document install in the kit README.

• *esigner requests tokeneditinFigma*→ reopen this RFC at

  6mo evaluation; promote to Option A overlay if demand sustained.

Não-escopo

• The Figma kit content itself (components designed in Figma — separate

  metabrandfigma-kit tickets).

• CodefromFigma direction (Figma → code, e.g., Anima / Locofy) —

  out of scope; KDS is codefirst per `policies/codefirst.kmd`.

• Perproduct Figma kits (only KDSscoped here).