### Component Configuration Example (JSON)

Source: https://github.com/redongreen/uspec/blob/main/api/agent-api-instruction.md

Provides examples of common component configurations, demonstrating specific use cases. Each example includes variant properties for live preview instantiation and relevant component properties with optional notes.

```json
{
  "title": "Example 1 — Primary button",
  "variantProperties": { "Hierarchy": "Primary", "Size": "M 16", "Leading icon#43744:0": true },
  "properties": [
    { "property": "label", "value": "\"Submit\"", "notes": "Action text" },
    { "property": "variant", "value": "primary", "notes": "–" }
  ]
}
```

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

### Button Configuration Examples

Source: https://github.com/redongreen/uspec/blob/main/api/agent-api-instruction.md

Illustrates various ways to configure the 'Button' component, showcasing different combinations of properties and their visual outcomes. Examples include primary, background-safe, menu, and danger buttons with specific icon and label settings.

```json
{
  "configurationExamples": [
    {
      "title": "Example 1 — Primary button",
      "variantProperties": { "Hierarchy": "Primary", "Size": "M 16", "Behvaior": "Hug", "Leading icon#43744:0": true, "Tailing icon#43744:12": false, "Label#43744:24": true },
      "properties": [
        { "property": "label", "value": "\"Awww!\"", "notes": "Text string" },
        { "property": "leadingArtwork", "value": "chevron_down_small", "notes": "Icon from iconography library" }
      ]
    },
    {
      "title": "Example 2 — Background safe button",
      "variantProperties": { "Hierarchy": "Tertiary", "Size": "L 18", "Behvaior": "Hug", "Leading icon#43744:0": true, "Tailing icon#43744:12": false, "Label#43744:24": false },
      "properties": [
        { "property": "size", "value": "large", "notes": "–" },
        { "property": "shape", "value": "rounded", "notes": "–" },
        { "property": "variant", "value": "tertiary", "notes": "–" },
        { "property": "layout", "value": "iconOnly", "notes": "–" },
        { "property": "backgroundSafe", "value": "true", "notes": "Icon from iconography library" },
        { "property": "leadingArtwork", "value": "chevron_down_small", "notes": "Icon from iconography library" }
      ]
    },
    {
      "title": "Example 3 — Menu button (Desktop only)",
      "variantProperties": { "Hierarchy": "Secondary", "Size": "S 14", "Behvaior": "Hug", "Leading icon#43744:0": false, "Tailing icon#43744:12": true, "Label#43744:24": true },
      "properties": [
        { "property": "behavior", "value": "popOver", "notes": "–" },
        { "property": "size", "value": "small", "notes": "–" },
        { "property": "shape", "value": "rounded", "notes": "–" },
        { "property": "variant", "value": "secondary", "notes": "–" },
        { "property": "label", "value": "\"Sort by\"", "notes": "–" },
        { "property": "trailingArtwork", "value": "chevron_down_small", "notes": "Indicates dropdown menu" }
      ]
    },
    {
      "title": "Example 4 — Danger button",
      "variantProperties": { "Hierarchy": "Primary", "Size": "L 18", "Behvaior": "Fill", "Leading icon#43744:0": true, "Tailing icon#43744:12": false, "Label#43744:24": true },
      "properties": [
        { "property": "size", "value": "large", "notes": "–" },
        { "property": "variant", "value": "dangerPrimary", "notes": "–" },
        { "property": "widthType", "value": "fill", "notes": "–" },
        { "property": "leadingArtwork", "value": "rocket", "notes": "Icon from iconography library" }
      ]
    }
  ]
}
```

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

### Define Component Specifications in JSON

Source: https://github.com/redongreen/uspec/blob/main/color/agent-color-instruction.md

A collection of JSON schema examples for defining component design specifications. These examples demonstrate how to map UI elements to design tokens for simple components, interactive states, and multi-variant components.

```json
{
  "componentName": "Section heading",
  "renderingStrategy": "A",
  "variants": [
    {
      "name": "Section heading",
      "tables": [
        {
          "name": "Spec",
          "elements": [
            { "element": "Background", "token": "backgroundPrimary", "notes": "Container surface. Optional in code." },
            { "element": "Primary labels", "token": "contentPrimary", "notes": "Main heading text" },
            { "element": "Secondary labels", "token": "contentSecondary", "notes": "Supporting description text" }
          ]
        }
      ]
    }
  ]
}
```

