# Figma-to-Component Pipeline (v5.0.0)

End-to-end guide for generating production-ready UI components from Figma designs through the multi-agent pipeline. Covers iOS (SwiftUI) and Android (Jetpack Compose) with the same workflow shape.

> Note: Component and Figma-to-code skills are no longer bundled in this repo. Phase 3 dispatches component work to the per-stack marketplace plugins (`ai-ios-toolkit` / `ai-android-toolkit` in the `multi-agent-plugins` marketplace) via the Skill tool. The workflow, subphases, and skill names described below are what those plugin skills run internally, not pipeline-bundled code. The 3-tier Figma design-access fallback still governs the analysis phase in this repo.

## What you get

- **One command** - `/multi-agent <figma-url-or-issue>` - produces a complete component: Configuration + View + Modifiers + Preview + README + three layers of tests + Code Connect + wiki doc.
- **Platform-agnostic orchestration** - classification happens once in Phase 0; the orchestrator picks the right code generator for iOS or Android based on `figmaConfig.project.platform`.
- **Multi-repo aware** - components span multiple repos (tokens in `common`, view in `components`, docs in `wiki`). The orchestrator sequences writes correctly.
- **Non-blocking side effects** - wiki generation + Jira sync run as augmentations; failures log and Phase 7 continues.
- **Cross-cutting integration skills** - Phase 3D detects content patterns (`figma-form-integration`, `figma-price-integration`, `figma-ui-patterns`) and interaction patterns (`figma-navigation`, `figma-overlays`, `figma-bottom-sheets`) and dispatches the matching skill. All are **native-SwiftUI-first**; a project's own navigation/overlay/sheet system is used only when `figmaConfig.ui.{navigationSystem,overlaySystem,sheetSystem}` declares one (absent → stock SwiftUI: `NavigationStack`, `.alert`/`.sheet(item:)`, `.presentationDetents`). Generic across SwiftUI codebases.
- **Evolve an existing component** - `figma-evolve-component` reconciles a shipped component against current Figma (drift-heal) and additively extends it for a new need, behind a mandatory human gate - distinct from a fresh build, `figma-mend` (rebuild), and `figma-fix` (review bug).

## How it runs

When multi-agent Phase 0 classifies a task as `component` (Figma URL in description, or figma-driven instruction path), Phase 3 delegates the entire phase to the enabled `ai-<platform>-toolkit` marketplace plugin's component skill (`create-component`, fallback `create-ui-component`) via the Skill tool. Component skills live in the plugin marketplace, not the pipeline. The dispatch layer records a coarse component-build row in `state.phases["3"].subphases[]` - multi-agent's phase-tracker reads that array with no special case. The subphase list below describes the flow the plugin skill runs internally.

### Internal phase order

```
3.0  init               - node-id parse, registry lookup, worktree confirm
3.1  gather             - Figma API / MCP fetch, variant properties, token extraction
3.2a testing identifiers - semantic tags (platform-agnostic)
3.2b localisation        - string keys → common repo
3.2c accessibility       - a11y metadata; platform-aware output
3.2d analytics           - event keys
3.3  token mapping       - Figma values → design token symbols
3.4a Configuration       - pure value type (SwiftUI struct / Compose @Immutable data class)
3.4b View                - SwiftUI body / @Composable fun
3.4c Docs                - FIGMA.md (iOS) / README.md (Android)
3.4d Preview             - variant grid
3.4e Modifiers           - fluent API
3.5a structural tests    - ViewInspector / Compose Testing
3.5b snapshot tests      - SnapshotTesting / Paparazzi
3.5c unit tests          - configuration semantics + behavioural
3.6  Code Connect        - .figma.swift / .figma.kt registration
3.7  wiki                - 4-adapter dispatch (submodule / in-repo / github-wiki / separate-repo)
3.8  cleanup             - artifact pruning, state finalize
```

Each subphase emits a `→ <verb> <object>` progress line per `refs/progress-contract.md`; multi-agent's phase-tracker renders them inline under the Phase 3 row.

## Configuration

Per-project config lives at `~/.claude/projects/{slug}/figma-config.json` (schema: `pipeline/schemas/figma-project-config.schema.json` v2.0.0). Never commit this file.

Minimum viable config:

```json
{
  "schemaVersion": "2.0.0",
  "project":  { "slug": "my-app", "platform": "ios" },
  "figma":    { "fileKey": "abc", "patKeychainKey": "Figma_Access_Token" },
  "github":   { "repo": "owner/repo" },
  "jira":     { "baseUrl": "https://jira.example.com", "projectKey": "PROJ" },
  "repos": {
    "main":       { "path": "." },
    "components": { "path": "Packages/components" },
    "common":     { "path": "Packages/common" },
    "wiki":       { "path": "Packages/wiki" }
  },
  "build": {
    "xcodeproj": "MyApp.xcodeproj",
    "scheme":    "MyApp-Dev"
  },
  "wiki": { "enabled": true, "mode": "in-repo" }
}
```

Android projects swap the `build` section to `{ "gradleModule": ":components:button", "variant": "debug" }` and set `project.platform` to `"android"`.

