gaia-framework 1.83.2 → 1.87.0

package/_gaia/_config/global.yaml

@@ -3,7 +3,7 @@
 # After modifying this file, run /gaia-build-configs to regenerate resolved configs.
 
 framework_name: "GAIA"
-framework_version: "1.83.2"
+framework_version: "1.87.0"
 
 # User settings
 user_name: "jlouage"

package/_gaia/dev/agents/_base-dev.md

@@ -62,8 +62,13 @@ abstract: true
 - Mark each as checked or document why it can't be checked
 - All DoD items must pass before status changes to `review`
 
+## Figma Design Consumption
+- When a story file or ux-design.md contains a `figma:` metadata block, load the figma-integration skill (tokens, components, export sections) via JIT
+- Extract design tokens and component specs using MCP, then generate stack-specific scaffolded code using the export section's resolution table
+- If no `figma:` metadata is present, skip all Figma operations and read ux-design.md text as-is (zero behavioral change)
+
 ## Skill Access
-- All 8 shared skills available via JIT loading
+- All 8 shared skills + figma-integration available via JIT loading
 - Load skill sections only when needed for current step
 - Drop skill from context when step completes
 - Skills can be overridden via .customize.yaml (skill_overrides for full file, skill_section_overrides for individual sections)

package/_gaia/dev/skills/_skill-index.yaml

@@ -56,9 +56,15 @@ skills:
 
   - file: figma-integration.md
     sections:
-      - { id: detection, line_range: [46, 133], description: "Figma MCP detection probe, failure handling, adapter selection, security guardrails, API scopes, error sanitization" }
-      - { id: tokens, line_range: [134, 164], description: "Design token extraction in W3C DTCG format" }
-      - { id: components, line_range: [165, 200], description: "Component spec extraction to tech-agnostic YAML" }
-      - { id: frames, line_range: [201, 221], description: "UI kit frame generation across viewports" }
-      - { id: assets, line_range: [222, 245], description: "Asset export at multiple densities" }
-      - { id: export, line_range: [246, 296], description: "Per-stack token resolution table, path resolution rules, and semantic alias resolution for all dev agents" }
+      - { id: detection, line_range: [48, 135], description: "Figma MCP detection probe, failure handling, adapter selection, security guardrails, API scopes, error sanitization" }
+      - { id: tokens, line_range: [136, 166], description: "Design token extraction in W3C DTCG format" }
+      - { id: components, line_range: [167, 202], description: "Component spec extraction to tech-agnostic YAML" }
+      - { id: frames, line_range: [203, 223], description: "UI kit frame generation across viewports" }
+      - { id: assets, line_range: [224, 247], description: "Asset export at multiple densities" }
+      - { id: export, line_range: [248, 299], description: "Per-stack token resolution table, path resolution rules, and semantic alias resolution for all dev agents" }
+      - { id: import-detection, line_range: [300, 322], description: "Import mode entry point — URL/key validation, error handling" }
+      - { id: import-discovery, line_range: [323, 347], description: "Import mode page and frame discovery via MCP" }
+      - { id: import-tokens, line_range: [348, 366], description: "Import mode design token extraction to W3C DTCG" }
+      - { id: import-screens, line_range: [367, 390], description: "Import mode screen inventory and frame-to-screen mapping" }
+      - { id: import-generate, line_range: [391, 419], description: "Import mode ux-design.md generation with figma: frontmatter" }
+      - { id: fidelity, line_range: [420, 498], description: "Design-to-implementation fidelity gate — token drift detection, per-category reporting, threshold-based gating" }

package/_gaia/dev/skills/figma-integration.md

@@ -41,7 +41,9 @@ test_scenarios:
 
 **Selection logic:** probe MCP tool list for known prefixes in order: `figma_` / `figma/` → `penpot_` → `sketch_`. Use the first match. If none found, report "No design tool MCP server detected."
 
