ds-figma-handover

name	ds-figma-handover
description	Diff the Figma component library against the MQTT Viewer frontend and produce a handover doc listing exactly what code needs to change. Use when the user says "check Figma for changes", "what drifted", "generate a handover", "sync from Figma", or after a design update. This skill DETECTS and DOCUMENTS only — it does not edit component code (that's /ds-implement-handover).

Figma → Code Handover (drift detection)

You are the drift agent. Your job: compare the Figma design library to the code, and write a precise handover doc for the implementing agent. You do not modify component source. Output is one markdown doc.

Read first: docs/design-system/STORYBOOK_SPEC.md (esp. §7c tier sync semantics, §10 workflow) and frontend/AGENTS.md.

Inputs

• frontend/src/design-system/component-index.json — run pnpm ds:registry first to ensure it's current. Source of truth is the colocated .spec.jsons.
• Figma, via MCP tools: get_metadata, get_variable_defs, get_screenshot, get_design_context. Resolve nodes from each component's figma.nodeId/url.
• frontend/src/design-system/design-tokens.json for token names.
• Storybook MCP (optional, framework-agnostic mcpland/storybook-mcp): pull the current rendered screenshot/props of a component to compare against Figma — most useful for view drift. Needs Storybook served/built first (pnpm storybook or pnpm build-storybook).

Procedure

1. Refresh the index: pnpm ds:registry. Note any specMissing / todo components — list them as "unlinked, needs authoring", don't try to diff them.
2. For each figma-linked component, pull its Figma node and diff by tier (see spec §7c — tier dictates the diff):
   • primitive: compare Figma variant properties ↔ props[].options; Figma bound variables ↔ tokens[]. This is the high-confidence diff.
   • component: compare child instances ↔ dependencies[]; flag added/ removed/swapped children. Don't over-claim prop drift.
   • view: screenshot compare only; describe layout/content deltas in prose. Recompute the structural hash and compare to figma.lastSyncedHash. Unchanged hash → skip (no drift).
3. Tokens: diff Figma variables against design-tokens.json. Report renamed/added/removed tokens separately — they have blast radius across many components.
4. Flag tier problems: if a Figma node has variants but the spec says view, or vice-versa, call it out — tier must be fixed first.
5. Compute blast radius: for each changed primitive, list every component/ view that has it in dependencies[] (read from the index). Order the handover bottom-up: tokens → primitives → components → views.

Output

Write frontend/src/design-system/changes/<YYYY-MM-DD>-<slug>.md with:

# Handover: <slug> — <date>

## Summary
<one paragraph: what changed in Figma, scope, risk>

## Token changes
| token | change | affected components |
|---|---|---|

## Component changes (bottom-up)
### <Name> (<tier>)  — status: <current>
- Figma node: <url>
- Drift: <variant `danger` added | child Icon swapped | frame relayout ...>
- Files to edit: `frontend/src/.../X.svelte`, `X.spec.json`, `X.stories.svelte`
- Concrete instructions: <exact prop/option/token edits>
- New `lastSyncedHash`: <hash>  (implement agent writes this on completion)

## Unlinked / needs authoring
- <components with no figma link or no spec>

## Out of scope / human decision needed
- <ambiguous composition or data-wiring changes the agent shouldn't guess>

Rules

• Never edit .svelte, .spec.json, or stories. Detection only.
• Be concrete: name files, props, option values, token keys. The next agent should not have to re-inspect Figma.
• Don't invent drift. No hash change → no entry. Uncertain → "human decision".
• Keep the bottom-up ordering; it's how the implement agent sequences work.