Troubleshooting

Solutions for common issues when creating specs

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

In Cursor

Skill not activating

Symptom: You type a prompt but the skill doesn’t run.

Solutions:

• Use the direct reference format: @create-voice instead of typing keywords
• Check that the Echo Specs project folder is open in Cursor (not a parent directory)
• Restart Cursor if skills don’t autocomplete

Poor output quality

Symptom: The generated JSON is missing information or has incorrect values.

Solutions:

• 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

Skills don't autocomplete

Symptom: Typing @create- doesn’t show skill suggestions.

Solutions:

• Confirm the Echo Specs project folder is open in Cursor
• Check that .cursor/skills/ contains the skill folders
• Restart Cursor after cloning the repository

Figma connection

Cursor 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
• In Cursor, type “Check Figma status” to diagnose the connection
• Restart the Desktop Bridge plugin if it’s unresponsive

Desktop Bridge not connecting

Symptom: The Desktop Bridge plugin is open but Cursor can’t connect.

Solutions:

• 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 Cursor’s MCP settings

In the plugin

Invalid JSON syntax

Symptom: The plugin shows “Invalid JSON” when you paste.

Solutions:

• Re-copy the entire JSON block from Cursor’s chat
• Check for trailing commas or missing brackets
• Ensure quotes are straight (") not curly (" or ")
• Remove any markdown wrappers like ```json if they got copied

Unknown templateType

Symptom: The plugin shows “Unknown templateType” error.

Solutions:

• Verify the templateType field is one of: screenReader, colorAnnotation, anatomyOverview, apiOverview, structureSpec, changelog, changelogUpdate
• Check for typos in the templateType value

Missing required fields

Symptom: The plugin shows “Missing required field” error.

Solutions:

• Check the spec type documentation for required fields
• Ensure componentName is present in the JSON
• Verify the JSON structure matches the expected format

Plugin not appearing in Figma

Symptom: You can’t find Echo Specs in the plugins menu.

Solutions:

• Make sure you imported via Plugins → Development → Import plugin from manifest
• Verify you selected the correct manifest.json from the figma-plugin folder
• Restart Figma Desktop

---

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: type “Check Figma status” in Cursor. 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”

The agent validates JSON structure internally. If the JSON is malformed, the issue is likely a connection problem, not a prompt problem. Check your MCP connection first.

---

Get the project

The Echo Specs repository is private. If you don’t have access, request it from ian.guisard.

Once you have access, clone the repository:

git clone https://github.com/iguisard/base-echo.git

This project is maintained by Ian Guisard. Reach out to Ian directly if you have questions or need help getting started.

Still stuck?

Get help

Reach out to Ian Guisard or open an issue on GitHub.

Check installation

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