Spirit:review Figma Design

Spirit Design System — Review Figma Design

This skill guides you through a structured design review from a Spirit Design System perspective, matching the team's handoff process. The output is a written report (for the ticket) and, if issues are found, a list of Figma comments to be added.

Invocation

/spirit:review-figma-design [type] [issue-id] [figma-url] [--post-comments-to-figma]

All arguments are optional and positionally flexible — each is unambiguous by its format: type is one of page, component, composition; issue-id matches [A-Z]+-\d+ (e.g. DS-2475); figma-url starts with https://; --post-comments-to-figma is a literal flag.

[type] — When omitted, auto-detected from the frame structure (see Step 1); falls back to composition if detection is inconclusive. page is never auto-detected — pass it explicitly when reviewing a full page.

[issue-id] — optional JIRA issue ID (e.g. DS-2475). When provided, it is prepended to the output directory name: design-reviews/DS-2475-reply-form/. When omitted, the directory uses only the frame-name slug.

[figma-url] — optional Figma frame URL. Two behaviours:

• Omitted — review the frame currently selected in the Figma desktop app. Call get_metadata without a nodeId.
• Provided — extract the nodeId from the URL and use it for all Figma MCP calls. The node ID is the node-id query parameter with - replaced by : (e.g. node-id=34675-59177 → nodeId: "34675:59177").

[--post-comments-to-figma] — optional flag. When present, all proposed Figma comments are posted automatically at the end of the review without asking for confirmation (see Step 13).

Checks that apply only to specific evaluation types are marked accordingly throughout this skill.

Prerequisites

• The Figma desktop app must be open — it exposes the Figma MCP server.
• Without a URL — the target frame must be selected in the Figma desktop app.
• With a URL — no frame selection is needed; the URL identifies the target node.
• You must have access to the Spirit component codebase (for cross-referencing component existence).

Workflow

Step 1: Fetch Design Data

1. Determine the target node:

   • No URL provided — call get_metadata without a nodeId (uses current Figma selection). If the call fails with an error such as "fileKey is required", the MCP server in this environment needs a file key. Stop and ask the user to provide a Figma URL, then proceed with the URL-based path below.
   • URL provided — extract the nodeId from the URL (see Invocation section) and pass it to all subsequent Figma MCP calls. If the URL has no node-id parameter, call get_metadata without a nodeId as well.

