Design to code workflow

How Subframe connects designs to your codebase.

Subframe is designed for building interfaces—the visual layer that designers own. Code generation in Subframe is deterministic and purely presentational (no API calls, state management, etc). Developers can later add application logic themselves using IDEs like Cursor or VS Code after export.

This guide explains Subframe’s design-to-code workflow in detail.

Components vs pages

As a developer, you should treat components and pages differently:

• Components are your design system (e.g. buttons, inputs, cards). They are synced via CLI to a folder in your codebase (default: ./ui/components). Each component syncs as a directory — a source file that Subframe generates and you don’t modify, plus a wrapper index.tsx that you can extend (see Component directories).
• Pages are screens built from components. They are exported as copyable React code or using the MCP server and are meant to be modified after export.

In a nutshell, components are synced, pages are exported. This is because pages are typically modified with business logic like API calls after export. If your component needs logic after syncing, see our guide on best practices for exporting components.

Design handoff

Suppose your designer creates a sign in page in Subframe:

When designers use Subframe, they are modifying the underlying code, which uses components that eventually live in your codebase. In this sign in page, the designer used the Button and SocialSignInButton components:

Syncing components

When the designs are ready for handoff, sync the Button and SocialSignInButton code to your codebase by running the following command:

npm

npx @subframe/cli@latest sync Button SocialSignInButton

You can also sync all design system components at once:

npm

npx @subframe/cli@latest sync --all

The CLI sync command pulls Button, SocialSignInButton, and any other components into a specific folder in your codebase. By default this folder is located in the ./src/ui/components folder but can be configured in the project settings.

src/ui/
└─ components/
  ├─ Button/
  │  ├─ Button.tsx
  │  └─ index.tsx
  └─ SocialSignInButton/
     ├─ SocialSignInButton.tsx
     └─ index.tsx

Each component syncs as a directory: the source file Subframe generates (Button.tsx) plus a wrapper index.tsx that re-exports it and is the import entrypoint. See Component directories for why, and how to add your own logic in the wrapper.

View synced code

Button.tsx

import React from "react"
import * as SubframeCore from "@subframe/core"
import * as SubframeUtils from "../utils"

interface ButtonRootProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  disabled?: boolean
  variant?: "brand-primary" | "brand-secondary" | "destructive-primary"
  size?: "large" | "medium" | "small"
  children?: React.ReactNode
  icon?: SubframeCore.IconName
  iconRight?: SubframeCore.IconName
  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void
  className?: string
}

const ButtonRoot = React.forwardRef<HTMLButtonElement, ButtonRootProps>(function ButtonRoot(
  {
    disabled = false,
    variant = "brand-primary",
    size = "medium",
    children,
    icon = null,
    iconRight = null,
    className,
    type = "button",
    ...otherProps
  }: ButtonRootProps,
  ref,
) {
  return (
    <button
      className={SubframeUtils.twClassNames(
        "group/3b777358 flex h-8 cursor-pointer items-center justify-center gap-2 rounded-md border-none bg-brand-600 px-3 text-left hover:bg-brand-500 active:bg-brand-600 disabled:cursor-default disabled:bg-neutral-200 hover:disabled:cursor-default hover:disabled:bg-neutral-200 active:disabled:cursor-default active:disabled:bg-neutral-200",
        {
          "h-6 w-auto flex-row flex-nowrap gap-1 px-2 py-0": size === "small",
          "h-10 w-auto px-4 py-0": size === "large",
          "bg-error-600 hover:bg-error-500 active:bg-error-600": variant === "destructive-primary",
          "bg-brand-50 hover:bg-brand-100 active:bg-brand-50": variant === "brand-secondary",
        },
        className,
      )}
      ref={ref}
      type={type}
      disabled={disabled}
      {...otherProps}
    >
      <SubframeCore.Icon
        className={SubframeUtils.twClassNames(
          "text-body font-body text-white group-disabled/3b777358:text-neutral-400",
          {
            "text-heading-3 font-heading-3": size === "large",
            "text-brand-700": variant === "brand-secondary",
          },
        )}
        name={icon}
      />
      <div
        className={SubframeUtils.twClassNames("hidden h-4 w-4 flex-none items-center justify-center gap-2", {
          "h-3 w-3 flex-none": size === "small",
        })}
      >
        <SubframeCore.Loader
          className={SubframeUtils.twClassNames(
            "font-['Inter'] text-[12px] font-[400] leading-[20px] text-white group-disabled/3b777358:text-neutral-400",
            {
              "text-caption font-caption": size === "small",
              "text-brand-700": variant === "brand-secondary",
            },
          )}
        />
      </div>
      {children ? (
        <span
          className={SubframeUtils.twClassNames(
            "whitespace-nowrap text-body-bold font-body-bold text-white group-disabled/3b777358:text-neutral-400",
            {
              "text-caption-bold font-caption-bold": size === "small",
              "text-brand-700": variant === "brand-secondary",
            },
          )}
        >
          {children}
        </span>
      ) : null}
      <SubframeCore.Icon
        className={SubframeUtils.twClassNames(
          "text-body font-body text-white group-disabled/3b777358:text-neutral-400",
          {
            "text-heading-3 font-heading-3": size === "large",
            "text-brand-700": variant === "brand-secondary",
          },
        )}
        name={iconRight}
      />
    </button>
  )
})

export const Button = ButtonRoot

For more information on syncing components, see the Syncing components guide.

