### Install Figma Widget and Plugin Typings

Source: https://github.com/figma/widget-typings/blob/main/README.md

Install both `@figma/plugin-typings` and `@figma/widget-typings` as development dependencies.

```sh
npm i --save-dev @figma/plugin-typings @figma/widget-typings
```

--------------------------------

### Install Figma Widget and Plugin Typings

Source: https://context7.com/figma/widget-typings/llms.txt

Install the necessary packages for Figma widget and plugin development. These typings extend `@figma/plugin-typings`.

```sh
npm install --save-dev @figma/plugin-typings @figma/widget-typings
```

--------------------------------

### Implement Widget Property Menus with `usePropertyMenu`

Source: https://context7.com/figma/widget-typings/llms.txt

Attach a property menu to a widget using `usePropertyMenu`. This example demonstrates various item types including color selectors, dropdowns, toggles, and links, along with their corresponding state management.

```tsx
const { widget } = figma
const { AutoLayout, Text, useSyncedState, usePropertyMenu } = widget

type Theme = "light" | "dark"
type Size = "small" | "medium" | "large"

function ThemedWidget() {
  const [theme, setTheme] = useSyncedState<Theme>("theme", "light")
  const [size, setSize] = useSyncedState<Size>("size", "medium")
  const [isLocked, setIsLocked] = useSyncedState("locked", false)

  usePropertyMenu(
    [
      {
        itemType: "color-selector",
        propertyName: "theme",
        tooltip: "Background theme",
        selectedOption: theme === "light" ? "#FFFFFF" : "#1E1E1E",
        options: [
          { option: "#FFFFFF", tooltip: "Light" },
          { option: "#1E1E1E", tooltip: "Dark" },
        ],
      },
      { itemType: "separator" },
      {
        itemType: "dropdown",
        propertyName: "size",
        tooltip: "Widget size",
        selectedOption: size,
        options: [
          { option: "small", label: "Small" },
          { option: "medium", label: "Medium" },
          { option: "large", label: "Large" },
        ],
      },
      {
        itemType: "toggle",
        propertyName: "locked",
        tooltip: "Lock content",
        isToggled: isLocked,
        icon: "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"16\" height=\"16\" viewBox=\"0 0 16 16\"><rect x=\"3\" y=\"7\" width=\"10\" height=\"8\" rx=\"1"/><path d=\"M5 7V5a3 3 0 016 0v2"/></svg>",
      },
      {
        itemType: "link",
        propertyName: "docs",
        tooltip: "Open docs",
        href: "https://developers.figma.com/docs/widgets",
        icon: null,
      },
    ],
    ({ propertyName, propertyValue }) => {
      if (propertyName === "theme") {
        setTheme(propertyValue === "#FFFFFF" ? "light" : "dark")
      } else if (propertyName === "size") {
        setSize(propertyValue as Size)
      } else if (propertyName === "locked") {
        setIsLocked(!isLocked)
      }
    }
  )

  const bg = theme === "light" ? "#FFFFFF" : "#1E1E1E"
  const fg = theme === "light" ? "#111111" : "#EEEEEE"
  const paddingMap = { small: 8, medium: 16, large: 24 }

  return (
    <AutoLayout fill={bg} padding={paddingMap[size]} cornerRadius={8} stroke="#CCCCCC">
      <Text fill={fg} fontSize={14}>
        {isLocked ? "🔒 Locked" : "✏️ Editable"} — {theme} / {size}
      </Text>
    </AutoLayout>
  )
}

widget.register(ThemedWidget)
```

--------------------------------

### Handle Async Operations with `waitForTask` in Figma Widgets

Source: https://context7.com/figma/widget-typings/llms.txt

Use `waitForTask` inside `useEffect` to prevent widget termination during async operations like network requests. This example fetches weather data and updates the widget's UI.

```tsx
const { widget } = figma
const { Text, AutoLayout, useEffect, waitForTask, useSyncedState } = widget

function WeatherWidget() {
  const [temp, setTemp] = useSyncedState<string>("temperature", "Loading...")
  const [city, setCity] = useSyncedState("city", "San Francisco")

  useEffect(() => {
    waitForTask(
      new Promise<void>(resolve => {
        // Show UI iframe to fetch data from the network
        figma.showUI(`
          <script>
            fetch('https://wttr.in/${city}?format=3')
              .then(r => r.text())
              .then(text => parent.postMessage({ pluginMessage: { type: 'weather', text } }, '*'))
          </script>
        `, { visible: false })

        figma.ui.onmessage = (msg: { type: string; text: string }) => {
          if (msg.type === "weather") {
            setTemp(msg.text)
            figma.closePlugin()
            resolve()
          }
        }
      })
    )
  })

  return (
    <AutoLayout padding={16} fill="#EEF4FF" cornerRadius={8}>
      <Text fontSize={14}>{temp}</Text>
    </AutoLayout>
  )
}

widget.register(WeatherWidget)
```

--------------------------------

### Access Widget Node ID with useWidgetNodeId

Source: https://context7.com/figma/widget-typings/llms.txt

Use `useWidgetNodeId` to get the current widget's node ID. This is essential for interacting with the Figma plugin API, such as using `figma.getNodeById`. Ensure it's only called within event handlers or effects, not during rendering.

