Canvas

A canvas is a single .canvas.tsx file the IDE compiles and renders beside the chat. Follow the workflow below in order.

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? If the output is a means to an end (a drafted message, a code fix, a dashboard in another tool), skip the canvas.

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

• Quantitative analyses and metrics breakdowns (e.g. "send 500 requests and tell me how many fail")
• Billing or account investigations that surface structured findings from database queries
• Security audits or architecture reviews with categorized findings
• Cross-system data analyses and overlap reports
• Structured data from MCP tools (Databricks, Datadog, etc.) where the data IS the deliverable
• Financial analyses, margin decompositions, usage trend reports
• Tables with more than a handful of rows that the user asked to see

Do NOT use a canvas when:

• The user asks for work in a specific tool — "create a Datadog dashboard" means give them a Datadog dashboard, not a canvas
• The user has a specific deliverable — "draft a support response", "fix this code", "make this PR"
• The user is working within an existing artifact — improving an HTML dashboard, editing an existing file
• The user is doing targeted debugging or active development, even if structured findings emerge along the way
• Short factual answers, one-off file edits, or quick clarifying questions
• MCP tools are queried as an intermediate step for a different deliverable (e.g. querying Stripe to draft a support reply)

2. Write the canvas

Location. Canvases live at /Users/<user>/.cursor/projects/<workspace>/canvases/<name>.canvas.tsx. The IDE only detects canvases written directly inside that exact directory — subfolders, alternate extensions, and other locations are not picked up. Treat that managed canvases/ directory as pre-provisioned by Cursor itself: write the canvas file directly there and do not spend turns creating the directory with mkdir or checking whether it exists before writing. Listing its contents for other purposes (e.g. checking for existing canvases) is fine. If you can't determine the workspace directory from absolute paths already in your environment (terminals, transcripts, recently-viewed files), list ~/.cursor/projects/ rather than guessing. Use a descriptive kebab-case filename ending in .canvas.tsx; preserve acronym capitalization and lowercase the rest.

File rules:

• Exactly one .canvas.tsx file per canvas. Never create helper files, style 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.

Component discovery: prefer built-in cursor/canvas components over hand-rolled markup. The full public surface (components, hooks, prop types, tokens) is declared in ~/.codex/skills/canvas/sdk/index.d.ts and its sibling .d.ts files — read them when you need exact exports, prop shapes, or hook signatures rather than guessing. Referencing an export that does not exist is the most common runtime error.

Apply the Canvas generation policy below as you write, and complete its pre-delivery self-check (section 6) before returning the canvas.

Design guidance

Be creative. The SDK gives you expressive building blocks — use them in whatever combination best serves the content. But avoid slop: no gradients, no emojis, no box-shadows, no rainbow coloring. Canvases are flat, minimal, and purposeful.

Visual hierarchy

Not everything deserves equal treatment. Primary content gets more space, larger headings, and accent color. Supporting content stays compact. Squint test: blur your eyes — can you tell what matters?

Color. All colors from useHostTheme() tokens — read its JSDoc in the SDK declarations for the return shape and usage pattern. No hardcoded hex. Use accent color deliberately, not on everything.

Slop patterns — forbidden

These specific patterns produce low-quality output. If 2+ are present, redesign.

• Gradients — no linear-gradient, radial-gradient, background-clip: text.
• Emojis — no emoji as icons, status indicators, bullets, or section markers.
• Box shadows — no box-shadow. Flat surfaces only.
• Wall of identical cards — every section wrapped in the same card style with no variation. Mix open sections with cards.
• Rainbow coloring — a different color on every element. Most elements are neutral; color is used sparingly with purpose.
• Giant text — font sizes above H1 (24px), or bold text stuffed in CardHeader.
• Decorative borders — colored borders on every element. Borders are structural (subtle stroke tokens), 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? Not just a single column of uniform blocks.
3. Slop check: scan for the forbidden patterns above.

Introducing the canvas

When you create a canvas, add a short note in your chat response:

• First canvas — if no other .canvas.tsx files exist in the workspace's canvases/ directory, include one sentence explaining what a canvas is.
• Unsolicited canvas — if the user didn't ask for a canvas, include one sentence explaining why you chose it over plain text.

Both can apply at once; one or two sentences total is enough. Skip the intro for subsequent canvases.

Troubleshooting

If a canvas appears blank or missing, the most common cause is that it was not written under /Users/<user>/.cursor/projects/<workspace>/canvases/ exactly — re-save it to that path. Do not debug this by trying to create the managed directory manually; focus on correcting the file path instead. Users can click the canvas file path in the response to open it, just like any other file path in Cursor. When present, the canvas server writes a <name>.canvas.status.json sidecar after each build with status, diagnostics, or error fields you can read; the file is best-effort and may not exist, so don't block on it.

Good example

import { Divider, Grid, H1, H2, Stack, Stat, Table, Text } from 'cursor/canvas';

export default function ServiceOverview() {
  return (
    <Stack gap={20}>
      <H1>Service Overview</H1>
      <Grid columns={3} gap={16}>
        <Stat value="6" label="Total Services" />
        <Stat value="5" label="Healthy" tone="success" />
        <Stat value="1" label="Degraded" tone="warning" />
      </Grid>
      <Divider />
      <H2>Service Status</H2>
      <Table
        headers={["Service", "Status", "Uptime", "Latency"]}
        rows={[
          ["api-gateway", "Operational", "99.99%", "12ms"],
          ["auth-service", "Degraded", "99.2%", "340ms"],
          ["billing", "Operational", "99.8%", "45ms"],
        ]}
        rowTone={[undefined, "warning", undefined]}
      />
      <Divider />
      <H2>Recent Changes</H2>
      <Text>Auth service latency increased after the 14:30 deploy.</Text>
      <Text tone="secondary" size="small">Last checked: Apr 7, 2026 14:52 UTC</Text>
    </Stack>
  );
}

Stats in a Grid, Table directly under H2, text sections without cards.

Bad example — do not imitate

// BAD — every section wrapped in Card, no hierarchy, Table unnecessarily boxed
<Stack gap={12}>
  <Card><CardHeader>Summary</CardHeader><CardBody><Text>6 services.</Text></CardBody></Card>
  <Card><CardHeader>Status</CardHeader><CardBody><Table headers={[...]} rows={[...]} /></CardBody></Card>
  <Card><CardHeader>Changes</CardHeader><CardBody><Text>Latency increased.</Text></CardBody></Card>
</Stack>