@sarjallab09/figma-intelligence 1.1.0 → 1.2.1

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

@@ -1,159 +0,0 @@
-# Anatomy Spec Reference
-
-Generate numbered anatomy annotations with attribute tables directly in Figma.
-
-## What This Spec Produces
-
-1. **Component artwork** — A default-variant instance with all hidden elements made visible
-2. **Numbered markers** — Pink circles (24px, #D946EF) with connector lines pointing to each element
-3. **Attribute table** — 4 columns: Number, Type (instance/text/shape icon), Element Name, Semantic Notes
-4. **Per-child sections** — Nested component instances get their own markers and tables
-5. **Cross-references** — Composition table notes link to per-child sections ("See X anatomy section")
-
----
-
-## Step-by-Step Pipeline
-
-### Phase 1: Extract Component Data
-
-1. Parse the Figma link to get `file_key` and `node_id`
-2. Read the component set or standalone component:
-   ```
-   get_node(file_key, node_id)
-   get_component_property_definitions(node_id)
-   ```
-3. Get the **default variant** (first child of the component set, or the component itself if standalone)
-4. Traverse all child layers recursively and collect:
-   - `name` — Layer name
-   - `type` — INSTANCE, TEXT, RECTANGLE, ELLIPSE, VECTOR, FRAME, GROUP, LINE
-   - `visible` — Whether the element is visible in the default state
-   - `componentPropertyReferences` — Which boolean property controls this element's visibility
-   - `characters` — Text content (for TEXT nodes)
-   - `componentId` — If an INSTANCE, the component it references
-
-5. For each INSTANCE child, resolve to its source component and check if it has meaningful internal structure (more than 1 visible child layer). If yes, mark it as a **per-child candidate**.
-
-6. **Filter out utility sub-components**: Skip elements whose resolved component name matches: `Spacer`, `Divider`, `Separator`, `Gap`, `Padding`. These have no meaningful anatomy to document.
-
-### Phase 2: Classify Each Element (AI Reasoning)
-
-For each collected element, determine its **role**:
-
-| Role | Description | Example |
-|------|-------------|---------|
-| `content-element` | Displays user-facing content | Label text, avatar image |
-| `optional-slot` | Controlled by a boolean toggle, can be hidden | Leading icon, trailing button |
-| `fixed-sub-component` | Always present nested instance | Icon component, badge |
-| `structural` | Layout container, not meaningful to document | Auto-layout wrapper frame |
-| `decorative` | Visual-only, no semantic meaning | Background shape, shadow layer |
-
-**Classification rules:**
-- If element has a `componentPropertyReference` to a boolean → `optional-slot`
-- If element is an INSTANCE with ≥2 meaningful children → `fixed-sub-component` or per-child candidate
-- If element is a FRAME/GROUP with only auto-layout purpose → `structural` (skip from table)
-- If element name starts with "." or is named "Background", "Shadow", "Overlay" → `decorative` (skip)
-- Everything else → `content-element`
-
-**Write semantic notes for each non-skipped element:**
-- For optional slots: "Optional. Controlled by [boolean-name] toggle. Hidden by default." or "Visible by default."
-- For content elements: Describe the element's purpose in the component context
-- For fixed sub-components: "Fixed sub-component. See [Name] anatomy section." (if per-child exists)
-- For instance swap slots: "Swappable. Accepts [list of allowed instances]."
-
-### Phase 3: Determine Per-Child Sections
-
-A nested instance warrants its own per-child section when:
-- It has ≥3 internal child layers (not counting structural wrappers)
-- It is NOT a utility component (Spacer, Divider, etc.)
-- It has its own configurable properties (booleans, variants)
-
-For qualifying per-child instances, repeat Phase 1 and Phase 2 on the nested component.
-
-**Collapsing identical siblings**: If the same component appears N times consecutively (e.g., 5 star icons), collapse into a single row with "(xN)" suffix.
-
-### Phase 4: Make Hidden Elements Visible
-
-For the artwork instance, unhide all hidden optional elements **through component properties**:
-```
-// DO THIS (property-aware unhide):
-set_component_properties(instance_id, { "Show Leading Icon": true, "Show Badge": true })
-
-// DO NOT DO THIS (raw visibility override):
-set_visibility(child_node_id, true)  // WRONG — breaks component property binding
-```
-
-This ensures the artwork shows the complete anatomy with all optional elements visible, while maintaining proper component property bindings.
-
-### Phase 5: Render the Documentation Frame
-
-#### Create the main frame
-```
-Main Frame (1440px wide, auto-layout vertical, padding 60px, gap 40px)
-├── Header Section
-│   ├── Title: "[Component Name] — Anatomy" (24px bold)
-│   └── Subtitle: "Component structure and element inventory" (14px, #6B7280)
-├── Artwork + Markers Section (horizontal layout)
-│   ├── Component Instance (all hidden elements visible)
-│   └── Marker Layer (positioned absolutely relative to artwork)
-├── Attribute Table
-│   ├── Header Row: # | Type | Element | Notes
-│   └── Body Rows: One per non-skipped element
-├── Per-Child Section 1 (if applicable)
-│   ├── Section Header: "[Child Name] Anatomy"
-│   ├── Child Artwork + Markers
-│   └── Child Attribute Table
-└── Per-Child Section N...
-```
-
-#### Place markers
-For each element in the attribute table:
-1. Get the element's absolute position and bounds within the artwork
-2. Create a marker circle (24px, #D946EF fill, white number text)
-3. Position the marker **outside** the component artwork (to the left, right, top, or bottom — whichever has the most space)
-4. Draw a 1px connector line from the marker center to the nearest edge of the element
-5. Avoid overlapping markers — distribute them evenly with ≥8px gaps
-
-#### Build the attribute table
-| Column | Width | Content |
-|--------|-------|---------|
-| # | 48px | Sequential number matching the marker |
-| Type | 48px | Icon indicator: 🔲 for instance, 📝 for text, ⬡ for shape/vector |
-| Element | 200px | Layer name. Append "(hidden)" if element is not visible in default state |
-| Notes | Fill remaining | Semantic notes from Phase 2 classification |
-
-### Phase 6: Validate
-
-1. Capture a screenshot of the completed frame
-2. Check against this checklist:
-   - [ ] All non-structural, non-decorative elements have a marker
-   - [ ] Marker numbers match table row numbers
-   - [ ] No markers overlap each other
-   - [ ] Connector lines point to the correct elements
-   - [ ] Hidden elements are labeled "(hidden)" in the table
-   - [ ] Per-child sections exist for qualifying nested instances
-   - [ ] Cross-references in the main table link to per-child sections
-3. Fix any issues found
-4. Repeat up to 3 times
-
----
-
-## Example Output Structure
-
-For a **Text Field** component with: Container, Leading Icon (optional), Label, Input Area, Placeholder Text, Helper Text (optional), Trailing Clear Button (optional):
-
-**Main Attribute Table:**
-| # | Type | Element | Notes |
-|---|------|---------|-------|
-| 1 | 🔲 | Container | Root frame. Auto-layout horizontal with nested vertical sections. |
-| 2 | 🔲 | Leading Icon (hidden) | Optional. Controlled by "Show Leading Icon" toggle. Hidden by default. |
-| 3 | 📝 | Label | Required. Displays the field's label text above the input area. |
-| 4 | 📝 | Input Text | Content element. Displays user-entered text or placeholder. |
-| 5 | 📝 | Placeholder Text | Content element. Visible when Input Text is empty. |
-| 6 | 📝 | Helper Text (hidden) | Optional. Controlled by "Show Helper" toggle. Provides guidance below the input. |
-| 7 | 🔲 | Clear Button (hidden) | Optional. Controlled by "Show Clear" toggle. See Clear Button anatomy section. |
-
-**Per-child: Clear Button Anatomy:**
-| # | Type | Element | Notes |
-|---|------|---------|-------|
-| 1 | 🔲 | Icon | Fixed sub-component. Displays the clear/close icon. |
-| 2 | ⬡ | Hit Area | Touch target overlay. 44x44px minimum for accessibility compliance. |

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

@@ -1,162 +0,0 @@
-# API Spec Reference
-
-Generate component property documentation with values, defaults, required/optional status, and configuration examples.
-
-## What This Spec Produces
-
-1. **Main property table** — All top-level properties with values, required status, defaults, and notes
-2. **Sub-component tables** — Separate tables for configurable nested elements
-3. **Configuration examples** — 1–4 annotated instances showing common setups
-
----
-
-## Step-by-Step Pipeline
-
-### Phase 1: Extract All Properties
-
-Properties come from **three sources** in Figma. You must check all three.
-
-#### Source 1: Variant Axes
-Read from the component set's variant names:
-```
-get_component_set_variants(node_id)
-```
-Parse variant names (formatted as "Property1=Value1, Property2=Value2") to extract:
-- Property name (e.g., "Size", "Type", "State", "Hierarchy")
-- All possible values (e.g., ["Large", "Medium", "Small", "XSmall"])
-- Default value (the first variant listed, or the one matching the default instance)
-
-#### Source 2: Instance (Boolean & Slot) Properties
-Read from `componentPropertyDefinitions` on the component set:
-```
-get_component_property_definitions(node_id)
-```
-This returns:
-- **Boolean properties**: Toggle-controlled elements (e.g., "Show Leading Icon": true/false)
-- **Instance swap properties**: Slots that accept different components (e.g., "Trailing Content": [IconButton, TextButton, None])
-- **Text properties**: Editable text content (e.g., "Label Text": string)
-
-#### Source 3: Variable Mode Collections
-Check for variable collections scoped to this component:
-```
-get_local_variable_collections()
-```
-Look for collections named after the component or containing modes like:
-- Shape: `Rounded`, `Square`, `Pill`
-- Density: `Compact`, `Default`, `Spacious`
-- Color/Style: `Default`, `Danger`, `Success`
-
-### Phase 2: Classify Properties (AI Reasoning)
-
-For each discovered property, determine:
-
-| Field | Description |
-|-------|-------------|
-| `name` | Property name as it appears in Figma |
-| `type` | `variant`, `boolean`, `instance-swap`, `text`, `variable-mode` |
-| `values` | All possible values |
-| `default` | The default value |
-| `required` | Whether the property must be explicitly set |
-| `notes` | Description of what this property controls |
-
-**Classification rules for required vs. optional:**
-- Variant axes that affect layout/appearance → **Required** (Size, Type)
-- State properties (enabled, disabled, selected) → **Required** 
-- Boolean toggles → **Optional** (they have a default on/off state)
-- Instance swap slots → **Optional** (they have a default or "None")
-- Text content properties → Depends on context (Label usually required, Helper Text optional)
-
-**Exclude transient interactive states:**
-- `hover`, `pressed`, `focused`, `hovered` → These are runtime states, NOT API properties
-- Only include **persistent** states: `disabled`, `selected`, `loading`, `error`, `active`
-
-### Phase 3: Identify Sub-Component Configurations
-
-For each instance swap slot or fixed nested component:
-1. Check if the nested component has its own configurable properties
-2. If yes, create a separate sub-component table
-3. In the main table, add a note: "See [Sub-component Name] configuration below"
-
-Example: A Section Heading with a trailing slot that accepts IconButton or TextButton:
-- Main table lists "Trailing Content" with values: "Icon Button | Text Button | None"
-- Sub-table for "Icon Button Configuration" lists the icon button's own properties
-- Sub-table for "Text Button Configuration" lists the text button's own properties
-
-### Phase 4: Generate Configuration Examples
-
-Create 1–4 examples showing common real-world setups:
-
-**Example selection strategy:**
-1. **Minimal** — Required properties only, all optionals at defaults
-2. **Common** — The most frequently used configuration
-3. **Full** — All optional elements enabled
-4. **Specialized** — A specific variant (e.g., "Error state with helper text")
-
-For each example:
-- Create a component instance with the specific properties set
-- Add a label below: Example name + brief description
-- Add a property callout listing which properties differ from default
-
-### Phase 5: Render the Documentation Frame
-
-```
-Main Frame (1440px wide, auto-layout vertical, padding 60px, gap 40px)
-├── Header Section
-│   ├── Title: "[Component Name] — API" (24px bold)
-│   └── Subtitle: "Properties and configuration reference" (14px, #6B7280)
-├── Main Property Table
-│   ├── Header: Property | Type | Values | Default | Required | Notes
-│   └── Rows: One per property (grouped by source: variants first, then booleans, then slots)
-├── Sub-Component Table(s) (if applicable)
-│   ├── Section Header: "[Sub-component] Configuration"
-│   └── Table with same column structure
-├── Configuration Examples Section
-│   ├── Section Header: "Configuration Examples"
-│   └── Example Grid (2-column layout)
-│       ├── Example 1: [Instance] + [Label + Property List]
-│       ├── Example 2: [Instance] + [Label + Property List]
-│       └── ...
-```
-
-**Main Property Table columns:**
-| Column | Width | Content |
-|--------|-------|---------|
-| Property | 160px | Property name |
-| Type | 100px | `variant` / `boolean` / `slot` / `text` / `mode` |
-| Values | 200px | All possible values, pipe-separated |
-| Default | 120px | Default value, **bold** |
-| Required | 80px | ✓ or — |
-| Notes | Fill | Description of what this property controls |
-
-### Phase 6: Validate
-
-Checklist:
-- [ ] All variant axes are listed
-- [ ] All boolean properties are listed
-- [ ] All instance swap slots are listed
-- [ ] All variable mode properties are listed
-- [ ] Transient states (hover, pressed) are NOT listed
-- [ ] Default values are correctly identified
-- [ ] Sub-component tables exist for configurable nested components
-- [ ] Configuration examples render correctly with the right property combinations
-
----
-
-## Example: Button API
-
-**Main Property Table:**
-| Property | Type | Values | Default | Required | Notes |
-|----------|------|--------|---------|----------|-------|
-| Size | variant | Large \| Medium \| Small \| XSmall | Medium | ✓ | Controls button height and padding |
-| Hierarchy | variant | Primary \| Secondary \| Tertiary | Primary | ✓ | Visual emphasis level |
-| State | variant | Enabled \| Disabled \| Loading | Enabled | ✓ | Interaction state |
-| Show Leading Icon | boolean | true \| false | false | — | Displays an icon before the label |
-| Show Trailing Icon | boolean | true \| false | false | — | Displays an icon after the label |
-| Label | text | string | "Button" | ✓ | Button text content |
-| Color | mode | Default \| Danger \| Success | Default | — | Color scheme via variable mode |
-
-**Configuration Examples:**
-1. **Default** — Medium, Primary, Enabled, no icons → The basic button
-2. **Icon + Label** — Medium, Primary, Leading Icon visible → Common CTA pattern
-3. **Danger Action** — Medium, Primary, Danger color, "Delete" label → Destructive action
-4. **Loading** — Medium, Primary, Loading state → Async operation in progress

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

@@ -1,148 +0,0 @@
-# Color Annotation Spec Reference
-
-Generate design token specifications mapping every UI element to its color token across states and variants.
-
-## What This Spec Produces
-
-1. **Color-annotated artwork** — Component instances with numbered markers pointing to color-bearing elements
-2. **Token mapping tables** — Element name → Token name → Resolved hex value, organized by state
-3. **Variant sections** — Separate sections for each color-affecting variant (Default, Danger, etc.)
-4. **Variable mode sections** — Sections for variable-mode-controlled color variants (Tag color, Badge style)
-
----
-
-## Step-by-Step Pipeline
-
-### Phase 1: Determine Rendering Strategy
-
-Before extracting data, analyze which variant axes affect color:
-
-**Strategy A — Section-per-variant** (simpler components):
-Use when the component has ≤3 color-affecting variant values (e.g., Default + Danger).
-Render: One section per variant, each containing state tables.
-
-**Strategy B — States-as-columns** (complex components):
-Use when the component has many variant combinations (e.g., 4 types × 4 states).
-Render: One table per variant type, with states as columns.
-
-**Strategy C — Variable-mode sections**:
-Use when color is controlled by a Figma variable collection (e.g., "Tag Color" with Default, Success, Warning, Error modes).
-Render: One section per mode value.
-
-**Decision logic:**
-1. Count variant axes that affect fill/stroke colors
-2. If only "State" axis changes colors → Strategy A (sections for other axes, states within each)
-3. If multiple axes × multiple states → Strategy B (states as columns)
-4. If color comes from variable modes → Strategy C
-
-### Phase 2: Extract Color Data
-
-For each variant/state combination that needs documentation:
-
-1. Create or navigate to the appropriate variant instance
-2. For every child layer (recursive), extract:
-   ```
-   get_node_fills(child_id)        → fill color(s)
-   get_node_strokes(child_id)      → stroke/border color(s)
-   get_bound_variables(child_id)   → variable bindings (token references)
-   ```
-
-3. For each color-bearing property, collect:
-   - **Element name**: Layer name (e.g., "Container", "Label Text", "Icon")
-   - **Property**: `fill`, `stroke`, `text-fill`
-   - **Token name**: The variable/token name if bound (e.g., `color/button/primary/bg`)
-   - **Resolved value**: The actual hex color value (e.g., `#6D28D9`)
-   - **Opacity**: If not 100%, include it
-
-4. **Enable hidden boolean elements** before extracting:
-   ```
-   set_component_properties(instance_id, { "Show Leading Icon": true, ... })
-   ```
-   Hidden elements may have color bindings that only appear when visible.
-
-### Phase 3: Classify Color Roles (AI Reasoning)
-
-Group elements by their color role:
-
-| Role | Elements | Example Tokens |
-|------|----------|----------------|
-| Background | Container fills, surface fills | `color/bg/primary`, `color/surface/default` |
-| Text | Label, helper text, placeholder | `color/text/primary`, `color/text/secondary` |
-| Icon | Leading icon, trailing icon fills | `color/icon/primary`, `color/icon/on-color` |
-| Border | Container strokes, input outlines | `color/border/default`, `color/border/focus` |
-| State Layer | Hover overlay, pressed overlay | `color/state-layer/hover`, `color/state-layer/pressed` |
-| Indicator | Error icon, success badge | `color/indicator/error`, `color/indicator/success` |
-
-### Phase 4: Render the Documentation Frame
-
-#### Strategy A Layout (Section-per-variant):
-```
-Main Frame (1440px wide)
-├── Header: "[Component Name] — Color Annotation"
-├── Variant Section: "Default"
-│   ├── State: "Enabled"
-│   │   ├── Annotated Artwork (instance + numbered markers)
-│   │   └── Token Table: Element | Property | Token | Value
-│   ├── State: "Hover"
-│   │   ├── Annotated Artwork
-│   │   └── Token Table (highlight changed values in bold)
-│   ├── State: "Pressed"
-│   │   └── ...
-│   └── State: "Disabled"
-│       └── ...
-├── Variant Section: "Danger"
-│   └── (same structure)
-```
-
-#### Strategy B Layout (States-as-columns):
-```
-Main Frame (1440px wide)
-├── Header: "[Component Name] — Color Annotation"
-├── Artwork Strip: [Enabled] [Hover] [Pressed] [Disabled]
-├── Token Table:
-│   Header: Element | Property | Enabled | Hover | Pressed | Disabled
-│   Row: Container | fill | token/bg/default | token/bg/hover | ... | ...
-│   Row: Label | text | token/text/primary | (same) | ... | token/text/disabled
-```
-
-#### Strategy C Layout (Variable modes):
-```
-Main Frame (1440px wide)
-├── Header: "[Component Name] — Color Annotation"
-├── Mode Section: "Default"
-│   ├── Annotated Artwork
-│   └── Token Table
-├── Mode Section: "Success"
-│   └── ...
-├── Mode Section: "Warning"
-│   └── ...
-```
-
-### Marker Placement for Color Specs
-
-Color markers differ from anatomy markers:
-- Use **same marker style** (24px circle, #D946EF)
-- Place markers pointing to the specific **color-bearing surface** (not the element in general)
-- For elements with both fill and stroke, use two markers (one for each)
-- Number markers per-section (restart numbering for each state/variant section)
-
-### Phase 5: Validate
-
-Checklist:
-- [ ] All color-bearing elements are documented (fills, strokes, text colors)
-- [ ] Token names match actual Figma variable names
-- [ ] Resolved hex values are correct
-- [ ] All relevant states are covered (enabled, hover, pressed, disabled at minimum)
-- [ ] All relevant variants are covered
-- [ ] Variable mode sections exist for mode-controlled colors
-- [ ] Light/dark themes are NOT duplicated (semantic tokens handle this)
-- [ ] Hidden elements' colors are captured (booleans toggled on during extraction)
-
----
-
-## Notes
-
-- **Semantic tokens only**: Document the semantic token names, not raw color primitives. If an element is bound to `color/text/primary` which resolves to `gray/900` which resolves to `#111827`, document `color/text/primary → #111827`.
-- **State layers**: Hover and pressed often use a semi-transparent overlay. Document both the overlay token and its opacity.
-- **Unchanged values**: When a token stays the same across states, you can use "—" or "(same)" in the table to reduce noise. Only highlight values that actually change.
-- **Sub-component reference**: If a nested component (e.g., Icon Button inside Section Heading) has its own color spec, add a note "See [Component] color annotation" rather than duplicating all its tokens.