-**MCP constraint (FR-140):** operations are read-heavy/write-light. Most interactions read design data (tokens, components, styles). Write operations are limited to frame generation and are clearly documented per section.
+**Zero-change path:** When no `figma:` metadata block is present in the story file or ux-design.md, all Figma-related operations are skipped — the dev agent reads ux-design.md text as-is (no MCP calls, no cache reads, no design system files generated). **MCP constraint (FR-140):** operations are read-heavy/write-light; most interactions read design data (tokens, components, styles). Write operations are limited to frame generation and are documented per section.
+
+**Response Cache and Offline Fallback (NFR-028):** MCP responses are cached in `{project-path}/.figma-cache/` (gitignored) with composite key `{file_key}:{page_id}:{design_version_hash}`, where the version hash derives from the Figma file's `lastModified` timestamp. The version hash is the primary invalidation signal — a changed design always triggers a fresh MCP call. A 1-hour TTL serves as secondary expiry when version metadata cannot be fetched. When the MCP server is unreachable and the cache TTL has expired, the skill continues with last-known-good files from `.figma-cache/`, emitting an `[OFFLINE]` warning logged in the story's dev record — stale design data is preferable to blocking implementation.
 
 <!-- SECTION: detection -->
 ## Detection Probe
@@ -294,3 +296,203 @@ Semantic tokens reference primitives via `{group.token}` syntax in their `$value
 → SCSS: $color-interactive-primary: #3B82F6;
 → Dart: static const interactivePrimary = Color(0xFF3B82F6);
 ```