```json
{
  "componentName": "Button",
  "renderingStrategy": "A",
  "variants": [
    {
      "name": "Enabled",
      "tables": [
        {
          "name": "Spec",
          "elements": [
            { "element": "Background", "token": "interactivePrimary", "notes": "Button fill color" },
            { "element": "Label", "token": "contentInversePrimary", "notes": "Button text" }
          ]
        }
      ]
    },
    {
      "name": "Hover",
      "tables": [
        {
          "name": "Spec",
          "elements": [
            { "element": "Background", "token": "interactivePrimaryHover", "notes": "Button fill on hover" },
            { "element": "Label", "token": "contentInversePrimary", "notes": "Button text" }
          ]
        }
      ]
    },
    {
      "name": "Disabled",
      "tables": [
        {
          "name": "Spec",
          "elements": [
            { "element": "Background", "token": "backgroundTertiary", "notes": "Muted fill when disabled" },
            { "element": "Label", "token": "contentStateDisabled", "notes": "Dimmed text when disabled" }
          ]
        }
      ]
    }
  ]
}
```

```json
{
  "componentName": "Checkbox",
  "renderingStrategy": "A",
  "generalNotes": "All variants share the same disabled state styling using contentStateDisabled.",
  "variants": [
    {
      "name": "Default / Enabled",
      "tables": [
        {
          "name": "Spec",
          "elements": [
            { "element": "State layer (backplate)", "token": "none", "notes": "Hover/press feedback overlay. Hidden at rest." },
            { "element": "stroke", "token": "contentTertiary", "notes": "Checkbox border" }
          ]
        }
      ]
    },
    {
      "name": "Default / Hover",
      "tables": [
        {
          "name": "Spec",
          "elements": [
            { "element": "State layer (backplate)", "token": "hoverOverlayAlpha", "notes": "Hover feedback overlay" },
            { "element": "stroke", "token": "contentTertiary", "notes": "Checkbox border" }
          ]
        }
      ]
    },
    {
      "name": "isNegative / Enabled",
      "tables": [
        {
          "name": "Spec",
          "elements": [
            { "element": "State layer (backplate)", "token": "none", "notes": "Hover/press feedback overlay. Hidden at rest." },
            { "element": "stroke", "token": "bigRedContentSecondary", "notes": "Error state border" }
          ]
        }
      ]
    }
  ]
}
```

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

### Documenting Variable Mode Properties

Source: https://github.com/redongreen/uspec/blob/main/api/agent-api-instruction.md

Example of how to structure the JSON output when a component property is controlled by a Figma variable collection rather than a standard variant.

```json
{
  "generalNotes": "Shape is controlled via the 'Button shape' variable collection mode, not a component property. Set at the container/frame level.",
  "mainTable": {
    "properties": [
      { "property": "shape", "values": "rectangular, rounded", "required": false, "default": "rectangular", "notes": "Controlled via 'Button shape' variable mode, not per-instance" }
    ]
  }
}
```

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

### Documenting Variable Mode Variants

Source: https://github.com/redongreen/uspec/blob/main/color/agent-color-instruction.md

JSON structure examples for documenting component variants controlled by Figma variable modes. Strategy A is used for simpler components, while Strategy B is used for complex components with high variant counts.

```json
{
  "variants": [
    {
      "name": "Default",
      "tables": [{ "name": "Spec", "elements": [] }]
    },
    {
      "name": "Success",
      "tables": [{ "name": "Spec", "elements": [] }]
    }
  ]
}
```

```json
{
  "renderingStrategy": "B",
  "stateColumns": ["Enabled", "Hover", "Pressed", "Active", "Disabled"],
  "collectionId": "VariableCollectionId:6006:13874",
  "variants": [
    { "name": "Primary / Gray", "modeId": "6006:2", "tables": [] },
    { "name": "Primary / Orange", "modeId": "6006:3", "tables": [] },
    { "name": "Secondary / Gray", "modeId": "6006:2", "tables": [] }
  ]
}
```

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

