# Adopt Frontfriend

Bring your existing shadcn project into a shared design system.

Frontfriend v4 is designed as an addon for teams already building with shadcn. Adoption starts with your existing codebase and target, then connects tokens and component configuration.

## Start with an inventory

Create a branch and commit your current UI. Record the framework, primitive library, Tailwind version, UI directory, local modifications and installed components. Identify any custom composition that differs from current upstream APIs.

Connect a Design System using [Installation](/docs/installation/). Set its framework and primitive explicitly. Existing Radix code should stay on the Radix target unless you deliberately plan a primitive migration.

## Extract your component styling

The CLI has a migration path for existing shadcn component styling:

```bash
npx frontfriend migrate --help
npx frontfriend migrate --component button --no-push
```

Use a single component first. `--no-push` keeps the generated configuration local for review. Check the output, semantic token mappings and remaining local classes before accepting a cloud write.

```bash
npx frontfriend migrate --component button
```

The v4 server migration implementation uses snapshots for recovery. Confirm the behavior supported by the package version you installed; do not assume a migration is complete just because a command exits successfully.

## Adopt deliberately

Download the same canonical target only after reviewing the existing source and generated configuration. An overwrite can replace local modifications. Test loading, disabled states, focus rings, nested overlays and responsive layouts in your actual application.

## What migration does not promise

The planned shadcn **ingest** feature is deferred until after v4 GA. Do not confuse it with the existing `migrate` command. Universal API equivalence, arbitrary component conversion and switching primitives without source changes are not guarantees.

## Validate the result

1. Check your source diff and configuration diff.
2. Verify light and dark mode and semantic color contrast.
3. Exercise the component with mouse and keyboard.
4. Run typechecking, application tests and a production build.
5. Repeat with the next component after the first one is accepted.

For existing Frontfriend v3 projects, use [v3 to v4 migration](/docs/migration-v3-v4/) instead. For the latest delivery state, see [Release status](/docs/release-status/).