@mmerterden/multi-agent-pipeline 11.1.0 → 11.3.0

package/pipeline/skills/figma-common/figma-mend/SKILL.md

@@ -1,331 +0,0 @@
----
-name: figma-mend
-description: Re-implements discarded components from scratch using the figma-to-swiftui workflow, preserving old implementation as complementary reference for animations, domain logic, and UI refinements. Cleans up old files after completion.
-user-invocable: true
-argument-hint: <figma-url> [--name ComponentName] | cleanup | status
-allowed-tools: Task, Read, Glob, Grep, Bash, Write, Edit, AskUserQuestion
-status: wip-v5
-sourced-from: upstream/figma-mend
----
-
-# /figma-mend  -  Re-implement Discarded Components
-
-This skill wraps the full `figma-to-swiftui` workflow (Phases 0-8) with two additions:
-1. **Pre-flight**: Locates old component in `Discarded/`, catalogs all its files
-2. **Cleanup**: Deletes old files after successful re-implementation
-
-All phase instructions, scripts, and references come from `.instructions/figma/figma-to-swiftui/`. Nothing is duplicated.
-
----
-
-## Parse Arguments
-
-`$ARGUMENTS` determines the mode:
-
-| Input | Mode | Action |
-|-------|------|--------|
-| `https://www.figma.com/design/...` | **Start** | Pre-flight → Phase 0-8 → Cleanup |
-| URL + `--name ComponentName` | **Start** | Same, with explicit name override |
-| `phase-0` through `phase-8` | **Resume** | Read mend-context.json, dispatch with old file injection |
-| `cleanup` | **Cleanup** | Delete old files only (manual invocation) |
-| `status` | **Status** | Read IMPLEMENTATION_HISTORY.md + mend-context.json |
-
-### URL Parsing
-
-Same as figma-to-swiftui: extract `fileKey` and `nodeId`, convert `-` to `:` in node-id.
-
----
-
-## Pre-Flight Phase (orchestrator-level  -  no subagent)
-
-Run BEFORE Phase 0. Uses Grep/Glob/Bash directly in the main orchestrator.
-
-### PRE-1: LOCATE_OLD_COMPONENT
-
-Search for the old component in `Discarded/` using these strategies in order:
-
-```bash
-UICOMP="{repos.components.path}/Sources/UIComponents"
-
-# 1. By node ID in FIGMA.md
-grep -rl "{nodeId}" --include="FIGMA.md" "$UICOMP/Discarded/"
-
-# 2. By node ID (dash format) in FIGMA.md
-grep -rl "{nodeIdDash}" --include="FIGMA.md" "$UICOMP/Discarded/"
-
-# 3. By node ID in .figma.swift
-grep -rl "{nodeId}" --include="*.figma.swift" "$UICOMP/Discarded/"
-
-# 4. By --name argument (directory match)
-find "$UICOMP/Discarded/" -type d -name "{nameOverride}"
-```
-
-If no match → HALT:
-```
-STATUS: HALT | GATE: LOCATE_OLD_COMPONENT
-REASON: No discarded component found for node {nodeId}.
-USER_ACTION_REQUIRED: Verify this component exists in Discarded/ or use /figma-to-swiftui instead.
-```
-
-Extract `oldComponentPath` (directory) and `oldComponentName` (directory name).
-
-### PRE-2: CATALOG_OLD_FILES
-
-Catalog ALL files related to the old component:
-
-```bash
-TESTS="{repos.components.path}/Tests/UIComponentsTests"
-ARTIFACTS="{repos.artifactsRepo}/ImplementationArtifacts"
-
-# Sources (all .swift in old directory)
-find "{oldComponentPath}" -name "*.swift" -type f
-
-# Tests (search by old component name)
-find "$TESTS/Snapshot" -type d -name "{OldComponentName}"
-find "$TESTS/ViewInspector" -type d -name "{OldComponentName}"
-find "$TESTS/Components" -path "*{OldComponentName}*" -name "*.swift"
-
-# Artifacts
-find "$ARTIFACTS/Figma/Components" -type d -name "{OldComponentName}"
-find "$ARTIFACTS/Confluence" -type d -name "{OldComponentName}"
-```
-
-Store as `oldFilesCatalog`:
-- `sources`: list of .swift file paths
-- `codeConnect`: list of .figma.swift paths
-- `documentation`: FIGMA.md path (if exists)
-- `tests.snapshot`: snapshot test directory (if exists)
-- `tests.viewInspector`: viewInspector test directory (if exists)
-- `tests.unit`: unit test files (if exist)
-- `artifacts`: old artifact directory (if exists)
-- `confluence`: old confluence directory (if exists)
-
-### PRE-3: NAME_RESOLUTION
-
-- `oldComponentName` = directory name from PRE-1
-- `newComponentName` = `--name` override if provided, else will be resolved by Phase 0 registry lookup
-- If names differ, record: `"nameChanged": true`
-
-### PRE-4: STORE CONTEXT (deferred)
-
-Hold the catalog in memory. Write `mend-context.json` to `{artifactPath}/` immediately AFTER Phase 0 creates the artifact directory.
-
----
-
-## Phase Execution
-
-Follow the EXACT same execution order as `.instructions/figma/figma-to-swiftui/SKILL.md`:
-
-```
-0 (Init) → 1 (Gather) → 2A → 2B → 2C → 2D → 3 (Analysis) → 4 (Implementation) → 5A → 5B → 5C → 6 (Code Connect) → 7A → 7B → 8 → Cleanup
-```
-
-### Dispatch Table
-
-Use the SAME dispatch table from `.instructions/figma/figma-to-swiftui/SKILL.md`  -  same phases, same models, same turn limits, same tool restrictions, same phase instruction paths. Do NOT read that file  -  the table is reproduced here for reference:
-
-| Phase | Instruction (under figma-to-swiftui/) | Model | Max Turns | Tool Restrictions |
-|-------|---------------------------------------|-------|-----------|-------------------|
-| 0 | `phases/phase-0-init.md` | opus | 30 | No Edit |
-| 1 | `phases/phase-1-gathering.md` + `scripts/phase1-gather.py` | N/A | N/A | Bash only |
-| 2A | `phases/phase-2a-testing-identifiers.md` | opus | 25 | No Edit |
-| 2B | `phases/phase-2b-localization.md` | sonnet | 25 | No Edit |
-| 2C | `phases/phase-2c-accessibility.md` | opus | 25 | No Edit |
-| 2D | `phases/phase-2d-analytics.md` | sonnet | 20 | No Edit, No Bash |
-| 3A | `phases/phase-3a-location.md` | sonnet | 20 | No Edit |
-| 3C | `phases/phase-3c-nested.md` | sonnet | 20 | No Edit |
-| 3D | `phases/phase-3d-patterns.md` | opus | 30 | No Edit |
-| 4A | `phases/phase-4a-configuration.md` | opus | 30 | ALL allowed |
-| 4B | `phases/phase-4b-view.md` | opus | 40 | ALL allowed |
-| 4C | `phases/phase-4c-documentation.md` | sonnet | 20 | ALL allowed |
-| 4D | `phases/phase-4d-preview.md` | sonnet | 20 | ALL allowed |
-| 4E | `phases/phase-4e-modifiers.md` | sonnet | 20 | ALL allowed |
-| 5A | `phases/phase-5a-viewinspector.md` | sonnet | 40 | ALL allowed |
-| 5B | `phases/phase-5b-snapshot.md` | sonnet | 40 | ALL allowed |
-| 5C | `phases/phase-5c-unit.md` | sonnet | 30 | ALL allowed |
-| 6 | `phases/phase-6-code-connect.md` | sonnet | 30 | No Edit |
-| 7A | `phases/phase-7a-confluence-generate.md` | sonnet | 30 | No Edit |
-| 7B | `phases/phase-7b-confluence-upload.md` | sonnet | 15 | No Edit |
-| 8 | `phases/phase-8-cleanup.md` | haiku | 10 | ALL allowed |
-
-### Phase Routing
-
-Use the SAME routing logic from figma-to-swiftui SKILL.md for Phase 2, Phase 3, Phase 4, Phase 5, Phase 6, and Phase 7. Read that file's routing sections when dispatching.
-
-### Dispatch Prompt Modification
-
-The ONLY change from figma-to-swiftui: append this section to every AI subagent dispatch prompt (NOT to scripts):
-
-```
-## Complementary Reference (Old Implementation)
-
-This component is being RE-IMPLEMENTED from Discarded/.
-Old source files (read as reference  -  do NOT copy verbatim):
-{list of relevant old file paths from oldFilesCatalog  -  see injection table below}
-
-Preserve domain-specific patterns if architecturally sound:
-- Animations, transitions, gesture handling
-- UI refinements (feathered edges, gradients, shadows)
-- Domain logic (list handling, data transformation)
-- State management patterns
-- Variant mappings that were manually refined
-
-IMPORTANT: New implementation MUST follow current workflow standards
-(macros, Configuration pattern, design tokens). Use old code ONLY as reference
-for domain logic  -  not as a template for architecture.
-```
-
-### Selective File Injection Table
-
-Each phase receives ONLY the relevant old files to prevent context bloat:
-
-| Phase | Old files to inject |
-|-------|--------------------|
-| 0 | None (standard init) |
-| 1 | None (automated script) |
-| 2A | Old FIGMA.md, old source files |
-| 2B | Old FIGMA.md |
-| 2C | Old FIGMA.md, old source files |
-| 2D | Old FIGMA.md |
-| 3A | None |
-| 3C | Old source files |
-| 3D | Old source files, old modifier files |
-| 3B/3E/3F/3G | None (automated scripts) |
-| 4A | Old Configuration + Model files |
-| 4B | ALL old source files (primary reference phase) |
-| 4C | Old FIGMA.md |
-| 4D | Old source files |
-| 4E | Old modifier files |
-| 5A | Old ViewInspector test files (if exist) |
-| 5B | Old Snapshot test files (if exist) |
-| 5C | Old unit test files (if exist) |
-| 6 | Old .figma.swift file |
-| 7A, 7B | None |
-| 8 | None |
-
-### After Phase 0 Completes
-
-Write `mend-context.json` to `{artifactPath}/`:
-
-```json
-{
-  "mode": "mend",
-  "oldComponentName": "{oldComponentName}",
-  "oldComponentPath": "{oldComponentPath}",
-  "oldFiles": {
-    "sources": ["{path1}", "{path2}"],
-    "codeConnect": ["{path}"],
-    "documentation": "{path}",
-    "tests": {
-      "snapshot": "{dirPath or null}",
-      "viewInspector": "{dirPath or null}",
-      "unit": "{filePath or null}"
-    },
-    "artifacts": "{dirPath or null}",
-    "confluence": "{dirPath or null}"
-  },
-  "nameChanged": false,
-  "newComponentName": "{newComponentName}"
-}
-```
-
----
-
-## Cleanup Phase
-
-Runs automatically after Phase 8, or manually via `/figma-mend cleanup`.
-
-### CLEANUP-1: VERIFY_NEW_IMPLEMENTATION
-
-```bash
-# Check new component exists
-ls {componentLocation}/{ComponentName}.swift
-
-# Check it builds
-xcodebuild build -project {build.xcodeproj} -scheme UIComponents \
-  -destination 'generic/platform=iOS' CODE_SIGNING_ALLOWED=NO -quiet
-```
-
-If new component missing or build fails → HALT. Do NOT delete old files.
-
-### CLEANUP-2: DELETE_OLD_SOURCE
-
-```bash
-rm -rf {oldComponentPath}
-```
-
-Walk up parent directories (max 3 levels) and remove if empty.
-
-### CLEANUP-3: DELETE_OLD_TESTS
-
-For each test directory in `oldFilesCatalog.tests`:
-```bash
-rm -rf {testDir}  # snapshot, viewInspector, unit test directories
-```
-
-Walk up parent directories and remove if empty.
-
-### CLEANUP-4: DELETE_OLD_ARTIFACTS
-
-```bash
-# Old Figma artifacts
-rm -rf {oldFilesCatalog.artifacts}
-
-# Old Confluence artifacts
-rm -rf {oldFilesCatalog.confluence}
-```
-
-### CLEANUP-5: VERIFY_BUILD
-
-```bash
-xcodebuild build -project {build.xcodeproj} -scheme UIComponents \
-  -destination 'generic/platform=iOS' CODE_SIGNING_ALLOWED=NO -quiet
-```
-
-Report result. Old files were in `Discarded/` (excluded from compilation) so deletion should not break anything.
-
-### CLEANUP-6: UPDATE_HISTORY
-
-Append to `{artifactPath}/IMPLEMENTATION_HISTORY.md`:
-
-```markdown
-## Mend Cleanup
-- Old component: {oldComponentName} at {oldComponentPath}
-- Sources deleted: {count} files
-- Tests deleted: {count} files/directories
-- Artifacts deleted: {count} directories
-- Build verified: yes/no
-- Date: {DD.MM.YYYY}
-```
-
----
-
-## Resume Mode
-
-When `$ARGUMENTS` is `phase-N`:
-
-1. Search for `mend-context.json` in `ImplementationArtifacts/Figma/Components/`
-2. Read it + IMPLEMENTATION_HISTORY.md to restore: oldComponentPath, oldFiles, componentName, fileKey, nodeId, artifactPath, componentLocation
-3. Dispatch the requested phase with old file injection from the catalog
-
-If `mend-context.json` not found → HALT. Run the full workflow from a Figma URL instead.
-
----
-
-## Cleanup Mode
-
-When `$ARGUMENTS` is `cleanup`:
-
-1. Search for `mend-context.json` in `ImplementationArtifacts/Figma/Components/`
-2. Read it to get old file catalog
-3. Read IMPLEMENTATION_HISTORY.md to get componentLocation and componentName
-4. Execute Cleanup Phase (CLEANUP-1 through CLEANUP-6)
-
----
-
-## Status Mode
-
-When `$ARGUMENTS` is `status`:
-
-1. Search for all `mend-context.json` files in `ImplementationArtifacts/Figma/Components/`
-2. For each, display: component name, old → new name, current phase, cleanup status