### First Run Setup Commands for uSpec

Source: https://context7.com/redongreen/uspec/llms.txt

Illustrates the commands to initiate the uSpec 'firstrun' skill on different platforms. This skill is crucial for initial environment configuration, syncing skills, and extracting essential template component keys from Figma libraries, setting up uSpec for subsequent documentation tasks.

```bash
# Run the firstrun skill based on your platform
# In Cursor chat: @firstrun
# In Claude Code CLI: /firstrun
# In Codex CLI: $firstrun

# The skill will:
# 1. Ask which platform you're using (Cursor, Claude Code, Codex)
# 2. Sync skills to the platform directory (if Claude Code or Codex)
# 3. Ask for your Figma template library link
# 4. Verify MCP connection with figma_get_status
# 5. Search for 8 required template components
# 6. Extract component keys and detect font family
# 7. Write configuration to uspecs.config.json
```

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

### JSON Example for Property Hierarchy

Source: https://github.com/redongreen/uspec/blob/main/api/agent-api-instruction.md

Illustrates how to use the `isSubProperty` flag within a JSON object to indicate a hierarchical relationship between properties. This is used to visually represent nested properties in documentation tables, providing clarity on component structure.

```json
{
  "property": "trailingContent",
  "values": "none, textButton, iconButton",
  "required": false,
  "default": "none",
  "notes": "Trailing slot configuration"
},
{
  "property": "label",
  "values": "string",
  "required": true,
  "default": "–",
  "notes": "Button label text",
  "isSubProperty": true
},
{
  "property": "variant",
  "values": "primary, secondary, tertiary",
  "required": false,
  "default": "tertiary",
  "notes": "Button style variant",
  "isSubProperty": true
}
```

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

### Image Accessibility in Swift

Source: https://github.com/redongreen/uspec/blob/main/screen-reader/voiceover.md

Provides examples for making images accessible in Swift. A descriptive label is added for meaningful images, while decorative images are hidden from VoiceOver.

```swift
Image("hero")
    .accessibilityLabel("Mountain landscape at sunset")
// Decorative:
Image("divider")
    .accessibilityHidden(true)
```

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

### uSpec Configuration File (uspecs.config.json)

Source: https://context7.com/redongreen/uspec/llms.txt

An example of the 'uspecs.config.json' file generated by the 'firstrun' skill. This JSON file stores critical configuration details, including the active environment, detected font family, and unique template keys for various specification types, enabling uSpec to function correctly.

```json
// uspecs.config.json - generated by firstrun
{
  "environment": "cursor",
  "fontFamily": "Inter",
  "templateKeys": {
    "screenReader": "6351e6a91a6785702ffa57f7e7ae085fe9f83f57",
    "colorAnnotation": "0b939a05e7b403b481d5221b08f33c97dc4acd39",
    "anatomyOverview": "a552bd211756add2661ed757a5aeafba24bd59a9",
    "apiOverview": "a182560cbe538de07f49f0aed5fadeea7d418e1c",
    "structureSpec": "9f5f7bdc834004ea47e59bb1502aab66348f1c99",
    "changelog": "dfcd9af939a9576ab29a28616d072b57ce37e89a",
    "propertyOverview": "401fa98128d882dc53c3d5987ed094b1ec66b9f3",
    "motionSpec": "31bc00ff1f47b602cb7129b24b1f3271e7c7b5dd"
  }
}
```

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

### Sync Skills Script Execution

Source: https://github.com/redongreen/uspec/blob/main/utils/README.md

Demonstrates various ways to execute the sync-skills.sh script for different syncing scenarios. It supports syncing all skills or specific skills, and targeting specific output directories.

```bash
./utils/sync-skills.sh
./utils/sync-skills.sh create-voice
./utils/sync-skills.sh --target claude
./utils/sync-skills.sh --target codex
./utils/sync-skills.sh --target claude create-voice
```

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

### Define Custom Accessibility Actions

Source: https://github.com/redongreen/uspec/blob/main/screen-reader/voiceover.md

