Design

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.

Treat a Subframe design as an explicit output, not a prerequisite for UI coding. When the user requests a Subframe design artifact or meaningful design exploration, design in Subframe first and then implement with /subframe:develop if requested. For implementation-only requests, edit the code directly.

When to use this skill

Use this skill when the user wants to:

• Create a page or screen in Subframe, materially redesign one, or explore visual directions
• Add or edit a reusable Subframe component or snippet
• Capture design intent or component usage guidance as a Subframe design document
• Update the Subframe project's visual theme (colors, fonts, corners, shadows, typography)
• Remove Subframe 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

MCP access

Discover the Subframe MCP tools first if your client loads them on demand. If no Subframe MCP tools are available, help the user install, enable, or authenticate the server using the MCP setup guide. In Claude Code or Codex, /mcp shows the server's connection and authentication status.

If read tools work but design or editing tools are unavailable, check the user's project permissions. Viewers have read-only MCP access, including screenshots and search; designing or editing requires an editor seat. Explain that permission requirement when it is the cause instead of asking the user to authenticate again.

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 / update_node_styles 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.

1. 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.

1. 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.

1. 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 and, if necessary, safe consolidation via alias bridging.

Grounding design calls in real code