@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-2c-accessibility.md

@@ -0,0 +1,617 @@
+# PHASE 2C — Accessibility Keys
+
+Accessibility key integration for VoiceOver labels, hints, and values.
+REF: `reference/accessibility.md`
+
+required — always execute this phase.
+PARALLEL WITH: Phase 2A, Phase 2B (all read from pass1/_index.md independently)
+NEXT: Phase 2D (after all parallel phases complete)
+
+---
+
+## CORE PRINCIPLE: ACCESSIBILITY IS FOR VISION-IMPAIRED USERS
+
+Accessibility exists to help vision-impaired people **navigate and use** the app. Every annotation must pass this test:
+
+**"Does a vision-impaired person need this information to navigate or use the app?"**
+
+- If YES → add it (e.g., a button's purpose, a meaningful image description)
+- If NO → do not add it. You are cluttering the experience with useless noise.
+
+Visual state indicators (colors, gradients, tier badges) are information that sighted users consume visually. A vision-impaired user already knows their own loyalty tier, their own account status, their own membership level. Announcing "Elite" or "Classic Plus" on a profile avatar adds zero navigational or functional value — it is noise.
+
+Do NOT generate per-enum-variant accessibility keys for state that the user already knows or that adds no navigational value. An avatar is "Passenger avatar". A status badge with visible text is just the text. A colored indicator is decorative context, not actionable information.
+
+### How VoiceOver actually works
+
+VoiceOver reads the accessibility tree, NOT the view tree. SwiftUI builds this tree automatically:
+
+1. **`Text("Hello")` is already accessible.** VoiceOver reads "Hello" with no modifiers. SwiftUI knows it's static text. Adding `.accessibilityLabel("Hello")` duplicates what's already there. Adding `.accessibilityAddTraits(.isStaticText)` adds a trait SwiftUI already assigned.
+
+2. **`Button("Save") { ... }` is already accessible.** VoiceOver reads "Save, Button" — the label AND the trait. Adding `.accessibilityLabel("Save")` or `.accessibilityAddTraits(.isButton)` is redundant.
+
+3. **`Image(decorative: "bg")` is already hidden.** No modifier needed.
+
+4. **`.accessibilityElement(children: .combine)` merges children.** If an HStack contains `Image` + `Text("Confirmed")`, combining them makes VoiceOver read "Confirmed" as one stop — because SwiftUI concatenates the accessible text of all non-hidden children. You do NOT need `.accessibilityLabel("Confirmed")` on top of this — SwiftUI already reads the `Text`.
+
+5. **`.accessibilityLabel` OVERRIDES, it does not supplement.** When you add `.accessibilityLabel("Confirmed, Success")` to a combined element, VoiceOver reads ONLY "Confirmed, Success" — it ignores the children's text. This is useful when children text is wrong or insufficient. It is HARMFUL when children text is already correct, because now you're maintaining a redundant string.
+
+### When to add NOTHING
+
+If a component is:
+- Non-interactive (no taps, no toggles, no gestures)
+- Contains visible `Text` that VoiceOver reads correctly
+- Has only decorative images (hidden with `.accessibilityHidden(true)`)
+
+Then you need ZERO accessibility modifiers on the container. Maybe `.accessibilityElement(children: .combine)` to group children into one stop. That's it. No `.accessibilityLabel`. No `.accessibilityAddTraits`. No `.accessibilityRemoveTraits`. No `.accessibilityHint`.
+
+A non-interactive badge that shows "Confirmed" in green does NOT need `.accessibilityLabel("Confirmed, Success")`. The user hears "Confirmed" — that's sufficient. "Success" is a visual color cue, not information the VoiceOver user needs or cares about.
+
+### The question to ask for EVERY modifier
+
+**"What breaks if I remove this?"**
+
+- Remove `.accessibilityLabel` → VoiceOver reads children text instead → if that's correct, the label was redundant
+- Remove `.accessibilityAddTraits(.isStaticText)` → SwiftUI already assigns it to `Text` → nothing breaks
+- Remove `.accessibilityRemoveTraits(.isButton)` → there was no Button, so there was no `.isButton` trait → nothing breaks
+- Remove `.accessibilityHidden(true)` on decorative icon → VoiceOver reads the icon as an image → this DOES break, keep it
+
+If removing a modifier changes nothing, the modifier should not exist.
+
+### Decision hierarchy (apply in order, STOP as soon as resolved)
+
+1. **Does the component need ANY accessibility work?** If SwiftUI reads it correctly as-is → add NOTHING.
+2. **Are there decorative elements?** → `.accessibilityHidden(true)` on those elements only.
+3. **Should children be grouped?** → `.accessibilityElement(children: .combine)` — then STOP. SwiftUI reads the combined text.
+4. **Is the combined text wrong or missing?** → ONLY then add `.accessibilityLabel` with the correct text.
+5. **Is there interactive state VoiceOver can't infer?** (custom toggle, not SwiftUI Toggle) → `.accessibilityValue`.
+6. **Is there a trait SwiftUI can't infer?** (custom tappable view, not Button) → `.accessibilityAddTraits`.
+7. **Only as last resort** → generate a `LocalizedAccessibilityStringKey`.
+
+Most components stop at step 2 or 3. If you reach step 4+, justify WHY in the artifact.
+
+### Anti-patterns (NEVER do these)
+
+| Anti-pattern | Why it's wrong |
+|---|---|
+| Adding `.isButton` to a `Button` | SwiftUI already provides it |
+| Adding `.isStaticText` to a `Text` | SwiftUI already provides it |
+| `.accessibilityRemoveTraits(.isButton)` when no Button exists | Removing a trait that was never there — nonsensical |
+| `.accessibilityLabel` that duplicates visible text | Overrides SwiftUI's correct reading with a redundant string you now maintain |
+| `.accessibilityLabel("\(text), \(state.rawValue)")` on a non-interactive badge | State name ("Success") is a color cue, not information. VoiceOver user doesn't need it |
+| Adding accessibility modifiers "just in case" | Every modifier is code to maintain. If it adds no value, it adds cost |
+| Labeling every child in a group | VoiceOver stops at each child separately — use `.accessibilityElement(children: .combine)` |
+| Separate key per enum variant | Key bloat — 5+ keys for trivially translatable names |
+| `.accessibilityHint` when label is self-explanatory | "Close" button doesn't need hint "Closes this dialog" |
+
+---
+
+## IMPORTS
+
+Components consume accessibility via these modules:
+
+```swift
+import UIComponentUtilities   // View extensions
+import AccessibilityStringKeys // LocalizedAccessibilityStringKey
+import UITestingIdentifiers    // UITestingIdentifierKey
+```
+
+---
+
+## KEY TYPES
+
+| Type | Purpose | Source |
+|------|---------|--------|
+| `LocalizedAccessibilityStringKey` | Labels, hints, values (localized) | AccessibilityStringKeys |
+| `UITestingIdentifierKey` | Identifiers (not localized) | UITestingIdentifiers |
+
+---
+
+## MODIFIERS
+
+Only use when the modifier adds information SwiftUI cannot infer:
+
+| Modifier | Use ONLY when | Key Type |
+|----------|---------------|----------|
+| `.accessibilityLabel(_:)` | Visible text is insufficient or absent | `LocalizedAccessibilityStringKey` or runtime string |
+| `.accessibilityHint(_:)` | Action is ambiguous from label alone | `LocalizedAccessibilityStringKey` |
+| `.accessibilityValue(_:)` | Interactive element with changing state (toggle, slider) | `LocalizedAccessibilityStringKey` or runtime string |
+| `.accessibilityIdentifier(_:)` | Always (UI testing, not VoiceOver) | `UITestingIdentifierKey` |
+| `.accessibilityAddTraits(_:)` | SwiftUI doesn't already provide the correct trait | `AccessibilityTraits` |
+| `.accessibilityRemoveTraits(_:)` | SwiftUI inferred a wrong trait | `AccessibilityTraits` |
+| `.accessibilityHidden(_:)` | Element is decorative or redundant | `Bool` |
+| `.accessibilityElement(children:)` | Group multiple children into one VoiceOver stop | `.combine` or `.contain` |
+
+---
+
+## TRAITS
+
+Only add traits SwiftUI cannot infer. Do NOT add `.isButton` to `Button`, `.isStaticText` to `Text`, etc.
+
+| Trait | Add ONLY when |
+|-------|---------------|
+| `.isButton` | Custom tappable view (not SwiftUI `Button`) |
+| `.isLink` | Custom link view (not SwiftUI `Link`) |
+| `.isHeader` | Section header (SwiftUI doesn't auto-detect) |
+| `.isImage` | Meaningful image needing description |
+| `.isSelected` | Custom selection (not SwiftUI `Toggle`) |
+| `.updatesFrequently` | Live data (timers, scores) |
+
+---
+
+## RULES
+
+| Rule | Implementation |
+|------|----------------|
+| Add nothing unless it breaks without it | Ask "what breaks if I remove this?" — if nothing, don't add it |
+| No redundant labels | Don't add `.accessibilityLabel` when SwiftUI reads visible text correctly |
+| No redundant traits | Don't add `.isStaticText` to `Text`, `.isButton` to `Button` |
+| No phantom trait removal | Don't `.accessibilityRemoveTraits(.isButton)` when no Button exists |
+| No state announcement for display components | Visual state (color) is not VoiceOver information |
+| No "button" in label | Trait handles it |
+| No "tap to" in hint | VoiceOver adds "double tap to" |
+| No hint for obvious actions | "Close" button needs no hint |
+| Group related content | `.accessibilityElement(children: .combine)` — then STOP |
+| Hide decorative | `.accessibilityHidden(true)` |
+| One stop per logical element | Group children, don't label each |
+
+---
+
+## IDENTIFIER CONTEXT FOR VOICEOVER AUTOMATION
+
+`.accessibilityIdentifier` is used by both UI tests AND accessibility automation
+tools (Accessibility Inspector, XCUITest). The cascading `UIIdentifierContext`
+ensures each component instance is uniquely identifiable even when the same
+component appears multiple times on a screen.
+
+VoiceOver `.accessibilityLabel` does NOT cascade — labels are human-readable and
+SwiftUI handles grouping/container semantics naturally via
+`.accessibilityElement(children: .combine)`.
+
+### When to Recommend Context
+
+In the Implementation section, note when a component is likely reused multiple
+times per screen (buttons, badges, cards, list items) and recommend that parent
+views set `.identifierContext()` for disambiguation:
+
+```swift
+// Parent screen disambiguates reusable components
+BookingSummaryView()
+    .identifierContext(.BookingSummary.screen)
+
+// Each section further scopes its children
+PassengerSection()
+    .identifierContext(.BookingSummary.passengers)
+```
+
+---
+
+## PRE-CHECK: Phase 1 Complete
+
+```
+Read: {artifactPath}/pass1/_index.md
+```
+
+Verify this file exists and lists the expected Phase 1 output files.
+
+Then read the files needed for this phase:
+- `{artifactPath}/pass1/design_context_response.json`
+- `{artifactPath}/pass1/screenshot_response.md`
+- `{artifactPath}/pass1/component_properties.json`
+
+Also read:
+- `{artifactPath}/IMPLEMENTATION_HISTORY.md`
+
+Extract: `componentName`, `artifactPath`.
+
+### Registry Input (optional)
+
+The orchestrator may pass `registryData` containing pre-existing keys from `{repos.common.path}/Shared/Figma/Components/{nodeId}.json`.
+If `registryData.accessibilityKeys` exists and is non-empty, use it to pre-populate the keys list.
+Keys found in both registry AND the data files can be marked "Existing" immediately (skip CLI check in GATE 4).
+
+If any required file is missing:
+
+```
+STATUS: HALT
+PHASE: phase-2c
+GATE: PRE_CHECK
+REASON: Required Phase 1 artifacts missing. Pass1/_index.md or referenced files not found.
+COMPLETED_GATES: []
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Run Phase 1 first to gather Figma data.
+```
+
+---
+
+## GATE 1: COLLECT_REQUIREMENTS
+
+| Priority | Source | Check |
+|----------|--------|-------|
+| 1 | User prompt | Explicit accessibility key requests |
+| 2 | Attached file | README.md, Confluence export, screenshot |
+| 3 | Generated | From design_context_response.json |
+
+USE: Merge all sources. User input overrides generated.
+
+---
+
+## GATE 2: EXTRACT_FROM_DESIGN_CONTEXT
+
+INPUT: `{artifactPath}/pass1/design_context_response.json`
+INPUT: `{artifactPath}/pass1/screenshot_response.md`
+INPUT: `{artifactPath}/pass1/component_properties.json`
+
+SCAN for accessibility-relevant elements. For each, ask: **does this need a key, or can SwiftUI/runtime handle it?**
+
+| Element Pattern | Key? | When to SKIP key |
+|-----------------|------|------------------|
+| Button (SwiftUI `Button`) | Hint only if ambiguous | Skip label if button text is visible. Skip hint if action is obvious from label. |
+| Button (custom tappable) | Label + maybe Hint | Skip hint if label makes action clear (e.g., "Close" needs no hint) |
+| Image (meaningful) | Label | — |
+| Image (decorative) | NONE | `.accessibilityHidden(true)` — no key |
+| Input field | Label | Skip if placeholder text serves as label |
+| Toggle/checkbox (interactive) | Value keys | Use `.Selected`/`.NotSelected` for state. Skip label if toggle text is visible. |
+| List item | NONE usually | Skip — use `.accessibilityElement(children: .combine)` to group child content |
+| Header text | NONE | Skip — use `.accessibilityAddTraits(.isHeader)` on the `Text` view, no key needed |
+| Close/dismiss button | Label only | Skip hint — "Close" is self-explanatory |
+| Grouped content | NONE | `.accessibilityElement(children: .combine)` — SwiftUI combines child text |
+| Static text | NONE | SwiftUI reads `Text` content automatically |
+| Variant state (non-interactive) | NONE | Evaluate through GATE 2B. No `.accessibilityLabel` needed — `.accessibilityElement(children: .combine)` reads visible text |
+| Variant state (interactive) | Value keys | Only for toggles/selections where state changes via user action |
+
+Use `screenshot_response.md` to cross-reference:
+- Which elements are visually prominent (need labels)
+- Which images are decorative vs meaningful
+- Whether grouped content should be combined
+
+Use `component_properties.json` to identify:
+- Boolean properties → value states (`.Selected`, `.NotSelected`) — only if interactive
+- Variant properties → evaluate through GATE 2B
+
+OUTPUT: List of `{ key, purpose, label_en, label_tr }`, filtered through GATE 2B.
+
+---
+
+## GATE 2B: EVALUATE_STATE_NECESSITY
+
+For each variant property or boolean property identified in GATE 2, evaluate whether state-specific accessibility keys are actually needed.
+
+### Decision Tree
+
+1. **Is the state interactive?** (Toggle, Checkbox, Selection, Switch)
+   - YES → Generate state keys (essential for VoiceOver)
+   - NO → Continue to step 2
+
+2. **Does visible text already communicate the state?**
+   - YES → Skip state key (redundant with label text)
+   - NO → Continue to step 3
+
+3. **Is this a non-interactive display component?** (Badge, Tag, Chip, Status indicator, Label)
+   - YES → Skip state value keys. Do NOT add `.accessibilityLabel` — use `.accessibilityElement(children: .combine)` only. SwiftUI reads visible text naturally. Visual state (color) is not relevant to VoiceOver.
+   - NO → Continue to step 4
+
+4. **Can the state be derived from an enum at runtime?**
+   - YES and state names are trivial (Success="Success", Warning="Warning") → Skip separate localized key, recommend `state.localized` pattern
+   - NO (complex localization needed) → Generate key
+
+### State Key Skip Criteria
+
+Skip generating separate `.accessibilityValue` state keys when ALL of these are true:
+1. Component is non-interactive (no buttons, toggles, or links)
+2. State is purely visual (color/style change only)
+3. State name is trivially translatable (matches variant name directly)
+4. Visible text or label already provides sufficient context
+
+Instead, recommend in the artifact:
+- Use `.accessibilityElement(children: .combine)` — SwiftUI reads visible text
+- Do NOT add `.accessibilityLabel` with state name — visual state is irrelevant to VoiceOver for non-interactive components
+- Do NOT add `.accessibilityAddTraits(.isStaticText)` — SwiftUI already knows `Text` is static text
+
+### Example: LabelBadge (non-interactive badge)
+
+Variant property: `State` = Success | Warning | Error | Standard | Secondary
+
+Evaluation:
+- Step 1: NOT interactive → Continue
+- Step 2: Badge label text communicates intent → Skip
+- Step 3: IS a display component (Badge) → Skip
+
+Result: Do NOT generate `LabelBadge.SuccessState`, `LabelBadge.WarningState`, etc.
+Recommend: `.accessibilityElement(children: .combine)` only — no custom `.accessibilityLabel`. Badge text is read naturally by SwiftUI.
+
+OUTPUT: Updated keys list with state keys filtered. Include skipped keys in artifact.
+
+---
+
+## GATE 3: VALIDATE_NAMING
+
+REF: `reference/accessibility.md`
+
+| Rule | Check |
+|------|-------|
+| Key format | PascalCase.Dot.Notation |
+| No redundant info | Don't repeat visible text in label |
+| No "button" in label | Trait handles it (use `.isButton` trait) |
+| No "tap to" in hint | VoiceOver adds "double tap to" |
+| Context-appropriate | Written from VoiceOver user perspective |
+
+If any key fails validation, fix it before proceeding.
+
+---
+
+## GATE 4: CHECK_EXISTING_KEYS
+
+### Registry fast-path
+
+If `registryData.accessibilityKeys` contains this key, run the CLI check to confirm it still exists in the data file.
+If both registry AND CLI confirm → mark "Existing" immediately.
+If registry has it but CLI says not found → mark "To Add" (re-add it).
+
+### CLI check
+
+For each key in the list:
+
+```bash
+{repos.common.path}/.build/debug/TranslationManagerTool check --key '<KEY>' --config 'Shared/Localization/AccessibilityStrings/accessibility-config.json'
+```
+
+OUTPUT:
+```
+✅ Key exists: <KEY>
+📊 Status:
+   Missing: 0
+```
+or
+```
+✅ Key exists: <KEY>
+📊 Status:
+   Missing: N
+```
+or
+```
+❌ Key not found: <KEY>
+```
+
+| Result | Action |
+|--------|--------|
+| `✅ Key exists` + `Missing: 0` | Mark status: "Existing" |
+| `✅ Key exists` + `Missing: N` | Mark status: "Incomplete" — needs missing language translations |
+| `❌ Key not found` | Mark status: "To Add" |
+
+FAIL (tool error) →
+```
+STATUS: HALT
+PHASE: phase-2c
+GATE: CHECK_EXISTING_KEYS
+REASON: TranslationManagerTool failed.
+COMPLETED_GATES: [PRE_CHECK, COLLECT_REQUIREMENTS, EXTRACT_FROM_DESIGN_CONTEXT, VALIDATE_NAMING]
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Options:
+  1) Retry command
+  2) Build tool first: swift build --package-path {repos.common.path} --product TranslationManagerTool
+  3) Skip accessibility integration
+```
+
+---
+
+## GATE 5: ADD_MISSING_KEYS
+
+For each key with status "To Add" or "Incomplete":
+
+Translate to all 8 languages: ar, de, en, es, fr, it, ru, tr
+
+```bash
+{repos.common.path}/.build/debug/TranslationManagerTool add \
+  --key '<KEY>' \
+  --translations '{"en":"...","ar":"...","de":"...","es":"...","fr":"...","it":"...","ru":"...","tr":"..."}' \
+  --config 'Shared/Localization/AccessibilityStrings/accessibility-config.json'
+```
+
+OUTPUT:
+```
+✅ Added/Updated: <KEY>
+```
+
+| Result | Action |
+|--------|--------|
+| All succeeded | Proceed to GATE 6 |
+| Any failed | HALT |
+
+FAIL →
+```
+STATUS: HALT
+PHASE: phase-2c
+GATE: ADD_MISSING_KEYS
+REASON: Failed to add accessibility key.
+COMPLETED_GATES: [PRE_CHECK, COLLECT_REQUIREMENTS, EXTRACT_FROM_DESIGN_CONTEXT, VALIDATE_NAMING, CHECK_EXISTING_KEYS]
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Options:
+  1) Retry failed command
+  2) Skip this key and continue
+  3) Skip accessibility integration entirely
+```
+
+---
+
+## GATE 6: REGENERATE_METADATA
+
+```bash
+{repos.common.path}/.build/debug/TranslationMetadataGenerator --config 'Shared/Localization/AccessibilityStrings/accessibility-config.json'
+```
+
+OUTPUT:
+```
+✅ Metadata regenerated
+```
+
+| Result | Action |
+|--------|--------|
+| Succeeded | Proceed to GATE 7 |
+| Failed | HALT |
+
+FAIL →
+```
+STATUS: HALT
+PHASE: phase-2c
+GATE: REGENERATE_METADATA
+REASON: TranslationMetadataGenerator failed.
+COMPLETED_GATES: [PRE_CHECK, COLLECT_REQUIREMENTS, EXTRACT_FROM_DESIGN_CONTEXT, VALIDATE_NAMING, CHECK_EXISTING_KEYS, ADD_MISSING_KEYS]
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Options:
+  1) Retry command
+  2) Skip code generation (keys added but metadata not regenerated)
+```
+
+---
+
+## GATE 7: GENERATE_PLATFORM_CODE
+
+```bash
+cd {repos.packagesContainer}/{project.slug}-common && swift package plugin --allow-writing-to-package-directory generate-accessibility-code
+```
+
+OUTPUT:
+```
+✅ Generated iOS code
+```
+
+| Result | Action |
+|--------|--------|
+| Succeeded | Proceed to GATE 8 |
+| Failed | HALT |
+
+FAIL →
+```
+STATUS: HALT
+PHASE: phase-2c
+GATE: GENERATE_PLATFORM_CODE
+REASON: Code generation plugin failed.
+COMPLETED_GATES: [PRE_CHECK, COLLECT_REQUIREMENTS, EXTRACT_FROM_DESIGN_CONTEXT, VALIDATE_NAMING, CHECK_EXISTING_KEYS, ADD_MISSING_KEYS, REGENERATE_METADATA]
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Options:
+  1) Retry command
+  2) Skip code generation (keys added but not accessible in Swift code yet)
+```
+
+---
+
+## GATE 8: WRITE_ARTIFACT
+
+### JSON Sidecar (machine-readable)
+
+Write `{artifactPath}/pass2/utility_accessibility.json`:
+
+```json
+{
+  "accessibilityKeys": [
+    { "key": "ComponentName.KeyName", "purpose": "Description of what VoiceOver reads" }
+  ]
+}
+```
+
+If no accessibility keys needed, write `{ "accessibilityKeys": [] }`.
+
+This JSON is consumed by `phase2-finalize.py` to build `component-utilities.json`. The orchestrator reads ONLY this JSON — never the markdown.
+
+### Markdown Artifact (human-readable)
+
+Write `{artifactPath}/pass2/utility_accessibility.md`:
+
+```markdown
+# Accessibility Keys
+
+Component: {componentName}
+Generated: {ISO_DATE}
+Source: pass1/design_context_response.json, pass1/screenshot_response.md, pass1/component_properties.json
+Languages: ar, de, en, es, fr, it, ru, tr
+
+## Keys
+
+Only keys that passed the necessity filter. If this table is empty, the component needs no custom accessibility keys.
+
+| Key | Purpose | Value (EN) | Value (TR) | Status |
+|-----|---------|-----------|------------|--------|
+
+## Skipped Keys
+
+| Candidate | Reason Skipped | Alternative |
+|-----------|---------------|-------------|
+
+## Implementation
+
+Show ONLY the modifiers this specific component actually needs. Do NOT include patterns the component doesn't use. If a component needs no accessibility modifiers beyond what SwiftUI provides, say so explicitly — an empty Implementation section is a VALID output.
+
+Ask for EVERY modifier: **"What breaks if I remove this?"** If the answer is "nothing", do not include it.
+
+```swift
+// EXAMPLE: Non-interactive display component (Badge, Tag, Chip)
+// SwiftUI reads Text content automatically — NO custom label needed
+
+// Decorative element → hide
+iconView
+    .accessibilityHidden(true)
+
+// Group children → one VoiceOver stop (SwiftUI reads visible Text)
+HStack { icon; label }
+    .accessibilityElement(children: .combine)
+// DONE. No .accessibilityLabel, no .accessibilityAddTraits, no .accessibilityRemoveTraits.
+
+// EXAMPLE: Interactive component with custom state
+// Custom label → ONLY when visible text is absent or insufficient
+.accessibilityLabel(.{ComponentName}.customDescription)
+
+// Interactive state → ONLY for toggles/selections
+.accessibilityValue(isOn ? .{ComponentName}.selected : .{ComponentName}.notSelected)
+```
+```
+
+---
+
+## VALIDATION CHECKLIST
+
+Before marking complete, verify:
+
+```
+MINIMALISM CHECKS (do these FIRST):
+[ ] Every modifier justified — no modifier added that SwiftUI already handles
+[ ] No redundant traits — .isButton not added to Button, .isStaticText not added to Text
+[ ] No unnecessary hints — obvious actions (Close, Back, Delete) have no hint
+[ ] No unnecessary labels — visible text not repeated in .accessibilityLabel
+[ ] No unnecessary keys — runtime strings used where possible instead of LocalizedAccessibilityStringKey
+[ ] Grouped content — related children combined into ONE VoiceOver stop, not labeled individually
+[ ] State keys evaluated through GATE 2B — non-interactive states use runtime pattern
+[ ] Each logical element = one VoiceOver announcement (not multiple stops)
+
+CORRECTNESS CHECKS:
+[ ] All decorative images hidden (.accessibilityHidden(true))
+[ ] Interactive toggles/selections have .accessibilityValue for state
+[ ] Headers use .isHeader trait (added to existing Text, not separate key)
+[ ] Labels use LocalizedAccessibilityStringKey only when runtime string is insufficient
+[ ] Skipped keys documented with alternative approach
+
+IF KEYS WERE GENERATED:
+[ ] All 8 language translations provided (ar, de, en, es, fr, it, ru, tr)
+[ ] TranslationManagerTool check passes
+[ ] TranslationMetadataGenerator completed
+[ ] generate-accessibility-code plugin completed
+
+OUTPUT:
+[ ] utility_accessibility.json written to pass2/ (JSON sidecar for finalize script)
+[ ] utility_accessibility.md written to pass2/
+[ ] Implementation shows ONLY modifiers this component needs (no unused patterns)
+```
+
+---
+
+## SUCCESS OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-2c
+GATES_PASSED: [PRE_CHECK, COLLECT_REQUIREMENTS, EXTRACT_FROM_DESIGN_CONTEXT, VALIDATE_NAMING, CHECK_EXISTING_KEYS, ADD_MISSING_KEYS, REGENERATE_METADATA, GENERATE_PLATFORM_CODE, WRITE_ARTIFACT]
+ARTIFACTS_CREATED:
+  - {artifactPath}/pass2/utility_accessibility.json
+  - {artifactPath}/pass2/utility_accessibility.md
+SUMMARY: Accessibility keys: {ADDED} added, {EXISTING} existing (8 languages each).
+```