Getting Started

This page covers everything you need to go from zero to your first generated spec.

Setup instructions

Install your AI agent, connect Figma, and configure your template library.

Create your first spec

Prompt format, available skills, and tips for better output.

Setup instructions

uSpec connects an AI coding agent to Figma through the Figma Console MCP. You need three things:

AI agent host: the coding environment that runs uSpec skills (Cursor, Claude Code, or Codex)
Figma Console MCP: the bridge that connects your agent to Figma files
Template library: the Figma file containing documentation templates

You only need to complete this setup once. After that, you can generate specs anytime by opening the project in your agent host.

1. Set up your agent host

Cursor
Claude Code
Codex

Cursor is an AI code editor. All uSpec skills run inside Cursor’s chat.

Download Cursor

Go to cursor.com and download the app for your platform.

Clone the uSpec repository

Clone the repository to your local machine.

git clone https://github.com/redongreen/uSpec.git

Open the project in Cursor

Open the uSpec folder in Cursor. The agent skills in .cursor/skills/ load automatically.

Select the right model

uSpec skills are token-intensive and require a model with high context capacity. In Cursor’s chat, select Claude 4.6 Opus (Thinking) or higher as your model.

Lower-capacity models may truncate instructions mid-skill, producing incomplete or broken specs. Claude 4.6 Opus (Thinking) is the minimum recommended model.

Verify skills are available by typing @create-voice in Cursor’s chat. It should autocomplete to the skill file.

Claude Code is Anthropic’s terminal-based coding agent. The firstrun skill is pre-installed in .claude/skills/ — running it deploys all other skills.

Install Claude Code

Follow the Claude Code installation guide to install the CLI.

Clone the uSpec repository

Clone the repository to your local machine.

git clone https://github.com/redongreen/uSpec.git

Open the project

Navigate to the uSpec folder. Claude Code reads CLAUDE.md for project instructions and discovers the firstrun skill in .claude/skills/ automatically.

cd uSpec
claude

Select the right model

Use Claude 4.6 Opus or higher. uSpec skills are token-intensive and require high context capacity.

Run claude in the project directory. Claude Code should load CLAUDE.md and recognize the firstrun skill.

Codex is OpenAI’s coding agent. The firstrun skill is pre-installed in .agents/skills/ — running it deploys all other skills.

Install Codex

Follow the Codex setup guide to install the CLI.

Clone the uSpec repository

Clone the repository to your local machine.

git clone https://github.com/redongreen/uSpec.git

Open the project

Navigate to the uSpec folder. Codex reads AGENTS.md for project instructions and discovers the firstrun skill in .agents/skills/.

cd uSpec

Select the right model

Use GPT 5.4 or higher. uSpec skills are token-intensive and may produce incomplete output with lower-capacity models.

Codex should discover the firstrun skill listed in AGENTS.md. Type $firstrun to get started, or use /skills to browse what’s available.

2. Set up Figma Console MCP

The Figma Console MCP connects your agent to Figma Desktop, giving it access to component data, variables, styles, and screenshots.

Get a Figma personal access token

Go to the Figma API settings

Open figma.com/developers/api#access-tokens

Create a token

Click “Get personal access token”, enter a description like Figma Console MCP, and copy the token. It starts with figd_.

Copy the token immediately. You won’t be able to see it again after closing the dialog.

Configure the MCP in your agent

Cursor
Claude Code
Codex

Add the Figma Console MCP to your Cursor MCP configuration:

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

Add this to your Cursor MCP settings (global or project-level .cursor/mcp.json).

The repo includes a .mcp.json at the project root. Open it and replace the placeholder token:

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

Claude Code reads .mcp.json from the project root automatically.

The repo includes a .codex/config.toml. Open it and replace the placeholder token:

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

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

Codex reads MCP configuration from .codex/config.toml.

This uses the NPX setup, which gives you all 59+ tools including design creation and variable management. For alternative installation methods, troubleshooting, and the latest configuration options, see the Figma Console MCP documentation.

