Subframe

View saved version →

---
name: design
description: Create or edit pages, components, snippets, design documents, and themes in Subframe, or explore and compare UI design options in Subframe.
argument-hint: "[what to design or change in Subframe]"
---

Use this workflow when the deliverable belongs in Subframe. For implementation, use develop; for bringing an existing design system into Subframe, use import.

## Why and when to use Subframe

**Why Subframe.** Give designs a persistent home outside a code branch so teammates can find, review, and revisit them. Compare variations and multi-screen flows side by side on a canvas. Gather teammate comments before code changes. Record decisions and rationale in design documents beside the design. When Subframe is the source of truth, sync code from its theme and components.

**When to use it:** Explore directions, compare options, seek review or a shareable artifact, or change several screens or the design system.

**When not to:** For small fixes to existing UI or code-only behaviour, work directly in code unless the user requests Subframe or the project keeps designs there.

## Steps

1. Identify what must stay and what should change. For an existing design, read its actual content and inspect its rendered appearance. For a website or codebase reference, use the host's browsing or file tools to collect the relevant source and screenshots. A prose description alone is weak evidence for recreating an existing UI.
2. Choose the smallest operation that delivers the request. Edit an existing page or snippet in place; duplicate for an exact copy. Use generation for a new design or a substantially different direction. Decide whether a reusable component, a page composition, a usage example, or written guidance is the intended output.
3. Prepare references before generating. Pass actual source, images, or Subframe resources with a usage note explaining what to preserve and what to change. Include relevant child components and styles when source code depends on them. Put these instructions in the generation brief; the generator does not see your conversation or reasoning.
4. Complete dependencies before their consumers. If a page needs missing reusable primitives, create those with design_component first. Finish independent primitives before components that embed them, then generate the page. Keep one-off page compositions inline. Do not turn recreating a page into an unsolicited component-library rebuild.
5. Complete the requested screens and edits, then review what landed. Compare screenshots with the reference and requested change, including lower sections, affected responsive layouts, and relevant states. Fix missing content, clipping, spacing, and typography discrepancies before reporting.

## Pages and flows

Make each variation's brief self-contained. Describe concrete differences in layout or emphasis; do not tell one variation to copy another. If the user requests more variations than one call permits, split the requested count across calls on the same canvas.

For a flow, establish the first screen's shared shell. Once wait_for_jobs reports it done, verify that the page actually exists and use its ID as sourcePageId for the next screen immediately. If several alternatives landed, select a coherent starting direction yourself and say which you carried forward. Preserve navigation and layout while specifying the next screen's differences. Do not wait for the user's pick.

## Existing designs

Use update_node_styles for styling and edit_page or edit_snippet for content or structure. Start from the existing classes and subtree so unrelated layout, children, and copy survive. On replacement, keep data-node-id on retained nodes; omit IDs on new or inserted nodes. After a stale-ID error, reread the affected resource and reconstruct the edit instead of retrying old markup.

Use edit_component when the requested change belongs to the shared component. Inspect representative usages to understand the effect. A page-specific adjustment belongs on that page's instance or composition.

For comment-driven edits, match each requested thread to its current element and track which feedback was addressed. A thread whose element disappeared needs interpretation, not an edit against its old ID.

## Theme and design guidance

For a restyle, update existing tokens so current designs inherit the intended look. Preserve semantic roles and aliases instead of creating parallel look-alike tokens. Check representative pages and components in the affected modes. Prepare concrete token mappings before requesting any confirmation required for deletions or replacements. Use import for adopting an external token source.

Write design documents for decisions a future designer cannot infer from the UI: when to use a pattern, content constraints, and product-specific exceptions. Update existing guidance and preserve embedded examples. Use design_snippet for reusable examples or compositions that do not need a component API; do not manufacture documents or examples for every page.

## Review and recovery

Use screenshot_page for changed pages and screenshot_component for changed components after jobs finish. For a snippet, inspect it in an existing page usage when available; do not create an extra page just for verification. Disclose any missing visual coverage.

Read parser warnings and applied results before treating an edit as successful. If content was dropped or normalized away, express the intended static design more directly. A masked “Something went wrong” error is not evidence that nothing changed: inspect the destination and job state before retrying a creation. Retry only missing work, and report a persistent failure with the affected resource and any returned job ID.

View saved version →

---
name: develop
description: Implement or update Subframe designs using synced components or an app's own design system, set up Subframe components, or explain canvas and code sync.
argument-hint: "[Subframe design to implement, or local setup task]"
---

Implement Subframe designs in an application. For sync questions, explain the boundary below without changing files.

