@mmerterden/multi-agent-pipeline 10.0.6 → 10.3.0

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

@@ -0,0 +1,142 @@
+---
+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
+```

package/pipeline/skills/figma-common/figma-ui-patterns/SKILL.md

@@ -94,6 +94,7 @@ Bullet list of other slugs in this skill (or in `figma-price-integration`, `core
 
 | Slug | Pattern | Status |
 |------|---------|--------|
+| `animated-gradient-border` | Snake/halo gradient stroke crawling the perimeter (promo/featured/premium cards)  -  angular-gradient stroke + animatable progress, corner-radius match, Reduce-Motion gate. Native-SwiftUI recipe; uses a project modifier if one ships. | Ready |
 | `carousel-banner` | Auto-advancing paged banner  -  single item visible, swipe/tap paging, `CarouselGroup` indicator, configurable interval + loop + pause-on-interaction. | Ready |
 | `scalloped-vstack` | Scalloped VStack (boarding-pass silhouette)  -  vertical card with semicircular edge cuts + dashed perforation line between segments. `CoreUI.ScallopedVStack`. | Ready |
 

package/pipeline/skills/figma-common/figma-ui-patterns/patterns/animated-gradient-border.md

@@ -0,0 +1,116 @@
+# Animated Gradient Border (Snake / Halo Border)
+
+## When to Use
+
+A component's frame has a stroked border whose color fades around the perimeter as if a **snake / halo of gradient light crawls around the edge** — continuous, looping, usually 2–4pt wide, with a radius matching the host's corner radius. Figma signals: promo banners, premium/featured cards, upsell surfaces, "lit up" states of otherwise calm cards; a spec named "animated / glowing / gradient border" or an endless-loop prototype on the stroke.
+
+**Not** this pattern when:
+- The border is a single, *static* color → `.stroke(...)` / `.overlay(RoundedRectangle().stroke(...))` directly.
+- The gradient is **on the fill**, not the stroke → that's an angular/linear gradient background.
+- It's a **state-transition** pulse (red on error) → `.animation(...)` with color interpolation, not a crawling gradient.
+- The stroke is **dashed/dotted** → different `StrokeStyle`; this pattern draws a solid stroke.
+
+## Minimal API
+
+If the project already ships a gradient-border modifier (some design systems do — check `reference/ui` / the repo), use it and do NOT re-implement the math. Otherwise use this generic modifier shape:
+
+```swift
+view
+    .background(fill)
+    .clipShape(RoundedRectangle(cornerRadius: radius))
+    .animatedGradientBorder(
+        colors: [start.opacity(0.6), middle, end.opacity(0.6)], // faded → solid → faded
+        lineWidth: 2,
+        cornerRadius: radius,          // MUST match the host corner radius
+        isAnimated: !reduceMotion,
+        duration: 3.0
+    )
+```
+
+**Parameter intent:** 3 colors read best (faded→solid→faded); `lineWidth` 1–3pt from tokens; `cornerRadius` must equal the host's; `isAnimated:false` renders a static stroke; `duration` 1.5 urgent / 3 calm / 5+ ambient.
+
+## Technique
+
+A self-contained native-SwiftUI recipe (no external package):
+
+1. **Overlay, don't replace.** Draw the stroke in an `.overlay` of a `RoundedRectangle` so the host keeps its own background/fill.
+2. **Angular gradient stroked along the shape.** `RoundedRectangle(cornerRadius:).stroke(AngularGradient(...), lineWidth:)`. The angular gradient's rotation is driven by an animated angle so the bright spot travels the perimeter.
+3. **Animatable progress 0→1 drives the gradient's `angle`.** Animate the `AngularGradient(angle:)` on a **static** shape — `.degrees(360 * progress)` — so only the bright band travels. Do NOT `.rotationEffect` the stroked shape (that spins the whole rounded-rect). Start in `.onAppear` with `withAnimation(.linear(duration:).repeatForever(autoreverses:false)) { progress = 1 }`.
+4. **Halo shape** = the gradient stop distribution (a bright band with faded shoulders); keep the fade symmetric for the "snake" read.
+5. **Static shortcut.** `isAnimated == false` → render the same stroke frozen (or a single-color stroke).
+
+## Gotchas
+
+1. **Corner-radius mismatch is the #1 bug** — the host `cornerRadius` and the border `cornerRadius` must be equal, or the stroke floats off the rounded path.
+2. **Apply the border after `.background`/`.clipShape`** so it overlays the current bounds and clips to the rounded shape.
+3. **Reduce Motion:** read `@Environment(\.accessibilityReduceMotion)` at the call site and pass `isAnimated: !reduceMotion`. A perpetually animating border must respect it.
+4. **Perf on long lists:** a forever-repeating animation per row costs frames and never pauses off-screen. Measure with Instruments before shipping it on `LazyVStack`/`List` rows.
+5. **`onAppear` restarts on every reappear** — don't rely on animation state surviving a re-mount.
+6. **`lineWidth` ≥ `cornerRadius`** produces blobby corners; keep `lineWidth < cornerRadius` for clean corners.
+7. **Use semantic tokens, not raw hex**, so the border follows light/dark + theme (`reference/ui` + figma-config token patterns).
+
+## Reference Snippet
+
+Drop-in preview — pure SwiftUI, no external dependency:
+
+```swift
+import SwiftUI
+
+struct AnimatedGradientBorder: ViewModifier {
+    var colors: [Color]
+    var lineWidth: CGFloat = 2
+    var cornerRadius: CGFloat = 12
+    var isAnimated: Bool = true
+    var duration: Double = 3.0
+    @State private var progress: CGFloat = 0
+
+    func body(content: Content) -> some View {
+        // Animate the AngularGradient's `angle` on a STATIC shape — the bright
+        // band sweeps the perimeter. (Do NOT rotationEffect the shape: that spins
+        // the whole rounded-rect, corners and all.)
+        content.overlay(
+            RoundedRectangle(cornerRadius: cornerRadius)
+                .stroke(
+                    AngularGradient(
+                        gradient: Gradient(colors: colors + [colors.first ?? .clear]),
+                        center: .center,
+                        angle: .degrees(isAnimated ? 360 * Double(progress) : 0)
+                    ),
+                    lineWidth: lineWidth
+                )
+        )
+        .onAppear {
+            guard isAnimated else { return }
+            withAnimation(.linear(duration: duration).repeatForever(autoreverses: false)) {
+                progress = 1
+            }
+        }
+    }
+}
+
+extension View {
+    func animatedGradientBorder(colors: [Color], lineWidth: CGFloat = 2,
+                               cornerRadius: CGFloat = 12, isAnimated: Bool = true,
+                               duration: Double = 3.0) -> some View {
+        modifier(AnimatedGradientBorder(colors: colors, lineWidth: lineWidth,
+                                        cornerRadius: cornerRadius, isAnimated: isAnimated,
+                                        duration: duration))
+    }
+}
+
+#Preview {
+    Text("Featured")
+        .padding(16)
+        .frame(maxWidth: .infinity, alignment: .leading)
+        .background(Color(.systemBackground))
+        .clipShape(RoundedRectangle(cornerRadius: 12))
+        .animatedGradientBorder(colors: [.blue.opacity(0.6), .blue, .blue.opacity(0.6)],
+                                cornerRadius: 12)
+        .padding()
+}
+```
+
+## Related Patterns
+
+- `carousel-banner` — promo banners often pair an auto-advancing pager with this border on the active card.
+- Price callouts — premium-price surfaces sit inside a card wearing this border; compose it at the card level, not on the price view (see `reference/ui` / `figma-price-integration`).

