@nnao45/figma-use 0.1.0

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@nnao45/figma-use",
+  "version": "0.1.0",
+  "description": "Control Figma from the command line. Full read/write access for AI agents.",
+  "keywords": [
+    "ai",
+    "ai-agents",
+    "automation",
+    "cli",
+    "design",
+    "figma",
+    "plugin"
+  ],
+  "homepage": "https://github.com/nnao45/figma-use#readme",
+  "bugs": {
+    "url": "https://github.com/nnao45/figma-use/issues"
+  },
+  "license": "MIT",
+  "author": "nnao45",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nnao45/figma-use.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "figma-fast": "bin/figma-fast.js",
+    "figma-use": "bin/figma-use.js"
+  },
+  "files": [
+    "bin",
+    "CHANGELOG.md",
+    "README.md",
+    "SKILL.md",
+    "dist/cli",
+    "packages/plugin/src",
+    "packages/cli/src/color.ts",
+    "packages/cli/src/render"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/cli/index.js",
+    "./render": "./packages/cli/src/render/index.ts",
+    "./components": "./packages/cli/src/render/components.tsx"
+  },
+  "scripts": {
+    "build": "bun run build:cli",
+    "build:cli": "bun build packages/cli/src/index.ts --outdir dist/cli --target node --minify --external esbuild --external typescript --external @modelcontextprotocol/sdk --external oxfmt --external whaticon --external pngjs --external pixelmatch",
+    "test": "cd packages/cli && bun test",
+    "lint": "oxlint packages/",
+    "format": "oxfmt --write packages/",
+    "prepublishOnly": "bun run build",
+    "build:fast": "bun build packages/cli/src/fast.ts --outfile dist/fast.mjs --target node --minify"
+  },
+  "dependencies": {
+    "agentfmt": "^0.1.3",
+    "citty": "^0.1.6",
+    "consola": "^3.4.2",
+    "diff": "^8.0.3",
+    "esbuild": "^0.25.4",
+    "fontoxpath": "^3.34.0",
+    "postcss": "^8.5.6",
+    "svgpath": "^2.6.0",
+    "typescript": "^5.8.3",
+    "whaticon": "0.1.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@figma/plugin-typings": "^1.122.0",
+    "@iconify/core": "^4.1.0",
+    "@iconify/types": "^2.0.0",
+    "@iconify/utils": "^3.1.0",
+    "@types/bun": "^1.3.6",
+    "@types/pngjs": "^6.0.5",
+    "@types/react": "^19.2.9",
+    "@types/ws": "^8.18.1",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "oxfmt": "^0.26.0",
+    "oxlint": "^1.39.0",
+    "pixelmatch": "^7.1.0",
+    "pngjs": "^7.0.0",
+    "react": "19"
+  }
+}

package/packages/cli/src/render/component-set.tsx

