> ## 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 produces the Component Markdown source. 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, 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. Once installed, it works offline thereafter.
    </Note>

    ### Install the plugin

    Install it from the Figma Community — no local build required.

    <Steps>
      <Step title="Open the Community plugin">
        Go to [uSpec Extract](https://www.figma.com/community/plugin/1635184425006534227/uspec-extract) on the Figma Community.
      </Step>

      <Step title="Install it">
        Click **Open in…** (or **Try it out**) to add it to your Figma. It then appears under **Plugins → uSpec Extract** in any file.
      </Step>

      <Step title="Run it">
        Select a `COMPONENT` or `COMPONENT_SET` on the canvas, then run **Plugins → uSpec Extract**.
      </Step>
    </Steps>

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

    <Tip>
      The plugin is open source. To run a modified build, clone [`figma-plugin/`](https://github.com/redongreen/uSpec/tree/main/figma-plugin), run `npm install && npm run build` (Node.js 18+), then import `manifest.json` via **Plugins → Development → Import plugin from manifest…**. Use `npm run build:watch` for an iterative dev loop.
    </Tip>

    ### Plugin issues

    <AccordionGroup>
      <Accordion title="Plugin doesn't appear in Figma after install">
        **Symptom**: You installed from Community but **Plugins → uSpec Extract** is missing.

        **Solutions**:

        * Confirm you're signed in to the same Figma account you installed the plugin under. Community plugins are tied to the account that added them.
        * Re-open the [Community page](https://www.figma.com/community/plugin/1635184425006534227/uspec-extract) and click **Open in…** again to re-add it.
        * Restart Figma after installing. Some installs need a full quit (`Cmd+Q` on macOS), not just closing the window.
        * Right-click the canvas and check **Plugins → Manage plugins…** to confirm it's listed.
        * If you built from source instead, you'll find it under **Plugins → Development → uSpec Extract** — confirm `dist/code.js` and `dist/ui.html` exist next to the manifest, and that you're on Figma Desktop (the Development menu only appears there).
      </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. Re-install the plugin from [Community](https://www.figma.com/community/plugin/1635184425006534227/uspec-extract) to pick up the latest version (or `git pull` + `npm run build` if you run from source), and run `npx uspec-skills update` to refresh the skills.
        * 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

A render skill can only document what the `.md` records or what you describe. If states, variants, or behaviors are missing, they were usually not captured when you generated the `.md`. Fix it at the source:

* **Add context when generating the `.md`**: list all states (enabled, hovered, pressed, disabled, selected, loading) in the plugin's design-intent field or your `create-component-md` prompt, then regenerate
* **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 the `.md` is complete**: open the component `.md` and confirm the relevant section is populated. If it's thin, regenerate it with `create-component-md` and more context
* **Check your MCP connection** (render skills only): 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 render the frame
* **Verify the render destination**: make sure any destination node-id points to where you want the annotation, not a parent frame

### 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. **Decide where it belongs**: if the `.md` is missing it, regenerate the `.md`; if only the render is off, re-run the render skill
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>