package/pipeline/skills/figma-common/figma-navigation/SKILL.md

@@ -1,156 +0,0 @@
----
-name: figma-navigation
-description: "Navigation pattern integration for Figma-to-UI components (iOS SwiftUI + Android Jetpack Compose). Guides how a component reaches other screens, tabs, or deep links without coupling to a router — headless screens that emit a typed Output/event, native NavigationStack (iOS) / Navigation Compose (Android) by default, an optional project-supplied navigation system when figma-config declares one. Reach for this when a design embeds a tab bar, nav bar / back button, a push/detail affordance, or a deep-link entry point."
-user-invocable: true
-allowed-tools: Read, Glob, Grep
-status: wip-v5
-sourced-from: upstream/figma-navigation
----
-
-# /figma-navigation  -  Navigation Pattern Integration
-
-## Purpose
-
-Consumed by the figma-to-swiftui pipeline (Phase 3D pattern detection, Phase 4B view implementation) and available for ad-hoc/vibe-coding, this skill defines how a component participates in navigation **without owning routing**. It is the navigation counterpart of `/figma-form-integration` and `/figma-price-integration`: a cross-cutting integration with a **native-SwiftUI default** and a **config-driven hook** for projects that ship their own navigation system.
-
-**Generic by design.** Nothing here assumes a specific app. The default is stock SwiftUI (`NavigationStack`, `navigationDestination`, `.toolbar`, `.sheet`). If the target project declares a custom navigation system in its `figma-config.json` (`ui.navigationSystem`), this skill routes to that system's types by name instead — same rules, project-specific vocabulary.
-
----
-
-## Strict Rules (non-negotiable)
-
-1. **A component never names a route, a sibling screen, or a router.** A component/screen takes its arrival data as init params and emits intent through a typed **`Output`** closure (`onSelect`, `onSubmit`, `output:`). The *caller* (scene/coordinator/parent) maps each output to a navigation edge. This keeps the component reusable and testable in isolation.
-2. **No navigation side effects inside a component body.** No `NavigationLink(destination:)` hardcoding a concrete next screen, no router calls, no global singletons touched from `body`. Navigation is a caller concern expressed via the emitted output.
-3. **Selection/tab state is observable data, not an imperative bridge.** A selected tab/section is a bound value (`@Binding`/observable), written by the caller; the component reflects it. A selection set before the container mounts is simply rendered on appear  -  no cold-start race.
-4. **Deep links reduce to state and never crash.** A URL parses to a plan/value; malformed input is dropped (logged, no trap). The component is never the deep-link parser  -  it only exposes the entry state the parser can set.
-5. **Native SwiftUI is the default; a custom system is opt-in via config.** Do NOT invent a bespoke router for a project that hasn't asked for one. Only use custom navigation types when `ui.navigationSystem.mode == "custom"` is set in `figma-config.json`.
-
----
-
-## When to Invoke This Skill
-
-Invoke when ANY of these are detected in the design or task:
-
-1. **Phase 3D  -  navigation sub-component / affordance:** a nested instance of a navigation-capable design element:
-   - Tab bar / segmented section switcher that changes the top-level view
-   - Navigation bar / header with a **back button** or close affordance
-   - A row/card whose variant implies a **push/detail** affordance (chevron, "Detaylar", disclosure)
-   - A link/button whose label implies leaving the screen ("Devam", "Tümünü gör")
-   - A deep-link entry point (the design is a landing surface reached by URL)
-2. **Phase 4B  -  View:** the view renders a back button, tab strip, or a control that should navigate.
-3. **Ad-hoc:** wiring a screen's push/pop/tab/deep-link flow outside the full pipeline.
-
-**Not navigation (false-positive guards):**
-- A segmented control that filters in-place (no screen change) → plain `Binding<Enum>`, not navigation.
-- A button that submits a form → that's `/figma-form-integration`; the *result* may navigate, but the control is a form action.
-- A modal card of data / a toast / a loading HUD → `/figma-overlays`. A bottom sheet surface → `/figma-bottom-sheets`.
-
----
-
-## Native-first architecture (default)
-
-```
-Parent / Scene (caller)
-    |  owns NavigationStack(path:) or tab Binding, maps Output → edge
-    v
-ComponentView
-    |  init(arrivalData…, output: @escaping (Output) -> Void)
-    |  emits .selected(id) / .continue / .back  -  never routes
-    v
-(caller) path.append(route)  |  selectedTab = .x  |  present(.sheet)
-```
-
-- **Push/pop within a flow:** caller owns `NavigationStack(path:)`; component emits `Output`; caller appends a `Hashable` route; `navigationDestination(for:)` renders it.
-- **Back button:** prefer the system back button. A custom header back affordance emits `.back` (or calls `dismiss`); it renders only when there is something to pop (depth > 0 / `isPresented`).
-- **Tabs:** `TabView(selection:)` bound to an observable selection the caller owns; the component reads/writes the binding, never a global.
-- **Deep links:** caller parses URL → a `Hashable` route / tab selection and applies it to the same path/selection state the UI already uses. Component only exposes the entry state.
-- **Modal presentation of another screen:** `.sheet(item:)` / `.fullScreenCover(item:)` driven by caller state (data-driven, no `AnyView`). A *bottom sheet surface* is `/figma-bottom-sheets`; an *alert/data modal card* is `/figma-overlays`.
-
-Design tokens (spacing, colors, typography) follow `reference/ui` + the project's figma-config token patterns  -  never raw literals.
-
-## Config hook  -  project-supplied navigation system
-
-When `figma-config.json` declares:
-```jsonc
-"ui": { "navigationSystem": {
-  "mode": "custom",
-  "router": "AppRouter",            // type that dispatches routes
-  "routeEnum": "AppRoute",          // exhaustive cross-surface route enum
-  "sceneType": "SceneContent",      // headless screen container (optional)
-  "navigatorProtocol": "NavigatorProtocol"  // DI'd selection/present API (optional)
-}}
-```
-then apply the SAME rules, but express them in the project's vocabulary resolved from config (do NOT hardcode the names below  -  read them from `ui.navigationSystem`):
-
-- Wrap screen content in `{sceneType}` (headless container) instead of a bare `NavigationStack` child, when provided.
-- Screens still emit a typed `Output`; the domain coordinator maps outputs to the project's route type (`{routeEnum}`) and the `{router}` dispatches.
-- Cross-surface jumps go through the DI'd `{navigatorProtocol}` (`selectTab`, `present`), never by importing a sibling domain.
-- Deep links build the project's `{routeEnum}` case and hand it to the router's deep-link entry.
-
-If `mode` is absent or `native`, use the native-first section above. Resolve types via `tools/resource-utility` / repo grep only when the config points at real files.
-
-## Android (Jetpack Compose)
-
-Same rules, Compose vocabulary. Default is stock **Navigation Compose**; a project system is used only when `ui.navigationSystem.mode == "custom"`.
-
-- **Push/pop within a flow:** caller owns `NavHostController` + `NavHost`; the composable emits events via lambdas (`onSelect: (Id) -> Unit`), never calls `navController.navigate(...)` itself. Prefer type-safe routes (`@Serializable` route objects, `navigation-compose` 2.8+).
-- **Back:** system back / `navController.popBackStack()`; intercept only with `BackHandler { }` when the screen owns the gesture. A custom top-bar back emits `onBack` / calls the caller's pop.
-- **Tabs:** state-hoisted selection (`var selected by rememberSaveable`) bound to a `NavigationBar`; the composable reads/writes the hoisted state, never a global.
-- **Deep links:** `navDeepLink { uriPattern = ... }` on the destination, or the caller parses the URI → route and applies it to the same `NavController`. The composable never parses URIs.
-- **Present another screen modally:** caller-owned `var showX by remember` → `Dialog`/`ModalBottomSheet` (see `/figma-bottom-sheets`).
-
-**Config hook:** `ui.navigationSystem.mode == "custom"` → use the project's `{router}` / `{routeEnum}` (and a screen container if `{sceneType}` is set) resolved from config; cross-graph jumps go through the DI'd `{navigatorProtocol}`.
-
-Tokens/theme via `MaterialTheme` + the project's figma-config token patterns.
-
----
-
-## Integration with Phase 3D
-
-When Phase 3D detects a navigation affordance, record it in `04b_component_architecture.md` and classify it as an **Output**, not a route:
-
-```markdown
-## Navigation
-| Affordance | Emits | Caller maps to |
-|---|---|---|
-| Back button (header) | `.back` closure / dismiss | pop current stack |
-| Row chevron ("Detaylar") | `.selected(id)` | push detail route |
-| Tab strip | `selection: Binding<Tab>` | caller-owned tab state |
-| Deep-link landing | entry `route`/`tab` param | parser sets caller state |
-```
-
-Property classification addition:
-
-| Classification | When | Swift Pattern |
-|---|---|---|
-| Navigation output | Component has a push/select/back affordance | `output: (Output) -> Void` / `onSelect: (ID) -> Void` closure on the View |
-| Tab/selection binding | Component switches top-level content | `selection: Binding<SomeTab>` |
-| Deep-link entry | Component is a URL landing surface | plain entry `route`/`tab` param on the View/Configuration |
-
-The affordance's **label/icon copy is static Configuration content** (localized), exactly like other copy  -  only the *intent* is an Output closure.
-
-## Integration with Phase 4B
-
-- Never hardcode `NavigationLink(destination: ConcreteScreen())` inside a reusable component  -  emit the Output.
-- Prefer the system back button; a custom back affordance calls `@Environment(\.dismiss)` or emits `.back`.
-- Bind tab/selection via the caller-owned binding; never a global.
-- If `ui.navigationSystem.mode == custom`, wrap in `{sceneType}` and route via `{router}`/`{routeEnum}` per config.
-- Verify by building + running on the simulator (`reference/build-and-test` / `figma-to-component` Phase 5): the transition happens, the back button appears only after a push, deep links land on the right surface.
-
----
-
-## When NOT to Use Navigation Integration
-- In-place filters/segmented state that never changes screen → `Binding<Enum>`.
-- Form submission → `/figma-form-integration` (the *result* may navigate; the control is a form action).
-- Toast / loading / alert / data modal → `/figma-overlays`. Bottom-sheet surface → `/figma-bottom-sheets`.
-
-## Checklist  -  Before Leaving the Skill
-```
-[ ] Component emits a typed Output for every navigation affordance  -  no hardcoded routes
-[ ] Back uses system back / dismiss / .back output; renders only when poppable
-[ ] Tab/selection is a caller-owned binding, not a global
-[ ] Deep-link entry is plain state the caller's parser can set (component never parses URLs)
-[ ] Default is native SwiftUI (NavigationStack/navigationDestination/TabView/.sheet(item:))
-[ ] Custom system used ONLY when figma-config ui.navigationSystem.mode == custom (names from config)
-[ ] Labels/icons are localized Configuration copy; only intent is a closure
-```