```tsx
const { widget } = figma
const { Text, useWidgetNodeId } = widget

function CloningWidget() {
  const widgetId = useWidgetNodeId()

  return (
    <Text
      fontSize={16}
      fill="#0055BB"
      padding={12}
      onClick={() => {
        // Safe to use figma API inside event handler
        const widgetNode = figma.getNodeById(widgetId) as WidgetNode
        const clone = widgetNode.clone()

        widgetNode.parent!.appendChild(clone)
        clone.x = widgetNode.x + widgetNode.width + 32
        clone.y = widgetNode.y

        figma.notify("Widget cloned!")
      }}
    >
      Duplicate me →
    </Text>
  )
}

widget.register(CloningWidget)
```

--------------------------------

### `useStickableHost`

Source: https://context7.com/figma/widget-typings/llms.txt

Registers a widget as a host that can receive stickables (stamps, other stickable widgets). Called when stickables are attached or detached. This is specific to FigJam.

```APIDOC
## `useStickableHost` — Stickable Host Widget (FigJam only)

*(FigJam only)* Registers a widget as a host that can receive stickables (stamps, other stickable widgets). Called when stickables are attached or detached.

```tsx
const { widget } = figma
const { AutoLayout, Text, useSyncedState, useStickableHost, useWidgetNodeId } = widget

function VoteCollectorWidget() {
  const [votes, setVotes] = useSyncedState<Record<string, number>>("votes", {})
  const widgetId = useWidgetNodeId()

  useStickableHost(() => {
    const node = figma.getNodeById(widgetId) as WidgetNode
    if (!node) return

    const tally: Record<string, number> = {}
    for (const stuck of node.stuckNodes) {
      if (stuck?.type !== "STAMP") continue
      tally[stuck.name] = (tally[stuck.name] ?? 0) + 1
    }
    setVotes(tally)
  })

  const entries = Object.entries(votes)

  return (
    <AutoLayout
      direction="vertical"
      padding={16}
      spacing={8}
      fill="#FFFFFF"
      stroke="#DDDDDD"
      width={240}
      minHeight={100}
      cornerRadius={8}
    >
      <Text fontSize={14} fontWeight="bold">Stamp Votes</Text>
      {entries.length === 0
        ? <Text fontSize={12} fill="#AAAAAA">Drop stamps here to vote</Text>
        : entries.map(([name, count]) => (
            <Text key={name} fontSize={12}>{name}: {count}</Text>
          ))
      }
    </AutoLayout>
  )
}

widget.register(VoteCollectorWidget)
```
```

--------------------------------

### Define Solid, Gradient, and Image Paints

Source: https://context7.com/figma/widget-typings/llms.txt

Specifies how a component's surface is painted. Supports solid colors, linear/radial gradients, and image fills with various scaling options.

```ts
const solidFill: WidgetJSX.SolidPaint = {
  type: "solid",
  color: "#FF5500",
  opacity: 0.9,
  blendMode: "multiply",
}

const gradientFill: WidgetJSX.GradientPaint = {
  type: "gradient-linear",
  gradientHandlePositions: [{ x: 0, y: 0 }, { x: 1, y: 1 }, { x: 0, y: 1 }],
  gradientStops: [
    { position: 0, color: { r: 0.2, g: 0.4, b: 1, a: 1 } },
    { position: 1, color: { r: 0.9, g: 0.1, b: 0.5, a: 1 } },
  ],
}

const imageFill: WidgetJSX.ImagePaint = {
  type: "image",
  src: "https://example.com/photo.jpg",
  scaleMode: "fill",
}
```

--------------------------------

### `usePropertyMenu` — Widget Property Menu

Source: https://context7.com/figma/widget-typings/llms.txt

Attaches a property menu to the widget, which appears when the widget is selected. It supports various interactive elements like action buttons, color selectors, dropdowns, toggles, separators, and external links.

```APIDOC
## `usePropertyMenu` — Widget Property Menu

Attaches a property menu to the widget shown when the widget is selected. Supports action buttons, color selectors, dropdowns, toggles, separators, and external links.

```tsx
const { widget } = figma
const { AutoLayout, Text, useSyncedState, usePropertyMenu } = widget

type Theme = "light" | "dark"
type Size = "small" | "medium" | "large"