Provides examples for adding custom actions to views, including single actions and grouped actions using the accessibilityActions container.

```swift
.accessibilityAction(named: "Delete") { deleteItem() }
.accessibilityAction(named: "Share") { shareItem() }

// Multiple actions at once
.accessibilityActions {
    Button("Delete") { deleteItem() }
    Button("Share") { shareItem() }
}
```

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

### Define Component Specification JSON Structure

Source: https://github.com/redongreen/uspec/blob/main/color/agent-color-instruction.md

A JSON schema example for a Tag component using Strategy B. It maps interactive states to design tokens across different color modes and variant types.

```json
{
  "componentName": "Tag",
  "generalNotes": "Color variants (Gray, Orange, Yellow, Green, Blue, Purple, Magenta, Teal, Lime, Red, Brand) are controlled via 'Tag color' variable mode at the container level. Size and Behavior axes do not affect color tokens.",
  "renderingStrategy": "B",
  "stateColumns": ["Enabled", "Hover", "Pressed", "Active", "Disabled"],
  "stateAxisName": "State",
  "collectionId": "VariableCollectionId:6006:13874",
  "variants": [
    {
      "name": "Primary / Gray",
      "modeId": "6006:2",
      "variantProperties": { "Behavior": "Interactive", "Type": "Primary", "Size": "Medium", "State": "Enabled" },
      "tables": [
        {
          "name": "Spec",
          "elements": [
            {
              "element": "Container (fill)",
              "tokensByState": {
                "Enabled": "Tag/Gray/backgroundPrimary",
                "Hover": "Tag/Gray/backgroundPrimary",
                "Pressed": "Tag/Gray/backgroundPrimary",
                "Active": "Tag/Gray/backgroundPrimary",
                "Disabled": "Tag/Gray/backgroundStateDisabled"
              },
              "notes": "Tag surface fill"
            }
          ]
        }
      ]
    }
  ]
}
```

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

### Configure Figma Console MCP for Codex

Source: https://github.com/redongreen/uspec/blob/main/docs/getting-started.mdx

This TOML configuration snippet sets up the Figma Console MCP for Codex. It includes the command to execute, arguments, and environment variables, notably the FIGMA_ACCESS_TOKEN. This configuration is typically found in the `.codex/config.toml` file.

```toml
[mcp_servers.figma-console]
command = "npx"
args = ["-y", "figma-console-mcp@latest"]

[mcp_servers.figma-console.env]
FIGMA_ACCESS_TOKEN = "figd_YOUR_TOKEN_HERE"
```

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

### Structure Rules for Color Annotation Data

Source: https://github.com/redongreen/uspec/blob/main/color/agent-color-instruction.md

Provides a reference for the rules governing the fields within the color annotation data structures. This guide clarifies the expected content and usage for each field, ensuring consistency in data organization.

```markdown
| Field | Rule |
|-------|------|
| `componentName` | Component name from Figma (e.g., "Checkbox", "Button") |
| `generalNotes` | Optional. High-level notes about color implementation for the entire component. |
| `renderingStrategy` | `"A"` for simple layout, `"B"` for consolidated multi-column layout |
| `variants` | Array of sections. Each entry renders as a heading + preview + table(s). |
| `variant.name` | Strategy A: state name, combined name, or mode name. Strategy B: non-state axis value ("Primary"), or "{Type} / {Mode}" for mode-controlled components ("Primary / Gray"). |
| `variant.modeId` | (Strategy B, mode-controlled only) Variable mode ID for this section's color mode. |
| `tables` | Array of tables within the section. Typically one table named "Spec". |
| `table.name` | Table label. Use "Spec" for standard cases. |
| `element` | Layer/element name from Figma: "Background", "stroke", "State layer" |
| `token` | (Strategy A) Clean token name extracted from Figma styles |
| `tokensByState` | (Strategy B) Object mapping each state column to its token value |
| `notes` | Brief description of the element (3-8 words). Add implementation notes if relevant. |
```

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

### Configure Live Regions for Accessibility Updates

Source: https://github.com/redongreen/uspec/blob/main/screen-reader/talkback.md