@@ -0,0 +1,157 @@
+/**
+ * ComponentSet (variants) support
+ *
+ * ## How ComponentSet works in Figma's multiplayer protocol
+ *
+ * ComponentSet is NOT a separate node type - it's a FRAME with special fields:
+ *   - type = FRAME (4)
+ *   - isStateGroup = true (field 225)
+ *   - stateGroupPropertyValueOrders (field 238) = [{property: "variant", values: ["A", "B"]}]
+ *
+ * Children are SYMBOL (Component) nodes with names like "variant=Primary, size=Large".
+ * Figma auto-generates componentPropertyDefinitions from these names.
+ *
+ * ## Why Instances are created via Plugin API
+ *
+ * IMPORTANT: Instance nodes with symbolData.symbolID CANNOT be created via multiplayer
+ * when linking to components in the same batch. Figma reassigns GUIDs on receive,
+ * breaking the symbolID references.
+ *
+ * Example: We send SYMBOL with localID=100, Instance with symbolData.symbolID=100.
+ * Figma receives and assigns new IDs: SYMBOL becomes 200, but Instance still
+ * references 100 → broken link.
+ *
+ * This works for defineComponent() because Component and first Instance are adjacent
+ * in the node tree, but fails for ComponentSet where variant components are created
+ * first, then instances are created as siblings of the ComponentSet.
+ *
+ * Solution: Create the ComponentSet and variant Components via multiplayer (fast),
+ * then create Instances via Plugin API in trigger-layout (correct linking).
+ * The pendingComponentSetInstances array passes instance specs to the plugin.
+ *
+ * Discovered through protocol sniffing - see scripts/sniff-ws.ts
+ */
+
+import * as React from './mini-react.ts'
+
+import type { FC, ReactElement } from './mini-react.ts'
+
+type VariantDef = Record<string, readonly string[]>
+type VariantProps<V extends VariantDef> = { [K in keyof V]: V[K][number] }
+
+interface ComponentSetDef<V extends VariantDef> {
+  name: string
+  variants: V
+  render: (props: VariantProps<V>) => ReactElement
+  symbol: symbol
+}
+
+// Use global registry to avoid module duplication issues between bundled CLI and source imports
+const REGISTRY_KEY = '__figma_use_component_set_registry__'
+const componentSetRegistry: Map<symbol, ComponentSetDef<VariantDef>> = ((
+  globalThis as Record<string, unknown>
+)[REGISTRY_KEY] as Map<symbol, ComponentSetDef<VariantDef>>) ||
+((globalThis as Record<string, unknown>)[REGISTRY_KEY] = new Map<
+  symbol,
+  ComponentSetDef<VariantDef>
+>())
+
+export function resetComponentSetRegistry() {
+  componentSetRegistry.clear()
+}
+
+export function getComponentSetRegistry() {
+  return componentSetRegistry
+}
+
+/**
+ * Define a component with variants (ComponentSet)
+ *
+ * @example
+ * const Button = defineComponentSet('Button', {
+ *   variant: ['Primary', 'Secondary'] as const,
+ *   size: ['Small', 'Large'] as const,
+ * }, ({ variant, size }) => (
+ *   <Frame style={{ padding: size === 'Large' ? 16 : 8 }}>
+ *     <Text>{variant}</Text>
+ *   </Frame>
+ * ))
+ *
+ * <Button variant="Primary" size="Large" />
+ */
+export function defineComponentSet<V extends VariantDef>(
+  name: string,
+  variants: V,
+  render: (props: VariantProps<V>) => ReactElement
+): FC<Partial<VariantProps<V>> & { style?: Record<string, unknown> }> {
+  const sym = Symbol(name)
+  componentSetRegistry.set(sym, {
+    name,
+    variants,
+    render,
+    symbol: sym
+  } as ComponentSetDef<VariantDef>)
+
+  const VariantInstance: FC<Partial<VariantProps<V>> & { style?: Record<string, unknown> }> = (
+    props
+  ) => {
+    const { style, ...variantProps } = props
+    return React.createElement('__component_set_instance__', {
+      __componentSetSymbol: sym,
+      __componentSetName: name,
+      __variantProps: variantProps,
+      style
+    })
+  }
+  ;(VariantInstance as unknown as { displayName: string }).displayName = name
+
+  return VariantInstance
+}
+
+/**
+ * Generate all variant combinations
+ */
+export function generateVariantCombinations<V extends VariantDef>(
+  variants: V
+): Array<VariantProps<V>> {
+  const keys = Object.keys(variants) as (keyof V)[]
+  if (keys.length === 0) return [{}] as Array<VariantProps<V>>
+
+  const result: Array<VariantProps<V>> = []
+
+  function combine(index: number, current: Partial<VariantProps<V>>) {
+    if (index === keys.length) {
+      result.push(current as VariantProps<V>)
+      return
+    }
+
+    const key = keys[index]!
+    for (const value of variants[key]!) {
+      combine(index + 1, { ...current, [key]: value })
+    }
+  }
+
+  combine(0, {})
+  return result
+}
+
+/**
+ * Build variant name string for Figma component (e.g., "variant=Primary, size=Large")
+ */
+export function buildVariantName(props: Record<string, string>): string {
+  return Object.entries(props)
+    .map(([k, v]) => `${k}=${v}`)
+    .join(', ')
+}
+
+/**
+ * Build stateGroupPropertyValueOrders for ComponentSet
+ */
+export function buildStateGroupPropertyValueOrders(
+  variants: VariantDef
+): Array<{ property: string; values: string[] }> {
+  return Object.entries(variants).map(([property, values]) => ({
+    property,
+    values: [...values]
+  }))
+}

package/packages/cli/src/render/components.tsx

