---
name: nano
description: Design in nano.design, a canvas where designs are real HTML and CSS that people and AI agents edit together live. Use when the person mentions nano or nano.design, shares a nano link (nano.design/d/…), or nano tools are available (create_frame, write_html, screenshot, get_handoff). Also use when they want to design screens, set up a design system, explore visual directions side by side, import from Figma, review a design, or turn a design into code, and would benefit from a canvas they can open, watch and edit.
---

# nano

nano.design is a design canvas where every design is real HTML and CSS. You design through its MCP tools while the person watches in their browser, and they can edit the same frames themselves. You can screenshot anything you build, so you can see your work and correct it, just as a designer would.

This skill covers how to connect and how to work well in nano. For what makes a design good (hierarchy, type, color, a distinct direction), pair it with the `design-taste` skill: https://nano.design/skills/design-taste. nano's MCP server also sends its own instructions and tool descriptions; follow them for the details of each tool.

## Connect

Check whether you have nano tools: `files`, `create_frame`, `write_html`, `screenshot`. Depending on the client they may carry a prefix, such as `mcp__nano__write_html`. If you have them, skip to the workflow.

If you don't, tell the person how to add nano. They do this themselves, and most clients need a restart or reload afterwards:

- **Claude Code**: `claude mcp add --transport http nano https://nano.design/mcp`
- **Claude.ai and Claude Desktop**: Settings → Connectors → Add custom connector, with the URL `https://nano.design/mcp`
- **Cursor**: add `"nano": { "url": "https://nano.design/mcp" }` under `mcpServers` in `~/.cursor/mcp.json`
- **VS Code**: add `"nano": { "type": "http", "url": "https://nano.design/mcp" }` under `servers` in `.vscode/mcp.json`
- **Any other MCP client**: streamable HTTP at `https://nano.design/mcp`, with OAuth sign-in

Signing in opens nano in the browser. People without an account can choose **Try without an account** to get a temporary guest workspace, and keep their designs later by claiming it.

An agent that can't complete a browser sign-in can ask for a guest key instead (https://nano.design/agents explains how). Only do this when the person has agreed to try nano.

If the person doesn't want to connect, continue without nano: build in code and follow `design-taste`.

## What to know before you start

- **Structure**: teams have projects and drafts; a design file has pages; a page holds frames, and each frame is a screen. Common widths are 1440 (desktop), 768 (tablet) and 390 (phone).
- **Writing**: `write_html` takes semantic HTML with inline `style` attributes only. No classes, no `<style>`, no scripts, no external `url()`. Use flexbox and grid, and name meaningful layers with `data-name`.
- **Assets**: upload images with `upload_file` and use the `/files/…` URL it returns. Write icons as inline `<svg>` with `stroke="currentColor"`. Any Google Fonts family, and the team's own fonts, load when named in `font-family`.
- **Tokens**: the design system compiles to CSS custom properties, so layers use `var(--color-accent)`, `var(--space-4)` and so on.
- **It's live**: people see each change as you make it. Frames you write to are locked for you while you work. Call `editing` with `start` (plus a status line) before longer work, and `done` when you finish.
- **Versions**: every write is a version. Save a named version before big changes and whenever the person likes where a design is.

## The workflow

1. **Brief and direction.** Work out the job, the content and a direction (design-taste, steps 1 and 2). For anything bigger than one screen, share the direction with the person in two or three lines before building.
2. **File.** Find the person's file (`files` with `search` or `list`) or create one. **Give them the live link straight away** so they can watch.
3. **System.** Read it with `design_system` `get`. If the team has libraries (`libraries` `list`), use them. If the file is empty, create tokens from your direction with `upsert_tokens`: a palette ramp, semantic roles that alias it (`{gray/900}`), spacing, radii, shadows and text styles. Use a Light/Dark collection if the product needs both.
4. **Frames.** Create one frame per screen at real widths, grouped on pages ("Desktop", "Mobile", "Components").
5. **Build section by section.** One `write_html` per section (header, hero, list…), using tokens throughout. One giant write is hard to check and hard to fix.
6. **Look.** `screenshot` after every section. Critique it honestly, using design-taste's critique checklist: the squint test, alignment, spacing rhythm, contrast, wrapping. Fix with `update_nodes`, or `write_html` with position `replace`.
7. **Componentize.** Turn repeated elements (buttons, cards, list rows) into components and place instances, so later changes happen in one place.
8. **Finish.** Run `design_system` `audit` and `adopt` its suggestions, set the file thumbnail, save a named version, call `editing` `done`, and send the person the link with a short note on the decisions you made.

