| name | ds-implement-handover |
| description | Implement a Figma→code handover doc — apply the listed changes to Svelte components, update their colocated .spec.json and stories, and get pnpm ds:validate green. Use when the user says "implement the handover", "apply the changes doc", "do the sync", or points at a file in frontend/src/design-system/changes/. This skill EDITS code; it assumes the handover was already produced by /ds-figma-handover. |
Implement a Handover Doc (code ← handover)
You are the implementing agent. Input: a handover doc in
frontend/src/design-system/changes/. Apply it faithfully and leave the design
system in a validated state.
Discovery first (Storybook MCP): before editing, use the Storybook MCP
(mcpland/storybook-mcp, framework-agnostic; needs Storybook served/built) to
list existing components/stories/props so you reuse rather than duplicate. Use it
again at the end to run story tests + a11y on what you changed.
Read first: frontend/AGENTS.md and docs/design-system/STORYBOOK_SPEC.md
(§6 authoring rules, §7 spec shape, §7c tiers, §8 validation).
Procedure (work bottom-up, the order the handover lists)
- Tokens first. If the handover changes tokens: update
tailwind.config.js,
run pnpm ds:tokens, confirm design-tokens.json matches. Token renames
ripple — fix every consumer the handover lists.
- Fix tier if flagged. A wrong
tier changes the contract; correct it in
.spec.json before touching props.
- Per component, in order:
- Edit
<Name>.svelte per the concrete instructions (add a variant, swap a
child, retoken). Keep Svelte 4 syntax — do not migrate to runes. No
store reads / wailsjs calls added to the render path (props only).
- Update
<Name>.spec.json: props[]/options, tokens[], dependencies[],
and write the new figma.lastSyncedHash + lastSyncedAt from the handover.
Advance status if its requirements are now met.
- Update
<Name>.stories.svelte: new argTypes options, a story per new
variant, real parameters.design.url. Keep tags: ['autodocs'].
- Regenerate + validate:
pnpm ds:registry then pnpm ds:validate. Fix
until green (schema, token validity, story coverage, dependency direction,
sync key). The checklist + index regenerate automatically.
- Visual + test check: run story tests + a11y via the Storybook MCP (or
pnpm test-storybook) for changed components, especially anything using
melt-ui (Tooltip/Dialog/DropdownMenu). Storybook must be served/built for the
MCP to see index.json.
Rules
- Implement only what the handover specifies. Anything marked "human decision /
out of scope" → stop and ask the user; do not guess composition or data wiring.
- Don't touch
src/design-system/component-index.json or
src/design-system/COMPONENT_CHECKLIST.md by hand — generated by step 4.
- One token rename can hit many files; trust the handover's "affected components"
list and verify with
pnpm ds:validate (it fails on dangling token refs).
- If
pnpm ds:validate reveals drift the handover didn't mention, note it back
to the user rather than silently fixing scope creep.
Done when
- All handover items applied (or explicitly deferred with reasons).
pnpm ds:validate exits 0.- Each touched component's
lastSyncedHash updated so the next drift run is clean.