function ThemedWidget() {
  const [theme, setTheme] = useSyncedState<Theme>("theme", "light")
  const [size, setSize] = useSyncedState<Size>("size", "medium")
  const [isLocked, setIsLocked] = useSyncedState("locked", false)

  usePropertyMenu(
    [
      {
        itemType: "color-selector",
        propertyName: "theme",
        tooltip: "Background theme",
        selectedOption: theme === "light" ? "#FFFFFF" : "#1E1E1E",
        options: [
          { option: "#FFFFFF", tooltip: "Light" },
          { option: "#1E1E1E", tooltip: "Dark" },
        ],
      },
      { itemType: "separator" },
      {
        itemType: "dropdown",
        propertyName: "size",
        tooltip: "Widget size",
        selectedOption: size,
        options: [
          { option: "small", label: "Small" },
          { option: "medium", label: "Medium" },
          { option: "large", label: "Large" },
        ],
      },
      {
        itemType: "toggle",
        propertyName: "locked",
        tooltip: "Lock content",
        isToggled: isLocked,
        icon: `<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"16\" height=\"16\" viewBox=\"0 0 16 16\"><rect x=\"3\" y=\"7\" width=\"10\" height=\"8\" rx=\"1"/><path d=\"M5 7V5a3 3 0 016 0v2"/></svg>`,
      },
      {
        itemType: "link",
        propertyName: "docs",
        tooltip: "Open docs",
        href: "https://developers.figma.com/docs/widgets",
        icon: null,
      },
    ],
    ({ propertyName, propertyValue }) => {
      if (propertyName === "theme") {
        setTheme(propertyValue === "#FFFFFF" ? "light" : "dark")
      } else if (propertyName === "size") {
        setSize(propertyValue as Size)
      } else if (propertyName === "locked") {
        setIsLocked(!isLocked)
      }
    }
  )

  const bg = theme === "light" ? "#FFFFFF" : "#1E1E1E"
  const fg = theme === "light" ? "#111111" : "#EEEEEE"
  const paddingMap = { small: 8, medium: 16, large: 24 }

  return (
    <AutoLayout fill={bg} padding={paddingMap[size]} cornerRadius={8} stroke="#CCCCCC">
      <Text fill={fg} fontSize={14}>
        {isLocked ? "🔒 Locked" : "✏️ Editable"} — {theme} / {size}
      </Text>
    </AutoLayout>
  )
}

widget.register(ThemedWidget)
```
```

--------------------------------

### Import Specific Widget API Types

Source: https://context7.com/figma/widget-typings/llms.txt

Import specific types from the standalone entry point if explicit imports are needed, otherwise types are globally available.

```ts
import type { WidgetJSXFrameProps, AutoLayoutProps } from "@figma/widget-typings/widget-api-standalone"
```

--------------------------------

### Register Widget as a Stickable Host

Source: https://context7.com/figma/widget-typings/llms.txt

Use `useStickableHost` to designate a widget as a host capable of receiving stickables (stamps or other stickable widgets) in FigJam. This hook is called when stickables are attached or detached, allowing you to manage and react to these events.

```tsx
const { widget } = figma
const { AutoLayout, Text, useSyncedState, useStickableHost, useWidgetNodeId } = widget

function VoteCollectorWidget() {
  const [votes, setVotes] = useSyncedState<Record<string, number>>("votes", {})
  const widgetId = useWidgetNodeId()

  useStickableHost(() => {
    const node = figma.getNodeById(widgetId) as WidgetNode
    if (!node) return

    const tally: Record<string, number> = {}
    for (const stuck of node.stuckNodes) {
      if (stuck?.type !== "STAMP") continue
      tally[stuck.name] = (tally[stuck.name] ?? 0) + 1
    }
    setVotes(tally)
  })

  const entries = Object.entries(votes)

  return (
    <AutoLayout
      direction="vertical"
      padding={16}
      spacing={8}
      fill="#FFFFFF"
      stroke="#DDDDDD"
      width={240}
      minHeight={100}
      cornerRadius={8}
    >
      <Text fontSize={14} fontWeight="bold">Stamp Votes</Text>
      {entries.length === 0
        ? <Text fontSize={12} fill="#AAAAAA">Drop stamps here to vote</Text>
        : entries.map(([name, count]) => (
            <Text key={name} fontSize={12}>{name}: {count}</Text>
          ))
      }
    </AutoLayout>
  )
}

widget.register(VoteCollectorWidget)
```

--------------------------------

### Configure tsconfig.json for Figma Widgets

Source: https://context7.com/figma/widget-typings/llms.txt

Configure your tsconfig.json to include the `@figma` type roots and set up JSX compilation for Figma widgets.

```json
{
  "compilerOptions": {
    "typeRoots": [
      "./node_modules/@types",
      "./node_modules/@figma"
    ],
    "jsx": "react",
    "jsxFactory": "figma.widget.h"
  }
}
```

--------------------------------

### Implement Stickable Widget Behavior

Source: https://context7.com/figma/widget-typings/llms.txt

The `useStickable` hook makes a widget behave like a stamp in FigJam, sticking to other nodes. It accepts an optional callback that triggers when the widget's stuck node changes, allowing for visual feedback based on the host node's type.

```tsx
const { widget } = figma
const { Rectangle, useSyncedState, useStickable, useWidgetNodeId } = widget

function StickyIndicatorWidget() {
  const [color, setColor] = useSyncedState("color", "#888888")
  const widgetId = useWidgetNodeId()

  useStickable(() => {
    const node = figma.getNodeById(widgetId) as WidgetNode
    const host = node?.stuckTo

    if (!host) {
      setColor("#888888") // Not stuck — grey
      return
    }

    switch (host.type) {
      case "STICKY": setColor("#FF4444"); break       // Red for sticky notes
      case "SHAPE_WITH_TEXT": setColor("#44BB44"); break // Green for shapes
      default: setColor("#4488FF"); break              // Blue for anything else
    }
  })

  return (
    <Rectangle
      width={48}
      height={48}
      fill={color}
      cornerRadius={24}
      tooltip="Drag me onto a node"
    />
  )
}

widget.register(StickyIndicatorWidget)
```

--------------------------------

### widget.register

Source: https://context7.com/figma/widget-typings/llms.txt