Sets up live regions for accessibility services to announce changes in UI elements. `LiveRegionMode.Polite` announces non-urgent updates, while `LiveRegionMode.Assertive` interrupts the user for urgent updates.

```kotlin
Modifier.semantics {
    liveRegion = LiveRegionMode.Polite // or Assertive
}
```

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

### Provide Content Description for Images in Compose

Source: https://github.com/redongreen/uspec/blob/main/screen-reader/talkback.md

Adds accessibility descriptions to images. Meaningful images require a descriptive `contentDescription`, while decorative images should have `contentDescription = null` to be ignored by screen readers.

```kotlin
// Meaningful
Image(
    painter = painterResource(R.drawable.hero),
    contentDescription = "Mountain landscape at sunset"
)

// Decorative
Image(
    painter = painterResource(R.drawable.divider),
    contentDescription = null
)
```

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

### Generate API Documentation via CLI

Source: https://github.com/redongreen/uspec/blob/main/docs/specs/api.mdx

Commands to trigger the API documentation generation process for a specific Figma component node. Requires a Figma URL and optional context regarding component properties and configuration.

```Cursor
@create-api https://www.figma.com/design/abc123/Components?node-id=100:200

This is a section heading with leading content (primary/secondary labels),
trailing content (text button, icon button, or none), and density options.
The label is required, subtitle is optional. Default trailing content is none.
```

```Claude Code
/create-api https://www.figma.com/design/abc123/Components?node-id=100:200

This is a section heading with leading content (primary/secondary labels),
trailing content (text button, icon button, or none), and density options.
The label is required, subtitle is optional. Default trailing content is none.
```

```Codex
$create-api https://www.figma.com/design/abc123/Components?node-id=100:200

This is a section heading with leading content (primary/secondary labels),
trailing content (text button, icon button, or none), and density options.
The label is required, subtitle is optional. Default trailing content is none.
```

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

### TypeScript Interfaces for API Documentation

Source: https://github.com/redongreen/uspec/blob/main/api/agent-api-instruction.md

Defines the TypeScript interfaces used to structure API documentation data. These interfaces cover component details, table properties, sub-component configurations, and example variations, serving as a schema for data passed into Figma templates.

```typescript
interface ApiOverviewData {
  componentName: string;
  generalNotes?: string;  // Optional implementation notes
  mainTable: ApiTableData;
  subComponentTables?: SubComponentApiTable[];
  configurationExamples: ConfigurationExample[];
}

interface ApiTableData {
  properties: ApiProperty[];
}

interface ApiProperty {
  property: string;       // Property name
  values: string;         // Possible values (e.g., "active, skeleton", "true, false")
  required: boolean;      // Is this required?
  default: string;        // Default value (or "–" if none)
  notes: string;          // Implementation notes
  isSubProperty?: boolean; // True if indented under parent (hierarchy indicator)
}

interface SubComponentApiTable {
  name: string;           // Pattern A: "Trailing content — Text button" | Pattern B: "Label"
  description?: string;   // "See full button API." or "Always-present child."
  properties: SubComponentProperty[];
}

interface SubComponentProperty {
  property: string;
  values: string;         // Possible values (matches ApiProperty)
  required: boolean;      // Is this required?
  default: string;        // Default value (or "–" if none)
  notes: string;          // Implementation notes
  isSubProperty?: boolean; // True if indented under parent (hierarchy indicator)
}

interface ConfigurationExample {
  title: string;          // "Example 1 — Primary button"
  variantProperties: Record<string, string | boolean>; // Figma property keys → values for instantiating the live component preview
  properties: ExampleProperty[];
}

interface ExampleProperty {
  property: string;
  value: string;
  notes: string;
}
```

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

### Calling Figma API to Get Variables

Source: https://github.com/redongreen/uspec/blob/main/structure/agent-structure-instruction.md

This code block illustrates the parameters required when calling the `figma_get_variables` function to fetch variable data. It specifies the `fileUrl`, `format` as 'filtered', a `namePattern` to filter tokens, and `verbosity` as 'standard'. This is crucial for analyzing token values across different Figma modes.

```text
figma_get_variables with:
  - fileUrl: <figma-url>
  - format: "filtered"
  - namePattern: "component/"  (or the token prefix)
  - verbosity: "standard"
```

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