package/pipeline/skills/figma-ios/figma-to-component/SKILL.md

@@ -113,6 +113,21 @@ Bundled in `.instructions/figma/figma-to-swiftui/reference/`. Include relevant p
 | `reference/viewinspector.md` | 5A |
 | `reference/snapshot-testing.md` | 5D |
 
+## Complementary integration skills
+
+Cross-cutting skills in `figma-common/` that feed Phase 3D / 4A / 4B when the design triggers them (see `reference/orchestrator-discipline.md` Rule 4). Native-SwiftUI-first; project specifics come from `figma-config` `ui.*` hooks.
+
+| Skill | Phase 3D trigger | Purpose |
+|-------|------------------|---------|
+| `/figma-form-integration` | form-capable sub-components | FormField/FormSection modeling |
+| `/figma-price-integration` | currency+amount / Price instance | PriceRepresentable modeling |
+| `/figma-ui-patterns` | scroll/motion/shape signal | reusable technique recipes (incl. `animated-gradient-border`) |
+| `/figma-navigation` | tab/back/push/deep-link affordance | headless Output; native NavigationStack or `ui.navigationSystem` |
+| `/figma-overlays` | toast/HUD/alert/data-modal | caller-owned; native `.alert`/`.sheet(item:)` or `ui.overlaySystem` |
+| `/figma-bottom-sheets` | sheet/drawer/pinned-CTA/multi-step | sheet content; native `.presentationDetents` or `ui.sheetSystem` |
+
+Related workflow: `/figma-evolve-component` reconciles + extends an already-implemented component (drift-heal + additive extend, human-gated)  -  distinct from a fresh build here, `/figma-mend` (rebuild), and `/figma-fix` (review bug).
+
 ---
 
 ## Dispatch Procedure

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-3d-patterns.md