## Recipes

### Explore directions side by side

When the person wants options, or the brief is open:

1. Create a page named "Directions".
2. Create one frame per direction (two to four) at the same width, side by side, each named after its direction ("Ledger", "Field guide", "Night shift").
3. Use **the same content** in each, so the person compares design rather than copy.
4. Make the directions differ on at least three axes: type, color temperature, density, shape, layout, signature move.
5. Give each frame its own palette as CSS custom properties on the frame itself (`--accent: #2B3FD6; --surface: #F3F1EA; …`) and reference them inside. Once the person picks one, `promote_frame_tokens` moves that frame's variables into the design system.
6. Screenshot each frame and present the options: the name, one line on the idea behind it, and what it's best at.
7. Build the chosen direction out on the main pages, and save a version.

### Set up a design system

1. Tokens: palette ramps, semantic roles (surface, text, text-muted, border, accent, danger…) aliasing the palette, spacing, radii, shadows, and text styles (type `typography`).
2. Modes: a collection with Light and Dark modes if the product needs both; check every frame in both with `set_mode`.
3. A "Components" page: buttons, inputs, badges, cards, list rows. Make each variant a component, combine them with `components` `combine_variants`, and add text and boolean properties so instances stay flexible.
4. A specimen frame showing the type scale, the color roles and the components, so the system is easy to review.
5. To share it across the team's files, publish the file with `libraries` `publish`. Other files add it and use its components and tokens.

### Redesign an existing screen

1. Bring in the current screen: rebuild it in a frame named "Current" from a screenshot or the live page.
2. Write down what isn't working, using the critique checklist: hierarchy, grouping, contrast, consistency.
3. Build "Proposed" beside it, at the same width with the same content.
4. Present both screenshots together, with the three most important changes and why each one helps.

### Review a design

1. `get_design` with format `outline`, then `screenshot` each frame.
2. Critique it with design-taste's checklist, in priority order: broken, hierarchy, system, character, polish.
3. Leave feedback where it belongs: `comments` `create` pinned to the layer (`node_id`), one thread per issue, each with what, why and a suggested fix. Don't silently change someone else's design. Make changes only when asked.

### Work through comments

`comments` `list` shows the open threads. For each one: make the change, reply saying what you changed, then resolve the thread.

### Hand off to code

- **In nano**: mark finished frames Ready for dev (`update_nodes` with `dev_status` `ready`). Add annotations on layers whose behavior a static design can't show: states, interactions, responsive rules, edge cases.
- **In the codebase**: call `get_handoff` with the nano link. It returns a screenshot, JSX, tokens, fonts, images and components for exactly that frame or layer. Adapt it to the codebase's own components and styling rather than pasting inline styles. Use `export_file` for images, SVG icons and PDFs. Once it's built, mark the frame completed.

### Share

- Anyone with the link can view (no sign-in): `files` `set_link_access` `public`.
- Specific people: `files` `share` with an email and a role.
- Teammates: put the file in a team project.

## Guest workspaces

If you connected with a guest key, or the person chose Try without an account, the workspace is temporary: it's deleted two hours after it was made unless the person claims it. Tell them early, and give them both links (`teams` with action `guest`): the share link anyone can open, and the claim link that's for them alone. Claiming keeps every design.

## Good habits

- Send the live link at the start, not just at the end.
- Re-read with `get_design` `outline` before editing a file that's been open a while; people may have changed it.
- If someone takes over a frame, stop writing to it unless they ask you to continue.
- Prefer real content and real imagery. Upload the person's own images and logos rather than placeholders.
- Keep the person in the loop at decision points (direction, structure, the chosen option), not at every step.