@sarjallab09/figma-intelligence 1.1.0 → 1.2.0

package/figma-bridge-plugin/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/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.

package/figma-bridge-plugin/references/structure-spec.md

@@ -1,165 +0,0 @@
-# Structure Spec Reference
-
-Generate dimensional properties documentation — spacing, padding, heights, widths, and gaps across size and density variants.
-
-## What This Spec Produces
-
-1. **Dimension tables** — Organized by component section (container, leading, labels, trailing)
-2. **Size/density columns** — Values shown across all variants so engineers see how dimensions change
-3. **Token references** — Values linked to design tokens when bound to variables
-4. **Composition mapping** — How parent sizes map to sub-component sizes
-
----
-
-## Step-by-Step Pipeline
-
-### Phase 1: Identify Dimensional Axes
-
-Determine which variant axes and variable modes affect dimensions:
-
-**Common dimensional axes:**
-- **Size**: Large, Medium, Small, XSmall → changes heights, padding, icon sizes, font sizes
-- **Density**: Compact, Default, Spacious → changes vertical padding, gaps
-- **Shape**: Rounded, Square, Pill → changes border-radius (not spacing, but sometimes affects padding)
-
-Read from two sources:
-1. Variant axes from component set variants
-2. Variable mode collections (density, size often come from variable modes)
-
-### Phase 2: Extract Measurements (Deterministic)
-
-For each dimensional variant combination, measure the component:
-
-```
-// For each size/density variant:
-get_node_dimensions(instance_id) → {
-  width, height,
-  paddingTop, paddingBottom, paddingLeft, paddingRight,
-  itemSpacing,        // gap between children in auto-layout
-  counterAxisSpacing, // gap in the cross-axis (if wrap)
-  borderRadius,
-  strokeWeight
-}
-```
-
-Traverse child layers and measure each section:
-```
-Container
-├── Leading Content → width, height, gap from label section
-│   └── Icon/Avatar → width, height
-├── Label Section → vertical layout
-│   ├── Primary Label → fontSize, lineHeight
-│   ├── Secondary Label → fontSize, lineHeight
-│   └── Gap between labels
-├── Trailing Content → width, height
-│   └── Icon/Button → width, height
-└── Internal gaps between all sections
-```
-
-**Token resolution**: For each measured value, check if it's bound to a variable:
-```
-get_bound_variables(node_id, "paddingLeft") → "spacing/component/md" (16)
-get_bound_variables(node_id, "height") → "sizing/button/lg" (56)
-```
-
-Report as: `token-name (resolved-value)` e.g., `spacing-md (16)` or just the raw number if hardcoded.
-
-### Phase 3: Plan Documentation Sections (AI Reasoning)
-
-Group measurements into logical sections based on the component's structure:
-
-| Section | What to Document |
-|---------|-----------------|
-| **Container** | Height, min-width, max-width, border-radius, stroke-weight |
-| **Padding** | Top, bottom, left, right (or horizontal/vertical if symmetric) |
-| **Internal Gaps** | Spacing between leading→labels, labels→trailing, label→sublabel |
-| **Leading Content** | Icon/avatar dimensions, gap from content |
-| **Labels** | Font sizes, line heights (note: these may go in a Typography spec instead) |
-| **Trailing Content** | Button/icon dimensions, gap from content |
-| **Touch Target** | Minimum touch area if different from visual bounds |
-
-**Section planning rules:**
-- Only create sections for parts that exist in the component
-- If a section has identical values across all variants, collapse it into a single-column note
-- If values vary across density but not size (or vice versa), use the varying axis as columns
-- Add a "Design Intent" note for non-obvious values (e.g., "Min-width ensures the button is tappable even with a single character label")
-
-### Phase 4: Render the Documentation Frame
-
-```
-Main Frame (1440px wide, auto-layout vertical, padding 60px, gap 40px)
-├── Header Section
-│   ├── Title: "[Component Name] — Structure" (24px bold)
-│   └── Subtitle: "Dimensions, spacing, and padding reference" (14px, #6B7280)
-│
-├── Section: "Container"
-│   ├── Section Header (18px bold)
-│   └── Table:
-│       Header: Property | Large | Medium | Small | XSmall
-│       Row: Height | sizing-lg (56) | sizing-md (48) | sizing-sm (40) | sizing-xs (32)
-│       Row: Border Radius | radius-md (8) | radius-md (8) | radius-sm (6) | radius-sm (6)
-│       Row: Stroke | 1 | 1 | 1 | 1
-│
-├── Section: "Padding"
-│   └── Table:
-│       Header: Property | Large | Medium | Small | XSmall
-│       Row: Horizontal | spacing-lg (24) | spacing-md (16) | spacing-sm (12) | spacing-xs (8)
-│       Row: Vertical | spacing-md (16) | spacing-sm (12) | spacing-xs (8) | spacing-2xs (4)
-│
-├── Section: "Leading Content"
-│   └── Table:
-│       Header: Property | Large | Medium | Small | XSmall
-│       Row: Icon Size | 24 | 24 | 20 | 16
-│       Row: Gap to Labels | spacing-sm (12) | spacing-sm (12) | spacing-xs (8) | spacing-xs (8)
-│
-├── Section: "Composition Mapping" (if component contains sub-components with their own sizes)
-│   └── Table:
-│       Header: Parent Size | Icon Size | Badge Size
-│       Row: Large | Medium | Small
-│       Row: Medium | Small | XSmall
-│       Row: Small | XSmall | —
-│
-└── Notes Section (optional)
-    └── Design intent notes, edge cases, responsive behavior
-```
-
-**Table formatting for structure specs:**
-- Values with tokens: Show as `token-name (value)` e.g., `spacing-md (16)`
-- Hardcoded values: Show as plain number e.g., `16`
-- Units: Always in pixels (px), but omit the "px" suffix in tables for cleanliness
-- Identical values across columns: Show the value (don't use "—" for same values in structure specs; engineers need explicit numbers)
-
-### Phase 5: Validate
-
-Checklist:
-- [ ] All size/density variants are represented as columns
-- [ ] Container dimensions are documented (height, width constraints, border-radius)
-- [ ] Padding values are documented (all four sides or horizontal/vertical)
-- [ ] Internal gaps between sections are documented
-- [ ] Sub-component dimensions are documented
-- [ ] Token names match actual Figma variable names
-- [ ] Resolved values match actual measured pixel values
-- [ ] Composition mapping exists for nested size relationships
-
----
-
-## Density vs. Size
-
-**Size** changes the overall scale: heights, icon dimensions, padding, font sizes, and minimum widths all change together.
-
-**Density** changes only vertical rhythm: vertical padding and gaps change, but heights, icon sizes, and horizontal values stay the same.
-
-If both axes exist, render size as primary columns and density as separate table sections:
-```
-## Container — Default Density
-Property | Large | Medium | Small
-Height   | 56    | 48     | 40
-
-## Container — Compact Density
-Property | Large | Medium | Small
-Height   | 48    | 40     | 32
-
-## Container — Spacious Density
-Property | Large | Medium | Small
-Height   | 64    | 56     | 48
-```