Cursor Canvas

A canvas is a single .canvas.tsx file the IDE compiles so the user can open it beside the chat.

Workflow

1. Decide whether to use a canvas

The trigger is user intent, not response shape. Ask: would the user benefit from viewing this output as its own standalone artifact, separate from the chat?

Use a canvas when the agent produces new standalone analytical output:

• Quantitative analyses and metrics breakdowns
• Billing or account investigations with structured findings
• Security audits or architecture reviews with categorized findings
• Cross-system data analyses and overlap reports
• Structured data from MCP tools where the data IS the deliverable
• Financial analyses, usage trend reports
• Tables with more than a handful of rows

Do NOT use a canvas when:

• The user asks for work in a specific tool (e.g., "create a Datadog dashboard")
• The user has a specific deliverable (e.g., "draft a support response", "fix this code")
• The user is working within an existing artifact
• Short factual answers, one-off file edits, or quick clarifying questions
• MCP tools are queried as an intermediate step for a different deliverable

2. Write the canvas

Location. Canvases live at /Users/<user>/.cursor/projects/<workspace>/canvases/<name>.canvas.tsx. The IDE only detects canvases in that exact directory — subfolders and other locations are not picked up.

File rules:

• Exactly one .canvas.tsx file per canvas. Never create helper files or supporting modules.
• Import only from cursor/canvas. No relative imports, no npm packages, no Node built-ins.
• Default-export the top-level component.
• Embed all data inline. No fetch(), no network calls.

Never render empty states. If a section has no data, omit it entirely.

Label every plot. Charts and tables must be self-describing:

• A title naming the specific metric
• Axis labels with units on both axes
• A legend when more than one series is shown
• The source and time range in a small caption

Design guidance

Be creative. The SDK gives you expressive building blocks. But avoid slop: no gradients, no emojis, no box-shadows, no rainbow coloring. Cursor canvases are flat, minimal, and purposeful.

Visual hierarchy

Primary content gets more space, larger headings, and accent color. Supporting content stays compact.

Color. All colors from useHostTheme() tokens. No hardcoded hex. Use accent color deliberately.

Slop patterns — forbidden

• Gradients — no linear-gradient, radial-gradient
• Emojis — no emoji as icons, status indicators, or bullets
• Box shadows — no box-shadow. Flat surfaces only.
• Wall of identical cards — mix open sections with cards
• Rainbow coloring — most elements are neutral; color is used sparingly
• Giant text — font sizes above H1 (24px)
• Decorative borders — borders are structural, not decorative

Pre-delivery self-check

Before returning canvas code, verify:

1. Does the layout have visual hierarchy? One thing should stand out.
2. Is there variety in the composition?
3. Slop check: scan for the forbidden patterns above.

Introducing the canvas

Always include a markdown link to the .canvas.tsx file using its full absolute path. When you create a canvas, add a short note telling the user they can open it beside the chat.

Troubleshooting

If a canvas appears blank or missing, the most common cause is that it was not written under the correct canvases/ path. Every canvas edit returns a Canvas TypeScript check line reporting current type errors — treat that as authoritative diagnostics.