> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uspec.design/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Solutions for common issues when creating specs

Having trouble creating a spec? Find solutions below based on where the issue occurs.

<Warning>
  uSpec specs are generated by an LLM. Always review the output for accuracy. The agent can misinterpret component structure, assign incorrect token names, or produce incomplete specs. Treat generated specs as a strong first draft that needs a human review pass before shipping.
</Warning>

<Tabs>
  <Tab title="Agent issues" icon="message-bot">
    <AccordionGroup>
      <Accordion title="Skill not activating">
        **Symptom**: You type a prompt but the skill doesn't run.

        First, run `npx uspec-skills doctor` from your project root. It reports missing skills, missing references, or broken links and tells you exactly what to fix.

        <Tabs>
          <Tab title="Cursor">
            * Use the direct reference format: `@create-voice` instead of typing keywords
            * Confirm your project folder is open in Cursor (the same folder where you ran `npx uspec-skills init`)
            * Verify `.cursor/skills/` contains the skill folders. If empty, run `npx uspec-skills install --platform cursor`
            * Restart Cursor if skills don't autocomplete
          </Tab>

          <Tab title="Claude Code">
            * Confirm you're running `claude` from the project root where you ran `npx uspec-skills init`
            * Verify `.claude/skills/` contains the skill folders. If empty, run `npx uspec-skills install --platform claude-code`
            * Try mentioning the skill by name: "Run create-voice for this component"
          </Tab>

          <Tab title="Codex">
            * Confirm you're in the project directory where you ran `npx uspec-skills init`
            * Verify `.agents/skills/` contains the skill folders. If empty, run `npx uspec-skills install --platform codex`
            * Try using `/skills` to list available skills, then invoke with `$skill-name`
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="Poor output quality">
        **Symptom**: The generated spec is missing information or has incorrect values.

        **Solutions**:

        * Make sure you're using a high-context model — **OpenAI GPT 5.4 High** or **Opus 4.6 High** or above. OpenAI 5.4 High is more economical to use. Lower-capacity models may truncate skill instructions and produce incomplete specs.
        * Start a **new agent session** for each prompt to give the model full context capacity
        * Add more context to your prompt: describe all states, variants, and behaviors
        * Specify states explicitly (e.g., "enabled, hovered, pressed, disabled")
        * Include a screenshot for complex components
        * Mention any non-obvious interactions or behaviors
      </Accordion>

      <Accordion title="Spec generation stops midway or produces garbled output">
        **Symptom**: The agent stops generating before finishing, or the output is truncated or malformed.

        **Solutions**:

        * Switch to a higher-context model — uSpec skills are token-intensive
        * Start a **new agent session** instead of continuing in an existing conversation — accumulated history reduces available context
        * If the issue persists, try running the skill again in a fresh session with a simpler prompt first
      </Accordion>

      <Accordion title="Skills don't appear in autocomplete (Cursor)">
        **Symptom**: Typing `@create-` doesn't show skill suggestions.

        **Solutions**:

        * Confirm your project folder is open in Cursor (the folder where you ran `npx uspec-skills init`)
        * Verify `.cursor/skills/` contains the skill folders. If empty, run `npx uspec-skills install --platform cursor` to repair the install
        * Restart Cursor after running `npx uspec-skills init` or `npx uspec-skills install`
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Figma connection" icon="plug">
    <Note>
      MCP providers update their setup and troubleshooting guides frequently. If the solutions below don't resolve your issue, check the provider's documentation for the latest instructions:
      [Figma Console MCP docs](https://docs.figma-console-mcp.southleft.com/) · [Native Figma MCP docs](https://github.com/figma/figma-mcp)
    </Note>

    <Tabs>
      <Tab title="Console MCP">
        <AccordionGroup>
          <Accordion title="Agent can't connect to Figma">
            **Symptom**: The agent reports it cannot access your Figma file.

            **Solutions**:

            * Confirm Figma Desktop is running (not the web version)
            * Check that the Desktop Bridge plugin is open and active in your Figma file
            * Ask your agent to "Check Figma status" to diagnose the connection
            * Restart the Desktop Bridge plugin if it's unresponsive
            * Verify your `FIGMA_ACCESS_TOKEN` is set correctly in your MCP configuration

            For detailed setup and troubleshooting, see the [Figma Console MCP documentation](https://docs.figma-console-mcp.southleft.com/).
          </Accordion>

          <Accordion title="Desktop Bridge not connecting">
            **Symptom**: The Desktop Bridge plugin is open but the agent can't connect.

            **Solutions**:

            * Close and reopen the Desktop Bridge plugin in Figma
            * Make sure only one instance of Figma Desktop is running
            * Verify your Figma access token is configured correctly:

            <Tabs>
              <Tab title="Cursor">
                Check your Cursor MCP settings or `.cursor/mcp.json`
              </Tab>

              <Tab title="Claude Code">
                Check `.mcp.json` at the project root
              </Tab>

              <Tab title="Codex">
                Check `.codex/config.toml`
              </Tab>
            </Tabs>
          </Accordion>

          <Accordion title="Unexpected behavior with multiple agents">
            **Symptom**: Output appears on the wrong page, node references break, or specs are corrupted when running two agents at the same time.

            **Why this happens**: The Console MCP supports multiple simultaneous connections (ports 9223–9232), but Figma Desktop has a single active page. When two agents navigate to different pages, they override each other's context, causing broken references and interleaved writes.

            **Solutions**:

            * Run **one agent at a time** per Figma file — finish one skill before starting the next
            * If you need parallel generation, use **separate Figma files** so each agent has its own page context
          </Accordion>
        </AccordionGroup>
      </Tab>

      <Tab title="Native Figma MCP">
        <AccordionGroup>
          <Accordion title="Agent can't connect to Figma">
            **Symptom**: The agent reports it cannot access your Figma file or the MCP server isn't responding.

            **Solutions**:

            * Confirm the MCP server is running — check your terminal or your agent's MCP panel for connection status
            * Verify your `FIGMA_API_KEY` is set correctly in your MCP configuration
            * Test with a simple command like *"List pages in my file"* with a Figma link
            * Make sure the token has read and write scopes

            For detailed setup and troubleshooting, see the [Figma MCP documentation](https://github.com/figma/figma-mcp).
          </Accordion>

          <Accordion title="Token validation errors">
            **Symptom**: The agent connects but returns authentication or permission errors.

            **Solutions**:

            * Regenerate your personal access token at [figma.com/developers/api#access-tokens](https://www.figma.com/developers/api#access-tokens)
            * Ensure the token has **read and write** scopes enabled
            * Check that the token hasn't expired — Figma tokens can be set to expire
            * Confirm the environment variable name matches your MCP configuration (`FIGMA_API_KEY`)
          </Accordion>

          <Accordion title="File or node not found">
            **Symptom**: The agent can connect but reports it can't find the specified file or node.

            **Solutions**:

            * Verify the `fileKey` in your Figma URL — it's the string between `/design/` and the file name
            * Check that the `node-id` parameter is correct — convert dashes to colons (e.g., `100-200` becomes `100:200`)
            * Confirm you have access to the file with the account that generated the token
          </Accordion>

          <Accordion title="Unexpected behavior with multiple agents">
            **Symptom**: Specs are corrupted or incomplete when running multiple agents simultaneously.

            **Why this happens**: The native Figma MCP uses the REST API, so it doesn't have the same port-sharing model as the Console MCP. However, concurrent writes to the same file can still cause conflicts.

            **Solutions**:

            * Run **one agent at a time** per Figma file — finish one skill before starting the next
            * If you need parallel generation, use **separate Figma files** so each agent has its own context
          </Accordion>
        </AccordionGroup>
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Figma Extract plugin" icon="puzzle-piece">
    The **uSpec Extract** Figma plugin powers the Component Markdown path. It walks a selected component, captures every variant and token binding, and writes a single `_base.json` that `create-component-md` consumes. Use this tab when the plugin won't install, won't build, or runs but doesn't produce a usable file.

    <Note>
      The plugin runs entirely inside Figma Desktop's plugin sandbox. It makes no network calls and stores nothing externally. If you can install it once, it will work offline thereafter.
    </Note>

    ### Install the plugin

    Build the plugin locally and import it into Figma Desktop. Requires Node.js 18 or later.

    <Steps>
      <Step title="Clone the uSpec repository">
        ```bash theme={null}
        git clone https://github.com/redongreen/uSpec.git
        cd uSpec/figma-plugin
        ```
      </Step>

      <Step title="Install dependencies">
        ```bash theme={null}
        npm install
        ```

        This installs `esbuild`, `ajv`, and the Figma plugin typings. Nothing else is fetched at runtime.
      </Step>

      <Step title="Build the plugin bundle">
        ```bash theme={null}
        npm run build
        ```

        The build writes `dist/code.js` and `dist/ui.html`. Both are referenced by `manifest.json`.
      </Step>

      <Step title="Import the manifest into Figma Desktop">
        In Figma Desktop, go to **Plugins → Development → Import plugin from manifest…** and select `figma-plugin/manifest.json` from your local clone.
      </Step>

      <Step title="Run from the Development menu">
        The plugin appears under **Plugins → Development → uSpec Extract**. Select a component on the canvas, then run it.
      </Step>
    </Steps>

    <Tip>
      For active development, run `npm run build:watch` instead of `npm run build`. Figma reloads the plugin on next open after each rebuild, so no manual re-import is needed.
    </Tip>

    <Check>
      When **Plugins → Development → uSpec Extract** opens the plugin window, the dev install is complete.
    </Check>

    ### Plugin issues

    <AccordionGroup>
      <Accordion title="Plugin doesn't appear in Figma after import (dev install)">
        **Symptom**: You imported `manifest.json` but **Plugins → Development → uSpec Extract** is missing or greyed out.

        **Solutions**:

        * Confirm you imported the manifest from the project you actually built. The manifest references `dist/code.js` and `dist/ui.html` by relative path, so moving the manifest without the `dist/` folder breaks the link.
        * Re-run `npm run build` and confirm `figma-plugin/dist/code.js` and `figma-plugin/dist/ui.html` exist.
        * Restart Figma Desktop after importing. Some macOS installs need a full quit (`Cmd+Q`), not just closing the window.
        * Confirm you're on **Figma Desktop**, not the browser. The Development menu only appears in the desktop app.
        * If you have multiple Figma accounts, confirm the dev plugin was imported under the account you're currently signed in to.
      </Accordion>

      <Accordion title="Build fails with `npm run build`">
        **Symptom**: `npm install` or `npm run build` errors out before producing `dist/code.js`.

        **Solutions**:

        * Confirm Node.js 18 or later. Older versions miss APIs `esbuild` 0.25 expects. Run `node --version` to check.
        * Delete `node_modules/` and `package-lock.json` inside `figma-plugin/`, then run `npm install` again. Stale lockfiles from a different Node version cause silent failures.
        * If the build complains about missing types, run `npm install` from inside `figma-plugin/`, not from the repo root. The plugin keeps its dependencies isolated.
        * On Apple Silicon, if `esbuild` reports a binary mismatch, run `npm rebuild esbuild`.
      </Accordion>

      <Accordion title="Plugin runs but the canvas selection is rejected">
        **Symptom**: The plugin shows "Select a component or component set on the canvas" even though something is selected.

        **Solutions**:

        * Select exactly one node. The plugin requires a single selection.
        * The selection must be a `COMPONENT` or `COMPONENT_SET`. Frames, groups, and instances are not accepted. Selecting a single variant inside a component set is fine — the plugin auto-promotes it to the parent set.
        * If you're working in a library file, confirm the component hasn't been detached from its master. Detached instances do not register as `COMPONENT` nodes.
        * Click **Refresh** in the plugin footer if you changed the selection while the plugin window was open.
      </Accordion>

      <Accordion title="Extract & download produces no file">
        **Symptom**: You click **Extract & download** but nothing lands in `~/Downloads/`.

        **Solutions**:

        * Check Figma Desktop's permission to download files. macOS may block downloads from sandboxed plugins on first run — look for a permission prompt.
        * Try **Copy JSON** instead. If the clipboard copy works, the issue is download-permission related, not extraction itself. Paste the JSON into a file manually and continue.
        * Open Figma's plugin developer console (**Plugins → Development → Open console**) and look for an `extract-error` message. The error reason indicates which extraction phase failed.
      </Accordion>

      <Accordion title="`create-component-md` rejects the `_base.json` with a schema error">
        **Symptom**: The agent runs `node figma-plugin/scripts/validate-base.mjs` and aborts with an Ajv FAIL.

        **Solutions**:

        * Re-run the plugin and re-export. A stale file from a previous plugin version may not match the current schema.
        * Confirm the plugin and the skill are on the same uSpec version. If you updated one without the other, the schema can drift. Run `git pull` in your local clone, then re-run `npm run build` if you're on the dev install.
        * Run the validator directly to see the full diagnostic:

          ```bash theme={null}
          node figma-plugin/scripts/validate-base.mjs ~/Downloads/your-component-_base.json
          ```

          The validator names the failing field and the expected shape.
        * The schema reference lives at [`figma-plugin/docs/base-json-schema.md`](https://github.com/redongreen/uSpec/blob/main/figma-plugin/docs/base-json-schema.md).
      </Accordion>

      <Accordion title="Sub-component checklist looks wrong">
        **Symptom**: The plugin's checklist marks something as **constitutive** that should be **referenced**, or vice versa.

        **Solutions**:

        * Flip the classification directly in the checklist before clicking **Extract & download**. Your override is recorded in `_base.json._childComposition.children[*].classificationEvidence` as `["user-selected"]`, and the orchestrator trusts user selections without re-asking.
        * Non-instance children (vectors, frames, text) are locked to **decorative** and cannot be flipped. If something you expect to be configurable is showing as decorative, the underlying node is not an instance — re-create it as a component instance in Figma.
        * For fully accurate classifications across runs, document the convention in your design system: what counts as constitutive vs. referenced for your library.
      </Accordion>

      <Accordion title="Extraction takes more than a minute">
        **Symptom**: The plugin progress indicator stalls for an unusually long time on a large component set.

        **Solutions**:

        * Components with more than 20 sub-component variants trigger Phase I's variant-walk cap, which slows extraction. The plugin emits a `skipped` marker when the cap is hit; check for those in the resulting `_base.json` and consider documenting oversize sub-components in their own `create-component-md` run.
        * Close other open Figma files. The sandbox shares memory across files, and very large libraries can exhaust the budget.
        * Restart Figma Desktop and re-run the plugin. A long Figma session sometimes accumulates state that slows plugin execution.
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

***

## Improving output quality

If the agent's output is incomplete or doesn't match your expectations, the issue is usually missing context rather than a technical problem.

### Output is incomplete or missing states

The agent can only document what it can see in Figma or what you describe. If states, variants, or behaviors are missing from the output:

* **Add them to your prompt**: explicitly list all states (enabled, hovered, pressed, disabled, selected, loading)
* **Describe behavioral modes**: fill vs. hug width, truncation rules, multi-select behavior
* **Mention invisible constraints**: tap target minimums, aspect ratios, focus order preferences

### Output seems generic or empty

If the output has the right structure but lacks detail:

* **Check your MCP connection**: ask your agent to verify the Figma connection (e.g., *"Check Figma status"* for Console MCP, or *"List pages in my file"* with a link for native MCP). If the connection is down, the agent can't read your component data
* **Verify the Figma link**: make sure the node-id points to the actual component, not a parent frame
* **Re-run with more context**: describe the component's parts and their relationships

### Re-prompting strategies

When the first output isn't quite right:

1. **Identify what's missing**: Is it a state? A variant? A specific part?
2. **Run the skill again** with additional context about the missing elements
3. **Be specific**: instead of "include all states," say "include enabled, disabled, and loading states"

<Note>
  If the output has the right structure but rendering fails, the issue is likely a connection problem, not a prompt problem. Check your MCP connection first.
</Note>

***

## Component structure matters

uSpec reads your component tree programmatically. The cleaner your Figma components are structured, the more accurate the output. A well-organized component gives the agent the information it needs to produce correct specs on the first run.

<CardGroup cols={2}>
  <Card title="Do" icon="check">
    * Use **auto-layout** for all layout containers
    * **Name every layer** descriptively ("Leading icon", "Primary label", "Helper text")
    * Use **component sets** with clear variant axis naming
    * **Bind colors and dimensions** to design tokens and variables
    * Keep your layer hierarchy **flat and purposeful**
  </Card>

  <Card title="Don't" icon="xmark">
    * Leave default names like "Frame 427", "Group 12", or "Rectangle 89"
    * Use **absolute positioning** where auto-layout would work
    * **Nest elements deeply** without purpose (wrapper frames inside wrapper frames)
    * Mix unrelated elements in a single **unnamed frame**
    * Use **flattened vectors** for elements that should be component instances
  </Card>
</CardGroup>

<Tip>
  Think of it this way: if another designer can't understand your component by reading the layer panel alone, the agent will struggle too. Layer names become table labels, auto-layout informs spacing specs, and token bindings drive color annotations.
</Tip>

***

<Info>
  uSpec is an actively developed open-source project. We're improving the skills, adding new spec types, and refining output quality continuously. If you encounter an issue or have an idea for improvement, open an issue on GitHub — contributions and feedback are welcome.
</Info>

## Still stuck?

<CardGroup cols={2}>
  <Card title="Get help" icon="github" href="https://github.com/redongreen/uSpec/issues">
    Open an issue on GitHub for questions or bug reports.
  </Card>

  <Card title="Check setup" icon="wrench" href="/getting-started">
    Review the setup steps to make sure everything is configured correctly.
  </Card>
</CardGroup>