The main entry point for registering a widget component. This function is called once with the root functional component and is re-invoked on every state update.

```APIDOC
## widget.register — Register a Widget Component

The main entry point for every widget. Called once with the root functional component; re-invoked on every state update.

```tsx
const { widget } = figma
const { AutoLayout, Text, useSyncedState } = widget

function CounterWidget() {
  const [count, setCount] = useSyncedState("count", 0)

  return (
    <AutoLayout
      direction="vertical"
      padding={24}
      spacing={12}
      cornerRadius={8}
      fill="#FFFFFF"
      stroke="#E0E0E0"
    >
      <Text fontSize={24} fontWeight="bold" fill="#333333">
        Count: {count}
      </Text>
      <Text
        fontSize={14}
        fill="#0066CC"
        onClick={() => setCount(count + 1)}
      >
        Increment
      </Text>
    </AutoLayout>
  )
}

widget.register(CounterWidget)
```
```

--------------------------------

### Configure tsconfig.json for Figma Typings

Source: https://github.com/figma/widget-typings/blob/main/README.md

Configure `tsconfig.json` to include type definitions from `./node_modules/@types` and `./node_modules/@figma`. This ensures TypeScript can find the plugin and widget typings, which are hosted separately from standard DefinitelyTyped packages.

```json
{
    "compilerOptions": {
        "typeRoots": [
            "./node_modules/@types",
            "./node_modules/@figma"
        ]
    }
}
```

--------------------------------

### Configure AutoLayout for Flex Container

Source: https://context7.com/figma/widget-typings/llms.txt

The `AutoLayout` component provides flexbox-like layout capabilities for Figma widgets. Configure its properties such as direction, spacing, padding, alignment, and visual styles to create responsive and structured UI elements.

```tsx
const { AutoLayout, Text, Rectangle } = figma.widget

function LayoutDemo() {
  return (
    <AutoLayout
      direction="horizontal"
      spacing={12}
      padding={{ vertical: 16, horizontal: 24 }}
      verticalAlignItems="center"
      horizontalAlignItems="center"
      fill="#F0F4FF"
      stroke="#AABBDD"
      strokeWidth={1}
      cornerRadius={12}
      width="hug-contents"
      wrap={true}
      effect={{ type: "drop-shadow", color: "#00000022", offset: { x: 0, y: 2 }, blur: 8 }}
    >
      <Rectangle width={32} height={32} fill="#5566FF" cornerRadius={4} />
      <Text fontSize={14} fontWeight="medium" fill="#223366">Figma Widget</Text>
    </AutoLayout>
  )
}
```

--------------------------------

### useSyncedMap

Source: https://context7.com/figma/widget-typings/llms.txt

A hook for creating a map-based state store that allows for concurrent-safe updates to individual keys. It's ideal for collaborative widgets where multiple users might modify the same data simultaneously.

```APIDOC
## `useSyncedMap` — Concurrent-Safe Key-Value State

A map-based state store where individual keys are updated last-writer-wins, preventing full overwrites when multiple users edit simultaneously. Ideal for collaborative widgets.

### `SyncedMap` Interface Methods

| Method | Signature | Description |
|--------|-----------|-------------|
| `has` | `(key: string) => boolean` | Returns whether a key exists |
| `get` | `(key: string) => T \| undefined` | Returns value for the key |
| `set` | `(key: string, value: T) => void` | Persists a key/value pair |
| `delete` | `(key: string) => void` | Removes a key |
| `keys` | `() => string[]` | Returns all keys |
| `values` | `() => T[]` | Returns all values |
| `entries` | `() => [string, T][]` | Returns key-value tuples |
| `size` | `readonly number` | Returns number of keys |
```

--------------------------------

### `useStickable`

Source: https://context7.com/figma/widget-typings/llms.txt

Makes a widget behave like a stamp, sticking to other nodes when dragged over them. Accepts an optional callback triggered when the widget's stuck node changes. This is specific to FigJam.

```APIDOC
## `useStickable` — Stickable Widget (FigJam only)

*(FigJam only)* Makes a widget behave like a stamp — it sticks to other nodes when dragged over them. Accepts an optional callback triggered when the widget's stuck node changes.

```tsx
const { widget } = figma
const { Rectangle, useSyncedState, useStickable, useWidgetNodeId } = widget

function StickyIndicatorWidget() {
  const [color, setColor] = useSyncedState("color", "#888888")
  const widgetId = useWidgetNodeId()

  useStickable(() => {
    const node = figma.getNodeById(widgetId) as WidgetNode
    const host = node?.stuckTo

    if (!host) {
      setColor("#888888") // Not stuck — grey
      return
    }

    switch (host.type) {
      case "STICKY": setColor("#FF4444"); break       // Red for sticky notes
      case "SHAPE_WITH_TEXT": setColor("#44BB44"); break // Green for shapes
      default: setColor("#4488FF"); break              // Blue for anything else
    }
  })

  return (
    <Rectangle
      width={48}
      height={48}
      fill={color}
      cornerRadius={24}
      tooltip="Drag me onto a node"
    />
  )
}

widget.register(StickyIndicatorWidget)
```
```

--------------------------------

### Create an Editable Text Field with Input

Source: https://context7.com/figma/widget-typings/llms.txt

