---
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)
1. **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.
2. **Fix tier if flagged.** A wrong `tier` changes the contract; correct it in
   `.spec.json` before touching props.
3. **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 / `bindings/...` 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']`.
4. **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.
5. **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.