Figma Requirements Extraction

Figma Requirements Extraction

When to use

You are the UI/UX Designer dispatched in extract mode. The Orchestrator has detected a Figma URL in the project's PRD source AND set SRS header Design-Flow: A (per BA Phase 1.X step 10) AND no docs/requirements/design-extracted/-*.md exists yet on disk.

The kit's pattern is: BA's first US/FR synthesis at Phase 1.X must be informed by FULL source corpus. Textual PRD + design-extracted requirements + conversational additions are the three branches. Without design-extracted input, BA invents details that Figma already specifies (or worse, misses details Figma specifies that the textual PRD omits) — every subsequent dispatch then re-discovers the gap.

You produce a structured markdown enumerating WHAT THE DESIGN SHOWS. You do NOT author requirements (that's BA's role); you produce evidence that BA synthesizes into the SRS. When the Figma file has no explicit design guideline, you still extract reusable visual-system evidence — color palette, typography, spacing, radius, elevation, component patterns, and layout grid — so BA can set Design-Guideline: from-figma instead of forcing a generic preset.

Inputs and outputs

• Inputs: Figma file URL passed by Orchestrator dispatch; Figma MCP server (read-only).
• Outputs: docs/requirements/design-extracted/-.md (the one and only artifact this skill produces). The file includes both requirements evidence and a design-guideline evidence inventory for Flow A.
• Consumed by: BA Phase 1.X (synthesis input); srs-source-validator (coverage check spans this file as part of docs/requirements/).

Hard discipline: confirmed vs inferred

The extractor enumerates two distinct categories:

• CONFIRMED elements — text the extractor reads directly from Figma text nodes; components that are instances of named master components; states that exist as Figma variants; explicit copy on buttons / labels / dialogs. These are facts on the canvas.
• INFERRED requirements — behaviors / rules / scope items the extractor THINKS the design implies but cannot prove without PRD anchor. Example: a "confirm" modal with a destructive action button is INFERRED to mean "destructive operations require confirmation," but the extractor cannot prove this is a global rule vs incidental to this one flow.

The output file ALWAYS separates the two. BA at Phase 1.X synthesizes US/FR ONLY from confirmed elements + inferred items the textual PRD also supports. Inferred-only items become OQs (per BA's no-invention invariant).

This is the same discipline as solution-defaults skill (kit-provided defaults vs project-confirmed values) and brownfield Mode E (extracted vs confirmed).

Procedure

Step 0 — Pre-flight + page-scoping

1. Read the dispatch prompt: confirm figma_url is present and Design-Flow: A per SRS header.
2. Compute the output filename: -.md where ` is parsed from the Figma URL (the segment after /file/ or /design/`).
3. Verify no design-extracted file already exists for this file-id+date. If one exists from today's date for the SAME file-id, halt with NEEDS_CONTEXT — the dispatch is redundant; the Orchestrator should reuse the existing file unless re-extraction is explicitly requested (e.g., the Figma version changed).
4. Read the Figma file's version ID via MCP. Capture it for the output header.

1. Resolve Figma-Design-Page-Node-ID — the root of all enumeration. Read SRS §3.4.1 header field Figma-Design-Page-Node-ID paired with this URL. A Figma file has MULTIPLE pages (top-level tabs); the project's design lives on ONE specific page. Without page-scoping, this extraction would walk every page (brainstorms, old designs, Foundation page, etc.) and either grab irrelevant frames OR miss the project design.

Three sub-cases:

• The captured value is a PAGE node (Figma MCP: query node type → CANVAS / PAGE) → use it directly as the root. Proceed to Step 1.
• The captured value is a FRAME or SECTION node (the PM deep-linked to a specific frame they wanted to highlight) → walk UP the tree via Figma MCP's parent-pointer until you reach a CANVAS / PAGE node. Record the resolution in the extract output's ## Page-scope resolution section. Update SRS §3.4.1 Figma-Design-Page-Node-ID to the resolved page node (you have write access to this single field; do NOT touch other SRS content).
• The captured value is a PAGE NAME (string, not Node ID) — BA at Phase 1.X step 10 wrote the operator's answer as a name (e.g., "Project Design") rather than an ID. Resolve by querying Figma MCP for pages in the file, finding the one with matching name (case-insensitive, trimmed), and recording its Node ID. Update SRS §3.4.1 with the resolved ID. If no page matches by name → halt with NEEDS_CONTEXT asking the operator to choose from the list of actual page names in the file.