+
+<!-- SECTION: import-detection -->
+## Import Mode — Detection and Entry Point
+
+Import mode reverses the Generate flow: reads existing Figma designs INTO GAIA (Figma → ux-design.md) instead of generating Figma frames FROM GAIA. Uses only read operations from the DesignToolProvider interface: `detect()`, `getTokens()`, `getComponents()`, `getFrames()`. No `exportAssets()` needed.
+
+### Import Entry Point
+
+The detection probe mode selection menu (from E13-S1) presents three options: **Generate** | **Import** | **Skip**. When the user selects Import mode:
+
+1. **Accept input** — prompt for Figma file URL or raw file key
+2. **Parse URL** — extract file key from `https://www.figma.com/file/{key}/...` format, or accept raw key directly
+3. **Validate file key** — issue a lightweight `figma/get_file` MCP call with `depth=1` (metadata only) to confirm the file exists and is accessible
+4. **Handle errors:**
+   - Invalid key format → client-side rejection, no MCP call
+   - 404 not found → "Figma file not found. Verify the file key or URL."
+   - 403 permission denied → "Access denied. Ensure the file is shared with your Figma account."
+   - 429 rate limited → single retry after 1-second delay; if retry fails, abort gracefully
+   - 5-second timeout → "MCP server unresponsive. Import aborted." (per E13-S1 hard limit)
+
+### API Scopes
+
+Import mode uses only read scopes: `files:read` and `file_content:read`. No write operations are performed on the Figma file — import is strictly read-only.
+
+<!-- SECTION: import-discovery -->
+## Import Mode — Page and Frame Discovery
+
+Enumerate all pages and top-level frames from the Figma file to build a complete document tree.
+
+### Discovery Steps
+
+1. **Fetch full document tree** — call `figma/get_file` with full depth to retrieve the complete document tree
+2. **Extract pages** — parse response for top-level CANVAS nodes (Figma's page type)
+3. **Extract frames** — within each CANVAS, collect FRAME nodes with metadata: name, nodeId, absoluteBoundingBox (x, y, width, height)
+4. **Build Page → Frames hierarchy** — structure: `{ page: { name, nodeId, frames: [{ name, nodeId, width, height }] } }`
+5. **Classify frames by viewport** — based on absoluteBoundingBox width:
+   - Mobile: width ≤ 480px
+   - Tablet: width 481–1024px
+   - Desktop: width > 1024px
+6. **Cache response** — store in `{project-path}/.figma-cache/` with 1-hour TTL per ADR-024
+
+### Partial Access Handling
+
+If some pages or frames are inaccessible (permission restricted), generate a partial ux-design.md with `[PARTIAL]` warnings for inaccessible pages. Do not abort the entire import.
+
+### Empty File Handling
+
+If the Figma file contains no frames (empty file), generate a minimal ux-design.md with empty screen sections and a note: "No frames found in Figma file."
+
+<!-- SECTION: import-tokens -->
+## Import Mode — Design Token Extraction
+
+Extract design tokens from an existing Figma file and write them in W3C DTCG format. This reverses the generate flow — reading tokens FROM Figma rather than pushing tokens TO Figma.
+
+### Extraction Steps
+
+1. **Extract color styles** — read the file's `styles` and `document` nodes. Resolve fill and stroke references to RGBA values. Map named styles to semantic token names using naming pattern: `Primary/500` → `color.primary.500`
+2. **Extract typography styles** — resolve font family, font size, font weight, line height, letter spacing from text style nodes
+3. **Extract effect styles** — resolve drop-shadow and inner-shadow parameters (offsetX, offsetY, blur, spread, color). Also extract blur effect parameters
+4. **Extract spacing from auto-layout** — read auto-layout frame properties: itemSpacing, paddingLeft, paddingRight, paddingTop, paddingBottom
+5. **Map to W3C DTCG format** — each token gets `$type`, `$value`, and optional `$description` per the W3C Design Tokens Community Group draft specification. Composite tokens (typography) use nested structure
+6. **Resolve semantic aliases** — match Figma style names to conventional naming patterns and create alias references (e.g., `color.surface.primary` → `{color.white}`)
+7. **Write output** — save design-tokens.json to `{planning_artifacts}/design-system/` with `schema_version` field
+
+### Error messages
+
+Log error messages with status codes only — no URLs, file keys, or design data in log output (per E13-S6 / FR-143).
+
+<!-- SECTION: import-screens -->
+## Import Mode — Screen Inventory
+
+Build a complete screen-to-frame mapping from the discovered page and frame hierarchy.
+
+### Screen Inventory Steps
+
+1. **Group frames by page** — organize the frame list from import-discovery into page groups
+2. **Build per-frame metadata** — for each frame: name, nodeId, width, height, viewport classification (mobile/tablet/desktop)
+3. **Extract component instances** — for each frame, enumerate component instances used within it. Map to component-specs.yaml format: name, props, layout type
+4. **Generate screen-to-frame mapping** — produce a structured mapping:
+   ```yaml
+   screens:
+     - page: "Home"
+       frames:
+         - name: "Home/Desktop"
+           nodeId: "123:456"
+           width: 1280
+           height: 800
+           viewport: desktop
+           components: [Button, Card, TextInput]
+   ```
+5. **Track all node IDs** — every Figma node referenced must include its nodeId for downstream dev agent consumption (E13-S5)
+
+<!-- SECTION: import-generate -->
+## Import Mode — Generate ux-design.md
+
+Assemble the extracted data into a complete ux-design.md document with Figma metadata frontmatter.
+
+### Generation Steps
+
+1. **Write `figma:` YAML frontmatter** — include:
+   ```yaml
+   figma:
+     file_key: "{extracted_file_key}"
+     pages: ["Page 1", "Page 2"]
+     node_ids: ["0:1", "123:456", "789:012"]
+     imported_at: "{ISO 8601 timestamp}"
+     import_mode: true
+   ```
+2. **Write Design Tokens section** — reference token paths from design-tokens.json (e.g., `{color.primary}`, `{spacing.4}`)
+3. **Write Component Inventory section** — list all components discovered from frame extraction with props and variants
+4. **Write Screen Descriptions** — for each screen: frame name, node ID, viewport classification, component list, and layout description
+5. **Preserve read-only guarantee** — the entire generation step produces only local files. Zero write operations to Figma via MCP. Only `get_file`, `get_file_nodes`, and `get_image` calls are used throughout the import flow
+
+### Output Files
+
+- `{planning_artifacts}/ux-design.md` — enhanced with `figma:` frontmatter
+- `{planning_artifacts}/design-system/design-tokens.json` — W3C DTCG format
+- `{planning_artifacts}/design-system/component-specs.yaml` — component specs (updated with import data)
+
+**Shared formats:** Import mode writes the same intermediate files as Generate mode (design-tokens.json, component-specs.yaml) using identical schemas from E13-S3. This ensures downstream dev agents consume imported designs identically to generated ones.
+
+<!-- SECTION: fidelity -->
+## Design-to-Implementation Fidelity Gate
+
+Post-implementation verification layer that compares token values in generated code against the approved `design-tokens.json` to detect and measure drift between design intent and implementation. Addresses FR-171 and ADR-024. Consumed by `/gaia-code-review` as a conditional step when the story has a `figma:` frontmatter block.
+
+### Token Extraction from Generated Code
+
+Scan generated code files for token references using platform-specific patterns:
+
+- **CSS custom properties:** `var(--color-primary-500)` maps to `color.primary.500`
+- **SCSS variables:** `$color-primary-500` maps to `color.primary.500`
+- **Flutter ThemeData:** `AppTokens.color.primary500` maps to `color.primary.500`
+- **Spring properties:** `design.tokens.color.primary.500`
+- **Python dict:** `TOKENS['color']['primary.500']`
+- **React Native / Swift / Compose:** platform-specific mappings per the export section resolution table
+
+Use the per-stack token resolution table from the `export` section above to reverse-map platform-specific references back to canonical W3C DTCG paths before comparison.
+
+### Deep Comparison Engine
+
+For each token reference extracted from code:
+
+1. Look up the canonical W3C DTCG path in `{planning_artifacts}/design-system/design-tokens.json`
+2. Compare the value used in code against the approved value in design-tokens.json
+3. Classify each token as:
+   - **matched** — value in code exactly matches design-tokens.json
+   - **drifted** — token exists in design-tokens.json but value differs
+   - **missing** — token referenced in code but absent from design-tokens.json
+
+### Per-Category Drift Reporting
+
+Group all compared tokens by W3C DTCG top-level category:
+
+- `color.*` — color palette, semantic colors, surface colors
+- `typography.*` — font families, sizes, weights, line heights
+- `spacing.*` — margins, paddings, gaps
+- `border.*` / `radius.*` — border widths, styles, border-radius values
+
+Calculate drift percentage per category using the formula: `drift_pct = (drifted + missing) / total × 100`
+
+Generate a structured fidelity report with a per-category breakdown table:
+
+| Category | Total | Matched | Drifted | Missing | Drift % | Status |
+|----------|-------|---------|---------|---------|---------|--------|
+| color.*  | 20    | 18      | 1       | 1       | 10%     | WARN   |
+
+### Threshold-Based Gating
+
+Two configurable thresholds (defaults from FR-171):
+
+- **10% WARNING** — drift exceeds 10% in any category: raise a WARNING. Story may continue but issue is flagged.
+- **25% BLOCK** — drift exceeds 25% in any category: story completion is BLOCKED and re-review is required.
+
+**Edge case handling:**
+
+- **Empty categories** — if a category has zero tokens referenced, skip it (do not report 0/0 as drift)
+- **N=1 single-token categories** — if a category has only one token and it is drifted, flag with a note "Single-token category — flagged but not auto-blocked (N=1 exception)" instead of blocking. Prevents a single mismatched border-radius from blocking an entire story.
+- **Missing design-tokens.json** — if `design-tokens.json` does not exist at the expected path, skip the fidelity check gracefully with a note: "Fidelity check skipped — design-tokens.json not found at {path}." No crash, no block.
+- **Zero tokens consumed** — if generated code references zero tokens (no `figma:` block consumed or no token patterns found), report "N/A — no tokens consumed" and skip the fidelity check.
+
+### Report Persistence
+
+Save the fidelity report to `{implementation_artifacts}/reviews/{story_key}/fidelity-report.md`. The report includes:
+
+- **Timestamp** — ISO 8601 date of the fidelity check
+- **Story key** — the story_key being checked
+- **Token source file path** — path to the design-tokens.json used as baseline
+- **Per-category breakdown table** (as shown above)
+- **Overall drift percentage** — weighted average across all categories
+- **Verdict** — PASS / WARNING / BLOCKED
+
+After saving the report, write the overall drift percentage to the story file YAML frontmatter:
+
+```yaml
+figma:
+  fidelity_drift_pct: 8.5
+```
+
+The `figma.fidelity_drift_pct` value is the weighted overall drift across all categories.

package/_gaia/lifecycle/templates/story-template.md

@@ -19,6 +19,13 @@ blocks: []
 traces_to: []
 date: "{creation_date}"
 author: "{agent_name}"
+# Optional: Figma design metadata — enables dev agents to extract design tokens and component specs via MCP.
+# Omit this block entirely if the story does not reference Figma designs.
+# figma:
+#   file_key: "{figma_file_key}"       # Figma file identifier (from URL)
+#   pages: ["{page_name}"]             # List of page names to extract from
+#   node_ids: ["{node_id}"]            # List of specific Figma node IDs
+#   design_version: null               # Populated by dev agent after first consumption (lastModified hash)
 ---
 
 # Story: {story_title}

package/_gaia/lifecycle/workflows/2-planning/create-ux-design/instructions.xml

@@ -76,17 +76,61 @@
   <action>Add Screen-to-Frame mapping table with all generated frames across all viewports</action>
   <action>Ensure backward compatibility: existing text-only ux-design.md content is preserved. Figma sections are additive — they appear after the standard UX design sections.</action>
 </step>
-<step n="13" title="Generate Output">
+<step n="13" title="Import Mode — File Key Entry and Validation" if="figma_mcp_available AND user_selected_import">
+  <critical>
+    <mandate>Import mode is strictly READ-ONLY. Only get_file, get_file_nodes, and get_image MCP calls are permitted. Zero write operations to Figma. Minimum required Figma API scopes: files:read + file_content:read.</mandate>
+  </critical>
+  <action>JIT-load figma-integration:import-detection section from _gaia/dev/skills/figma-integration.md</action>
+  <ask>Enter the Figma file URL (e.g., https://www.figma.com/file/abc123/Design-Name) or raw file key:</ask>
+  <action>Parse input: extract file key from URL format, or accept raw key directly</action>
+  <action>Validate key via lightweight figma/get_file MCP call with depth=1 (metadata only)</action>
+  <action>Handle errors: invalid key format (client-side rejection), 404 not found, 403 permission denied, 429 rate limited (single retry after 1s delay), 5-second timeout (abort gracefully per E13-S1)</action>
+</step>
+<step n="14" title="Import Mode — Page and Frame Discovery" if="figma_mcp_available AND user_selected_import">
+  <action>JIT-load figma-integration:import-discovery section</action>
+  <action>Call figma/get_file with full depth to retrieve the complete document tree</action>
+  <action>Parse response: extract pages (top-level CANVAS nodes) and frames (FRAME nodes within each page)</action>
+  <action>Build Page → Frames hierarchy with metadata (name, nodeId, absoluteBoundingBox dimensions)</action>
+  <action>Classify frames by viewport width: mobile (≤480px), tablet (481–1024px), desktop (>1024px)</action>
+  <action>Cache response in {project-path}/.figma-cache/ with 1-hour TTL per ADR-024</action>
+  <action>Handle partial access: if some pages/frames are inaccessible, continue with warnings and proceed with accessible content</action>
+</step>
+<step n="15" title="Import Mode — Design Token Extraction" if="figma_mcp_available AND user_selected_import">
+  <action>JIT-load figma-integration:import-tokens section</action>
+  <action>Extract color styles from file's styles and document nodes, resolving fill/stroke references to RGBA values</action>
+  <action>Extract typography styles: font family, size, weight, line height, letter spacing</action>
+  <action>Extract effect styles: drop-shadow and inner-shadow parameters</action>
+  <action>Extract spacing values from auto-layout frames: itemSpacing, paddingLeft/Right/Top/Bottom</action>
+  <action>Map all extracted tokens to W3C DTCG format with semantic alias support (e.g., Primary/500 → color.primary.500)</action>
+  <action>Write design-tokens.json to {planning_artifacts}/design-system/ with schema_version field</action>
+</step>
+<step n="16" title="Import Mode — Screen Inventory" if="figma_mcp_available AND user_selected_import">
+  <action>JIT-load figma-integration:import-screens section</action>
+  <action>Group frames by page from the discovered hierarchy</action>
+  <action>Build per-frame metadata: name, nodeId, width, height, viewport classification</action>
+  <action>Extract component instances used in each frame — map to component-specs.yaml format (name, props, layout type)</action>
+  <action>Generate structured screen-to-frame mapping with tracked nodeIds for downstream dev agent consumption (E13-S5)</action>
+  <action>Write component-specs.yaml to {planning_artifacts}/design-system/</action>
+</step>
+<step n="17" title="Import Mode — Generate ux-design.md Content" if="figma_mcp_available AND user_selected_import">
+  <action>JIT-load figma-integration:import-generate section</action>
+  <action>Prepare figma: YAML frontmatter block containing: file_key, pages array, node_ids array, imported_at ISO 8601 timestamp, import_mode: true</action>
+  <action>Prepare Design Tokens section with token path references (e.g., {color.primary}, {spacing.4})</action>
+  <action>Prepare Component Inventory section listing all components discovered from frame extraction with props and variants</action>
+  <action>Prepare Screen Descriptions section with per-screen: frame name, node ID, viewport classification, component list, layout description</action>
+  <action>Verify read-only guarantee: audit all MCP calls made during steps 13-17 — confirm only get_file, get_file_nodes, and get_image were used. Zero write operations. Abort and report if any write operation is detected.</action>
+</step>
+<step n="18" title="Generate Output">
   <template-output file="{planning_artifacts}/ux-design.md">
-    Generate UX design document with: personas, information architecture, wireframe descriptions, interaction patterns, component specifications, accessibility plan, FR-to-Screen Mapping table (FR ID | Screen/Page | Wireframe Section). If Generate mode was active: include figma: frontmatter block, Design Tokens section, Component Inventory with Figma node IDs, and Screen-to-Frame mapping table.
+    Generate UX design document with: personas, information architecture, wireframe descriptions, interaction patterns, component specifications, accessibility plan, FR-to-Screen Mapping table (FR ID | Screen/Page | Wireframe Section). If Generate mode was active: include figma: frontmatter block, Design Tokens section, Component Inventory with Figma node IDs, and Screen-to-Frame mapping table. If Import mode was active: include figma: frontmatter block (file_key, pages, node_ids, imported_at, import_mode: true), Design Tokens section with token references, Component Inventory, and Screen Descriptions.
   </template-output>
 </step>
-<step n="14" title="FR-140 Compliance Check" if="figma_mcp_available AND user_selected_generate">
+<step n="19" title="FR-140 Compliance Check" if="figma_mcp_available AND user_selected_generate">
   <action>Audit all MCP calls executed during Generate mode: classify each as READ (get_file, get_styles, get_components, get_images, get_frames) or WRITE (create_frame, create_component_instance, create_page)</action>
   <action>Verify FR-140 constraint: write operations only occurred during Generate mode steps (8–12). Import mode and Skip mode must have zero write calls.</action>
   <action>Document minimum required Figma API scopes: files:read + file_content:read (default for all modes), files:write (Generate mode only)</action>
 </step>
-<step n="15" title="Optional: Accessibility Review">
+<step n="20" title="Optional: Accessibility Review">
   <ask>Would you like to review the UX design for WCAG 2.1 accessibility compliance? This spawns a subagent in a separate context. Recommended for user-facing applications. (yes / skip)</ask>
   <action>If yes: spawn a subagent using the Agent tool: "Load {project-root}/_gaia/core/tasks/review-accessibility.xml. Read its entire contents. Target: {planning_artifacts}/ux-design.md. Follow the flow steps EXACTLY. Generate accessibility findings report."</action>
   <action>If skip: accessibility review can be run anytime later with /gaia-review-a11y</action>

package/_gaia/lifecycle/workflows/4-implementation/code-review/instructions.xml

@@ -25,6 +25,16 @@
   </action>
   <action>Include an "Architecture Conformance" section in findings with PASS/FAIL per check</action>
 </step>
+<step n="3c" title="Design Fidelity Check">
+  <action>Read story file YAML frontmatter — check if a `figma:` block exists</action>
+  <action if="story_has_figma_block">Load the `figma-integration:fidelity` section JIT from `_gaia/dev/skills/figma-integration.md`</action>
+  <action if="story_has_figma_block">Run the fidelity comparison: extract token references from changed code files, compare against `{planning_artifacts}/design-system/design-tokens.json`, classify as matched/drifted/missing</action>
+  <action if="story_has_figma_block">Calculate per-category drift percentages (color, typography, spacing, borders)</action>
+  <action if="story_has_figma_block">Save fidelity report to `{implementation_artifacts}/reviews/{story_key}/fidelity-report.md`</action>
+  <action if="story_has_figma_block">Write `figma.fidelity_drift_pct` to story file frontmatter</action>
+  <action if="story_has_figma_block">Include fidelity results in code review findings: PASS (0% drift), WARNING (any category exceeds 10%), or BLOCKED (any category exceeds 25%)</action>
+  <action if="no figma block">Skip fidelity check — story does not use Figma design tokens</action>
+</step>
 <step n="4" title="Generate Findings">
   <action>List issues by severity: critical, warning, suggestion</action>
 </step>

package/_gaia/lifecycle/workflows/4-implementation/dev-story/instructions.xml

@@ -48,6 +48,16 @@
   </action>
   <action if="mode == REWORK or mode == RESUME">Skip status change — story is already in-progress.</action>
 </step>
+<step n="4b" title="Figma Design Consumption">
+  <action>Check for figma: metadata block in story file YAML frontmatter. Expected fields: file_key (string — Figma file identifier), pages (list of page names to extract from), node_ids (list of specific node IDs), design_version (string — Figma lastModified hash for traceability). Also check ux-design.md for a figma: metadata block.</action>
+  <action if="no figma: metadata block found in story file or ux-design.md">No Figma metadata present — skip all Figma-related actions. Use ux-design.md text as-is with zero behavioral change. Proceed to Step 5.</action>
+  <action if="figma: metadata block is present">JIT-load figma-integration.md tokens and components sections for MCP extraction.</action>
+  <action if="figma: metadata block is present">Check for cached responses in {project-path}/.figma-cache/ using composite cache key {file_key}:{page_id}:{design_version_hash}. If cache hit with valid version hash, use cached data. If cache miss or design version changed since last implementation, proceed with MCP extraction.</action>
+  <action if="figma: metadata block is present and MCP available">Extract design tokens via MCP and write design-tokens.json to {planning_artifacts}/design-system/ in W3C DTCG format. Extract component specs via MCP and write component-specs.yaml to the same directory.</action>
+  <action if="figma: metadata block is present and MCP unreachable">If cached data exists in {project-path}/.figma-cache/ (even with expired TTL), continue with last-known-good files and display [OFFLINE] warning: "Design data loaded from cache — MCP unreachable. Token data may be stale." Do not halt — proceed with stale data.</action>
+  <action if="figma: metadata block is present">Compare design_version in story figma: metadata against the current Figma file version. If the design version has changed since the last implementation run, offer an incremental update: "Design has changed since last implementation (stored: {old_version}, current: {new_version}). Run incremental token update? [y/n]". Record the design_version consumed in the story figma: metadata for traceability.</action>
+  <action if="figma: metadata block is present">JIT-load figma-integration.md export section. Generate stack-specific scaffolded code from intermediate files (design-tokens.json and component-specs.yaml) using the active dev agent's resolution table. Output token files and component scaffolds to {project-path} design system directory.</action>
+</step>
 <step n="5" title="Plan Implementation">
   <action if="mode == REWORK">REWORK MODE — Focus plan on fixing review feedback:
     1. Read the story's Review Gate table — identify which reviews FAILED

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gaia-framework",
-  "version": "1.83.2",
+  "version": "1.87.0",
   "description": "GAIA — Generative Agile Intelligence Architecture installer",
   "bin": {
     "gaia-framework": "./bin/gaia-framework.js"