Connect to Figma Desktop

The Desktop Bridge plugin provides real-time access to your Figma file data. It comes bundled with the Figma Console MCP.

Install the Desktop Bridge plugin

The Desktop Bridge plugin is included in the figma-console-mcp npm package. After running npx figma-console-mcp@latest, find the plugin at node_modules/figma-console-mcp/figma-desktop-bridge/manifest.json. In Figma Desktop, go to Plugins → Development → Import plugin from manifest… and select this file.

Run the plugin

Open the Desktop Bridge plugin in your Figma file. It auto-connects via WebSocket. No special launch flags needed.

Verify the connection

In your agent, type: “Check Figma status”The agent should confirm an active connection.

When the connection is active, your agent can read Figma file data, take screenshots, and access variables and styles.

3. Run firstrun

The firstrun skill is your single entry point for setting up uSpec. It asks which platform you’re using, deploys skills to the right directory, and configures your template library.

You only need to run firstrun once per environment. It handles both skill deployment and template configuration.

Get the template file

uSpec renders documentation using Figma component templates. You need to add the templates to your Figma organization before running firstrun.

Uber designers can skip this — the internal template library is already configured. When firstrun asks for a library link, type “skip”.

Open the Community file

Go to the uSpec Template on Figma Community.

Duplicate to your drafts

Click Open in Figma to add a copy to your drafts.

Publish as a library

Move the file to your team or organization project, then publish it as a library:

Open the file in Figma
Go to the Assets panel
Click the book icon and select Publish library
Confirm the publish

This makes the templates available for uSpec to import.

If you’re working solo or testing, you can skip publishing and use the file directly. The firstrun skill will still work as long as you have the file open.

Run the firstrun skill

Open the Desktop Bridge plugin

In Figma Desktop, open the Desktop Bridge plugin in your template library file.

Run firstrun

Cursor
Claude Code
Codex

In Cursor’s chat, type:

@firstrun

Invoke the skill directly or let Claude auto-discover it:

/firstrun

Invoke the skill with $ or let Codex match it from the description:

$firstrun

Answer the prompts

The agent asks two questions:

Which environment? — Select Cursor, Claude Code CLI, or Codex CLI. This deploys all skills to the right directory.
Library link — Paste the link to your Figma template library (Uber designers can type “skip”).

Wait for confirmation

The agent extracts component keys from your templates and writes the configuration automatically.

When you see “Setup complete! You are now ready to use uSpec”, your environment and template library are configured.

Create your first spec

Before running a skill, confirm all three setup steps are complete:

Your agent host is open with the uSpec project and skills are available
The Desktop Bridge plugin is running in Figma and the connection is active
You’ve run firstrun — the template library is configured (uspecs.config.json has your template keys)

Every prompt follows the same format:

Prompt format showing skill name, Figma component link, and additional context

Reference a skill, paste a Figma link, and describe anything the agent can’t infer from the design: states, variants, behavior, or interaction details.

Example prompt

Cursor
Claude Code
Codex

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

This is a primary action button with enabled, hover, pressed, and disabled states.
The button has a text label and an optional leading icon.

/create-voice https://www.figma.com/design/abc123/Components?node-id=100:200

This is a primary action button with enabled, hover, pressed, and disabled states.
The button has a text label and an optional leading icon.

You can also skip the / and describe what you need — Claude auto-discovers the skill from its description.

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

This is a primary action button with enabled, hover, pressed, and disabled states.
The button has a text label and an optional leading icon.

Type $ to mention a skill explicitly, or use /skills to browse what’s available. Codex can also match skills implicitly from their description.

Available skills

Skill	What it generates
`create-anatomy`	Numbered markers on a component with an attribute table
`create-property`	Variant axis and boolean toggle exhibits with instance previews
`create-voice`	Screen reader specs for VoiceOver, TalkBack, and ARIA
`create-color`	Color token annotations for all elements and states
`create-api`	Property tables with values, defaults, and examples
`create-structure`	Dimensional specs for spacing, padding, and sizing
`create-motion`	Animation timeline and easing spec from After Effects data