1. The root of all enumeration in Steps 1-7 below is the resolved page node. Walk only its subtree. Frames on OTHER pages are NOT enumerated (they are out of scope for the project's design).

Step 1 — Enumerate screens (frames)

Walk every top-level frame under the resolved page node only. For each frame:

• Capture: frame name, Node ID, page name, dimensions, position on page.
• Identify variants: if the frame is part of a component-set, list all variants by name.
• Infer purpose from name (e.g., "RepositoryList/Default" → purpose: browse repositories; state: default).
• Identify states from variants and from frames with same base-name + state suffix (e.g., "RepositoryList/Empty", "RepositoryList/Loading", "RepositoryList/Error").

Step 2 — Enumerate components per screen

For each frame, walk every nested instance:

• Capture: component master name, instance name, testID (if data-testid set in any node), position within frame, visible properties (label text, icon, state variant).
• Group by type: buttons, inputs, cards, modals, navs, list items, toasts, etc.
• For interactive components: note interaction targets (Figma Prototype connections) — these reveal flows.

Step 3 — Enumerate exact copy

Walk every text node in every frame:

• Capture the EXACT text (no normalization, no rephrasing). Preserve locale if multi-language frames exist.
• Group by element role: page titles, section headings, button labels, helper text, error messages, placeholder text, empty-state copy, confirmation-dialog copy, toast text.
• Flag template-style copy (e.g., "Show {count} repositories") — these become parameterized strings BA must specify in the FR.

Step 4 — Enumerate form fields

For every form-shaped frame (input + label + helper pattern):

• Per field: label text, placeholder, default value, validation hints visible in Figma (e.g., red border on RepoNameInput/Error variant), error message text, required-marker visibility.
• Per form: submit button label, submit button states (default / loading / disabled), validation timing (on-blur vs on-submit if inferable from interactions).

Step 5 — Enumerate interaction flows

Walk Figma Prototype connections (the connector arrows between frames). For each:

• Source frame + interaction (click button X) → destination frame + transition style.
• Build a list of flows: "Login → Dashboard" / "Repository List → Repository Detail (drill-in)" / etc.
• Flag flows with no explicit destination in Figma as gaps.

Step 6 — Extract design guideline evidence

Build a confirmed visual-system inventory from the scoped page. Prefer formal Figma variables/styles/components when present; otherwise infer only from repeated values in the scoped frames. Do not create or modify Figma styles in this mode.

For each category, capture the source of truth, observed values, usage locations, confidence, and whether the value is formal or inferred:

• Color palette
• First read Figma Variables and local/shared color styles attached to scoped nodes.
• If no formal styles exist, sample fills, strokes, text colors, and gradients across frames; normalize solid colors to hex or rgba with opacity; group repeated values.
• Classify by usage where evidence supports it: surface, text, border, accent, state-success, state-warning, state-error, disabled, overlay.
• Record contrast-relevant pairs when visible: text color + immediate background.
• Typography
• Read text styles when present.
• Otherwise group text nodes by font family, font size, weight, line height, paragraph spacing, and role inferred from position/name (heading, body, label, caption, button).
• Preserve exact numeric values; do not "fix" them into a scale.
• Spacing and layout rhythm
• Read Auto Layout padding, itemSpacing, layout grids, column/gutter settings, and frame constraints.
• Infer common spacing values from repeated x/y gaps only when the same value appears across multiple frames/components.
• Identify likely baseline unit (4px, 8px, or unknown) from the greatest common repeated spacing pattern.
• Border radius
• Capture per-corner radius values from frames, rectangles, buttons, inputs, cards, modals, chips, and avatars.
• Group repeated values and classify by component role when clear.
• Elevation and effects
• Capture shadow/effect styles when present; otherwise list repeated effect signatures (offset, blur, spread, color, opacity).
• Component pattern evidence
• Inventory named component masters/instances and repeated component-like groups (buttons, inputs, cards, nav, modals, badges, tabs, menus).
• Note variant/state coverage visible in Figma.
• Layout grid / breakpoints
• Capture frame sizes, platform hints, columns, gutters, margins, and responsive constraints if present.
• If only frame sizes exist, list them as observed viewport targets, not as declared breakpoints.

Set a design-guideline recommendation in the output:

• Candidate Design-Guideline: from-figma when either:
• formal Figma styles/variables/components exist for at least colors plus typography, or
• inferred repeated values cover colors plus at least two of typography, spacing, radius, or component patterns.
• Candidate Design-Guideline: needs-human-choice when evidence is too sparse, inconsistent, or decorative-only.

Confidence rules:

• High — formal styles/variables/components exist and are used by most scoped screens.
• Medium — no formal styles, but repeated values are consistent across multiple screens/components.
• Low — one-off values, too few frames, or conflicting palettes/scales.

Step 7 — Enumerate accessibility hints

When the design carries explicit a11y metadata:

• Focus order if numbered on the canvas.
• ARIA semantics in component descriptions.
• Color contrast pairs annotated in Figma (some designers note "AA-compliant" on swatches).
• Touch-target sizes for mobile-bridge surfaces.

Empty when design doesn't specify (most projects don't).

Step 8 — Write the design-extracted file

Open docs/requirements/design-extracted/-.md. Use the structure below (template: confirmed-first, inferred-last). Except for the required Candidate Design-Guideline field derived from Step 6 evidence, do not include opinion or recommendation — enumerate what the design contains.

# Design-extracted requirements — 