@@ -0,0 +1,115 @@
+/**
+ * Figma JSX Components
+ *
+ * Returns TreeNode objects for Figma Widget API rendering.
+ * Use @ts-expect-error in .figma.tsx files if TypeScript complains about JSX types.
+ */
+
+import { node, type BaseProps, type TextProps, type TreeNode } from './tree.ts'
+
+// Core components
+export function Frame(props: BaseProps): TreeNode {
+  return node('frame', props)
+}
+
+export function Text(props: TextProps): TreeNode {
+  return node('text', props)
+}
+
+export function Rectangle(props: BaseProps): TreeNode {
+  return node('rectangle', props)
+}
+
+export function Ellipse(props: BaseProps): TreeNode {
+  return node('ellipse', props)
+}
+
+export function Line(props: BaseProps): TreeNode {
+  return node('line', props)
+}
+
+export function Image(props: BaseProps & { src: string }): TreeNode {
+  return node('image', props)
+}
+
+export function SVG(props: BaseProps & { src: string }): TreeNode {
+  return node('svg', props)
+}
+
+export function Star(props: BaseProps & { points?: number; innerRadius?: number }): TreeNode {
+  return node('star', props)
+}
+
+export function Polygon(props: BaseProps & { pointCount?: number }): TreeNode {
+  return node('polygon', props)
+}
+
+export function Vector(props: BaseProps): TreeNode {
+  return node('vector', props)
+}
+
+export function Group(props: BaseProps): TreeNode {
+  return node('group', props)
+}
+
+export function Section(props: BaseProps): TreeNode {
+  return node('section', props)
+}
+
+// Aliases
+export const View = Frame
+export const Rect = Rectangle
+export const Component = Frame
+export const Instance = Frame
+export const Page = Frame
+
+// Intrinsic elements
+export const INTRINSIC_ELEMENTS = [
+  'frame',
+  'text',
+  'rectangle',
+  'ellipse',
+  'line',
+  'image',
+  'svg',
+  'star',
+  'polygon',
+  'vector',
+  'group',
+  'section'
+]
+
+// Variables
+export {
+  defineVars,
+  figmaVar,
+  isVariable,
+  loadVariablesIntoRegistry,
+  isRegistryLoaded,
+  type FigmaVariable
+} from './vars.ts'
+
+// Legacy component registry
+const componentRegistry = new Map<symbol, { name: string; element: unknown }>()
+export const resetComponentRegistry = () => componentRegistry.clear()
+export const getComponentRegistry = () => componentRegistry
+
+export function defineComponent(name: string, element: unknown) {
+  const sym = Symbol(name)
+  componentRegistry.set(sym, { name, element })
+  return () => element
+}
+
+// Icon
+export interface IconProps {
+  icon: string
+  size?: number
+  color?: string
+}
+
+export function Icon(props: IconProps) {
+  return { __icon: true, ...props }
+}
+
+// Re-export types
+export type { BaseProps, TextProps, StyleProps, TreeNode } from './tree.ts'

package/packages/cli/src/render/icon.ts