Exporting pages

Subframe generates page code with stubs for business logic that need to be filled in:

SignInPage.tsx

import React from "react"
import { Button } from "@/ui/components/Button"
import { SocialSignInButton } from "@/ui/components/SocialSignInButton"

function SignInPage() {
  return (
    <div className="flex h-full w-full flex-col items-center justify-center bg-white">
      <div className="flex w-64 flex-col items-center justify-center gap-8">
        <div className="flex flex-col items-center justify-center gap-1">
          <img
            className="h-16 flex-none object-cover"
            src="https://res.cloudinary.com/subframe/image/upload/v1767591134/uploads/302/zzfsz5tcwky0pkjkru9d.png"
          />
          <span className="text-heading-2 font-heading-2 text-default-font">Welcome</span>
          <span className="text-body font-body text-subtext-color">Login or sign up below</span>
        </div>
        <div className="flex w-full flex-col items-center gap-2">
          <SocialSignInButton
            variant="google"
            onClick={(event: React.MouseEvent<HTMLButtonElement>) => {
              // TODO: Implement Google sign in
            }}
          />
          <SocialSignInButton
            variant="apple"
            onClick={(event: React.MouseEvent<HTMLButtonElement>) => {
              // TODO: Implement Apple sign in
            }}
          />
        </div>
        <div className="flex h-px w-full flex-none flex-col items-center gap-2 bg-neutral-border" />
        <Button
          className="h-10 w-full flex-none"
          variant="brand-secondary"
          size="large"
          icon="FeatherMail"
          onClick={(event: React.MouseEvent<HTMLButtonElement>) => {
            // TODO: Implement email sign in
          }}
        >
          Continue with email
        </Button>
      </div>
    </div>
  )
}

export default SignInPage

The page code can be exported in two ways:

• MCP server (recommended) - install Subframe MCP server and ask your AI tool to integrate the page code directly using the page link.
• Copy/paste - Open Code > Inspect in Subframe and copy the React code.

We recommend using the MCP server because you can also ask AI to add business logic or update the page code based on code changes. Once exported, refactor the code or add any business logic as needed.

SignInPage.tsx

import React from "react"
import { Button } from "@/ui/components/Button"
import { SocialSignInButton } from "@/ui/components/SocialSignInButton"
import { useNavigate } from "react-router-dom"
import { signInWithGoogle, signInWithApple } from "@/lib/auth"

function SignInPage() {
  const navigate = useNavigate()

  return (
    <div className="flex h-full w-full flex-col items-center justify-center bg-white">
      <div className="flex w-64 flex-col items-center justify-center gap-8">
        <div className="flex flex-col items-center justify-center gap-1">
          <img
            className="h-16 flex-none object-cover"
            src="https://res.cloudinary.com/subframe/image/upload/v1767591134/uploads/302/zzfsz5tcwky0pkjkru9d.png"
          />
          <span className="text-heading-2 font-heading-2 text-default-font">Welcome</span>
          <span className="text-body font-body text-subtext-color">Login or sign up below</span>
        </div>
        <div className="flex w-full flex-col items-center gap-2">
          <SocialSignInButton
            variant="google"
            onClick={async () => {
              await signInWithGoogle()
              navigate("/dashboard")
            }}
          />
          <SocialSignInButton
            variant="apple"
            onClick={async () => {
              await signInWithApple()
              navigate("/dashboard")
            }}
          />
        </div>
        <div className="flex h-px w-full flex-none flex-col items-center gap-2 bg-neutral-border" />
        <Button
          className="h-10 w-full flex-none"
          variant="brand-secondary"
          size="large"
          icon="FeatherMail"
          onClick={() => {
            navigate("/sign-in/email")
          }}
        >
          Continue with email
        </Button>
      </div>
    </div>
  )
}

export default SignInPage

Iterating on designs

After the initial export, both designs and code will evolve. Here’s how to handle changes:

Designer makes changes

Subframe lets designers own the visual layer. When a change is made in Subframe, you can re-export the diff into your codebase.

Component updates

Run the sync command to get the latest component code:

npm

npx @subframe/cli@latest sync --all

If a component has breaking changes, TypeScript will throw errors wherever that component is used. This makes it easy for developers to find and update the affected code.

Page updates

The recommended way is to prompt your AI tool using the MCP server to update the page code:

Update the existing page to match the Subframe design at
https://app.subframe.com/<YOUR_PROJECT_ID>/design/<DESIGN_ID>/edit.

Preserve all existing functionality unless the new design requires a change.

AI will fetch the latest design and merge it with your existing code, preserving your business logic.

Developer makes changes

Often times, you will need to add or modify the component behavior after handoff.

The best practice is to add your logic to the component’s wrapper index.tsx. You probably don’t need to sync code back to Subframe, since the source file that Subframe generates stays untouched and keeps receiving design updates. As a last resort, you can disable sync for the source file itself.

In the near future, we will add CLI commands to sync component code back to Subframe. If you are interested in this feature, please let us know by joining our Slack community.

To import an existing page code back to Subframe, you can take a screenshot of the page and ask Subframe AI to recreate the design in Subframe.

Beyond handoff

Once a feature ships, page designs may drift from code. That’s okay — page designs are artifacts for communication. Once the feature is live, the code is the source of truth.

Components are different. They stay synced, so Subframe remains the single source of truth for your design system. When a designer updates a button or input, you re-run sync and every page using that component gets the update.