- **Figma-File-URL:** 
- **Figma-File-ID:** 
- **Figma-File-Version:** 
- **Figma-Design-Page-Node-ID:** 
- **Figma-Design-Page-Name:** 
- **Extracted-by:** ui-ux-designer (extract mode)
- **Extracted-at:** 
- **Designer (per Figma metadata):** 
- **Total frames:** 
- **Total pages:** 

## Provenance

This file is one of three branches of the `docs/requirements/` source corpus that BA reads at Phase 1.X synthesis. The other two are top-level PM-authored files and `conversational-additions/` (BA Mode D Step D0 captures). The srs-source-validator's coverage check spans ALL three branches.

This file contains CONFIRMED elements (Sections 1–7 below) and INFERRED requirements (Section 8 below). BA at Phase 1.X synthesizes US/FR only from confirmed elements + inferred items the textual PRD also supports. BA uses Section 6 to set `Design-Guideline:` when Flow A provides enough design-system evidence. Inferred-only items must become OQs per BA's no-invention invariant.

## Section 1 — Screens (frames)

| Frame name | Node ID | Page | Purpose | States detected |
|---|---|---|---|---|
| RepositoryList/Default | 530:2 | Repositories | List view | default, loading, empty, error |
| RepositoryList/SelectedRow | 530:14 | Repositories | List with selection | with-selection (1+ rows checked) |
| ConfirmDialog/Hide | 533:2 | Repositories | Destructive action confirm | open, closing |

## Section 2 — Components per screen

### RepositoryList/Default (530:2)
- Per-row checkbox (testID: `rep-row-checkbox-`) — states: default / checked / disabled. Touch target 24×24.
- Select-all checkbox (testID: `rep-select-all-checkbox`) — states: unchecked / mixed / all.
- Search input (testID: `rep-search`) — placeholder: "Search repositories…".
- Filter chips (testIDs: `rep-filter-region`, `rep-filter-status`) — 4 chip variants visible (Active, Hidden, Pending, Archived).
- Batch action bar (testID: `rep-batch-bar`) — sticky-bottom, visible when ≥1 row checked. Contains: "Show selected" button, "Hide selected" button, selection-count indicator.

(Repeat per screen.)

## Section 3 — Exact copy

| Element | Text | Locale | Notes |
|---|---|---|---|
| Page title (RepositoryList) | "Repository Visibility Admin" | en | h1 |
| Search placeholder | "Search repositories…" | en | input.placeholder |
| Empty state heading (RepositoryList/Empty) | "No repositories yet" | en | empty state |
| Empty state body | "Connect your first repository to get started" | en | empty state |
| Batch button — Show | "Show selected" | en | primary action |
| Batch button — Hide | "Hide selected" | en | destructive action |
| Confirm dialog title | "Show {count} repositories?" | en | PARAMETERIZED — `count` must be supplied by FR |
| Confirm dialog body | "{count} repositories will become publicly visible." | en | PARAMETERIZED |
| Confirm dialog button — primary | "Show" | en | primary |
| Confirm dialog button — secondary | "Cancel" | en | secondary |
| Completion toast | "{count} repositories updated" | en | PARAMETERIZED |

## Section 4 — Form fields

(Per form: label, placeholder, validation rules visible in Figma, error message text, default values. Empty if no forms in the file.)

## Section 5 — Interaction flows

| Flow | Source | Trigger | Destination | Notes |
|---|---|---|---|---|
| Browse → Detail | RepositoryList/Default | click row | RepositoryDetail/Default | drill-in |
| Batch Hide flow | RepositoryList/SelectedRow | click "Hide selected" | ConfirmDialog/Hide | open modal |
| Batch Hide confirm | ConfirmDialog/Hide | click "Show" | RepositoryList/Default | close modal + toast |
| Batch Hide cancel | ConfirmDialog/Hide | click "Cancel" | RepositoryList/SelectedRow | close modal, preserve selection |

## Section 6 — Design guideline extraction (Flow A)

- **Formal design system present:** 
- **Candidate Design-Guideline:** 
- **Confidence:** 
- **Evidence basis:** 
- **Foundation recommendation:** 

### Color palette evidence

| Token candidate | Value | Role evidence | Source | Usage count | Confidence |
|---|---|---|---|---:|---|
| surface-default | #FFFFFF | Frame backgrounds | inferred from 12 frames | 12 | medium |
| text-primary | #111827 | Body/title text | inferred from text nodes | 87 | medium |
| accent-brand | #2563EB | Primary buttons + active nav | Figma color style `Brand/Blue/600` | 24 | high |
| state-error | #DC2626 | Error text + destructive buttons | inferred repeated value | 6 | medium |

### Typography evidence

| Token candidate | Family | Size | Weight | Line height | Role evidence | Source | Confidence |
|---|---|---:|---:|---:|---|---|---|
| heading-lg | Inter | 32 | 700 | 40 | Page titles | text style `Headi

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [evolplus](https://github.com/evolplus)
- **Source:** [evolplus/talos](https://github.com/evolplus/talos)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.