## Choose the source of truth

Before writing code, inspect the application package's .subframe/sync.json, synced directory, component imports, theme files, routes, and package.json. State which model the evidence supports:

- **Subframe owns the theme and components.** A sync configuration and generated components used by the app establish this model. Build pages from those components. Keep visual changes in Subframe and re-sync; keep application behavior in code. If a required component or token is missing from Subframe, use design to add it there, then bring it into code. Do not hand-roll a look-alike or patch generated styles.
- **The codebase owns the theme and components.** An established library such as MUI, shadcn, or custom components, with no Subframe sync, establishes this model. Treat the Subframe page as a visual reference. Implement with the app's components and tokens; translate styling to their equivalents instead of pasting Tailwind classes that bypass them. Do not initialize or sync Subframe unless the user chooses to adopt it. Use import when asked to bring the code's system into Subframe so future designs use it faithfully.
- **Mixed or unclear.** Name both models and the evidence for each, including any project mismatch. Follow an established boundary for the target screen. Ask only when the unresolved choice changes which components, theme, or files you will use.

Read [setup.md](setup.md) only when the app has no Subframe setup and the user wants Subframe's components, or init/sync fails.

## Get code with fewest tokens

Fetch get_page_info once for the page being implemented and inspect screenshot_page. Use files[].fileName and files[].contents as the page source. Keep the clean export defaults; node IDs and editor metadata are unnecessary for implementation. Page imports follow the project's export settings, normally its configured import alias; resolve them against the local setup.

In the Subframe model, use CLI sync for missing components and init for theme files: they write code directly to disk without passing it through context. Read only the local component APIs needed for implementation. Do not fetch every component with get_component_info to obtain code already available through sync.

Sync missing components by name, for example `npx @subframe/cli@latest sync Button Alert`. Never automatically re-sync components already present; refresh them only for a requested design update. Avoid routine sync --all or a bare sync, which also syncs everything. Named sync includes dependencies; inspect those changes too.

## Turn page code into app code

Place the implementation in the app's route and layout structure. Reuse its shell, routing, and server/client conventions.

- Match component variants and prop types to the intended states. Inspect local types and existing usages; map to equivalent APIs in the codebase model.
- Fill slots through their declared props or children, preserving compound component structure. Put page composition around components; do not edit generated internals to insert content.
- Follow local icon imports and prop types. In the Subframe model, create a missing page-only uploaded icon module from get_icon_info; do not sync the whole library for it. In the codebase model, use the app's icon library and asset conventions.
- Resolve image URLs and assets through the app's asset pipeline. Preserve crop, aspect ratio, and meaningful alt text; verify assets load.
- Replace placeholder copy and repeated JSX with real data and mapped items with stable keys. Use existing data fetching and formatting conventions; identify unavailable data instead of inventing a backend.

In the Subframe model, leave generated component files untouched. Put custom component logic in index.tsx and mark that wrapper with `// @subframe/sync-disable`. Keep the generated component available for visual updates. Merge changes manually into already disabled files.

## Implement behavior

Wire navigation, forms, validation, selection, dialogs, and loading, empty, and error states through the app's existing patterns. A static page export does not establish runtime behavior.

If the user points to a Subframe prototype for the intended behavior, read only its relevant files with read_prototype_file and translate that behavior; the prototype is a separate scaffold with mock data, not necessarily code to adopt.

For animation or motion work, start with the motion library's search_motion_examples and get_motion_example tools, and read get_motion_guidance before building motion from scratch.

## Verify in the app

Run the app with the host's shell and browser tools. Compare against screenshot_page at the same viewport, theme, content, and state. Check lower sections, responsive layouts, and interactions as well as the initial screen. Fix discrepancies, then run the relevant build or checks. Report what ran and any visual or behavioral verification you could not complete.

## Apply a later design change

For a requested update in the Subframe model, re-sync affected components by name. Refresh changed theme files through init with the existing configuration and component syncing disabled; sync alone does not refresh tokens. Re-fetch the page once after design changes finish. In the codebase model, translate the visual delta into the app's components and tokens.

Compare the refreshed export with a previous export when available, otherwise with the implemented JSX and screenshot. Check imports, variants, slots, layout classes, assets, and copy; inspect local component diffs.

Merge the changed regions into the existing implementation, preserving hooks, handlers, state, data bindings, and wrapper customizations. Do not replace the route with a fresh export. Repeat visual and behavioral verification.

## Explain canvas and code sync

