/design

name: design
description: Design and edit anything in Subframe — pages, components, snippets, design documents, the theme. Also handles deletion of those resources except theme. Always load this skill when taking any action through the Subframe MCP server. This includes building or iterating on UI, evolving the design system, capturing design intent in writing, or cleaning up a project. Don't write UI code directly — design first, then implement with /subframe:develop.
argument-hint: "[what to design or change]"

The Subframe MCP server exposes tools for the full design surface — pages, components, snippets, design documents, theme — and this skill teaches you when to reach for each one. Each tool returns a URL the user can open to see the result. The heaviest ones (`design_page`, `design_component`, `edit_component`) run as background AI jobs and also return a `jobId` — pass it to `wait_for_jobs` if you need to ensure completion.

**Don't write UI code directly.** Subframe generates production-ready React/Tailwind code that matches the design system. Design in Subframe first, then implement with `/subframe:develop`.

When to use this skill

The user wants to:

• Build a new page or screen, or iterate on an existing one
• Add a new reusable component or snippet to the project or edit existing ones
• Capture design intent or component usage guidance as written documentation
• Update the project-wide visual theme (colors, fonts, corners, shadows, typography)
• Remove pages, components, snippets, or flows that are no longer needed

The key value: `/subframe:design` and `/subframe:develop` bridge coding and design. They work in both directions — create designs while coding and then ensure your code exactly reflects your design.

Picking the right tool

| Intent | Tool | | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | Find out what already exists in the project | `list_components`, `list_pages`, `list_snippets`, `list_flows`, `get_project_info` | | Build a screen the user navigates to | `design_page` (new) / `edit_page` (targeted change) | | Build a reusable building block (Button, Card, ListItem) used inside pages | `design_component` (new) / `edit_component` (targeted change) | | Build a small example used inside a design document (e.g. a Button-variants demo) | `design_snippet` (new) / `edit_snippet` (targeted change) | | Write or update written design / usage documentation | `write_design_document` | | Change project-wide colors, fonts, corners, shadows, typography | `edit_theme` | | Remove a page, flow, component, or snippet | `delete_page` / `delete_flow` / `delete_component` / `delete_snippet` |

MCP Authentication

If you cannot find the design tools (or any Subframe MCP tools), the MCP server likely needs to be authenticated. Ask the user to authenticate the Subframe MCP server. If the user is using Claude Code or Codex, instruct them to run `/mcp` to view and authenticate their MCP servers, and then say "done" when they're finished.

Find the projectId

Every design tool takes a `projectId`. Resolve it like this:

1. Check `.subframe/sync.json` if it exists locally. 2. If no projectId is found, call `list_projects`. Each project includes a `projectId`, `name`, `teamId`, and `teamName`.

• **One project**: Use it automatically.
• **Multiple projects**: Always ask the user which project to use. Present each project with its `teamName` to disambiguate. If the user already mentioned a specific team or project name, match it against the `teamName` and `name` fields — but still confirm before proceeding. Never silently pick a project when multiple exist.

Audit what already exists

Before working on any design, get a picture of the project's current state. On any project where you don't already have explicit knowledge of what's been built, call:

• `list_components` — see which components already exist. Some projects may have pre-existing components, some may not have any components yet.
• `get_theme` — see the project's theme tokens (colors, fonts, corners, shadows, typography).
• `get_project_info` — see project-level design documents.

This audit is cheap and critical to proper project management.

Verify theme alignment before designing

The first time you're about to call `design_page` / `design_component` / `edit_page` / `edit_component` against a given project in this conversation, follow this process:

1. **If the project has codebase context** (working in a repo, recreating a page, importing a design), locate and read the codebase's theme source — `tailwind.config.*`, theme CSS variables, a tokens module. Also read the codebase's most canonical filled component (typically `Button`) to see which token is used where — names and values can match while roles diverge.

2. **Write the comparison** — a brief alignment summary covering colors, fonts, corners, shadows, typography, **and role** (which token is used for what, on both sides). Flag mismatches even when names/values look the same. Watch specifically for:

• **Role divergence** — e.g., the codebase's `brand` token paints focus rings only while a separate `primary` token paints filled-button backgrounds; the Subframe project's convention may have `brand-primary` painting the filled-button background instead. If you need to verify Subf