Utilize the Input component for creating editable text fields. Supports placeholders, custom styling, and multiline input behavior. Use useSyncedState to manage the input's value.

```tsx
const { AutoLayout, Input, useSyncedState } = figma.widget

function EditableWidget() {
  const [text, setText] = useSyncedState("text", "")

  return (
    <AutoLayout padding={16} fill="#FFFFFF" stroke="#DDDDDD" cornerRadius={8}>
      <Input
        value={text}
        placeholder="Type something..."
        placeholderProps={{ fill: "#AAAAAA", italic: true }}
        onTextEditEnd={(e) => setText(e.characters)}
        fontSize={14}
        fill="#111111"
        width={240}
        inputBehavior="multiline"
        inputFrameProps={{ padding: 8, fill: "#FAFAFA", cornerRadius: 4 }}
      />
    </AutoLayout>
  )
}
```

--------------------------------

### Convert Color Map to Widget Options

Source: https://context7.com/figma/widget-typings/llms.txt

Use `colorMapToOptions` to transform a `ColorPalette` map into an array of `WidgetPropertyMenuColorSelectorOption[]`. This is useful for populating color-selector property menus in FigJam widgets.

```tsx
const { widget } = figma
const { colorMapToOptions, useSyncedState, usePropertyMenu, AutoLayout, Text } = widget

function FigJamColorWidget() {
  const [color, setColor] = useSyncedState(
    "color",
    figma.constants.colors.figJamBase.black
  )

  usePropertyMenu(
    [
      {
        itemType: "color-selector",
        propertyName: "color",
        tooltip: "Pick a color",
        selectedOption: color,
        options: [
          // Spread the official FigJam palette and add a custom color
          ...colorMapToOptions(figma.constants.colors.figJamBase),
          { option: "#FF69B4", tooltip: "Hot Pink" },
        ],
      },
    ],
    ({ propertyName, propertyValue }) => {
      if (propertyName === "color") setColor(propertyValue!)
    }
  )

  return (
    <AutoLayout padding={20} fill={color} cornerRadius={8}>
      <Text fontSize={14} fill="#FFFFFF">{color}</Text>
    </AutoLayout>
  )
}

widget.register(FigJamColorWidget)
```

--------------------------------

### useEffect

Source: https://context7.com/figma/widget-typings/llms.txt

A hook for managing side effects and event handlers within a widget. It runs a callback after each render and supports returning a cleanup function. This is useful for setting up event listeners, fetching data, and synchronizing state.

```APIDOC
## `useEffect` — Side Effects and Event Handlers

Runs a callback after every render. Supports returning a cleanup function. Used for setting up event listeners, data fetching with `waitForTask`, and syncing state from the plugin API.
```

--------------------------------

### useSyncedState

Source: https://context7.com/figma/widget-typings/llms.txt

A hook similar to React's `useState` that persists state on the widget node and synchronizes it across all clients. It accepts a unique key, a default value, or a lazy initializer function.

```APIDOC
## useSyncedState — Synchronized Widget State

React `useState`-like hook where state is persisted on the widget node and automatically synchronized across all clients. Accepts a unique key, a default value, or a lazy initializer function.

```tsx
const { widget } = figma
const { Text, AutoLayout, useSyncedState } = widget

function TodoWidget() {
  // Simple value state
  const [title, setTitle] = useSyncedState("title", "My Todo List")

  // Lazy initializer for plugin API calls not allowed during render
  const [creator, setCreator] = useSyncedState("creator", () => {
    return figma.currentUser?.name ?? "Unknown"
  })

  // Functional update using previous value
  const [completedCount, setCompletedCount] = useSyncedState("completedCount", 0)

  return (
    <AutoLayout direction="vertical" padding={16} spacing={8} fill="#FAFAFA">
      <Text fontSize={18} fontWeight="semi-bold">{title}</Text>
      <Text fontSize={12} fill="#888888">Created by: {creator}</Text>
      <Text
        fontSize={14}
        fill="#22AA44"
        onClick={() => setCompletedCount(prev => prev + 1)}
      >
        Complete task ({completedCount} done)
      </Text>
    </AutoLayout>
  )
}

widget.register(TodoWidget)
```
```

--------------------------------

### `colorMapToOptions`

Source: https://context7.com/figma/widget-typings/llms.txt

Converts a `ColorPalette` map into an array of `WidgetPropertyMenuColorSelectorOption[]` for use in a color-selector property menu item. This is specific to FigJam.

```APIDOC
## `colorMapToOptions` — FigJam Color Palette Helper

*(FigJam only)* Converts a `ColorPalette` map (e.g., `figma.constants.colors.figJamBase`) into an array of `WidgetPropertyMenuColorSelectorOption[]` for use in a color-selector property menu item.

```tsx
const { widget } = figma
const { colorMapToOptions, useSyncedState, usePropertyMenu, AutoLayout, Text } = widget