**Optional `ui` block - UI interaction systems.** Consumed by the `figma-navigation` / `figma-overlays` / `figma-bottom-sheets` skills and Phase 4 review. Omit it (or set `mode: "native"`) and the pipeline generates stock SwiftUI (`NavigationStack`, `.alert`/`.sheet(item:)`, `.sheet`+`presentationDetents`). Set `mode: "custom"` to route to a project-supplied system by type name:

```json
"ui": {
  "navigationSystem": { "mode": "custom", "router": "AppRouter", "routeEnum": "AppRoute", "sceneType": "SceneContent" },
  "overlaySystem":    { "mode": "custom", "center": "OverlayCenter" },
  "sheetSystem":      { "mode": "custom", "brandedModifier": "bottomSheet", "detentType": "SheetDetentType" }
}
```

## The issue → Jira → wiki triad

When a GitHub issue triggers the pipeline and has no Jira link:

1. Phase 0 Step 1 applies the `autoJiraFromGithubIssue` policy (`ask` | `always` | `never`, default `ask`). Autopilot forces `ask` to `always`.
2. If create path: Jira ticket inherits title/body/labels; GitHub issue body gets a `Jira: [KEY](url)` link patch.
3. Phase 7 Step 3.5 runs component wiki capture.
4. Phase 7 posts a humanizer'd wiki summary back to the linked Jira (`wikiToJiraComment`, default `true`).

Full contract: [`pipeline/multi-agent-refs/issue-jira-triad.md`](../pipeline/multi-agent-refs/issue-jira-triad.md).

## Wiki modes (pick one per project)

| Mode | Path layout | Push semantics |
|---|---|---|
| `submodule` | `{repos.wiki.path}/FigmaComponents/{Category}/{Name}/{Name}.md` | Commit into submodule's branch, push, update parent repo's pointer |
| `in-repo` | `{repos.components.path}/.wiki/components/{Category}/{Name}.md` | No push - ships with the component commit in Phase 6 |
| `github-wiki` | `{owner}/{repo}.wiki.git/{Category}/{Name}.md` | Clone the `.wiki.git`, commit, push |
| `separate-repo` | Remote repo's configured branch | Clone to cache, commit, push |

Full contract: [`pipeline/multi-agent-refs/wiki-capture.md`](../pipeline/multi-agent-refs/wiki-capture.md).

## Preferences

Global settings that affect the figma pipeline:

| key | type | default | controls |
|---|---|---|---|
| `promptLanguage` | `en` / `tr` | `en` | Interactive prompt language (pickers, Phase 5/6 confirmations) |
| `outputLanguage` | `en` / `tr` | `en` | Assistant's explanations / status / reports (independent of `promptLanguage`; external payloads stay English) |
| `progressVerbosity` | `quiet` / `normal` / `verbose` | `normal` | Progress-line emission level |
| `wikiDefault` | bool | `true` | Phase 7 wiki auto-yes under autopilot |
| `autoJiraFromGithubIssue` | `ask` / `always` / `never` | `ask` | Phase 0 Jira auto-create policy |
| `wikiToJiraComment` | bool | `true` | Post wiki summary to linked Jira issue |
| `confluenceDefault` | bool | `false` | Phase 7 Confluence auto-yes |
| `jiraCommentDefault` | bool | `true` | Phase 7 test-scenarios Jira comment auto-yes |

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| Phase 3 halts with "plugin not enabled" | The `ai-<platform>-toolkit` plugin is not enabled in this repo | Enable it in the repo's `.claude/settings.local.json` (`"ai-ios-toolkit@<marketplace>": true`) and reload the session |
| `multi-agent:create-component` not found | Marketplace not installed / plugin disabled | Install the marketplace and enable the platform toolkit; dispatch tries `create-component` then `create-ui-component` |
| Wiki adapter failure | Remote unreachable (separate-repo mode) | Adapter caches pending output; next run retries. Non-blocking - Phase 7 continues. |
| Jira auto-create hits 5xx | Transient Jira outage | Non-blocking - pipeline continues without link. User can run `/multi-agent:channels` post-hoc to add it. |
| Android gradle unresolved | `figmaConfig.build.gradleModule` not set | Populate the config; halt is intentional (no guessing) |

## Further reading

- [`pipeline/multi-agent-refs/component-dispatch.md`](../pipeline/multi-agent-refs/component-dispatch.md) - Phase 3 delegation contract.
- [`pipeline/multi-agent-refs/wiki-capture.md`](../pipeline/multi-agent-refs/wiki-capture.md) - Phase 7 wiki contract.
- [`pipeline/multi-agent-refs/issue-jira-triad.md`](../pipeline/multi-agent-refs/issue-jira-triad.md) - issue → jira → wiki triad contract.
- [`pipeline/multi-agent-refs/progress-contract.md`](../pipeline/multi-agent-refs/progress-contract.md) - live progress-line emission contract.
- [`pipeline/multi-agent-refs/cross-cli-contract.md`](../pipeline/multi-agent-refs/cross-cli-contract.md) - Claude ↔ Copilot CLI parity.