@sarjallab09/figma-intelligence 1.0.0

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

@@ -0,0 +1,314 @@
+# 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

@@ -0,0 +1,175 @@
+# 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

@@ -0,0 +1,180 @@
+# 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.