Skip to main content
Having trouble creating a spec? Find solutions below based on where the issue occurs.
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.
Symptom: You type a prompt but the skill doesn’t run.
  • Use the direct reference format: @create-voice instead of typing keywords
  • Check that the uSpec project folder is open in Cursor (not a parent directory)
  • Restart Cursor if skills don’t autocomplete
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, hover, pressed, disabled”)
  • Include a screenshot for complex components
  • Mention any non-obvious interactions or behaviors
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
Symptom: Typing @create- doesn’t show skill suggestions.Solutions:
  • Confirm the uSpec project folder is open in Cursor
  • Check that .cursor/skills/ contains the skill folders
  • Restart Cursor after cloning the repository

​
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, hover, 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”
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.

​
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.

Do

  • 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

Don't

  • 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
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.
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.

​
Still stuck?

Get help

Open an issue on GitHub for questions or bug reports.

Check setup

Review the setup steps to make sure everything is configured correctly.