function FigJamColorWidget() {
  const [color, setColor] = useSyncedState(
    "color",
    figma.constants.colors.figJamBase.black
  )

  usePropertyMenu(
    [
      {
        itemType: "color-selector",
        propertyName: "color",
        tooltip: "Pick a color",
        selectedOption: color,
        options: [
          // Spread the official FigJam palette and add a custom color
          ...colorMapToOptions(figma.constants.colors.figJamBase),
          { option: "#FF69B4", tooltip: "Hot Pink" },
        ],
      },
    ],
    ({ propertyName, propertyValue }) => {
      if (propertyName === "color") setColor(propertyValue!)
    }
  )

  return (
    <AutoLayout padding={20} fill={color} cornerRadius={8}>
      <Text fontSize={14} fill="#FFFFFF">{color}</Text>
    </AutoLayout>
  )
}

widget.register(FigJamColorWidget)
```
```

--------------------------------

### Define Widget Padding in TypeScript

Source: https://context7.com/figma/widget-typings/llms.txt

Use WidgetJSX.Padding to define uniform, per-side, or vertical/horizontal padding values for widgets.

```typescript
// Uniform padding
const p1: WidgetJSX.Padding = 16
```

```typescript
// Per-side padding
const p2: WidgetJSX.Padding = { top: 8, right: 16, bottom: 8, left: 16 }
```

```typescript
// Vertical/horizontal shorthand
const p3: WidgetJSX.Padding = { vertical: 12, horizontal: 24 }
```

--------------------------------

### `AutoLayout` Component

Source: https://context7.com/figma/widget-typings/llms.txt

A flex container component for arranging child elements within a Figma widget. It supports various layout properties like direction, spacing, padding, alignment, and styling.

```APIDOC
### `AutoLayout` — Flex Container

```tsx
const { AutoLayout, Text, Rectangle } = figma.widget

function LayoutDemo() {
  return (
    <AutoLayout
      direction="horizontal"
      spacing={12}
      padding={{ vertical: 16, horizontal: 24 }}
      verticalAlignItems="center"
      horizontalAlignItems="center"
      fill="#F0F4FF"
      stroke="#AABBDD"
      strokeWidth={1}
      cornerRadius={12}
      width="hug-contents"
      wrap={true}
      effect={{ type: "drop-shadow", color: "#00000022", offset: { x: 0, y: 2 }, blur: 8 }}
    >
      <Rectangle width={32} height={32} fill="#5566FF" cornerRadius={4} />
      <Text fontSize={14} fontWeight="medium" fill="#223366">Figma Widget</Text>
    </AutoLayout>
  )
}
```
```

--------------------------------

### Define Drop Shadow and Layer Blur Effects

Source: https://context7.com/figma/widget-typings/llms.txt

Applies visual effects to components. Supports drop shadows with configurable color, offset, blur, and spread, as well as layer blurs.

```ts
const shadow: WidgetJSX.DropShadowEffect = {
  type: "drop-shadow",
  color: { r: 0, g: 0, b: 0, a: 0.2 },
  offset: { x: 0, y: 4 },
  blur: 12,
  spread: 2,
  visible: true,
}

const blur: WidgetJSX.BlurEffect = {
  type: "layer-blur",
  blur: 8,
  visible: true,
}
```

--------------------------------

### Use SyncedMap for Collaborative Key-Value State

Source: https://context7.com/figma/widget-typings/llms.txt

Use `useSyncedMap` to manage key-value state that updates concurrently. Individual key updates are last-writer-wins, suitable for collaborative widgets.

```tsx
const { widget } = figma
const { Rectangle, AutoLayout, Text, useSyncedMap, useWidgetNodeId } = widget

function VotingWidget() {
  // Each user's session ID maps to their vote choice
  const votes = useSyncedMap<string>("userVotes")
  const widgetId = useWidgetNodeId()

  const tallyVotes = (option: string)
    => votes.values().filter(v => v === option).length

  return (
    <AutoLayout direction="vertical" padding={20} spacing={12} fill="#FFFFFF">
      <Text fontSize={16} fontWeight="bold">Cast your vote</Text>

      {["Option A", "Option B", "Option C"].map(option => (
        <AutoLayout
          key={option}
          direction="horizontal"
          spacing={8}
          verticalAlignItems="center"
          padding={{ vertical: 8, horizontal: 12 }}
          fill="#F0F0F0"
          cornerRadius={4}
          onClick={() => {
            const sessionId = figma.activeUsers[0].sessionId.toString()
            votes.set(sessionId, option)
          }}
        >
          <Text fontSize={14}>{option}</Text>
          <Text fontSize={12} fill="#666666">({tallyVotes(option)} votes)</Text>
        </AutoLayout>
      ))}

      <Text
        fontSize={12}
        fill="#CC3333"
        onClick={() => {
          const sessionId = figma.activeUsers[0].sessionId.toString()
          votes.delete(sessionId)
        }}
      >
        Clear my vote
      </Text>
    </AutoLayout>
  )
}

widget.register(VotingWidget)
```

--------------------------------

### `waitForTask` — Async Work in Widgets

Source: https://context7.com/figma/widget-typings/llms.txt

Ensures a widget is not terminated while an asynchronous operation is in progress. This function must be used within a `useEffect` hook.

```APIDOC
## `waitForTask` — Async Work in Widgets

Prevents the widget from being terminated while an async operation (network request, timer, UI interaction) is pending. Must be used inside `useEffect`.

```tsx
const { widget } = figma
const { Text, AutoLayout, useEffect, waitForTask, useSyncedState } = widget