package/pipeline/skills/figma-common/figma-overlays/SKILL.md

@@ -1,142 +0,0 @@
----
-name: figma-overlays
-description: "Overlay pattern integration for Figma-to-UI components (iOS SwiftUI + Android Jetpack Compose) — toasts/snackbars, blocking loading HUDs, alert dialogs, and data-driven modal cards presented from anywhere without the component owning presentation. Native by default (SwiftUI .alert/.confirmationDialog/.overlay + ref-counted loading + .sheet; Compose Snackbar/AlertDialog/Dialog + state-driven loading); an optional project-supplied overlay center when figma-config declares one. Reach for this when a design shows a toast/snackbar, a spinner/HUD, an alert, or a modal card, or when giving post-action feedback (saved/deleted/error) from a view model."
-user-invocable: true
-allowed-tools: Read, Glob, Grep
-status: wip-v5
-sourced-from: upstream/figma-overlays
----
-
-# /figma-overlays  -  Overlay Pattern Integration
-
-## Purpose
-
-Consumed by the figma-to-swiftui pipeline (Phase 3D detection, Phase 4B view) and available ad-hoc, this skill defines how transient/blocking UI is presented **without a component owning the presentation surface**. Overlays counterpart of `/figma-form-integration` / `/figma-price-integration`: native-SwiftUI default + a config-driven hook for projects that ship an overlay center.
-
-Four channels: **toast** (transient, non-blocking), **loading** (blocking HUD), **alert** (blocking dialog), **modal** (data-driven card). Rich/interactive content is a local view-modifier, never routed as an erased view.
-
-**Generic by design.** Default is stock SwiftUI. If `figma-config.json` declares `ui.overlaySystem`, route through that DI'd center by name instead  -  same rules, project vocabulary.
-
----
-
-## Strict Rules (non-negotiable)
-
-1. **A component does not present its own app-level overlays.** A reusable component emits an intent (`onSaved`, `output: .removed`) or exposes state; the **caller** (scene/VM/coordinator) shows the toast/alert/modal. A component owning a global toast/alert makes it un-reusable and double-fires when composed.
-2. **Overlay requests are pure data, not erased views.** Toast/alert/modal content is a value (title, style, actions), mapped to a design-system view at the host. **Never** pass `AnyView` through an overlay center. Rich/interactive content uses a **local** `.modal/.sheet { }` view modifier declared at the owning view.
-3. **Loading is ref-counted with a min-show.** Pair every begin with an end (or use a `withLoading { }` wrapper); enforce a ~300ms minimum visible so it doesn't flash. Never leave a HUD un-ended on an error path.
-4. **Presentable from non-view code.** Post-action feedback originates in a VM/coordinator; the overlay API must be callable there (a DI'd center or a bound state), not only from SwiftUI `body`.
-5. **Native SwiftUI is the default; a custom center is opt-in via config.** Only use a project overlay center when `ui.overlaySystem.mode == "custom"`.
-
----
-
-## When to Invoke This Skill
-
-1. **Phase 3D  -  overlay affordance/pattern:** the design shows a toast/snackbar, a spinner/HUD or blocking dim, an alert dialog (1-3 buttons), or a data-driven modal card; or a component action needs post-action feedback.
-2. **Phase 4B  -  View:** the view triggers feedback after an action, or renders a dim/HUD/alert/modal.
-3. **Ad-hoc:** "show a confirmation", "flash a message", "block the screen while loading", "pop a dialog", "feedback after save".
-
-**Not an overlay (guards):**
-- A bottom sheet / half-sheet / drawer *surface* → `/figma-bottom-sheets`.
-- Screen-to-screen routing / tabs / deep links → `/figma-navigation`.
-- An inline banner that is part of the component's own layout (not app-level, not dismissible-over-content) → plain component content.
-
----
-
-## Native-first architecture (default)
-
-```
-Scene / VM (caller)
-    |  owns overlay state, calls after an action
-    v
-SwiftUI presentation modifiers on the scene root:
-  toast    → .overlay(alignment:) of a transient message view + auto-dismiss task
-  loading  → a ref-counted @Observable LoadingState → dim + ProgressView, min-show
-  alert    → .alert(_:isPresented:) / .confirmationDialog (roles: cancel/destructive/default)
-  modal    → .sheet(item:) driven by an Identifiable data value → host maps data → card
-  rich     → local .sheet/.fullScreenCover { InteractiveContent() } at the owning view
-```
-
-- **Toast:** newest-replaces (single visible), `hug`≈2s / `fill`≈5s auto-dismiss; anchor above any bottom bar. Model as a small value + an `.overlay`.
-- **Loading:** an observable counter (`begin`/`end`, `withLoading`) with min-show; dim + `ProgressView`.
-- **Alert:** native `.alert` / `.confirmationDialog` with proper button roles; data-driven.
-- **Modal card:** `.sheet(item:)` with an `Identifiable` request value; the host builds the design-system card from data (no `AnyView`).
-- **Over a bottom sheet:** mount the toast/HUD host on the sheet's own content (a root-level host sits *behind* a presented sheet).
-
-Tokens per `reference/ui` + figma-config token patterns; no literals.
-
-## Config hook  -  project-supplied overlay center
-
-When `figma-config.json` declares:
-```jsonc
-"ui": { "overlaySystem": {
-  "mode": "custom",
-  "center": "OverlayCenter",       // DI'd protocol callable from VM/coordinator
-  "surfaces": ["root", "currentScene"]  // independent render surfaces (optional)
-}}
-```
-apply the SAME rules via the project's center (names from config, do NOT hardcode):
-- Inject `any {center}` (with a Noop default for previews/tests); call `.toast/.withLoading/.alert/.modal` from the VM.
-- Keep the center **UI-framework-free**: it stores data; a host maps data → design-system component. If you reach for `AnyView`, use a local `.modal { }` view modifier instead.
-- Choose the surface from the caller's context (`root` vs `currentScene`); over-a-sheet fires on `currentScene`.
-
-If `mode` is absent or `native`, use the native-first section.
-
-## Android (Jetpack Compose)
-
-Same rules, Compose vocabulary. Default is stock Compose/Material3; a project overlay system is used only when `ui.overlaySystem.mode == "custom"`.
-
-- **Toast/snackbar:** `SnackbarHostState` hoisted at a `Scaffold(snackbarHost = { SnackbarHost(state) })`; the composable emits an intent and the caller calls `snackbarHostState.showSnackbar(...)` from a coroutine. (Prefer an in-app `Snackbar` over the platform `android.widget.Toast`.)
-- **Loading:** a state-driven overlay — `if (uiState.isLoading) Box(Modifier.fillMaxSize()) { CircularProgressIndicator() }`; back the flag with a ref-count in the ViewModel + a min-show so it doesn't flash.
-- **Alert:** `AlertDialog(onDismissRequest, confirmButton, dismissButton)` — data-driven from state, proper confirm/dismiss roles.
-- **Modal card:** data-driven `Dialog { }` / `ModalBottomSheet { }` where a host maps the request value → a Material component (no arbitrary erased content passed through a "center").
-- **From a ViewModel:** expose events (`SharedFlow`/`Channel`) or state; the composable collects and shows the overlay. Keep the VM UI-framework-free.
-
-**Config hook:** `ui.overlaySystem.mode == "custom"` → inject/collect the project's `{center}` and render its Material host; keep it data-only.
-
-Rich/interactive content stays a local composable (`Dialog`/`ModalBottomSheet` declared at the owning composable), not routed through a center.
-
----
-
-## Integration with Phase 3D
-
-Record overlays in `04b_component_architecture.md` as **caller intents**, not component-owned UI:
-
-```markdown
-## Overlays
-| Trigger | Channel | Owner | Note |
-|---|---|---|---|
-| Row "Sil" tapped | alert (confirm) | caller | component emits .removeRequested(id) |
-| Save succeeded | toast (success) | caller VM | component emits .saved |
-| Async fetch | loading HUD | caller VM | withLoading around the call |
-```
-
-Property classification addition:
-
-| Classification | When | Swift Pattern |
-|---|---|---|
-| Overlay intent | Component action needs app-level feedback/confirm | `output`/`onX` closure on the View (caller shows the overlay) |
-| Local rich modal | Interactive content owned by this view | local `.sheet/.modal { }` at the owning view, caller state |
-
-## Integration with Phase 4B
-- Never present an app-level toast/alert/modal from inside a reusable component  -  emit the intent.
-- Use native `.alert`/`.confirmationDialog` for 1-3 button dialogs; `.sheet(item:)` for data modal cards.
-- Ref-count loading; guarantee `end` on all paths; min-show to avoid flash.
-- If `ui.overlaySystem.mode == custom`, inject and call `{center}`; keep it data-only.
-- Verify on the simulator: toast above the bottom bar, HUD min-show, alert roles, data modal, overlays over a sheet.
-
----
-
-## When NOT to Use Overlay Integration
-- Bottom-sheet surface → `/figma-bottom-sheets`. Routing/tabs/deep links → `/figma-navigation`.
-- A static inline banner that is part of the component layout → plain content.
-- Form validation error shown inline on a field → `/figma-form-integration` (field state), not an overlay.
-
-## Checklist  -  Before Leaving the Skill
-```
-[ ] Reusable component emits intent/state; caller owns the overlay (no self-presentation)
-[ ] Overlay content is data, not AnyView; rich content uses a local .sheet/.modal { }
-[ ] Loading is ref-counted with min-show; end guaranteed on error paths
-[ ] Alerts use native roles (cancel/destructive/default) unless a design card is required
-[ ] Default native SwiftUI; custom center only when figma-config ui.overlaySystem.mode == custom
-[ ] Over-a-sheet feedback mounts on the sheet's content surface, not the root
-```