figma-to-spec

name	figma-to-spec
description	Converts a Figma frame into a structured intent-package with AC confidence scoring, state matrix enumeration, and JP/VI/EN annotation handling. Used by kopi-figspec agent.
license	MIT
allowed-tools	["file-search","mcp__figma__get_design_context","mcp__figma__get_screenshot","mcp__figma__get_metadata"]

figma-to-spec

Converts a Figma frame into a structured intent-package with AC confidence scoring, state matrix enumeration, and JP/VI/EN annotation handling.

Step 1: Frame Classification

Before extracting, classify the frame type:

Frame type	AC emphasis
Form	Validation, empty state, error state, submit success
List/Table	Empty state, loading, pagination, sort/filter
Modal	Open/close trigger, backdrop dismiss, keyboard escape
Page	Navigation, deep-link, breadcrumb, 404
Dashboard	Data-loaded, empty, loading, refresh

Step 2: Node Tree Extraction

Use Figma MCP to read node tree. For each interactive component:

1. Identify base state (what's designed)
2. Enumerate sibling variants (other states in the component set)
3. Flag gaps (states with no variant = must ask)

Step 3: Annotation Parsing

• Extract verbatim and store in source_refs
• Translate to EN for criterion fields
• If annotation contains 仮/tạm/tentative → confidence ≤ 0.5

Step 4: AC Generation

Given [condition],
When [action],
Then [expected result].

Assign confidence, category (behavior/display/validation/navigation/accessibility/performance/security), priority (must/should/could).

Step 5: State Matrix

[
  {
    "element": "Login Button",
    "states": [
      { "name": "default",  "designed": true,  "gap": false },
      { "name": "loading",  "designed": false, "gap": true  },
      { "name": "disabled", "designed": true,  "gap": false },
      { "name": "error",    "designed": false, "gap": true  }
    ]
  }
]

Gap = open_question with priority: "important" (or "blocker" if in a must path).

Step 6: Open Questions

Blockers: validation rules not shown, API endpoints not specified, navigation targets ambiguous, security requirements unclear.

Output Contract

Produce an intent-package for contracts/intent-package.schema.json. Required fields are artifact_type, artifact_version, task_id, trace_id, source_type, clarified_intent, acceptance_criteria, open_questions, generated_at, generated_by, and generated_by_model. For this skill under kopi-figspec, use artifact_type: "intent_package", source_type: "figma_design", and generated_by: "kopi-figspec".

Confidence Reference

Confidence	Meaning
0.9-1.0	Explicit in design, no ambiguity
0.7-0.8	Inferred from pattern, standard behavior
0.5-0.6	Partially shown, annotation helps
0.3-0.4	Mostly guessed — add open_question
< 0.3	Do not generate AC — add blocker question