function WeatherWidget() {
  const [temp, setTemp] = useSyncedState<string>("temperature", "Loading...")
  const [city, setCity] = useSyncedState("city", "San Francisco")

  useEffect(() => {
    waitForTask(
      new Promise<void>(resolve => {
        // Show UI iframe to fetch data from the network
        figma.showUI(`
          <script>
            fetch('https://wttr.in/${city}?format=3')
              .then(r => r.text())
              .then(text => parent.postMessage({ pluginMessage: { type: 'weather', text } }, '*'))
          </script>
        `, { visible: false })

        figma.ui.onmessage = (msg: { type: string; text: string }) => {
          if (msg.type === "weather") {
            setTemp(msg.text)
            figma.closePlugin()
            resolve()
          }
        }
      })
    )
  })

  return (
    <AutoLayout padding={16} fill="#EEF4FF" cornerRadius={8}>
      <Text fontSize={14}>{temp}</Text>
    </AutoLayout>
  )
}

widget.register(WeatherWidget)
```
```

--------------------------------

### Register a Counter Widget Component

Source: https://context7.com/figma/widget-typings/llms.txt

Register the root functional component for a widget using `widget.register`. This component will be re-invoked on state updates. It uses `useSyncedState` for managing and synchronizing widget state.

```tsx
const { widget } = figma
const { AutoLayout, Text, useSyncedState } = widget

function CounterWidget() {
  const [count, setCount] = useSyncedState("count", 0)

  return (
    <AutoLayout
      direction="vertical"
      padding={24}
      spacing={12}
      cornerRadius={8}
      fill="#FFFFFF"
      stroke="#E0E0E0"
    >
      <Text fontSize={24} fontWeight="bold" fill="#333333">
        Count: {count}
      </Text>
      <Text
        fontSize={14}
        fill="#0066CC"
        onClick={() => setCount(count + 1)}
      >
        Increment
      </Text>
    </AutoLayout>
  )
}

widget.register(CounterWidget)
```

--------------------------------

### Handle Side Effects with useEffect

Source: https://context7.com/figma/widget-typings/llms.txt

Use `useEffect` to run callbacks after renders for side effects like setting up event listeners or fetching data. It supports cleanup functions, which are crucial for preventing memory leaks by removing listeners before the next effect runs.

```tsx
const { widget } = figma
const { Text, AutoLayout, useEffect, waitForTask, useSyncedState } = widget

function SelectionTrackerWidget() {
  const [selectionCount, setSelectionCount] = useSyncedState("selectionCount", () =>
    figma.currentPage.selection.length
  )
  const [lastMessage, setLastMessage] = useSyncedState("lastMessage", "")

  useEffect(() => {
    // Set up selection change listener; clean it up on next effect run
    const onSelectionChange = () => {
      setSelectionCount(figma.currentPage.selection.length)
    }
    figma.on("selectionchange", onSelectionChange)

    // Handle UI messages
    figma.ui.onmessage = (msg: { type: string; text: string }) => {
      if (msg.type === "update-text") {
        setLastMessage(msg.text)
      }
    }

    // Cleanup: remove listener before next effect
    return () => {
      figma.off("selectionchange", onSelectionChange)
    }
  })

  return (
    <AutoLayout direction="vertical" padding={16} spacing={8} fill="#F9F9F9">
      <Text fontSize={14}>Selected nodes: {selectionCount}</Text>
      {lastMessage ? <Text fontSize={12} fill="#555">{lastMessage}</Text> : null}
    </AutoLayout>
  )
}

widget.register(SelectionTrackerWidget)
```

--------------------------------

### Use `useSyncedState` for Synchronized Widget State

Source: https://context7.com/figma/widget-typings/llms.txt

Utilize the `useSyncedState` hook, similar to React's `useState`, for persisting and synchronizing widget state across all clients. It accepts a unique key, a default value, or a lazy initializer.

```tsx
const { widget } = figma
const { Text, AutoLayout, useSyncedState } = widget

function TodoWidget() {
  // Simple value state
  const [title, setTitle] = useSyncedState("title", "My Todo List")

  // Lazy initializer for plugin API calls not allowed during render
  const [creator, setCreator] = useSyncedState("creator", () => {
    return figma.currentUser?.name ?? "Unknown"
  })

  // Functional update using previous value
  const [completedCount, setCompletedCount] = useSyncedState("completedCount", 0)

  return (
    <AutoLayout direction="vertical" padding={16} spacing={8} fill="#FAFAFA">
      <Text fontSize={18} fontWeight="semi-bold">{title}</Text>
      <Text fontSize={12} fill="#888888">Created by: {creator}</Text>
      <Text
        fontSize={14}
        fill="#22AA44"
        onClick={() => setCompletedCount(prev => prev + 1)}
      >
        Complete task ({completedCount} done)
      </Text>
    </AutoLayout>
  )
}

widget.register(TodoWidget)
```

--------------------------------

### Display Images and SVGs with Image and SVG Components

Source: https://context7.com/figma/widget-typings/llms.txt

Embed images from URLs or SVG code using the Image and SVG components. Supports sizing, corner radius, and tooltips for interactive elements.

```tsx
const { AutoLayout, Image, SVG } = figma.widget

const ICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
  <circle cx="12" cy="12" r="10" fill="#5566FF"/>
  <text x="12" y="16" text-anchor="middle" fill="white" font-size="12">W</text>
</svg>`

