@sarjallab09/figma-intelligence 1.1.0 → 1.2.1

package/figma-bridge-plugin/knowledge-hub/uspec-references/full-spec-template.md

@@ -1,314 +0,0 @@
-# Component Specification Template
-
-> This is the gold-standard reference for what a complete component spec should look like.
-> When generating a spec with `figma_component_spec`, the output should match this quality,
-> tone, and depth. Use this as a writing guide — adapt the content to the actual component
-> but maintain the same level of detail and structure.
-
----
-
-## Example: Button Component Specification
-
----
-
-### 1. Overview
-
-Component:       Button
-Type:            COMPONENT_SET (24 variants)
-Node ID:         1:234
-Dimensions:      160 × 44 px (default variant)
-Layout:          HORIZONTAL auto layout, 8px gap, padding 12/16/12/16
-Description:     Button is a primary interactive component used to trigger actions
-                 and submit forms. It supports 3 hierarchy levels (Primary, Secondary,
-                 Tertiary), 4 sizes (XSmall, Small, Medium, Large), and full state
-                 coverage (Default, Hover, Pressed, Focused, Disabled). Composed of
-                 5 elements including 2 optional icon slots controlled by boolean toggles.
-                 All 8 color fills are bound to design tokens for full theme support.
-States:          Default, Hover, Pressed, Focused, Disabled
-Detected pattern: button
-Direct children: Leading Icon, Label, Trailing Icon, Loader, Focus Ring
-
----
-
-### 2. Anatomy
-
-#    Element          Type       Role                 Visible   Controlled By
-──────────────────────────────────────────────────────────────────────────────────
-1    Leading Icon     INSTANCE   optional-slot        true      Show Leading Icon
-2    Label            TEXT       content-element      true      —
-3    Trailing Icon    INSTANCE   optional-slot        false     Show Trailing Icon
-4    Loader           INSTANCE   optional-slot        false     Is Loading
-5    Focus Ring       FRAME      decorative           false     —
-
-Anatomy notes:
-- Leading Icon and Trailing Icon are optional slots controlled by boolean toggles.
-  When hidden, the button auto-resizes due to auto layout.
-- Label is the primary content element and must always remain visible.
-- Loader replaces the label content during async operations when Is Loading = true.
-- Focus Ring is a decorative element rendered on keyboard focus via the Focused state variant.
-
----
-
-### 3. Variants
-
-Axis         Values                              Default    Count
-──────────────────────────────────────────────────────────────────
-Hierarchy    Primary, Secondary, Tertiary        Primary    3
-Size         XSmall, Small, Medium, Large        Medium     4
-State        Default, Hover, Pressed, Focused,   Default    5
-             Disabled
-
-Toggle       Default   Controls
-──────────────────────────────────────────────
-Show Leading Icon    false     Leading Icon
-Show Trailing Icon   false     Trailing Icon
-Is Loading           false     Loader
-
-Swap Slot              Current Component
-──────────────────────────────────────────
-Leading Icon Swap      Icon / Arrow Left
-Trailing Icon Swap     Icon / Chevron Right
-
-Total possible configurations: 60 (3 hierarchy × 4 size × 5 state).
-Boolean multiplier: ×8 (3 toggles). Defined variants in file: 24.
-
-Defined variant names:
-- Hierarchy=Primary, Size=Large, State=Default
-- Hierarchy=Primary, Size=Large, State=Hover
-- Hierarchy=Primary, Size=Large, State=Pressed
-- Hierarchy=Primary, Size=Large, State=Focused
-- Hierarchy=Primary, Size=Medium, State=Default
-- ... and 19 more
-
----
-
-### 4. States
-
-State      Source          Axis / Property
-───────────────────────────────────────────
-Default    variant-axis    State
-Hover      variant-axis    State
-Pressed    variant-axis    State
-Focused    variant-axis    State
-Disabled   variant-axis    State
-
-State behavior notes:
-- Default: Normal idle state with standard fill colors and cursor: pointer.
-- Hover: Background shifts to a lighter/darker tint (token: button/primary/hover).
-  Triggered on mouse enter. Transition: 150ms ease-out.
-- Pressed: Background shifts further. Active fill token: button/primary/pressed.
-  Applied on mousedown, released on mouseup.
-- Focused: Visible focus ring (2px offset, brand color) for keyboard navigation.
-  Must meet WCAG 2.4.7 — 3:1 contrast against adjacent colors.
-- Disabled: Reduced opacity (0.4) or muted fill. Remove from tab order.
-  Use aria-disabled="true" rather than the disabled attribute when possible
-  to maintain focus for screen reader discoverability.
-
----
-
-### 5. Properties / API
-
-Property              Type            Values / Default                      Required
-────────────────────────────────────────────────────────────────────────────────────
-Hierarchy             Variant         Primary, Secondary, Tertiary          Yes
-                                      (default: Primary)
-Size                  Variant         XSmall, Small, Medium, Large          Yes
-                                      (default: Medium)
-State                 Variant         Default, Hover, Pressed, Focused,     Yes
-                                      Disabled (default: Default)
-Show Leading Icon     Boolean         true / false (default: false)         No
-Show Trailing Icon    Boolean         true / false (default: false)         No
-Is Loading            Boolean         true / false (default: false)         No
-Leading Icon Swap     Instance Swap   Any icon component                    No
-Trailing Icon Swap    Instance Swap   Any icon component                    No
-Label Text            Text Override   "Button" (editable)                   No
-
-Total properties: 9 (3 variants, 3 booleans, 2 instance swaps, 1 text override).
-
-Implementation notes:
-- Variant properties (Hierarchy, Size, State) are required and must always be set.
-- Boolean toggles control child visibility — they do not add/remove DOM elements,
-  only toggle display.
-- Instance swap slots accept any component from the Icon library. Ensure swapped
-  icons maintain the same bounding box (20×20 for Medium size) to avoid layout shift.
-- Label Text supports single-line text only. Truncation with ellipsis should be
-  handled if text overflows the maximum width.
-
----
-
-### 6. Spacing & Structure
-
-Root layout:     HORIZONTAL auto layout
-Dimensions:      160 × 44 px (Medium)
-Padding:         12 / 16 / 12 / 16 (T/R/B/L)
-Item spacing:    8px
-
-Element             Layout       W × H        Padding (T/R/B/L)   Gap    Sizing (H/V)
-──────────────────────────────────────────────────────────────────────────────────────
-Button (root)       HORIZONTAL   160 × 44     12/16/12/16          8px    HUG / FIXED
-Leading Icon        —            20 × 20      —                    —      FIXED / FIXED
-Label               —            auto × 20    —                    —      HUG / HUG
-Trailing Icon       —            20 × 20      —                    —      FIXED / FIXED
-
-Size scale:
-- XSmall: 28px height, 8/12 padding, 6px gap, 14px font
-- Small:  32px height, 8/12 padding, 6px gap, 14px font
-- Medium: 44px height, 12/16 padding, 8px gap, 16px font
-- Large:  52px height, 16/20 padding, 8px gap, 18px font
-
-Touch target compliance:
-- XSmall (28px): Below 44×44 WCAG minimum — ensure adequate spacing or hit area padding.
-- Small (32px): Below 44×44 — same concern.
-- Medium (44px): Meets 44×44 minimum touch target.
-- Large (52px): Exceeds minimum. Recommended for primary CTAs on mobile.
-
----
-
-### 7. Color Tokens
-
-Element          Property   Hex Value   Token Name
-────────────────────────────────────────────────────────────────
-Button (root)    fill       #0F62FE     color/interactive/primary
-Button (root)    fill       #0043CE     color/interactive/primary/hover
-Button (root)    fill       #002D9C     color/interactive/primary/pressed
-Label            fill       #FFFFFF     color/text/on-color
-Leading Icon     fill       #FFFFFF     color/icon/on-color
-Focus Ring       stroke     #0F62FE     color/focus/outline
-Disabled fill    fill       #C6C6C6     color/interactive/disabled
-Disabled text    fill       #8D8D8D     color/text/disabled
-
-Token coverage: 8/8 colors are bound to design tokens. Fully theme-ready.
-
-Token architecture notes:
-- All interactive colors use the `color/interactive/*` namespace.
-- Text and icon colors on filled backgrounds use `color/*/on-color` tokens
-  which automatically invert in dark mode.
-- The Disabled state uses dedicated disabled tokens — do not use opacity
-  reduction as it creates inconsistent results across themes.
-- Focus ring uses `color/focus/outline` which must maintain 3:1 contrast
-  against any background.
-
----
-
-### 8. Typography
-
-Element   Content     Font               Size    Line Height   Token
-────────────────────────────────────────────────────────────────────────
-Label     "Button"    Inter SemiBold      16px    20px          type/body/semibold/md
-
-Font families used: Inter SemiBold. Size range: 14px–18px across 4 size variants.
-
-Typography scale by size variant:
-- XSmall / Small: Inter SemiBold 14px / 18px line height
-- Medium: Inter SemiBold 16px / 20px line height
-- Large: Inter SemiBold 18px / 24px line height
-
-Accessibility notes:
-- Minimum font size (14px) meets readability guidelines.
-- All text uses SemiBold weight for adequate legibility on colored backgrounds.
-- Line height ratio (1.25–1.33) is within WCAG recommended range.
-
----
-
-### 9. Accessibility
-
-Touch target:
-- Medium (44×44px) and Large (52×52px) variants meet WCAG 2.5.8 minimum.
-- XSmall (28px) and Small (32px) are below minimum — add padding or spacing.
-
-Typography:
-- Label: Inter SemiBold 16px / 20px line height
-- All text sizes ≥ 14px — meets readability guidelines.
-
-Keyboard interaction:
-- Component must be focusable and operable via keyboard.
-- Focus state detected — visible focus indicator (2px ring) meets 3:1 contrast.
-- Disabled state: use aria-disabled="true" rather than removing from tab order.
-- Expected keyboard behavior: Enter/Space activates the button.
-
-Screen reader:
-- Role: button (native HTML or role="button" for custom elements)
-- Label: Computed from visible text content. If icon-only, provide aria-label.
-- State: Announce disabled state. Announce loading state with aria-busy="true"
-  and aria-live="polite" on the status region.
-
-Color contrast:
-- Primary: White text (#FFF) on blue (#0F62FE) = 4.66:1 ratio (passes AA)
-- Disabled: Gray text (#8D8D8D) on light gray (#C6C6C6) — verify ≥ 3:1 for
-  decorative non-text contrast.
-
-Structure:
-- 8 token aliases bound — supports theming.
-- Drop shadow: none on default. If added for elevation, verify contrast in all themes.
-- Expected ARIA pattern: WAI-ARIA Button pattern
-- Minimum contrast requirement: 4.5:1 for normal text, 3:1 for large text
-
----
-
-### 10. Usage Guidelines
-
-✓ DO:
-   ✓  Use the variant properties (Hierarchy, Size, State) to configure the button.
-      Don't detach instances to create custom variations.
-   ✓  Use boolean toggles (Show Leading Icon, Show Trailing Icon, Is Loading) to
-      show/hide optional elements instead of deleting layers.
-   ✓  Keep required elements intact: Label.
-   ✓  Support all defined states (Default, Hover, Pressed, Focused, Disabled).
-   ✓  Use Primary hierarchy for the most important action on the page.
-      Only one Primary button per view/section.
-   ✓  Use Secondary for supporting actions, Tertiary for low-emphasis actions.
-   ✓  Preserve auto layout settings — don't switch to absolute positioning.
-   ✓  Maintain the 8px gap between icon and label.
-   ✓  Use instance swap properties for icons — only swap in compatible 20×20 icons.
-   ✓  Test the component in both light and dark themes before publishing.
-
-✗ DON'T:
-   ✗  Don't remove or hide the Label element — this breaks semantic structure.
-   ✗  Don't create undocumented state variations — extend the variant set formally.
-   ✗  Don't use buttons for navigation — use Link component instead.
-   ✗  Don't replace icon swap slots with non-icon components.
-   ✗  Don't override internal padding or spacing values.
-   ✗  Don't use opacity to create disabled appearance — use the Disabled state variant.
-   ✗  Don't place more than one Primary button in the same section.
-
----
-
-### 11. Related Components
-
-Related Component         When to Use Instead
-──────────────────────────────────────────────────────────────────
-Link / Anchor             Use for navigation instead of triggering actions
-Icon Button               Use for icon-only actions with a tooltip
-FAB (Floating Action)     Use for the primary page-level action on mobile
-Split Button              Use when the button needs a dropdown for secondary actions
-Toggle Button             Use when the button represents an on/off state
-
----
-
-## Template Usage Notes
-
-This template demonstrates the expected quality bar:
-
-1. **Every section has content** — even when data is sparse, provide guidance,
-   recommendations, or explain what's missing and why it matters.
-
-2. **Tables are clean and aligned** — use consistent column widths, separator
-   lines, and clear headers.
-
-3. **Descriptive prose accompanies data** — don't just dump a table. Explain
-   what the data means, why it matters, and what to do about it.
-
-4. **Accessibility is specific** — mention exact WCAG criteria, contrast ratios,
-   keyboard patterns, and screen reader behavior.
-
-5. **Usage guidelines are actionable** — each do/don't references a specific
-   component feature or behavior, not generic advice.
-
-6. **Token architecture is explained** — don't just list token names. Explain
-   the naming pattern, theme behavior, and contrast requirements.
-
-7. **States include behavior notes** — describe transitions, timing, cursor
-   changes, and ARIA state management.
-
-8. **Spacing includes size scale** — if the component has size variants, show
-   how spacing/typography scales across all sizes.

package/figma-bridge-plugin/knowledge-hub/uspec-references/property-spec.md

@@ -1,175 +0,0 @@
-# Property Spec Reference
-
-Generate visual property annotations with live instance previews for every configurable property — variant axes, boolean toggles, variable modes, and child component properties.
-
-## What This Spec Produces
-
-1. **Variant axis exhibits** — One section per axis with instance previews for every value
-2. **Boolean toggle exhibits** — On/off states shown side by side, defaults labeled
-3. **Variable mode exhibits** — Shape, density, and other mode-driven properties as visual chapters
-4. **Child component chapters** — Nested component properties shown in-context on parent instances
-
----
-
-## Step-by-Step Pipeline
-
-### Phase 1: Extract All Properties
-
-Read `componentPropertyDefinitions` from the component set:
-```
-get_component_property_definitions(node_id)
-```
-
-Collect four categories:
-
-**1. Variant Axes** — From variant names (e.g., Size=Large, Hierarchy=Primary)
-- Property name
-- All values
-- Default value
-
-**2. Boolean Toggles** — From component property definitions
-- Property name (e.g., "Show Leading Icon")
-- Default state (true/false)
-- Which child layer it controls
-
-**3. Variable Mode Collections** — Check for component-scoped variable collections
-```
-get_local_variable_collections()
-```
-- Collection name (e.g., "Button Shape", "Density")
-- Mode names (e.g., ["Rounded", "Square", "Pill"])
-
-**4. Child Component Properties** — For each INSTANCE child layer:
-- Resolve to source component
-- Read its `componentPropertyDefinitions`
-- Group by child component name
-
-### Phase 2: Normalize Properties (AI Reasoning)
-
-Consolidation rules to avoid redundant exhibits:
-
-- **Coupled axes**: If two variant axes always change together (e.g., "Icon Size" always matches "Button Size"), merge them into a single exhibit showing the coupling
-- **Container-gated booleans**: If a boolean only matters when a specific variant value is active, show it within that variant's context rather than as a standalone exhibit
-- **Unified slots**: If multiple instance swap properties represent the same conceptual slot (e.g., "Leading Content" accepts both Icon and Avatar), combine into one exhibit
-- **Sibling booleans**: If two booleans are mutually exclusive (toggling one forces the other off), show them as a single either/or exhibit
-
-### Phase 3: Plan Exhibits
-
-For each property, determine the exhibit type:
-
-| Property Type | Exhibit Layout |
-|--------------|----------------|
-| Variant axis (≤6 values) | Horizontal row of instances, one per value |
-| Variant axis (>6 values) | 2-column or 3-column grid |
-| Boolean toggle | Side-by-side: OFF (default labeled) and ON |
-| Variable mode | Row of instances, one per mode value |
-| Child component | Show on parent instance with callout arrows |
-
-**Instance creation for exhibits:**
-- Start from the **default variant** of the component
-- Change ONLY the property being exhibited (keep everything else at defaults)
-- For variant axes: create one instance per value, changing only that axis
-- For booleans: create two instances — one with false, one with true
-- For modes: create one instance per mode, applying the mode via variable binding
-
-### Phase 4: Render the Documentation Frame
-
-```
-Main Frame (1440px wide, auto-layout vertical, padding 60px, gap 40px)
-├── Header Section
-│   ├── Title: "[Component Name] — Properties" (24px bold)
-│   └── Subtitle: "Configurable properties and visual reference" (14px, #6B7280)
-│
-├── Variant Axis Chapter(s)
-│   ├── Chapter Header: "[Axis Name]" (20px bold)
-│   ├── Values label: "Values: Large | Medium | Small | XSmall" (13px, #6B7280)
-│   ├── Default label: "Default: Medium" (13px, bold tag on value)
-│   └── Exhibit Row (horizontal auto-layout, gap 24px)
-│       ├── [Instance: value 1] + Value Label below
-│       ├── [Instance: value 2] + Value Label below (DEFAULT badge if applicable)
-│       └── ...
-│
-├── Boolean Toggle Chapter(s)
-│   ├── Chapter Header: "[Boolean Name]" (20px bold)
-│   ├── Default label: "Default: false"
-│   └── Exhibit Row (horizontal, gap 40px)
-│       ├── [Instance: OFF state] + "Off" label + (DEFAULT badge)
-│       └── [Instance: ON state] + "On" label
-│
-├── Variable Mode Chapter(s)
-│   ├── Chapter Header: "[Collection Name]" (20px bold)
-│   ├── Modes: "Rounded | Square | Pill"
-│   └── Exhibit Row
-│       ├── [Instance: Mode 1] + Mode Label
-│       ├── [Instance: Mode 2] + Mode Label
-│       └── ...
-│
-└── Child Component Chapter(s) (if applicable)
-    ├── Chapter Header: "[Child Name] Properties" (20px bold)
-    ├── Context note: "Shown in context on [Parent Name]"
-    └── Sub-exhibits for each child property
-        └── Same exhibit format but instances are parent component
-            with the child property varied
-```
-
-**Exhibit instance sizing:**
-- Use the default variant size for all exhibits within a chapter
-- Exception: Size axis exhibits obviously show each size at its actual dimensions
-- Maximum instance width: 300px (scale down if needed, maintaining aspect ratio)
-- Minimum gap between instances: 24px
-
-**Default badges:**
-- Small rounded rectangle: 4px padding, #E5E7EB background, "DEFAULT" text 10px bold #6B7280
-- Placed below the instance, centered
-
-### Phase 5: Validate
-
-Checklist:
-- [ ] Every variant axis has an exhibit with an instance per value
-- [ ] Every boolean toggle has a side-by-side OFF/ON exhibit
-- [ ] Variable mode collections are rendered (if present)
-- [ ] Child component properties are shown in-context on parent
-- [ ] Default values are labeled on every exhibit
-- [ ] No duplicate or redundant exhibits (normalization applied)
-- [ ] Instances render correctly (no broken components)
-
----
-
-## Example: Button Properties
-
-### Size (Variant Axis)
-```
-Values: Large | Medium | Small | XSmall
-Default: Medium
-
-[Large instance] [Medium instance] [Small instance] [XSmall instance]
-    Large           Medium              Small           XSmall
-                    DEFAULT
-```
-
-### Show Leading Icon (Boolean)
-```
-Default: false
-
-[Button without icon]    [Button with icon]
-        Off                     On
-      DEFAULT
-```
-
-### Shape (Variable Mode)
-```
-Modes: Rounded | Square | Pill
-Default: Rounded
-
-[Rounded button]    [Square button]    [Pill button]
-    Rounded             Square             Pill
-    DEFAULT
-```
-
-### Trailing Content — Icon Button Properties (Child Component)
-```
-Shown in context on Button
-
-[Button with small icon]    [Button with medium icon]
-     Icon Size: Small           Icon Size: Medium
-```

package/figma-bridge-plugin/knowledge-hub/uspec-references/screen-reader-spec.md

@@ -1,180 +0,0 @@
-# Screen Reader Spec Reference
-
-Generate accessibility specifications for VoiceOver (iOS), TalkBack (Android), and ARIA (Web).
-
-## What This Spec Produces
-
-1. **Focus order diagram** — Visual showing the tab/swipe order through interactive elements
-2. **Per-platform tables** — VoiceOver, TalkBack, and ARIA properties for each focus stop
-3. **State-specific announcements** — How announcements change across enabled, disabled, selected, etc.
-4. **Merge analysis** — Which visual elements combine into a single focus stop vs. independent stops
-
----
-
-## Step-by-Step Pipeline
-
-### Phase 1: Extract Component Elements
-
-1. Read all child layers from the component:
-   ```
-   get_node_children(node_id, recursive=true)
-   ```
-2. Classify each element:
-   - **Interactive**: buttons, toggles, inputs, links (elements users can act on)
-   - **Informational**: labels, helper text, badges, icons (content that informs but isn't interactive)
-   - **Decorative**: backgrounds, shadows, dividers (invisible to screen readers)
-
-### Phase 2: Merge Analysis (Critical AI Step)
-
-The merge analysis determines which visual parts become independent **focus stops** and which get merged into a parent element's announcement.
-
-**Rules for merging:**
-
-| Visual Part | Merge Behavior |
-|-------------|---------------|
-| Label text adjacent to a control | **Merge** into the control's accessibility label |
-| Helper/hint text below a control | **Merge** as the accessibility hint/description |
-| Decorative icons (bullets, arrows) | **Hide** from screen readers entirely |
-| Functional icons (clear, search, edit) | **Separate** focus stop if independently tappable |
-| Action buttons within a compound control | **Separate** focus stop |
-| Static content (read-only text, images) | **Merge** into nearest logical container |
-| Error messages | **Live region** announcement, not a focus stop |
-| Badges/counts | **Merge** into parent element's value announcement |
-
-**Decision framework:**
-1. Is this element independently interactive (tappable/clickable)? → **Separate focus stop**
-2. Does this element add information to an adjacent interactive element? → **Merge** into that element
-3. Is this element purely visual? → **Hide** (decorative)
-4. Is this element dynamic content that changes without user action? → **Live region**
-
-### Phase 3: Determine Focus Order
-
-For compound components with multiple focus stops:
-
-1. List all independent focus stops in their natural reading/tab order
-2. Default order: **left-to-right, top-to-bottom** (LTR layouts)
-3. Note any exceptions requested by the user (e.g., "input should focus before clear button")
-4. For each focus stop, note:
-   - Focus stop number
-   - Element name
-   - Which visual parts merge into this stop
-
-**Example — Text Field:**
-```
-Focus Stop 1: Input Field
-  Merges: Label text, Placeholder text, Helper text
-  
-Focus Stop 2: Clear Button (only when text is entered)
-  Merges: Clear icon
-```
-
-### Phase 4: Build Per-Platform Specifications
-
-For each focus stop, document platform-specific properties:
-
-#### iOS (VoiceOver)
-
-| Property | Description | Example |
-|----------|-------------|---------|
-| `accessibilityLabel` | What VoiceOver announces as the element's name | "Search" |
-| `accessibilityTraits` | Element type: `.button`, `.textField`, `.staticText`, `.header`, `.adjustable`, `.selected` | `.button` |
-| `accessibilityHint` | Action description, read after a pause | "Double tap to activate" |
-| `accessibilityValue` | Current value for adjustable elements | "3 of 5" |
-| `isAccessibilityElement` | Whether this is a single focus stop (true) or a container (false) | `true` |
-
-#### Android (TalkBack)
-
-| Property | Description | Example |
-|----------|-------------|---------|
-| `contentDescription` | What TalkBack announces | "Search, Edit field" |
-| `role` | Android role: `Button`, `EditText`, `CheckBox`, `Switch`, `Tab` | `Button` |
-| `stateDescription` | Current state in human-readable form | "Disabled" |
-| `importantForAccessibility` | Whether element is visible to TalkBack | `yes` |
-| `liveRegion` | For dynamic content: `polite` or `assertive` | — |
-
-#### Web (ARIA)
-
-| Property | Description | Example |
-|----------|-------------|---------|
-| `role` | ARIA role: `button`, `textbox`, `checkbox`, `tab`, `tabpanel`, `alert` | `button` |
-| `aria-label` | Accessible name (when visual text is insufficient) | "Close dialog" |
-| `aria-labelledby` | ID reference to visible label element | `"label-email"` |
-| `aria-describedby` | ID reference to description/hint element | `"hint-email"` |
-| `aria-expanded` | For expandable elements: `true` or `false` | `false` |
-| `aria-selected` | For selectable elements | `true` |
-| `aria-disabled` | Disabled state | `true` |
-| `aria-live` | For live regions: `polite` or `assertive` | — |
-| `tabindex` | Tab order: `0` (natural), `-1` (programmatic only) | `0` |
-
-### Phase 5: Document State Variations
-
-For each state the component can be in, document how announcements change:
-
-| State | What Changes |
-|-------|-------------|
-| **Enabled** | Base announcement — label, role, hint |
-| **Disabled** | Add "dimmed" (VoiceOver) / "disabled" (TalkBack) / `aria-disabled="true"` (ARIA) |
-| **Selected** | Add "selected" trait/state |
-| **Loading** | Announce "loading" via live region, disable interaction |
-| **Error** | Announce error message via live region or `aria-invalid` + `aria-errormessage` |
-| **Expanded** | Toggle `aria-expanded`, announce "expanded"/"collapsed" |
-
-### Phase 6: Render the Documentation Frame
-
-```
-Main Frame (1440px wide, auto-layout vertical, padding 60px, gap 40px)
-├── Header Section
-│   ├── Title: "[Component Name] — Screen Reader" (24px bold)
-│   └── Subtitle: "VoiceOver, TalkBack, and ARIA specifications" (14px, #6B7280)
-│
-├── Focus Order Section (only for compound components)
-│   ├── Section Header: "Focus Order" (20px bold)
-│   ├── Component Artwork with numbered focus indicators
-│   ├── Focus sequence: "1 → 2 → 3" with element names
-│   └── Notes about conditional focus stops
-│
-├── Platform Section: "iOS — VoiceOver"
-│   ├── Section Header (20px bold)
-│   ├── Per-Focus-Stop Tables:
-│   │   ├── Focus Stop 1: [Element Name]
-│   │   │   └── State Table:
-│   │   │       Header: Property | Enabled | Disabled | Selected
-│   │   │       Row: accessibilityLabel | "Save" | "Save" | "Save"
-│   │   │       Row: accessibilityTraits | .button | .button, .notEnabled | .button, .selected
-│   │   └── Focus Stop 2: [Element Name]
-│   │       └── ...
-│
-├── Platform Section: "Android — TalkBack"
-│   └── (same structure, Android properties)
-│
-└── Platform Section: "Web — ARIA"
-    └── (same structure, ARIA properties)
-```
-
-### Phase 7: Validate
-
-Checklist:
-- [ ] All interactive elements have a focus stop
-- [ ] Non-interactive informational elements are merged into appropriate focus stops
-- [ ] Decorative elements are marked as hidden from screen readers
-- [ ] All three platforms (VoiceOver, TalkBack, ARIA) are documented
-- [ ] State variations are documented (at minimum: enabled, disabled)
-- [ ] Focus order is specified for compound components
-- [ ] Error messages and dynamic content use live regions
-- [ ] Merge analysis is consistent across platforms
-
----
-
-## Component Complexity Guide
-
-**Simple components (1 focus stop):**
-Button, Checkbox, Switch, Toggle, Badge, Tag, Avatar
-→ Single focus stop, all visual parts merged. Document state changes.
-
-**Compound components (2–5 focus stops):**
-Text Field + Clear Button, Chip + Dismiss, Search Bar, Stepper
-→ Focus order section + per-stop tables. Document conditional stops.
-
-**Complex components (5+ focus stops):**
-Tab Bar, Navigation Bar, Data Table Row, Form Section
-→ Full focus order diagram. Consider documenting as a composite of simpler components with cross-references.