// Two Figma files — a design system and production screens — become frontend code through MCP. The DS file generates .md specs, the screen file generates components. Based on the actual Senco DS pipeline used in this project.
// Overview — full pipeline at a glance
Generate a Figma Personal Access Token from your Figma account. Configure the Figma MCP server with this token. Start the MCP local server — Claude Code can access Figma files through the MCP server, which acts as a bridge to the Figma API. This bridge must be set up before anything else.
The pipeline is driven by two distinct Figma sources: a Design System file and a Screen file.
The Design System Figma file defines tokens, components, variants, and usage guidelines. MCP reads this file and generates a structured set of .md specifications — design-system.md at the top, foundations/ (color, typography, spacing), and components/.
The Screen Figma file represents real product screens composed using the Design System. MCP derives patterns/ and templates/ from it — how screens combine DS components into layouts and flows.
Screen specs reference the DS — they don't override it. The DS definitions always win.
During code generation, MCP reads the Screen Figma and maps each node to the corresponding DS definitions. Figma variables map to DS tokens, so generated components use the same values as the spec.
The original 4-layer structure (Base → Semantic → Component → Tailwind) had three structural problems: no State layer for interaction/status tokens, Component tokens overloaded with state responsibility, and Tailwind appearing too early as a design layer rather than a rendering layer.
The revised architecture adds two critical layers:
State layer sits between Semantic and Component. State tokens define transformations, not static values. Hover applies darken(8%) to color tokens, elevate(+1) to surface tokens, ring(2px) to focus tokens. Components never define states inline — they compose Semantic + State references, preventing naming explosion (no sidebar-hover, sidebar-active, sidebar-error). Component tokens define stable slots, not state variants.
Platform layer sits between Component and Tailwind. It handles theme resolution (light/dark mode), density variants (compact/cozy), and reduced-motion preferences. Platform tokens resolve per context: --primary outputs #0F62FE in light mode, #4589FF in dark. The DS remains technology-agnostic; only the platform bridge changes when switching from Tailwind to CSS-in-JS or native.
Underlying the entire structure is a token dependency graph: primary-hover → primary → accent-600. Every token knows its upstream source. So when accent-600 changes, you can trace what breaks, derive dark mode automatically, and catch regressions in QA.
Full pipeline: Figma → Base → Semantic → State → Component → Platform → Tailwind.
Review follows dependency order, not parallel execution. Design Agent and Copywriter Agent run first in parallel — visual fidelity and text/tone have no mutual dependency. Design output goes to Dev Agent — code quality, token usage, component architecture. Copy review is resolved in parallel and incorporated before QA.
QA Agent runs last as the final gate. It performs token audit, visual diff against Figma source, and WCAG AA accessibility checks. QA always sees the fully reviewed build — never a partial state.
FAIL is classified, not generic. QA routes failures to their source: design issues go back to Design Agent, code/token issues to Dev Agent, accessibility issues go back with the specific WCAG criterion that failed. This prevents the "loop back to build" black hole where nobody knows what to fix.