Figma Parity

Figma ↔ code parity (QBDS)

Scope: Run this workflow only for Figma-driven implement/review of QBDS components. Skip for unrelated tasks (deps, CI, docs, refactors with no design change). Figma MCP output is reference only — still run the full workflow below.

If no Figma URL/node is provided, ask for it (or use the team’s internal/shared link).

Sources of truth (read before styling)

1. docs/TOKENS.md — semantic Tailwind utilities; design-name column maps to Figma variables.
2. src/styles/globals.css — CSS variables and @theme inline; trace utilities back to semantics (e.g. bg-fill-* → --color-fill-* → --fill-*). Verify light and dark (.dark); use -inverse on dark/accent surfaces.
3. Spacing scale — gap-1 / p-1 = 4px, gap-2 / p-2 = 8px, gap-3 / p-3 = 12px. No gap-[Npx], text-[#…], bg-[#…], or primitives (slate-*, mist-*) in components.

Match Figma tokens via docs/TOKENS.md (Design name + Tailwind utility). CSS semantics in globals.css: --text-*, --border-*, --fill-*, --surface-*, --status-*, --stateslayer-*, --elevations-*, --brand-accents-* (each has a -inverse form where the spec uses inverse surfaces). In components use Tailwind utilities from TOKENS.md — e.g. text-fg-* (→ --color-fg-* → --text-*), border-stroke-* (→ --color-stroke-* → --border-*), bg-fill-* — not raw --fg-* / --stroke-* or primitives.

Feedback / status colour (do not flag text-status-*): Figma may bind feedback copy to Text/Error, Text/Warning, etc. In QBDS code the established theme utilities are text-status-error, text-status-warning, text-status-success, text-status-information (same family as fills/borders via --color-status-*). That mapping is correct and intentional — match sibling demos (field, input, alert, …). Do not treat text-status-* on feedback, counters, or required markers as a token drift, and do not rewrite them to text-error / text-warning / text-success / text-fg-error. Use border-stroke-status-* / bg-status-* for control chrome as today.

Repo patterns (match siblings, do not reinvent)

• Component: src/components/ui/<name>.tsx — primitive + cva + context + data-slot; copy structure from the closest sibling, not from scratch. Base UI vs Radix: see Which primitive to use in AGENTS.md — the library is mid-migration, so check the imports in the file you are editing.
• Demo: src/app/demo/[name]/ui/<name>.tsx — named exports + examples: DemoExample[] (canonical; createLegacyDemo is a legacy wrapper still exported by many existing demos — do not add it to new demos). Follow demos.md; covering a Figma axis does not require a separate example per optional slot toggle.
• Registry: registry.json + npm run registry:build → public/r/.
• Tests: src/tests/<name>.test.tsx — a11y roles, data-* attrs, interaction; assert key variant outputs where helpers exist.
• Icons: <IconShell> + <Icon icon="snake_case" />; shell owns colour — pair sizes with the parent control per sibling demos. When the parent surface flips (dropdown-open, toggle-on, inverse fill), re-check nested IconShell Type (neutral vs neutral-inverse) and State/opacity (primary vs secondary) — size alone is not enough.
• Typography: globals utilities (cta-*, paragraph-*, …) — not hand-rolled text-sm / font-* / leading-*.
• Interactive states: match the nearest button-like sibling — state overlays, disabled fills, focus rings; do not let variant branches override size-level focus treatment.
• Slots: follow composition.md export decision tree — SLOT → children of existing parts first; new export only when the tree says so. Mark seams with data-slot.
• Field footer: FieldDescription (helper) and FieldError (feedback) are mutually exclusive — one per field. Error/invalid → FieldError only; otherwise FieldDescription when helper is shown. Never both in demo or Code Connect.
• Horizontal Field lists: Field is w-full; horizontal labels use flex-auto. Inside horizontal CheckboxGroup / RadioGroup, that stretches items and makes density gaps look wrong. Shrink-wrap on the group ([&>[data-slot=field]]:w-auto + label flex-none). Do not change Field globals.
• Primitive composition: The primitive that owns focus and keyboard behavior must be the rendered element — Base UI render, or Radix asChild on the outer primitive wrapping the styled QBDS sub-component (not the reverse). Verify keyboard navigation in the demo.
• Public API: follow composition.md. Figma parity verifies styling of exported parts, not that every Figma layer becomes an export. Every exported sub-component needs a demo example and at least one test, or remove it from the public API — do not export Figma-internal frames to satisfy this rule.
• Size drift red flag: the same axis on both data-* and React Context without a documented reason in the alignment table.
• Field-composed controls (input, textarea, select, date/time pickers, …): Figma nests Elements/ instances (Label, Help-Text, Status-Messages, Characters-Counter). Match each slot per size × state in the demo — copy the per-size fieldConfig pattern from the nearest sibling (e.g. input.tsx). Do not assume shared Field* defaults match the parent set’s spec.

Workflow (run in order)

0 — Code Connect (do NOT treat as source of truth)

code-connect/<name>.figma.ts (or legacy .figma.tsx) is a downstream artifact — it can be wrong or stale. Do not seed the alignment table from it and do not "verify" Figma against it.

• Source of truth = Figma (get_metadata, get_variable_defs, get_screenshot) + the real React API (src/components/ui/<name>.tsx).
• Build the alignment table from those first, then check the mapping against it (see step 4). Any mismatch — enum values, size names, variant→prop mapping — is a Code Connect bug to fix, not a spec to follow.
• If Figma has a dropdown-open (or similar expanded) state and Code Connect maps it to false, omits open fill/icon changes, or documents a static IconShell type with no open override — that is a mapping bug to flag, not proof that open equals enabled.
• To create or update a mapping, use the code-connect skill — it owns the mechanics and QBDS conventions.
• When calling get_design_context, pass disableCodeConnect: true so the response cannot seed the spec with a stale mapping.

For field-composed controls: derive errorClass (and warning/success/info) the same way as labelClass / descClass — pass explicit className on <FieldError> when Figma typography varies by size.

1 — Structure & variants

1. Component description (Figma) — On the component set root (not a single variant instance), read the designer-written description in Dev Mode, or from get_design_context on that node (follow component documentation links and design annotations in the response when present). QBDS descriptions often state the default layout and which variant axes exist (e.g. “Defaults to unboxed horizontal… also supports boxed, vertical, …”). Treat this as the narrative source of truth for defaults and scope before inferring from one frame.
2. get_metadata (or Dev Mode) on the component set — list every variant, boolean, text, and SLOT property; note which property values are the set’s default selections.
3. Read src/components/ui/<name>.tsx — cva keys, props, data-slot, exports.
4. Prop naming: props.md — map Figma sizes to React vocabulary (reg→default, xlg→xl, …); variant uses default not primary.
5. Build an alignment table from Figma + React API (never from Code Connect); flag asymmetric coverage (Figma-only or code-only values). The Code Connect column records what the mapping claims — a mismatch there is a mapping bug to fix, not a reason to change the spec:

If a Code Connect mapping exists, confirm its enum values, size names, and variant→prop mapping match the Figma + React columns above. Fix the mapping (via the code-connect skill) when it drifts.

6. Field chrome table (required when Figma nests Elements/* or booleans showLabel, showHelpText, showFeedbackMessage, showCounter): inspect each text slot at sm, reg/default, and lg (and error/disabled states). Shared primitives (FieldError, FieldDescription) often ship generic defaults — override in demo/Code Connect when Figma differs.

Red flags: label/description are per-size in demo but error/feedback is not; bare <FieldError> with no className on a sized field set; wrong paragraph-* (e.g. paragraph-regular-primary when Figma shows Paragraph/Large-Primary). Not a red flag: text-status-* on feedback / counter / required * (see Text vs status note above).

7. Defaults & demos:
   • Defaults: Figma description, cva defaults, and registry.json must agree.
   • Demos: Start examples[0] simple — developer's choice, not necessarily the Figma default. Cover every alignment-table row across examples[]. Include at least one error/feedback example per size when typography differs.

2 — Tokens (every distinct variant × state)

Use get_variable_defs on representative nodes: at minimum enabled, hover, focus, pressed, disabled, plus every other Figma state enum value when present — dropdown-open, toggle-on, selected/active/loading, etc. Do not stop at focus when the set also has expanded/open cells. Map fill, text, stroke, elevation, radius, and state overlays per docs/TOKENS.md. Check light and dark. Flag: wrong -inverse prefix; raw hex; primitives; right hex but wrong token name. When Figma shows Text/Error (etc.) on feedback, accept code that uses text-status-error (etc.) — do not flag that as a name mismatch.

3 — Layout, spacing, typography & states

For each matrix cell (every meaningful variant combination), use get_design_context or Dev Mode — not only the root frame. For field sets, also pull context on nested Elements/ frames in that cell.

CTA button vs button-link (underline) — mandatory per variant × state

Figma text styles encode underline. Do not assume one underline rule for all variants.

Red flags

• Shared hover-only underline wrapper for every variant while Figma ghost (or similar) binds CTA/button-link-* at enabled.
• Always-on underline while Figma enabled cell is plain CTA/button-*.
• Size axis only sets cta-button-* with no per-variant link/underline branch when Figma differs by type.

Record pass/drift for underline in the variant × state matrix (not only font size/weight).

Compound spacing: Derive spacing from Figma per variant cell, not from a single axis (e.g. “if boxed, always gap-2”). Size and shape often change gap/padding independently — document or test non-default cells when logic is non-obvious.

Spacing verification rules

• Record pl and pr separately in the spacing table — never assume symmetric padding.
• Do not infer padding from symbol bounding-box width or total component width.
• Verify padding on the inner State-Overlays frame (Dev Mode or MCP codegen on the variant cell).
• When Spacing/N tokens appear together (e.g. Spacing/8 + Spacing/12), map each to its side; do not dismiss larger tokens as "internal only" without checking the overlay frame.
• Shared cva ≠ shared spacing — if a sibling component (e.g. Tag vs TagToggle) diverges, document and fix per component file.

Interactive states (on controls inside the component):

Composition components (split buttons, icon+menu triggers): verify open on the trigger segment that receives data-state=open, including nested IconShell — not only the parent cva file.

Visual pass (required): npm run dev on the demo vs Figma / get_screenshot per matrix cell. Fix or document any ≥2px mismatch.

Report a variant × state matrix: pass / drift (note ≥2px or wrong token).

Figma MCP (when available): get_design_context (primary — layout, description, screenshot), get_metadata, get_variable_defs, get_screenshot.

Acceptance checklist

• Alignment table: all Figma axes ↔ cva/props (both directions); SLOT seams covered
• Every Figma state value has a matrix cell; when both focused and dropdown-open exist, open ≠ focus verified (fill + nested IconShell type/opacity)
• Code Connect (if present): enums, size names, variant→prop mapping verified against Figma + React API (not the reverse); drift fixed — including open/expanded not collapsed to enabled/false when Figma differs
• Field chrome table (when Elements/* present): label, helper, feedback, counter — typography + color per size
• Feedback / status copy uses theme utilities text-status-error|warning|success|information (Figma Text/* → text-status-* is OK)
• Variant × state matrix: tokens + geometry per cell
• CTA button-* vs button-link-* (underline) checked per variant × state — including ghost/link-like types at enabled
• Light and dark where the component appears on both
• Defaults aligned (Figma, cva, registry); demos start simple and cover the full alignment table
• Compound spacing from per-cell Figma values (no undocumented single-axis shortcuts)
• Horizontal padding verified as pl + pr per matrix cell (not width-inferred, not assumed symmetric)
• Shared styling helpers checked per component when spacing differs
• Exported sub-components: demo + test, or not exported
• Composed primitives: correct asChild direction; keyboard nav verified
• Visual pass: no undocumented ≥2px gaps
• Exit gate passes — see create-qbds-component

User only shares a URL

Extract node-id from the URL, run the workflow above, and compare to the nearest sibling in src/components/ui/.