Figma MCP × Cursor

Design-to-code handoff is where quality usually dies — tokens drift, accessibility gets retrofitted, tests bind to class names that vanish on the next refactor. I built this pipeline solo to see if one architecture could fix that, not to ship another toolchain essay.

Typical flow: designers export, engineers interpret, three sources of truth disagree (Figma, repo, Notion). A11y notes live in comments. Playwright suites snap when markup changes. That is not a people problem — it is missing contracts between design, code, and tests.

Audience for this work: me first, then any eng or agent team that might adopt the pattern on a real storefront. Proof is a mobile-first Next.js demo shaped like commerce (PLP, cart drawer, search) plus Storybook on the same deploy — not a client brand engagement.

What I owned: token pipeline, Code Connect + MCP scaffolding workflow, manifest and a11y agent contract, demo app, Storybook co-deploy, test suite. What I did not own: a production client rollout, Figma the product, or adoption metrics — this is R&D with a defensible reference implementation.

Hand-maintained token JSON. Killed: drift is guaranteed the moment design moves faster than a spreadsheet.

Selector-based Playwright. Killed: tests document DOM accidents, not behavior — every refactor taxes the suite.

Screenshot or generic prompt AI for scaffolding. Killed: guesses at the spec. Figma MCP exposes structured layer, token, and constraint data — the model reads the file, not a PNG.

Token pipeline — Style Dictionary + Figma MCP sync. One tokens:buildtokens:build feeds Tailwind, CSS variables, and Storybook theme from the same primitives. Trade-off: a build step; watch mode during active design work.

Component contract — Code Connect maps Figma components to React; Cursor pulls live Dev Mode context via MCP when scaffolding. Trade-off: garbage-in from poorly named or untokenized Figma; pipeline quality is upstream design system quality.

Manifest + a11y agent contract — each interactive surface gets data-agent-iddata-agent-id, manifest entry (expected success event), and ARIA live region announcements; Playwright reads the manifest at runtime, not CSS selectors. Trade-off: discipline on every new action; missing manifest entry means invisible to tests.

Single Vercel deploy for Next + static Storybook under /storybook/storybook — one domain, one version history. Trade-off: longer builds; worth it so story links stay canonical beside the app they document.

Component ships without a manifest entry — tests pass vacuously or skip the behavior; Storybook a11y addon and review are the guardrails, not magic.

Upstream Figma sloppiness — generic layer names, hard-coded hex — produces weak MCP output; the pipeline does not forgive a messy source file.

Dual-build deploy failure — if Storybook build fails, the whole release fails; intentional, so /storybook/storybook never lags a broken app silently.

Solo build, but the artifact is a handoff contract: manifest JSON + Code Connect mappings are what the next engineer — or coding agent — reads before touching UI. Same move as Shop Canvas’s setup skill: make boundaries explicit so collaborators do not improvise scope.

Defensible claims from the repo: Playwright suite uses manifest-driven actions, not hardcoded selectors; WCAG 2.1 AA checks run at component level via Storybook a11y; one token build syncs Figma → Tailwind → Storybook theme. The demo includes cart drawer flows (open, qty, remove) and PLP add-to-cart as proof the contract holds on real interactions — not a count of experimental pages.

Full pipeline notes live in Notion (meta link). I am not claiming client adoption or production rollouts from this R&D project.

I would wire Chromatic from the first component, not mid-project — visual regression needs a baseline from day one; retrofitting throws away early evolution.

Next eng/agent handoff in flight: I am adapting this pipeline pattern toward Avnzor’s Hydrogen storefront — real client stack, work in progress, not a completed production rollout or adoption metric.

Running this on a real client means Bouguessa/Avnzor-shaped constraints: messy legacy Figma, market-specific surfaces, and a team that will not maintain manifest entries unless the workflow is default. The architecture is transferable; the organizational cost is the real gate — I would negotiate manifest + token builds as part of definition of done, not a side quest.