@@ -0,0 +1,166 @@
+import { loadIcon } from '@iconify/core/lib/api/icons'
+import { setAPIModule } from '@iconify/core/lib/api/modules'
+import { fetchAPIModule } from '@iconify/core/lib/api/modules/fetch'
+import { iconToSVG } from '@iconify/utils'
+
+import type { ReactNode } from './mini-react.ts'
+import type { Props, ReactElement } from './tree.ts'
+import type { IconifyIcon } from '@iconify/types'
+
+// Initialize API module
+setAPIModule('', fetchAPIModule)
+
+export interface IconData {
+  svg: string
+  width: number
+  height: number
+  body: string
+  viewBox: { left: number; top: number; width: number; height: number }
+}
+
+const iconCache = new Map<string, IconData>()
+
+// Raw icon data cache (before size transformation)
+const rawIconCache = new Map<string, IconifyIcon>()
+
+/**
+ * Load raw icon data (without size transformation)
+ */
+async function loadRawIcon(name: string): Promise<IconifyIcon | null> {
+  if (rawIconCache.has(name)) {
+    return rawIconCache.get(name)!
+  }
+
+  const icon = await loadIcon(name)
+  if (!icon) {
+    return null
+  }
+
+  rawIconCache.set(name, icon)
+  return icon
+}
+
+/**
+ * Load icon from Iconify and return SVG string
+ * @param name Icon name in format "prefix:name" (e.g., "mdi:home", "lucide:star")
+ * @param size Optional size (default: 24)
+ */
+export async function loadIconSvg(name: string, size: number = 24): Promise<IconData | null> {
+  const cacheKey = `${name}@${size}`
+
+  if (iconCache.has(cacheKey)) {
+    return iconCache.get(cacheKey)!
+  }
+
+  const icon = await loadRawIcon(name)
+  if (!icon) {
+    return null
+  }
+
+  const result = iconToSVG(icon, { height: size, width: size })
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" ${Object.entries(result.attributes)
+    .map(([k, v]) => `${k}="${v}"`)
+    .join(' ')}>${result.body}</svg>`
+
+  const data: IconData = {
+    svg,
+    width: size,
+    height: size,
+    body: result.body,
+    viewBox: {
+      left: result.viewBox[0],
+      top: result.viewBox[1],
+      width: result.viewBox[2],
+      height: result.viewBox[3]
+    }
+  }
+
+  iconCache.set(cacheKey, data)
+  return data
+}
+
+/**
+ * Get cached icon data (synchronous, for use in React components)
+ * Returns null if icon not preloaded
+ */
+export function getIconData(name: string, size: number = 24): IconData | null {
+  return iconCache.get(`${name}@${size}`) || null
+}
+
+/**
+ * Preload icons for use in JSX render
+ * Call before rendering to ensure icons are available synchronously
+ */
+export async function preloadIcons(icons: Array<{ name: string; size?: number }>): Promise<void> {
+  await Promise.all(icons.map(({ name, size }) => loadIconSvg(name, size || 24)))
+}
+
+/**
+ * Get list of popular icon sets
+ */
+export const iconSets = {
+  mdi: 'Material Design Icons',
+  lucide: 'Lucide',
+  heroicons: 'Heroicons',
+  'heroicons-outline': 'Heroicons Outline',
+  'heroicons-solid': 'Heroicons Solid',
+  tabler: 'Tabler Icons',
+  'fa-solid': 'Font Awesome Solid',
+  'fa-regular': 'Font Awesome Regular',
+  'fa-brands': 'Font Awesome Brands',
+  ri: 'Remix Icon',
+  ph: 'Phosphor',
+  'ph-bold': 'Phosphor Bold',
+  'ph-fill': 'Phosphor Fill',
+  carbon: 'Carbon',
+  fluent: 'Fluent UI',
+  ion: 'Ionicons',
+  bi: 'Bootstrap Icons'
+}
+
+/**
+ * Recursively collect Icon primitives from React element tree
+ */
+export function collectIcons(element: ReactNode): Array<{ name: string; size?: number }> {
+  const icons: Array<{ name: string; size?: number }> = []
+
+  function traverse(node: ReactNode): void {
+    if (!node || typeof node !== 'object') return
+
+    if (Array.isArray(node)) {
+      node.forEach(traverse)
+      return
+    }
+
+    const el = node as ReactElement
+    if (!el.type) return
+
+    if (el.type === 'icon') {
+      const props = el.props as { icon?: string; size?: number }
+      if (props.icon) {
+        icons.push({ name: props.icon, size: props.size })
+      }
+    }
+
+    if (typeof el.type === 'function') {
+      try {
+        const rendered = (el.type as (p: Props) => ReactNode)(el.props as Props)
+        if (rendered) traverse(rendered)
+      } catch {
+        // Ignore render errors during collection
+      }
+    }
+
+    const props = el.props as { children?: ReactNode }
+    if (props.children) {
+      if (Array.isArray(props.children)) {
+        props.children.forEach(traverse)
+      } else {
+        traverse(props.children)
+      }
+    }
+  }
+
+  traverse(element)
+  return icons
+}

package/packages/cli/src/render/index.ts

@@ -0,0 +1,47 @@
+/**
+ * React → Figma Renderer
+ */
+
+export { renderWithWidgetApi } from './widget-renderer.ts'
+
+export {
+  Frame,
+  Text,
+  Rectangle,
+  Ellipse,
+  Line,
+  Image,
+  SVG,
+  View,
+  Rect,
+  Star,
+  Polygon,
+  Vector,
+  Component,
+  Instance,
+  Group,
+  Page,
+  Icon,
+  INTRINSIC_ELEMENTS,
+  defineVars,
+  figmaVar,
+  isVariable,
+  loadVariablesIntoRegistry,
+  isRegistryLoaded,
+  type FigmaVariable,
+  defineComponent,
+  resetComponentRegistry,
+  getComponentRegistry
+} from './components.tsx'
+
+export { preloadIcons, loadIconSvg, getIconData, collectIcons } from './icon.ts'
+
+export { renderJsx } from './render-jsx.ts'
+
+export {
+  defineComponentSet,
+  resetComponentSetRegistry,
+  getComponentSetRegistry
+} from './component-set.tsx'
+
+export { buildComponent, readStdin, renderFromString } from './render-from-string.ts'

package/packages/cli/src/render/jsx-dev-runtime.ts

@@ -0,0 +1,6 @@
+/**
+ * Development JSX Runtime - re-exports production runtime
+ */
+
+export { jsx, jsxs, jsxDEV, Fragment } from './jsx-runtime.ts'
+export type { JSX } from './jsx-runtime.ts'

package/packages/cli/src/render/jsx-runtime.ts

@@ -0,0 +1,90 @@
+/**
+ * Custom JSX Runtime for Figma components
+ *
+ * This module provides jsx/jsxs functions that produce TreeNode objects
+ * instead of React elements.
+ */
+
+import { node, type BaseProps, type TreeNode, type TextProps } from './tree.ts'
+
+export function jsx(type: string | ((props: BaseProps) => TreeNode), props: BaseProps): TreeNode {
+  if (typeof type === 'function') {
+    return type(props)
+  }
+  return node(type, props)
+}
+
+export const jsxs = jsx
+export const jsxDEV = jsx
+
+// Fragment just returns children
+export function Fragment({ children }: { children?: unknown }): TreeNode {
+  return node('fragment', { children } as BaseProps)
+}
+
+// SVG element props
+interface SvgProps {
+  width?: string | number
+  height?: string | number
+  viewBox?: string
+  fill?: string
+  children?: unknown
+}
+
+interface PathProps {
+  d: string
+  fill?: string
+  stroke?: string
+  strokeWidth?: string | number
+  fillRule?: string
+  clipRule?: string
+}
+
+interface RectProps {
+  x?: string | number
+  y?: string | number
+  width?: string | number
+  height?: string | number
+  rx?: string | number
+  ry?: string | number
+  fill?: string
+  stroke?: string
+}
+
+interface CircleProps {
+  cx?: string | number
+  cy?: string | number
+  r?: string | number
+  fill?: string
+  stroke?: string
+}
+
+// JSX namespace for TypeScript
+export namespace JSX {
+  export type Element = TreeNode
+
+  export interface IntrinsicElements {
+    frame: BaseProps
+    text: TextProps
+    rectangle: BaseProps
+    ellipse: BaseProps
+    line: BaseProps
+    star: BaseProps & { points?: number; innerRadius?: number }
+    polygon: BaseProps & { pointCount?: number }
+    vector: BaseProps
+    group: BaseProps
+    image: BaseProps & { src: string }
+    // Figma SVG component with src string
+    SVG: BaseProps & { src: string }
+    // Native SVG elements (inline)
+    svg: SvgProps
+    path: PathProps
+    rect: RectProps
+    circle: CircleProps
+    g: { children?: unknown; fill?: string; stroke?: string }
+  }
+
+  export interface ElementChildrenAttribute {
+    children: {}
+  }
+}

package/packages/cli/src/render/mini-react.ts

@@ -0,0 +1,33 @@
+// Minimal React-compatible createElement for JSX rendering
+// Replaces 86KB react package with ~200 bytes
+
+export type ReactElement = {
+  type: string | Function
+  props: Record<string, unknown> & { children?: ReactNode[] }
+}
+
+export type ReactNode = ReactElement | string | number | null | undefined | ReactNode[]
+
+export type FC<P = Record<string, unknown>> = (props: P) => ReactElement
+
+export function createElement(
+  type: string | Function,
+  props: Record<string, unknown> | null,
+  ...children: ReactNode[]
+): ReactElement {
+  const flatChildren = children.flat()
+  return {
+    type,
+    props: {
+      ...props,
+      children:
+        flatChildren.length === 1
+          ? (flatChildren as ReactNode[])
+          : flatChildren.length > 0
+            ? flatChildren
+            : undefined
+    }
+  }
+}
+
+export default { createElement }