feat: add component property support (BOOLEAN & TEXT) (#340)

## Summary

Today when an AI fetches a Figma component, it only sees the default state — any layers hidden by boolean properties (like "On Sale" or "Show Badge") are silently dropped. The AI has no idea those layers exist or that the component supports toggling them.

This PR fixes that:

- **Components now show their full capability.** Hidden conditional layers are included in the output, annotated with which property controls them. Property definitions list all available properties with their types and defaults.
- **Instances stay clean.** Instance output shows the resolved state with simplified property values — hidden layers are still stripped since they represent "what is" rather than "what could be."
- **Property format is AI-friendly.** Explicit `{ type, defaultValue }` on definitions, `Record<name, value>` on instances, `characters` renamed to `text` to match existing fields.

Covers BOOLEAN and TEXT properties. VARIANT and INSTANCE_SWAP are Phase 2.

Author: GLips

src/extractors/built-in.ts

@@ -14,6 +14,11 @@ import {
   hasTextStyle,
   isTextNode,
 } from "~/transformers/text.js";
+import {
+  simplifyComponentProperties,
+  simplifyPropertyDefinitions,
+  simplifyPropertyReferences,
+} from "~/transformers/component.js";
 import { hasValue, isRectangleCornerRadii } from "~/utils/identity.js";
 import { generateVarId, isVisible } from "~/utils/common.js";
 import type { Node as FigmaDocumentNode } from "@figma/rest-api-spec";
@@ -143,23 +148,55 @@ export const visualsExtractor: ExtractorFn = (node, result, context) => {
 };
 
 /**
- * Extracts component-related properties from INSTANCE nodes.
+ * Extracts component-related properties from nodes.
+ * Handles three cases: INSTANCE property values, property references on any node,
+ * and property definitions on COMPONENT/COMPONENT_SET nodes.
  */
-export const componentExtractor: ExtractorFn = (node, result, _context) => {
+export const componentExtractor: ExtractorFn = (node, result, context) => {
+  // Instance nodes: componentId + simplified componentProperties
   if (node.type === "INSTANCE") {
     if (hasValue("componentId", node)) {
       result.componentId = node.componentId;
     }
-
-    // Add specific properties for instances of components
     if (hasValue("componentProperties", node)) {
-      result.componentProperties = Object.entries(node.componentProperties ?? {}).map(
-        ([name, { value, type }]) => ({
-          name,
-          value: value.toString(),
-          type,
-        }),
+      const props = simplifyComponentProperties(
+        node.componentProperties as Record<string, { type: string; value: boolean | string }>,
       );
+      if (Object.keys(props).length > 0) {
+        result.componentProperties = props;
+      }
+    }
+  }
+
+  // Any node with property references: annotate with simplified refs
+  if (
+    "componentPropertyReferences" in node &&
+    node.componentPropertyReferences &&
+    typeof node.componentPropertyReferences === "object"
+  ) {
+    const refs = simplifyPropertyReferences(
+      node.componentPropertyReferences as Record<string, string>,
+    );
+    if (Object.keys(refs).length > 0) {
+      result.componentPropertyReferences = refs;
+    }
+  }
+
+  // Component/ComponentSet definitions: collect property definitions
+  if (
+    (node.type === "COMPONENT" || node.type === "COMPONENT_SET") &&
+    "componentPropertyDefinitions" in node &&
+    node.componentPropertyDefinitions &&
+    typeof node.componentPropertyDefinitions === "object"
+  ) {
+    const defs = simplifyPropertyDefinitions(
+      node.componentPropertyDefinitions as Record<
+        string,
+        { type: string; defaultValue: boolean | string }
+      >,
+    );
+    if (Object.keys(defs).length > 0) {
+      context.traversalState.componentPropertyDefinitions[node.id] = defs;
     }
   }
 };
@@ -177,7 +214,7 @@ function getStyleMatch(
   for (const key of keys) {
     const styleId = styleMap[key];
     if (styleId) {
-      const meta = context.globalVars.extraStyles?.[styleId];
+      const meta = context.extraStyles?.[styleId];
       if (meta?.name) return { name: meta.name, id: styleId };
     }
   }

src/extractors/design-extractor.ts

@@ -7,8 +7,7 @@ import type {
   Style,
 } from "@figma/rest-api-spec";
 import { simplifyComponents, simplifyComponentSets } from "~/transformers/component.js";
-import { isVisible } from "~/utils/common.js";
-import type { ExtractorFn, TraversalOptions, SimplifiedDesign, TraversalContext } from "./types.js";
+import type { ExtractorFn, TraversalOptions, SimplifiedDesign } from "./types.js";
 import { extractFromDesign } from "./node-walker.js";
 
 /**
@@ -24,20 +23,20 @@ export async function simplifyRawFigmaObject(
     parseAPIResponse(apiResponse);
 
   // Process nodes using the flexible extractor system
-  const globalVars: TraversalContext["globalVars"] = { styles: {}, extraStyles };
-  const { nodes: extractedNodes, globalVars: finalGlobalVars } = await extractFromDesign(
-    rawNodes,
-    nodeExtractors,
-    options,
-    globalVars,
-  );
+  const {
+    nodes: extractedNodes,
+    globalVars: finalGlobalVars,
+    traversalState,
+  } = await extractFromDesign(rawNodes, nodeExtractors, options, { styles: {} }, extraStyles);
 
-  // Return complete design
   return {
     ...metadata,
     nodes: extractedNodes,
-    components: simplifyComponents(components),
-    componentSets: simplifyComponentSets(componentSets),
+    components: simplifyComponents(components, traversalState.componentPropertyDefinitions),
+    componentSets: simplifyComponentSets(
+      componentSets,
+      traversalState.componentPropertyDefinitions,
+    ),
     globalVars: { styles: finalGlobalVars.styles },
   };
 }
@@ -65,15 +64,15 @@ function parseAPIResponse(data: GetFileResponse | GetFileNodesResponse) {
         Object.assign(extraStyles, nodeResponse.styles);
       }
     });
-    nodesToParse = nodeResponses.map((n) => n.document).filter(isVisible);
+    nodesToParse = nodeResponses.map((n) => n.document);
   } else {
     // GetFileResponse
     Object.assign(aggregatedComponents, data.components);
     Object.assign(aggregatedComponentSets, data.componentSets);
     if (data.styles) {
       extraStyles = data.styles;
     }
-    nodesToParse = data.document.children.filter(isVisible);
+    nodesToParse = data.document.children;
   }
 
   const { name } = data;

src/extractors/index.ts

@@ -4,6 +4,7 @@ export type {
   SimplifiedNode,
   TraversalContext,
   TraversalOptions,
+  TraversalState,
   GlobalVars,
   StyleTypes,
 } from "./types.js";

src/extractors/node-walker.ts

@@ -1,10 +1,12 @@
 import type { Node as FigmaDocumentNode } from "@figma/rest-api-spec";
 import { isVisible } from "~/utils/common.js";
 import { hasValue } from "~/utils/identity.js";
+import type { Style } from "@figma/rest-api-spec";
 import type {
   ExtractorFn,
   TraversalContext,
   TraversalOptions,
+  TraversalState,
   GlobalVars,
   SimplifiedNode,
 } from "./types.js";
@@ -41,24 +43,32 @@ export async function extractFromDesign(
   extractors: ExtractorFn[],
   options: TraversalOptions = {},
   globalVars: GlobalVars = { styles: {} },
-): Promise<{ nodes: SimplifiedNode[]; globalVars: GlobalVars }> {
+  extraStyles?: Record<string, Style>,
+): Promise<{
+  nodes: SimplifiedNode[];
+  globalVars: GlobalVars;
+  traversalState: TraversalState;
+}> {
   const context: TraversalContext = {
     globalVars,
+    extraStyles,
     currentDepth: 0,
+    traversalState: { componentPropertyDefinitions: {} },
   };
 
   nodesProcessed = 0;
 
   const processedNodes: SimplifiedNode[] = [];
   for (const node of nodes) {
-    if (!shouldProcessNode(node, options)) continue;
+    if (!shouldProcessNode(node, context, options)) continue;
     const result = await processNodeWithExtractors(node, extractors, context, options);
     if (result !== null) processedNodes.push(result);
   }
 
   return {
     nodes: processedNodes,
     globalVars: context.globalVars,
+    traversalState: context.traversalState,
   };
 }
 
@@ -71,7 +81,7 @@ async function processNodeWithExtractors(
   context: TraversalContext,
   options: TraversalOptions,
 ): Promise<SimplifiedNode | null> {
-  if (!shouldProcessNode(node, options)) {
+  if (!shouldProcessNode(node, context, options)) {
     return null;
   }
 
@@ -95,13 +105,20 @@ async function processNodeWithExtractors(
       ...context,
       currentDepth: context.currentDepth + 1,
       parent: node,
+      // COMPONENT nodes define properties; INSTANCE nodes resolve them
+      insideComponentDefinition:
+        node.type === "COMPONENT" || node.type === "COMPONENT_SET"
+          ? true
+          : node.type === "INSTANCE"
+            ? false
+            : context.insideComponentDefinition,
     };
 
     // Use the same pattern as the existing parseNode function
     if (hasValue("children", node) && node.children.length > 0) {
       const children: SimplifiedNode[] = [];
       for (const child of node.children) {
-        if (!shouldProcessNode(child, options)) continue;
+        if (!shouldProcessNode(child, childContext, options)) continue;
         const processed = await processNodeWithExtractors(child, extractors, childContext, options);
         if (processed !== null) children.push(processed);
       }
@@ -125,13 +142,23 @@ async function processNodeWithExtractors(
 /**
  * Determine if a node should be processed based on filters.
  */
-function shouldProcessNode(node: FigmaDocumentNode, options: TraversalOptions): boolean {
-  // Skip invisible nodes
+function shouldProcessNode(
+  node: FigmaDocumentNode,
+  context: TraversalContext,
+  options: TraversalOptions,
+): boolean {
   if (!isVisible(node)) {
-    return false;
+    // Rescue hidden nodes controlled by a boolean property inside component definitions
+    const hasVisibleRef =
+      "componentPropertyReferences" in node &&
+      node.componentPropertyReferences &&
+      typeof node.componentPropertyReferences === "object" &&
+      "visible" in node.componentPropertyReferences;
+    if (!(hasVisibleRef && context.insideComponentDefinition)) {
+      return false;
+    }
   }
 
-  // Apply custom node filter if provided
   if (options.nodeFilter && !options.nodeFilter(node)) {
     return false;
   }

src/extractors/types.ts

@@ -4,9 +4,9 @@ import type { SimplifiedLayout } from "~/transformers/layout.js";
 import type { SimplifiedFill, SimplifiedStroke } from "~/transformers/style.js";
 import type { SimplifiedEffects } from "~/transformers/effects.js";
 import type {
-  ComponentProperties,
   SimplifiedComponentDefinition,
   SimplifiedComponentSetDefinition,
+  SimplifiedPropertyDefinition,
 } from "~/transformers/component.js";
 
 export type StyleTypes =
@@ -22,9 +22,16 @@ export type GlobalVars = {
 };
 
 export interface TraversalContext {
-  globalVars: GlobalVars & { extraStyles?: Record<string, Style> };
+  globalVars: GlobalVars;
+  extraStyles?: Record<string, Style>;
   currentDepth: number;
   parent?: FigmaDocumentNode;
+  insideComponentDefinition?: boolean;
+  traversalState: TraversalState;
+}
+
+export interface TraversalState {
+  componentPropertyDefinitions: Record<string, Record<string, SimplifiedPropertyDefinition>>;
 }
 
 export interface TraversalOptions {
@@ -87,9 +94,9 @@ export interface SimplifiedNode {
   borderRadius?: string;
   // layout & alignment
   layout?: string;
-  // for rect-specific strokes, etc.
   componentId?: string;
-  componentProperties?: ComponentProperties[];
+  componentProperties?: Record<string, boolean | string>;
+  componentPropertyReferences?: Record<string, string>;
   // children
   children?: SimplifiedNode[];
 }