The CLI brings Subframe components into code through sync and theme files through init. Pages are implemented or copied separately; CLI sync does not update them. Local edits do not automatically appear on the canvas, and canvas edits do not automatically update an implemented page. Re-fetch and merge a changed page when requested. Bringing code back into Subframe is an explicit design or import task, not continuous two-way sync.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: import
description: Import an existing codebase's or website's design system into Subframe, including theme tokens, light and dark modes, fonts, icons, and reusable components.
argument-hint: "[codebase, website, or design-system source to import]"
---

Use this workflow to reproduce an existing visual system in Subframe. Use design for a single page recreation, and develop for moving a Subframe design into code.

## Steps

1. Inventory the requested source before importing. Read Tailwind configuration, global CSS, token modules, font declarations, icon assets, reusable components, and their usage examples. For a website, use the host's browsing tools to inspect rendered states and accessible styles and assets. A screenshot alone cannot establish the complete token system or component library; distinguish observed values from inferred ones.
2. Compare that inventory with the destination theme, fonts, icons, and components. Keep a mapping from source names to Subframe names and IDs. Define the total requested inventory before starting so progress can be reported as N of M, not “a few components.” If the source is only partly accessible, state that the inventory is incomplete.
3. Import required fonts before the theme and required icons before components. When components are requested, recreate them in dependency order after their visual foundations are available. Validate one representative component early to catch systematic translation errors, then continue through the full requested inventory.
4. Compare imported results against the source. Check light and dark appearances, typography, dimensions, icon shapes, and the requested variants and states. Fix discrepancies before expanding a flawed pattern across the library.
5. Report counts separately for tokens, fonts, icons, and components, with source-to-destination mappings where names changed. List failures, unsupported details, approximations, and remaining items. Continue through the requested scope unless blocked; a successful first batch is not a completed library import.

## Fonts and icons

Match source font families, weights, and styles against list_fonts before uploading. Stage missing files with create_asset_upload, upload through the host's file/network tools, then add_fonts or add_icons. Keep the upload results associated with the inventory so a failed file is not counted as imported.

Extract SVG artwork from icon components or sprites when necessary. Choose recolorable icons for UI glyphs and preserve authored colors for brand artwork. Inspect artwork that uses unsupported SVG features before import; simplify it only if the appearance survives, otherwise report the limitation. Compare the stored result through get_icon_info when fidelity is uncertain.

Resolve name collisions deliberately. Reuse an identical destination asset; choose a distinct name for different artwork unless replacing the existing asset is intended. Carry the returned import names into component references rather than assuming filenames become exact names.

## Theme mapping

Keep a record of source token names, aliases, groups, and mode values. Preserve semantic relationships instead of sampling a few visible colors. Import the whole requested token set, including tokens not visible on the reference screen.

Pass supported Tailwind CSS or configuration source to import_theme unchanged. Use a dry run to inspect the mapping and skipped declarations before applying it. For other formats, translate the inventory into supported source or edit_theme operations while retaining the source mapping. Do not redesign values to fit a preferred palette or type scale.

Resolve missing fonts before reimporting typography. Read every skipped declaration: unsupported spacing tokens, unresolved values, and missing fonts are gaps to account for, not successful imports. Retain unsupported measurements in component styling where possible and report that they are not editable theme tokens.

Map light values to base values and dark values to dark overrides, enabling dark mode before writing overrides with edit_theme. Check aliases in both modes. Do not flatten dark values into the base palette or confuse a separate brand theme with dark mode.

For multiple source themes, inspect list_themes and map each to an explicit destination. Shared token identities must have consistent meanings across themes. Preserve color grouping where supported; report other collection/group structures that cannot be represented directly. Read back each affected theme with get_theme to compare values, aliases, and dark overrides. Keep existing token references attached when merging equivalent roles; prepare a concrete mapping for confirmation before deleting or replacing tokens.

## Components

Read the implementation, styles, dependencies, and representative usages of each component. Pass source code to design_component as a code reference with instructions to preserve its visual structure, variants, slots, and state styling. Include a rendered reference when available; code with unresolved imports alone is insufficient.

Build primitives before composites. Use newly imported Subframe components in later references and briefs. If a matching destination component already exists, compare it first and use edit_component for an intended update rather than creating another copy.

Recreate the visual contract, not runtime logic: API calls and application state remain in the source app. Express visual states as component variants or examples. Keep missing behavior or unsupported styling visible in the import report instead of claiming a lossless conversion.

After wait_for_jobs completes, read back each component and inspect screenshot_component. Check representative existing page usages with screenshot_page when the import changes shared assets or tokens. Count a component as imported only when it exists; separately identify anything that could not be visually verified. After an ambiguous failure, inspect the destination before retrying to avoid duplicates.