function MediaWidget() {
  return (
    <AutoLayout direction="horizontal" spacing={12} padding={16}>
      <Image
        src="https://picsum.photos/seed/figma/80/80"
        width={80}
        height={80}
        cornerRadius={8}
        tooltip="Placeholder image"
      />
      <SVG
        src={ICON_SVG}
        width={48}
        height={48}
        tooltip="Widget icon"
      />
    </AutoLayout>
  )
}
```

--------------------------------

### Draw Lines with Line Component

Source: https://context7.com/figma/widget-typings/llms.txt

Use the Line component to render lines. Supports custom stroke color, width, dash patterns, and length. Can be set to 'fill-parent' for dynamic sizing.

```tsx
const { AutoLayout, Line } = figma.widget

function DividerWidget() {
  return (
    <AutoLayout direction="vertical" spacing={12} padding={16} width={200}>
      <Line
        stroke="#CCCCCC"
        strokeWidth={1}
        length="fill-parent"
        strokeDashPattern={[4, 4]}
      />
      <Line
        stroke="#FF3300"
        strokeWidth={2}
        length={100}
        strokeCap="arrow-equilateral"
        rotation={45}
      />
    </AutoLayout>
  )
}
```

--------------------------------

### Create Shapes with Rectangle and Ellipse

Source: https://context7.com/figma/widget-typings/llms.txt

Draw basic shapes like rectangles and ellipses using dedicated components. Supports fills (solid, gradient), strokes, corner radius, and effects like inner shadows.

```tsx
const { AutoLayout, Rectangle, Ellipse } = figma.widget

function ShapesWidget() {
  return (
    <AutoLayout direction="horizontal" spacing={16} padding={20}>
      <Rectangle
        width={80}
        height={80}
        fill={{ type: "gradient-linear",
          gradientHandlePositions: [{ x: 0, y: 0 }, { x: 1, y: 0 }, { x: 0, y: 1 }],
          gradientStops: [
            { position: 0, color: { r: 0.3, g: 0.4, b: 1, a: 1 } },
            { position: 1, color: { r: 0.9, g: 0.3, b: 0.8, a: 1 } },
          ]
        }}
        cornerRadius={{ topLeft: 16, topRight: 4, bottomLeft: 4, bottomRight: 16 }}
        stroke="#333366"
        strokeWidth={2}
        strokeAlign="inside"
      />
      <Ellipse
        width={80}
        height={80}
        fill="#FF6644"
        arcData={{ startingAngle: 0, endingAngle: Math.PI * 1.5, innerRadius: 0.5 }}
        effect={{ type: "inner-shadow", color: "#00000044", offset: { x: 2, y: 2 }, blur: 4 }}
      />
    </AutoLayout>
  )
}
```

--------------------------------

### Define RGBA and Hex Colors

Source: https://context7.com/figma/widget-typings/llms.txt

Represents colors using RGBA objects or hex color codes. Used for fills, strokes, and text colors within widget components.

```ts
// RGBA color object
const red: WidgetJSX.Color = { r: 1, g: 0, b: 0, a: 1 }

// Hex shorthand also accepted where Color is expected
const blue: HexCode = "#0044FF"
```

--------------------------------

### useWidgetNodeId

Source: https://context7.com/figma/widget-typings/llms.txt

A hook that provides the ID of the current widget node. This ID can be used with the Figma plugin API, such as `figma.getNodeById`, to interact with the widget's node. It should only be called within event handlers or effects, not during rendering.

```APIDOC
## `useWidgetNodeId` — Access the Widget's Node ID

Returns the ID of the current widget node for use inside event handlers with the plugin API (e.g., `figma.getNodeById`). Must not be called during rendering; use only inside event handlers or effects.
```

--------------------------------

### Render Rich Text with Text and Span

Source: https://context7.com/figma/widget-typings/llms.txt

Use the Text and Span components to render styled text, including bold, italic, and underlined elements. Supports custom fonts, sizes, and colors.

```tsx
const { Text, Span } = figma.widget

function RichTextDemo() {
  return (
    <Text
      fontSize={16}
      fontFamily="Inter"
      fontWeight={500}
      fill="#111111"
      horizontalAlignText="left"
      lineHeight={1.5}
      letterSpacing={0.2}
      truncate={3}
      href="https://figma.com"
    >
      Normal text with{" "}
      <Span fontWeight="bold" fill="#FF3300">bold red</Span>
      {" "}and{" "}
      <Span italic={true} textDecoration="underline">italic underline</Span>
    </Text>
  )
}
```

--------------------------------

### Handle Click Events with Coordinates in Figma Widgets

Source: https://context7.com/figma/widget-typings/llms.txt

The onClick handler for components like Rectangle receives a WidgetClickEvent object containing canvas-absolute and component-relative coordinates.

```tsx
<Rectangle
  width={100}
  height={100}
  fill="#5566FF"
  onClick={(event: WidgetClickEvent) => {
    // Canvas-absolute coordinates (same units as node.x, node.y)
    console.log(`Canvas: (${event.canvasX}, ${event.canvasY})`)
    // Coordinates relative to the clicked component
    console.log(`Offset: (${event.offsetX}, ${event.offsetY})`)
  }}
/>
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.