Adopt Frontfriend

You can keep shadcn’s native tokens and components while adding shared design contracts. Conversion to Frontfriend styling is a separate choice.

Record the existing application

Create a branch and commit the current UI. Record the framework, primitive library, Tailwind version, UI directory and local component changes. Preserve the current target: connecting a Radix app does not convert it to Base UI.

Keep the native shadcn base

Create a Design System with the shadcn base in Studio. Install the SDK, then connect the first application:

pnpm exec frontfriend login
pnpm exec frontfriend connect --ff-id YOUR_DESIGN_SYSTEM_ID --base-library shadcn --agent codex --adopt contracts,tokens,components

The first import keeps native light, dark and custom tokens. When components are adopted, it compares local UI sources with the pinned shadcn base. Modified components and local helpers become immutable private versions. Later applications adopt the Design System’s existing Release; they do not replace it with their local files. Running import again does not publish subsequent local edits.

connect performs the import, adopts its Release and initializes the selected native CSS. A source conflict stops the operation and identifies the affected files. Resolve the conflict, then rerun Connect. Do not add --replace without reviewing which source will be replaced.

To perform the steps individually:

pnpm exec frontfriend import-shadcn
pnpm exec frontfriend update --release RELEASE_ID --installed --tokens --dry-run
pnpm exec frontfriend update --release RELEASE_ID --installed --tokens --yes
pnpm exec frontfriend init

Use the Release ID returned by the import. Native shadcn keeps its own tokens and components without a Frontfriend runtime build plugin. Use --adopt contracts when you only want design contracts, without token or component adoption.

Complete design onboarding

Connection and design readiness are separate. Follow the next step reported by Connect: start with the application’s areas, have your agent run ff-setup, review the proposal in Studio, then run pnpm exec frontfriend connect --resume. See Design Skills.

Convert to Frontfriend when ready

For a native shadcn Design System, this is an explicit platform write:

pnpm exec frontfriend migrate

Migration converts token classes while preserving component logic, publishes new private versions, and adopts this application’s installed sources and tokens. Other applications keep their locks. If publication succeeds but local adoption fails, rerun migrate to resume that adoption.

For an existing project already connected to the Frontfriend base, inspect migrate --help before using component-specific conversion. A fresh unmigrated shadcn project can require migration before Frontfriend token initialization. init --force deliberately applies the Design System’s styling; it is not a substitute for preserving an existing theme.

Review and recovery

Inspect source and configuration diffs. Test light/dark mode, keyboard focus, overlays and responsive layouts, then run application typechecks, tests and a production build. pnpm exec frontfriend restore lists available recovery snapshots; review the selected snapshot before applying a restore.

Migration does not guarantee arbitrary component conversion or identical APIs across primitives.