design

What this skill does

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 Subframe-side roles, call `get_component_info` on the relevant component to see which tokens it actually references.
   - **Dual-token systems** — shadcn-style `primary` / `primary-foreground`, `destructive` / `destructive-foreground`, etc., where each role pairs a surface token with a content token. The Subframe theme may not have direct equivalents.

3. **If anything mismatches, or `get_theme` is empty**, stop and ask the user if they would like to set up the theme via `edit_theme` first since any design call is at risk of using hardcoded values and breaking the design system source-of-truth promise. Treat this like destructive-deletion confirmation: required even under autonomy / no-clarifying-questions directives.

4. **If the codebase uses hardcoded values instead of token**, the user may be hoping to start using tokens with Subframe. Ask the user if they want to create a theme in Subframe from their hardcoded values or if they would prefer to stick with hardcoded values.

If the project has no codebase context, only the empty-theme check applies — skip the comparison.

**When roles diverge**, ask the user how they would like to proceed as far as keeping the Subframe roles versus matching their codebase ones. Based on their answer, follow the process outlined in [Risk-classify before calling](#risk-classify-before-calling) and, if necessary, [safe consolidation via alias bridging](#safe-consolidation-via-alias-bridging).

## Grounding design calls in real code

Subframe's design AI is far more accurate when the call carries raw code than when it carries paraphrase. "Make the primary darker" leaves a guess; pasting `--color-primary: oklch(0.55 0.18 250)` doesn't. Wherever the codebase already has the source — a component implementation, theme tokens, a similar page — paste it into the call instead of describing it.

**Default to pasting full files when they exist.** Under-including is generally worse than over-including. Use the format:

```
// src/components/Button.tsx
<full file content>
```

Group related files in adjacent blocks (component + stories + CSS module).

**Don't paste what the AI already has.** For `edit_component`, `edit_page`, and `edit_snippet`, the current Subframe code is already on the server — don't echo it back. Read it with `get_component_info` / `get_page_info` / `get_snippet_info` so your description can target exactly what differs. Prefer the most efficient form: plain language when the change doesn't depend on any code the AI hasn't seen ("change padding from 4 to 6, add a hover state"); otherwise reference code scaled to what's needed — a targeted diff or code snippet when the Subframe code already resembles the target, a full file when handing over a wholesale target, a sibling pattern, or related types.

**Soft cap on very large files (~500 LOC combined).** When trimming, keep verbatim:

- Prop / type / interface definitions
- JSX structure with `className` strings (and any `cva` / variant maps) intact
- All styling rules — never paraphrase styles ("subtle shadow with rounded corners" → paste `className="rounded-md shadow-sm"`)

Safe to trim:

- Business handlers, event wiring, data fetching, side effects
- Imports unrelated to structure/styli