@@ -278,6 +278,37 @@ Configuration then carries `public let section: ComponentName.Section` plus stat
 
 **Architecture output (atomic, 1 field):** Configuration (or View init) carries the FormField directly, e.g. `public let terms: CheckboxFormField`.
 
+### 1.5.4 Interaction Pattern Detection (navigation / overlays / bottom sheets)
+
+Beyond content patterns, detect **interaction affordances** the component must expose without owning the presentation/routing. Each maps to a cross-cutting integration skill (native-SwiftUI default; a project-supplied system only when `figma-config` declares `ui.<system>`). The rule is the same in all three: the component emits a typed intent (Output closure) or takes a caller-owned binding  -  it never routes, never presents an app-level surface, never owns the sheet.
+
+**Navigation pattern** → read `/figma-navigation` (`.instructions/figma/figma-navigation/SKILL.md`).
+- **Detect:** a tab/section switcher that changes top-level content; a nav bar / header with a **back** or close affordance; a row/card variant implying a **push/detail** (chevron, "Detaylar", disclosure); a link/button whose label implies leaving the screen; a URL landing surface.
+- **Architecture output:** a navigation **Output** (`output: (Output) -> Void` / `onSelect: (ID) -> Void`) OR a caller-owned `selection: Binding<Tab>` OR a plain deep-link entry param. Labels/icons are static (localized) Configuration copy; only the *intent* is a closure. Never a hardcoded `NavigationLink(destination:)`.
+- **Guard:** an in-place segmented filter (no screen change) is a plain `Binding<Enum>`, not navigation.
+
+**Overlay pattern** → read `/figma-overlays` (`.instructions/figma/figma-overlays/SKILL.md`).
+- **Detect:** a toast/snackbar, a spinner/HUD or blocking dim, an alert dialog (1-3 buttons), a data-driven modal card; or a component action needing post-action feedback (saved/deleted/error).
+- **Architecture output:** the component emits an **intent** (`.saved` / `.removeRequested(id)`); the caller (scene/VM) shows the toast/alert/modal. Overlay content is data, never `AnyView`; rich/interactive content is a local `.sheet/.modal { }` at the owning view. Loading is ref-counted with min-show.
+- **Guard:** a static inline banner that is part of the component's own layout is plain content, not an overlay.
+
+**Bottom-sheet pattern** → read `/figma-bottom-sheets` (`.instructions/figma/figma-bottom-sheets/SKILL.md`).
+- **Detect:** the component is (or reveals) a bottom sheet / half-sheet / drawer, a **pinned bottom CTA** bar, a resizable pull-up panel, a **content-sized** sheet, or a **multi-step** in-sheet flow.
+- **Architecture output:** the component is sheet **content**; the caller owns `isPresented`/`item` + detents. A pinned CTA is `.safeAreaInset(edge:.bottom)`, not a presented sheet. If the component *reveals* a child sheet, it emits the trigger intent and the caller presents.
+- **Guard:** an inline expandable/disclosure within the page flow is plain component content.
+
+**Property classification additions:**
+
+| Classification | When | Swift Pattern |
+|---|---|---|
+| Navigation output | push/select/back affordance | `output`/`onSelect` closure on the View |
+| Tab/selection binding | switches top-level content | `selection: Binding<Tab>` |
+| Overlay intent | action needs app-level feedback/confirm | `output`/`onX` closure (caller shows overlay) |
+| Sheet content | component lives inside a sheet | plain component; caller adds `.presentationDetents(...)` |
+| Pinned CTA | sticky bottom action bar | `.safeAreaInset(edge:.bottom)` at the screen |
+
+Record detected interaction patterns in `04b_component_architecture.md` under **Navigation / Overlays / Bottom Sheet** headings (see each skill's "Integration with Phase 3D" for the table shape).
+
 ### 1.5.2 Image Asset Classification
 
 Figma designs contain images that are either **static assets** (bundled in the app) or **dynamic content** (loaded remotely at runtime). Classify each image in the design context.

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-4b-view.md

@@ -552,6 +552,16 @@ if isExpanded {
 
 Do NOT use `DisclosureGroup`  -  it has limited styling control. Build the expand/collapse manually for pixel-perfect Figma match.
 
+### 4.7.4 Interaction pattern rendering (navigation / overlays / bottom sheets)
+
+When the architecture identifies an **interaction pattern** (section1.5.4 in Phase 3D), read the matching skill and follow its "Integration with Phase 4B". The component **emits intent / takes a caller-owned binding  -  it never routes, presents an app-level overlay, or owns the sheet surface.** Native SwiftUI is the default; use a project system only when `figma-config` declares `ui.<system>`.
+
+- **Navigation** (`/figma-navigation`): emit a typed `output`/`onSelect` for push/detail/back; system back or `@Environment(\.dismiss)`; tab via a caller-owned `Binding`. Never hardcode `NavigationLink(destination: ConcreteScreen())` in a reusable component.
+- **Overlays** (`/figma-overlays`): the component emits `.saved` / `.removeRequested(id)`; the caller shows the toast/alert/modal. Native `.alert`/`.confirmationDialog` for 1-3 button dialogs; `.sheet(item:)` for a data modal card; rich content via a local `.sheet/.modal { }`. Loading is ref-counted with min-show. No `AnyView` through a center.
+- **Bottom sheets** (`/figma-bottom-sheets`): author the component as sheet **content**; the caller owns `isPresented`/`item` + `.presentationDetents([...])`. A pinned CTA is `.safeAreaInset(edge:.bottom)`, not a presented sheet. Multi-step = `NavigationStack` inside the sheet (native) or the project engine's nav sheet (custom).
+
+If `figma-config` sets `ui.navigationSystem`/`ui.overlaySystem`/`ui.sheetSystem` to `custom`, use that project's types (router/route enum/scene container, overlay center, branded/headless sheet modifiers) resolved from config  -  do not hardcode their names.
+
 ### 4.8 @ViewBuilder for complex conditional views
 
 ```swift

package/pipeline/skills/figma-ios/figma-to-component/reference/accessibility.md

@@ -1,6 +1,60 @@
 # ACCESSIBILITY INTEGRATION
 
-SwiftUI accessibility implementation guide.
+SwiftUI accessibility implementation guide. **Minimalism first, then correctness** — decide *whether* to annotate before deciding *what*. The key-type names below (`LocalizedAccessibilityStringKey`, `UITestingIdentifierKey`) are the project's generated a11y/testing-id key types; a project without them uses runtime strings.
+
+---
+
+## Core principle — accessibility is for vision-impaired users
+
+Every annotation must pass one test:
+
+> **"Does a vision-impaired person need this information to navigate or use the app?"** YES → add it. NO → don't; it's noise.
+
+Visual state (colors, gradients, tier badges) is information sighted users consume *visually*. A colored "Success"/"Elite"/"Classic" indicator with visible text is just the text; the color is decorative, not actionable. Do **not** generate a per-enum-variant a11y key for state the user already knows.
+
+## How VoiceOver already works (don't duplicate it)
+
+VoiceOver reads the **accessibility tree**, which SwiftUI builds automatically:
+- `Text("Hello")` is already read — `.accessibilityLabel("Hello")` / `.accessibilityAddTraits(.isStaticText)` are redundant.
+- `Button("Save"){}` already reads "Save, Button" — label + trait are redundant.
+- `Image(decorative:)` is already hidden.
+- `.accessibilityElement(children: .combine)` merges an `HStack`/`VStack`'s child text into one stop — you do NOT then add `.accessibilityLabel`.
+- `.accessibilityLabel` **overrides** (replaces child text), it does not supplement — harmful when the child text was already correct.
+
+**The question for EVERY modifier: "what breaks if I remove this?"** If nothing breaks, the modifier should not exist.
+
+## Decision hierarchy (apply in order, STOP as soon as resolved)
+
+1. **Does it need ANY a11y work?** SwiftUI reads it correctly as-is → add NOTHING.
+2. **Decorative elements?** → `.accessibilityHidden(true)` on those only.
+3. **Group children?** → `.accessibilityElement(children: .combine)` — then STOP.
+4. **Combined text wrong/missing?** → ONLY then add `.accessibilityLabel`.
+5. **Interactive state VoiceOver can't infer** (custom toggle, not SwiftUI `Toggle`) → `.accessibilityValue`.
+6. **A trait SwiftUI can't infer** (custom tappable, not `Button`) → `.accessibilityAddTraits`.
+7. **Last resort** → author a localized a11y key.
+
+Most components stop at step 2 or 3. Reaching step 4+ requires a written justification.
+
+## State-necessity decision tree (per variant/boolean)
+
+1. **Interactive?** (Toggle/Checkbox/Selection/Switch) → YES: generate state value keys. NO → 2.
+2. **Visible text already communicates the state?** → YES: skip (redundant). NO → 3.
+3. **Non-interactive display component?** (Badge/Tag/Chip/Status/Label) → YES: skip state keys; use `.accessibilityElement(children: .combine)` only, no `.accessibilityLabel`. NO → 4.
+4. **Trivially derivable from an enum at runtime?** → YES: use `state.localized`, skip the separate key. NO: author a key.
+
+**Worked example — a non-interactive `LabelBadge` (Success | Warning | Error | …):** not interactive → visible text communicates intent → it's a display component ⇒ do NOT generate `LabelBadge.SuccessState` etc. Combine children; the badge text is read naturally.
+
+## Anti-patterns (never)
+
+| Anti-pattern | Why wrong |
+|---|---|
+| `.isButton` on a `Button` / `.isStaticText` on a `Text` | SwiftUI already provides it |
+| `.accessibilityRemoveTraits(.isButton)` with no Button | removing a trait that was never there |
+| `.accessibilityLabel` duplicating visible text | overrides SwiftUI's correct reading with a string you now maintain |
+| `.accessibilityLabel("\(text), \(state)")` on a non-interactive badge | the state name is a color cue, not information |
+| A separate key per enum variant | key bloat for trivially translatable names |
+| `.accessibilityHint` when the label is self-explanatory ("Close") | VoiceOver already prepends "double tap to" |
+| Modifiers "just in case" | every modifier is cost with no value |
 
 ---
 

package/pipeline/skills/figma-ios/figma-to-component/reference/orchestrator-discipline.md

@@ -55,7 +55,7 @@ If you must write code directly (after 2+ retries), read the phase instruction f
 
 ## Rule 4: Skills Are Complementary, Not Dismissable
 
-`/figma-form-integration`, `/figma-ui-patterns`, `/figma-price-integration`, `/coreui-forms`  -  these skills feed INTO phases. They augment Phase 3D, Phase 4A, Phase 4B with domain-specific patterns.
+`/figma-form-integration`, `/figma-ui-patterns`, `/figma-price-integration`, `/figma-navigation`, `/figma-overlays`, `/figma-bottom-sheets`, `/coreui-forms`  -  these skills feed INTO phases. They augment Phase 3D, Phase 4A, Phase 4B with cross-cutting patterns (content: forms/price/ui-patterns; interaction: navigation/overlays/bottom-sheets). Each is native-SwiftUI-first and reads project specifics from `figma-config` (`ui.*` hooks)  -  generic across SwiftUI projects, not tied to any one app.
 
 When the user says "check /figma-form-integration":
 - That is a directive to integrate, not a suggestion to evaluate.