What happens when you run a skill

Template import

The agent imports the documentation template into your current Figma page.

Content population

Component name, guidelines, properties, and tables are filled in automatically.

Section cloning

Sections are cloned for each variant, state, or property in your component.

Validation

A screenshot is captured and verified. Issues are fixed automatically.

If a documentation frame appears in your Figma file, your setup is working correctly.

Tips for better output

Be specific about states: Mention all states (selected, disabled, expanded) in your prompt. The agent cannot infer states that aren’t visible in the current Figma frame.
Describe the parts: For complex components, describe the interactive elements (e.g., “This is a tooltip. The bell icon triggers it, and the bubble appears on hover and focus.”)

Best practices

Do

Start a new agent session for every prompt. Each skill consumes significant context. A fresh session ensures the model has full capacity and avoids degraded output.
Confirm the MCP connection before running a skill. Run the Desktop Bridge plugin in Figma and verify the connection in your agent. If the agent can’t reach Figma, the skill will fail.
Run one agent per Figma file at a time. The MCP supports multiple connections, but all agents share one active page and file context. Finish one skill before starting the next.

Don’t

Interact with the Figma frame while a skill is running. The agent writes to the frame in multiple steps. Clicking, selecting, or editing mid-generation can break node references and corrupt the output.
Run multiple agents on the same file simultaneously. They override each other’s page navigation and produce corrupted specs. If you need parallel generation, use separate Figma files.
Reuse a long chat session for multiple skills. Accumulated history reduces available context and degrades output quality. Start fresh each time.

Setup issues

Skills not loading

Cursor
Claude Code
Codex

Confirm the uSpec project folder is open in Cursor (not a parent directory)
Check that .cursor/skills/ contains the skill folders
Restart Cursor after cloning the repository

Confirm you’re running claude from the uSpec project root
Check that CLAUDE.md exists at the project root
Only firstrun is available before initial setup — run /firstrun to deploy all skills

Confirm you’re in the uSpec project directory
Check that AGENTS.md exists at the project root
Only firstrun is available before initial setup — run $firstrun to deploy all skills

Desktop Bridge not connecting

Confirm Figma Desktop is running (not the web version)
Close and reopen the Desktop Bridge plugin in Figma
Make sure only one instance of Figma Desktop is running
Check that your Figma access token is configured correctly in your agent’s MCP settings

For issues with skills or Figma connection, see the Troubleshooting guide.

Getting Started

Spec Types

Resources

Getting Started

Setup instructions

Create your first spec

Setup instructions

1. Set up your agent host

2. Set up Figma Console MCP

Get a Figma personal access token

Configure the MCP in your agent

Connect to Figma Desktop

3. Run firstrun

Get the template file

Run the firstrun skill

Create your first spec

Example prompt

Available skills

What happens when you run a skill

Tips for better output

Best practices

Do

Don’t

Setup issues

Getting Started

Spec Types

Resources

Setup instructions

Create your first spec

​Setup instructions

​1. Set up your agent host

​2. Set up Figma Console MCP

​Get a Figma personal access token

​Configure the MCP in your agent

​Connect to Figma Desktop

​3. Run firstrun

​Get the template file

​Run the firstrun skill

​Create your first spec

​Example prompt

​Available skills

​What happens when you run a skill

​Tips for better output

​Best practices

​Do

​Don’t

​Setup issues

Setup instructions

1. Set up your agent host

2. Set up Figma Console MCP

Get a Figma personal access token

Configure the MCP in your agent

Connect to Figma Desktop

3. Run firstrun

Get the template file

Run the firstrun skill

Create your first spec

Example prompt

Available skills

What happens when you run a skill

Tips for better output

Best practices

Do

Don’t

Setup issues