### Slot Content Type Documentation (JSON)

Source: https://github.com/redongreen/uspec/blob/main/api/agent-api-instruction.md

Documents a specific content type within a slot, detailing its configurable properties. Useful when a slot has multiple interchangeable content options, each with its own properties.

```json
{
  "name": "Leading content — Avatar",
  "description": "Configuration when leadingContentType is avatar.",
  "properties": [
    { "property": "size", "values": "36x, 48x, 64x", "required": false, "default": "36x", "notes": "Avatar diameter" },
    { "property": "imageSource", "values": "string", "required": true, "default": "–", "notes": "URL or local path to avatar image" },
    { "property": "fallbackText", "values": "string", "required": false, "default": "–", "notes": "Initials shown when image fails to load" }
  ]
}
```

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

### Request Focus with FocusRequester in Jetpack Compose

Source: https://github.com/redongreen/uspec/blob/main/screen-reader/talkback.md

Manages focus for UI elements using FocusRequester. It allows requesting focus programmatically, typically triggered by a state change like showing an error. This is useful for guiding user attention to important elements.

```kotlin
val focusRequester = remember { FocusRequester() }

Text(
    "Error",
    modifier = Modifier.focusRequester(focusRequester)
)

// Request focus
LaunchedEffect(showError) {
    if (showError) focusRequester.requestFocus()
}
```

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

### Configure Figma Console MCP for Cursor

Source: https://github.com/redongreen/uspec/blob/main/docs/getting-started.mdx

This JSON configuration snippet adds the Figma Console MCP to your Cursor MCP settings. It specifies the command to run, arguments, and environment variables, including the Figma access token. This configuration can be added to global or project-level `.cursor/mcp.json` files.

```json
{
  "mcpServers": {
    "figma-console": {
      "command": "npx",
      "args": ["-y", "figma-console-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE"
      }
    }
  }
}
```

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

### Format Changelog Entries (JavaScript)

Source: https://context7.com/redongreen/uspec/llms.txt

Generates and maintains changelogs for design system updates. This skill formats changelog entries with titles and descriptions, applying bullet formatting to description lines starting with '- '. It also handles date and author information.

```javascript
// Fill changelog entry with bullet formatting
const CHANGES = [
  {
    title: "Updated spacing tokens",
    description: "- spacing-sm: 4px → 8px\n- spacing-md: 8px → 12px\n- spacing-lg: 16px → 20px"
  },
  {
    title: "Added disabled state",
    description: "New disabled variant with 40% opacity overlay"
  }
];

// Clone #new-date-entry for each date+author group
const entryClone = entryTemplate.clone();
container.insertChild(0, entryClone);  // Newest first

// Set date (MM.DD.YYYY format) and author
setText(entryClone, '#date', '01.15.2026');
setText(entryClone, '#author', 'Design System Team');

// Clone #changes for each change item, apply bullet formatting
for (const change of CHANGES) {
  const changeClone = changesTemplate.clone();
  setText(changeClone, '#changes-title', change.title);
  // Lines starting with "- " get native Figma bullet formatting
  await setTextWithBullets(changeClone, '#changes-description', change.description);
}

```

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

### Configure Expand/Collapse Semantics

Source: https://github.com/redongreen/uspec/blob/main/screen-reader/talkback.md

Defines semantic actions for expandable content, allowing TalkBack to trigger expand, collapse, and dismiss actions. This is used for elements like expandable cards or menus.

```kotlin
Modifier.semantics {
    expand {
        expanded = true
        true
    }
    collapse {
        expanded = false
        true
    }
    dismiss {
        onDismiss()
        true
    }
}
```

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

### Bar Position and Width Calculation (JavaScript)

Source: https://github.com/redongreen/uspec/blob/main/motion/agent-motion-instruction.md

Computes the X position and width of individual bars within the timeline. These calculations are performed at render time within the Figma code, using the segment's start time and duration multiplied by the pxPerMs rate.

```javascript
barX = seg.startMs * pxPerMs;
barWidth = Math.max(seg.durationMs * pxPerMs, 4);
```