develop

Implement Subframe designs in the codebase. Fetch the design via MCP, sync components, and add business logic.

MCP Authentication

If you cannot find the

get_page_info

tool (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, instruct them to run

/mcp

to view and authenticate their MCP servers.

Detect Project State

Before starting, check for

package.json

and

.subframe/

folder in the current directory:

Condition	Action
No `package.json`	Run `/subframe:setup` first — there's no project to implement into yet.
Has `package.json` AND has `.subframe/` folder	Proceed with the workflow below.
Has `package.json` but NO `.subframe/` folder	Ask the user (see below).

Existing non-Subframe project

If the current directory has a

package.json

but no

.subframe/

folder, ask the user which approach they prefer:

Use the design as inspiration — Fetch the design via MCP for reference, but implement the page using the existing styles, components, and patterns already in the repo. Translate the Subframe design's layout and structure into whatever UI framework the project already uses (e.g., existing component library, CSS modules, styled-components). Do NOT install Subframe or sync components. Skip to Inspiration Workflow.
Use Subframe styles and components — Install Subframe into the project so the design renders pixel-perfect with Subframe's generated code. Run
```
/subframe:setup
```
first, then continue with the Workflow below.

Workflow

Fetch the design - Use
```
get_page_info
```
with the URL, ID, or name
Sync components if needed - Only if components don't exist locally
Create the page - Put it in the right place per codebase patterns
Add business logic - Data fetching, forms, events, loading/error states

Inspiration Workflow

Use this workflow when the user chose to use the design as inspiration in an existing non-Subframe project.

Fetch the design - Use
```
get_page_info
```
with the URL, ID, or name to get the design's layout and structure
Study existing patterns - Look at the project's existing components, styles, and conventions
Create the page - Implement the design using the project's existing UI framework, mapping Subframe components to their equivalents in the codebase (e.g., Subframe
```
Button
```
→ the project's own button component)
Add business logic - Data fetching, forms, events, loading/error states

Fetching Designs

// By URL
get_page_info({ url: "https://app.subframe.com/PROJECT_ID/design/PAGE_ID/edit" })

// By ID (e.g., from /subframe:design)
get_page_info({ id: "PAGE_ID", projectId: "PROJECT_ID" })

// By name
get_page_info({ name: "Settings Page", projectId: "PROJECT_ID" })

// List all pages first if needed
list_pages({ projectId: "PROJECT_ID" })

Get the

projectId

from

.subframe/sync.json

Syncing Components

Sync components when they don't exist locally. You can sync specific components by name:

bash

npx @subframe/cli@latest sync Button Alert TextField

Or sync all components:

bash

npx @subframe/cli@latest sync --all

When to sync:

Components don't exist locally → Sync those specific components before implementing
Components already exist → Don't sync automatically. If the user wants the latest versions, they'll ask.

Never modify synced component files - they get overwritten. Create wrapper components if you need to add logic.

Sync Disable

If you must modify a synced component file directly, add

// @subframe/sync-disable

to the top of the file:

tsx

// @subframe/sync-disable
import * as React from "react"
// ... rest of component

This prevents the file from being overwritten on future syncs.

Updating a sync-disabled component:

If the user wants to update a component that has sync-disable, the sync command will skip it. To get the latest version:

Use
```
get_component_info
```
to fetch the latest code from Subframe
Manually merge the changes with the local modifications

Adding Business Logic

Subframe generates presentational code with placeholder data. You add:

Data fetching:

tsx

const { data, isLoading, error } = useQuery(...)

if (isLoading) return <Skeleton />
if (error) return <Alert variant="error">{error.message}</Alert>

return <PageComponent {...data} />

Form handling:

tsx

const handleSubmit = async (e: FormEvent) => {
  e.preventDefault()
  await submitForm(formData)
}

Event handlers:

tsx

<Button onClick={handleClick}>Submit</Button>
<Card actionSlot={<IconButton onClick={handleDelete} />} />

Updating Existing Pages

When a design changes:

Fetch the updated design
Update layout/structure from new design
Preserve existing hooks, handlers, and state management
Sync any new components

When diffing the updated design against the existing code, if there are design changes beyond what the user asked you to design (e.g., layout tweaks, new elements, removed sections), call those out and ask whether to include them.

MCP Tools Reference

Tool	Purpose	Key Parameters
`get_page_info`	Fetch page code	`url` , `id` , or `name` ; `projectId`
`get_component_info`	Fetch component code	`url` , `id` , or `name` ; `projectId`
`list_pages`	List all pages	`projectId`
`list_components`	List all components	`projectId`
`get_theme`	Get Tailwind config	`projectId` , `cssType`