Figma

Purpose: Establish Figma as the single source of truth for UI, and define how the frontend analyst pulls a Figma frame through to a placeholder component the developer can finish.

Figma as source of truth

Figma is the single source of truth for UI; work items link to specific frames or nodes — do not paraphrase the design in prose. The rule has a sharp edge: any prose description of visual layout in a work item is by definition either redundant (the Figma already says it) or wrong (it disagrees with the Figma). The analyst trusts the link and ignores the prose; the developer trusts the spec the analyst produced. If a visual rule cannot be expressed in Figma — a conditional display, a tooltip's text, a hover behaviour — it belongs in the work-item description as a conditional-logic rule with literal text, in the form taught in Work-Item Composition, not as freeform prose about how the design "should look."

The corollary: a work item with no Figma link, for a UI scope that has one, is missing its most important input. Filter it back to the BA before it enters the backlog.

How Figma is wired in

Figma reaches the analyst through two channels — and the one that matters for day-to-day work is the per-work-item link, not a project setting.

• The work-item figmaUrl field. Each UI work item carries a Figma link, validated against the platform's Figma-URL pattern (https://figma.com/(file|design|proto)/…). This is the canonical input; the triage and analyst flows read it before doing anything else. Paste the link into the work item's Figma field — relying on a URL buried in prose is not the documented channel.
• A project-level Design System integration (optional). A project can reference a design-system integration, but it is optional and org-scoped, and the Figma integration provider is declared, not implemented — there is no Figma provider client behind it. So this setting does not, by itself, drive Figma access.

How the analyst actually reads Figma: via the Framelink Figma MCP server, which the frontend analyst's skills call directly. This MCP path is separate from the generic integration abstraction — it does not go through the optional design-system integration. Access is governed by the MCP server's own configuration/credentials, not by a per-agent hook layer (the frontend analyst ships with no hooks at all).

Linking patterns for a work item

• Frame-level link — preferred for component and page work items. Right-click the frame in Figma, copy the link, paste it into the work item's Figma field. fetch-figma-data resolves the link to a specific node and pulls only that subtree.
• Node-level link — when a single element inside a frame is the scope (a button, a row, an icon). Same paste-and-resolve flow; the analyst respects the narrower scope.
• A page composed of several frames — for a page work item that assembles multiple frames (header, body, footer), give each its own link rather than one whole-file URL. define-page-spec builds the page's component(s) via define-component-spec and then adds routing.

A whole-file URL is almost always wrong: the analyst won't paraphrase an entire file into one spec, and the work item balloons past a clean session arc and fragments into "attempt-2"/"attempt-3" descendants.

How styles map to design tokens

Token mapping is not a page-spec approval gate — it happens inside match-figma-styles, which define-component-spec invokes while building a component. (define-page-spec is routing-only and performs no token checks.)

match-figma-styles extracts style properties from the Figma frame and matches each against the project's design tokens:

• Colours — matched by exact value, RGB distance, semantic role, or token name.
• Spacing — paddings, gaps, and margins matched to spacing tokens.
• Typography — font family, size, weight, line height, letter spacing matched to typography tokens.

For each property it records the match type, a confidence (high / medium / low / none), any alternative matches, and a user decision, into {cache_name}.style-mapping.json. Where confidence is medium or low, the analyst runs an interactive confirmation so a human can accept a token, pick an alternative, or keep a custom value. Values with no token match are recorded as custom values — not as blocking "violations." If the project has no design system configured (empty token sets), matching simply yields no results.

What this stage does not do. There is no "component-token / Material-override" validation and no "functional-element → library-wrapper" check here. In fact the analyst's placeholder is built from raw HTML or project-specific components only — external library components (MUI, Angular Material, …) are prohibited in the placeholder. Choosing library wrappers and the production state/styling patterns is the developer's generate-component job, not the analyst's.

Resolving low-confidence mappings during the component spec is cheap; discovering a wrong token after the developer has built the page is expensive — which is why the confirmation happens here.

Placeholder components

The analyst produces a faithful vanilla HTML/CSS preview plus a placeholder framework component; the developer agent later replaces the placeholder with production code. The handoff is deliberate.

define-component-spec orchestrates the Figma chain — fetch-figma-data → match-figma-styles → generate-figma-html-css — and then calls onboard-component. The artefacts produced along the way:

Artefact	Where it lives	Produced by
Cached Figma JSON subtree ({cache_name}.json + .meta.json)	.swifter/cache/figma/	fetch-figma-data
{cache_name}.style-mapping.json (token-match output)	.swifter/cache/figma/	match-figma-styles
template.html / styles.css / preview.html (vanilla preview) + mapping-used.json	the component's spec dir	generate-figma-html-css
component-implementation.md (placeholder path, main file, import statement)	the component's spec dir	define-component-spec
Placeholder framework component (in the project source tree, marked as a placeholder)	project source	define-component-spec
Stories / MDX / metadata.yaml	the component's spec dir	onboard-component

For a project-specific component, the data model and logic specs (data_model.yaml, plus display-rule / validation / function specs) are produced by the separate work-on-component-data-model and work-on-component-logic commands (or in bulk by import-component-specs) — they are not output of the fetch → … → onboard-component chain above, and onboard-component requires them to already exist for a project-specific component.

The developer agent's generate-component command then reads the spec and the placeholder and rewrites the placeholder as production code using the project's component library, state pattern, and styling rules. The placeholder gives the developer a known-good shape; the spec tells it which rules and bindings to honour. That split is what lets a simple component finish in one analyst-only session and a complex one finish in two — without a third.