2. Detect multi-frame mode — inspect the root node returned by get_metadata:

   • If the root is a page or canvas (its direct children are <frame> elements rather than component layers), the URL points to a zoomed area or page rather than a single frame.
   • List the frames numbered and ask:

     This URL contains N frames:

     1. Frame One
     2. Frame Two … Review all N frames, or pick one? Enter a number to pick a single frame, or all.

   • Wait for the user's answer before continuing.
   • User picks a number — review only that frame in single-frame mode (continue with step 3 below, using the picked frame's node ID as the target).
   • User answers all — review all frames together and produce a single combined report. Run Steps 3–8 for each <frame> child in order (collecting findings across all frames), then write one report (Steps 9–11) that covers all frames. See Step 9 for the output path and Step 10 for the Frames Reviewed section format.
   • Single-frame mode (the normal case): the root node is already a single frame — continue with step 3 below.

3. If [type] was not provided, auto-detect it from the get_metadata output:

   • Inspect the direct children of the root frame.
   • If all direct children are <symbol> elements with names in Property=Value format (e.g. Color=Primary, Size=Medium), set type to component.
   • Otherwise, set type to composition.
   • Log the detected type so the user can see which was chosen.
   • If [type] was provided, use it as-is — skip detection entirely.

4. Call get_design_context on the root node to extract:

   • All component instances and their Code Connect snippets
   • All token references (spacing, color, typography, radius, shadow)
   • Raw hardcoded values (CSS literals without var(--...))
   • Any custom/raw HTML compositions that lack Code Connect mappings

5. Call get_variable_defs on the root node to see exactly which variables are bound versus unbound. Use this as corroborating evidence for token findings in Step 5 — a layer present in get_design_context with a token reference but absent or unbound in get_variable_defs confirms the token is not properly attached.

6. Call get_screenshot on the root node for visual context.

If the frame is large (> ~2000px tall), call get_design_context section by section using node IDs from get_metadata to avoid truncation.

Step 2: Check Page Structure (type=page Only)

Inspect the top-level children of the root frame in the get_metadata output. The allowed structure, in order, is:

1. An optional Header component instance (may be wrapped in a layer named Header)
2. One or more Section [Size] layers, each containing a Container [Size] child layer
3. An optional Footer component instance
4. An optional Modal component instance

Rules:

• Section and Container sizes do not need to match (Section Small > Container Large is valid)
• Any unnamed or unrecognised top-level layer (e.g. Frame 12) fails this check
• Skip entirely for component and composition evaluations

Step 3: Check Variant Completeness (type=component Only)

For each property dimension visible in the component, run two checks.

Dictionary Enum Completeness

Fetch docs/DICTIONARIES.md from GitHub to get the current list of Spirit dictionaries and their values. If the component defines any value from a dictionary, it must define all values from that dictionary. Flag any missing values as ⚠️.

If a property spans two dictionaries (e.g. a Color prop that combines ComponentButtonColor and EmotionColor), check completeness against both.

Interaction State Completeness

If the component has an Interaction State property, every other property combination must have all of: Default, Hover, Focus, Active, Disabled. Flag any combination that is missing one or more states as ⚠️.

Step 4: Check DS Component Usage

For each visible UI element, verify it maps to an existing Spirit component:

When a layer lacks a Code Connect snippet and its structure or name suggests it may correspond to a Spirit component, try to suggest a replacement:

1. search_design_system (preferred, if available) — call with the layer's role or name (e.g. "avatar", "stat tile", "navigation item"). Available in Codex/Cursor environments.
2. get_code_connect_suggestions (fallback) — call on the specific node. Available in the Figma desktop app MCP.

Use whichever tool is available in the current environment; skip silently if neither is. Include a replacement suggestion in the finding only when the match is credible. Omit a suggestion when results are ambiguous or the match is implausible.

Differentiating "not yet Implemented" From "lacks Code Connect"

When a Figma instance has no Code Connect snippet, the root cause is one of two very different things:

• Component exists in code but has no Code Connect binding — the fix is to add a Code Connect file (DS work only). Code Connect files use one of these patterns: *.figma.tsx, *.figma.ts, or *.figma.stories.tsx.
• Component does not exist in code at all — the Code Connect gap is a downstream symptom; the real work is implementing the component first.

To determine which case applies, search the codebase for the component name and for its Code Connect file.

1. Resolve the components search path by trying the following in order, stopping at the first match:

   1. packages/web-react/src/components/ — Spirit's default components path
   2. libs/design-system/components/ — Cyborg convention
   3. componentsPath value in .agents/skills/review-figma-design/config.json — custom override (set componentsPath to a relative path from the repo root; null skips this step)

   If none of the paths exist in the repository, skip the existence check and treat the component as "not yet implemented".

2. Grep the resolved path for the component name:

   grep -r "ComponentName" <resolved-path> --include="*.tsx" -l 2>/dev/null | head -1
   

3. When the component exists, look for its Code Connect file. Match all Code Connect file patterns — a component may be bound from any of them, so a *.figma.tsx-only search reports false "lacks Code Connect" gaps:

   find <resolved-path> \
     \( -name "*.figma.tsx" -o -name "*.figma.ts" -o -name "*.figma.stories.tsx" \) \
     -path "*ComponentName*" 2>/dev/null | head -5
   

   If the component's files are not laid out per-directory, fall back to matching the file name instead of the path:

   find <resolved-path> \
     \( -name "ComponentName.figma.tsx" -o -name "ComponentName.figma.ts" \
        -o -name "ComponentName.figma.stories.tsx" \) 2>/dev/null | head -5
   

Apply the result as follows:

Product-specific components (names with a product prefix such as OPU-, Cyborg-, or similar) will not be added to the Spirit DS. For these:

• Keep the 🚨 severity (implementation is still blocked).
• Change the wording to reflect that it is a product-level concern: "product-specific component not in Spirit DS; implement in the product codebase using DS primitives, then add Code Connect there."
• Omit the Required DS Changes row (Spirit DS has no action to take).

Cross-Frame Instance Height Consistency (multi-Frame Mode Only)

After collecting get_metadata for all frames, build a name → heights map by recording the height attribute of every <instance name="…"> element across all frames. For any named instance that appears in more than one frame with differing height values, flag it in Findings as ⚠️:

<name> has inconsistent heights across frames (Npx in "Frame A" vs Mpx in "Frame B"). Verify all variants were built from the same master component and that the height difference is intentional.

This is especially important for custom subcomponents that stack a label above a form field: a small unintended height change silently misaligns an adjacent Button and cannot be seen when frames are reviewed in isolation.

Step 5: Check Token Usage

Inspect the get_design_context output for hardcoded CSS literals. These indicate missing token references in the design.

All token references must use one of three valid prefixes: device, global, or themed. Any var(--...) that does not start with one of these is invalid regardless of which DS is in use.

Spacing tokens:

• Hardcoded gap-[Xpx], p-[Xpx], m-[Xpx] without a var(--global/spacing/...) reference → tokens missing; flag so the designer can attach the correct token.

Color tokens:

• Hardcoded hex/rgb values → tokens missing; flag as ⚠️.
• Token-referenced colors that do not start with themed → wrong token scope; colors must use var(--themed/...) tokens; flag as ⚠️.
• Exception: hardcoded colors on <vector> layers (SVG illustration paths) are expected and should NOT be flagged — illustrations embed colors by design and are not tokenised.

Typography:

• Verify text styles use var(--device/typography/...) tokens.
• Custom font-weight/size combinations outside the scale should be flagged.

Radius / shadow:

• Verify border-radius uses var(--global/radius/...) tokens.
• Verify box-shadow uses var(--global/shadow/...) or var(--themed/shadow/...) tokens.
• Border-radius in sibling form-field + Button rows: when a Button instance and a form-field component (TextField, Select, Picker, or a custom search-input subcomponent) appear as direct siblings in the same auto-layout frame, call get_variable_defs on both and compare their border-radius variable bindings. If they reference different --global/radius/... tokens, or one uses a token while the other uses a hardcoded value, flag it in Findings as ⚠️ — the designer can fix this by attaching the matching global/radius/... token to the outlying component.

Step 6: Check Icon Usage

For every icon in the design:

1. Resolve the icon search path by trying the following in order, stopping at the first match:

   1. packages/icons/src/ — Spirit's default icon path
   2. libs/design-icons/ — Cyborg convention
   3. iconsPath value in .agents/skills/review-figma-design/config.json — custom override (set iconsPath to a relative path from the repo root; null skips this step)

   If none of the paths exist in the repository, skip the existence check and note in the report that the icon path could not be resolved.

2. Verify the icon name exists in the resolved path:

   Grep for the icon name in <resolved-path>
   

3. Verify it is using <Icon name="..." /> via Code Connect — not a raw SVG or image asset.

4. Route failures by type:

   • Icon name missing from the codebase — this is a joint designer + developer concern:
     • Record in Findings with 🚨 severity — the designer should make sure the icon is present in their Figma asset library and published so downstream consumers have access.
     • Record in Development Considerations with 🚨 severity and add a matching row to Required DS Changes (e.g. Add missing icon "<name>") — the DS needs to ship the icon in code before the design can be implemented.
   • Raw SVG / image asset instead of <Icon name="..." /> — this is a Code Connect binding concern. Record in Development Considerations with 🚨 severity and, if a DS fix is needed, add a row to Required DS Changes. Do not include it in Findings.

Step 7: Spirit Repo Checks (Spirit Repo Only)

Check whether the skill is running inside the Spirit repo by testing for the presence of packages/web-react/. If the directory does not exist, skip this step entirely — all JIRA cells in the Required DS Changes table will be to be created.

If running in Spirit, perform the following:

1. Cross-reference git history — run git log --oneline -50 and scan recent commit messages for DS- ticket references (e.g. #DS-2300). If a commit relates to a component or feature visible in the design (e.g. a recently shipped prop, a new component, a Code Connect update), note the ticket number and annotate the relevant finding — either to flag it as already in progress or to explain why something appears incomplete.

2. Populate JIRA column — for each row in the Required DS Changes table, check whether a matching DS- ticket was found in the git log. If yes, link it as [DS-XXXX](https://jira.almacareer.tech/browse/DS-XXXX). If no matching ticket was found, write to be created.

Step 8: Identify Required DS Changes

Based on your findings, list any changes needed in the DS itself:

• New components (e.g., "File Upload NEW" → new FileUpload component needed) — always a 🚨 blocker, as development cannot proceed without a DS component or an agreed implementation path
• Component updates (e.g., a prop variant that doesn't exist yet)
• Token additions (e.g., a spacing value not in the Spirit scale)
• Code Connect updates (e.g., a recently shipped feature not yet reflected in Code Connect)
• Missing icons (e.g., a name referenced in the design that is not present in packages/icons/src/)

Required DS Changes is the canonical work-item list for implementation issues. Every severity-tagged item recorded in Development Considerations that requires DS work must have a matching row here.

Estimate effort for each: Low (< 2h), **Medium** (2–8h), **High** (> 8h).

Step 9: Compile Design Evaluation

Based on all findings from Steps 2–8, compile the generic checks table. Each row either passes (✅) or fails (❌). This gives an at-a-glance view of what's correct as well as what isn't.

Specific findings do NOT go in this table — they are routed by audience per Steps 4 and 6:

• Designer-actionable (wrong component choice, missing token in a particular spot, detached component, deprecated component used, missing icon in the designer's asset library, etc.) → Findings (see Step 11).
• Implementation-actionable (Code Connect gaps, unimplemented component features, icon name missing from the codebase, raw SVG used instead of the Icon component, etc.) → Development Considerations with severity and, where DS work is required, a row in Required DS Changes.

See Step 11 for the detailed routing and format.

Step 10: Capture Per-Finding Screenshots

1. Derive the output names:

   Slugification rule (used throughout): lowercase the input, replace whitespace, hyphens, pipes, and other non-alphanumeric characters with hyphens, collapse consecutive hyphens, trim leading/trailing hyphens.

   • Single-frame mode: <topic-slug> = slugified frame name, optionally prefixed with [issue-id]-. Example: DS-2475-user-account-settings
   • Multi-frame mode (combined report): <topic-slug> = slugified canvas/page name, optionally prefixed with [issue-id]-. Example: DS-2475-reply-form
   • <report-name> = [issue-id]-design-review (with issue ID) or design-review (without).
   • Output (both modes): design-reviews/<topic-slug>/<report-name>.{md|html|pdf}

2. Run mkdir -p design-reviews/<topic-slug> to create the output folder.

3. For each finding that references a specific node ID (not just the root frame), call get_screenshot with that node ID. The tool zooms to the node bounds automatically — no manual crop needed. Do NOT capture a screenshot for findings that only reference the root frame (already captured in Step 1).

4. Save each screenshot to design-reviews/<topic-slug>/ as finding-{n}.png, where {n} matches the finding's number in the report (🚨 first, then ⚠️, then ℹ️, matching sort order). In multi-frame mode findings are numbered sequentially across all frames. The Figma MCP server returns images as base64 PNG — decode and save each one using the save-screenshots.js script in this skill's scripts/ directory. Each argument is a NODE_ID:PATH pair (the script splits on the last colon, so node IDs like 2802:66561 work correctly):

   node .agents/skills/review-figma-design/scripts/save-screenshots.js \
     "NODE_ID_1:design-reviews/SLUG/finding-1.png" \
     "NODE_ID_2:design-reviews/SLUG/finding-2.png"
   

   Replace NODE_ID_* and SLUG with the actual values before running.

5. Keep a numbered index (finding → screenshot filename) to use during report writing.

6. If a finding spans multiple nodes and warrants more than one screenshot, use letters: finding-1a.png, finding-1b.png, finding-1c.png, …

7. Save the overview and compute pin positions for the HTML report:

   a. Decode and save the root screenshot to <output-folder>/overview.png using the same save-screenshots.js script (add an entry with the root node ID and path <output-folder>/overview.png). Capture the overview's natural dimensions from the script's stdout — the line has the form Saved <path> (<width>x<height>). They are needed in step 7d below to size the overview box on the HTML cover.

   b. For each finding, compute its absolute position within the root frame by walking the metadata tree from that node up to the root frame and summing the x/y offsets of every ancestor (not including the root frame itself). This means building a parent map from the XML tree and following it all the way up — not just adding one parent's offset. For deeply nested nodes (e.g. a text layer inside a component inside a frame inside a section) every intermediate x/y must be accumulated; skipping levels produces pins that cluster incorrectly. Record:

   • center_x = abs_x + width / 2
   • center_y = abs_y + height / 2
   • pin_left = round(center_x / canvas_w * 100, 1) — percentage of canvas width
   • pin_top = round(center_y / canvas_h * 100, 1) — percentage of canvas height

   Store (n, pin_left, pin_top) for each finding — these become the style values for the pin <a> elements in the HTML cover page (style="left:XX.X%;top:YY.Y%").

   c. The canvas dimensions used for pin percentages (canvas_w, canvas_h) must come from the root frame's bounding box in get_metadata, not the overview PNG. The Figma screenshot may be rendered at a different resolution than the frame's logical coordinates, but the positions of findings are in logical units — matching the root frame is what keeps pins aligned with features in the image.

   d. Build the overview wrapper's inline style using the PNG dimensions captured in step 7a. The HTML cover sizes the overview with aspect-ratio, so the wrapper needs the image's natural ratio as a CSS custom property:

   style="--overview-aspect: <width>/<height>;"</height></width>
   

   (note the leading space — the placeholder sits where an HTML attribute would). Substitute this into {{OVERVIEW_WRAP_STYLE}} when writing the HTML. Without it, the overview box falls back to an unconstrained aspect and the image will not fit the cover page correctly.

Step 11: Write the Report

Output the complete report to the conversation first — the user reads it here. Then write the identical content to design-reviews/<topic-slug>/<report-name>.md immediately, without asking for confirmation. Both happen together; neither requires user approval.

Produce a structured Markdown report with the sections below. Use the same tone and format as the team's existing reports — concise, developer-facing,

…(truncated)