f0-move-component

name: f0-move-component description: Use when moving an F0 component from one Storybook section to another. Covers folder moves, deprecated re-exports for backward compatibility, and bulk import updates across the codebase.

PURPOSE: Step-by-step instructions for moving a component between sections in the F0 design system (packages/react/src/), preserving backward compatibility and keeping all imports consistent.

Storybook Sections Reference

All sections are registered in packages/react/.storybook/main.ts via { directory, titlePrefix } entries.

Source folder	`titlePrefix`	Notes
`src/components`	`Components`	All public F0 components
`src/patterns`	`Patterns`	—
`src/kits`	`Kits`	—
`src/experimental`	`Experimental`	Legacy only — do NOT add new components here
`src/layouts`	`Layouts`	Page layout components
`src/lib`	`Library`	Internal utilities and providers
`src/hooks`	`Library`	Public exported hooks
`src/sds`	`SDS`	Satellite design systems
`src/examples`	`Examples`	Full-app example stories
`src/ui`	`🔒 Internal`	Radix/shadcn primitive wrappers — not public

If the destination section is not in this table, see Adding a new section before continuing.

Workflow

Step 1 — Move the entire folder

Move the component folder as-is. Do not rename anything inside it.

mv packages/react/src/<source>/<ComponentName> packages/react/src/<destination>/<ComponentName>

Example — moving F0Button from components to kits:

mv packages/react/src/components/F0Button packages/react/src/kits/F0Button

Step 2 — Do NOT rename any story's `title` field

The titlePrefix in main.ts is prepended automatically by Storybook. The title field inside each .stories.tsx file only needs the component-relative path — never the section name.

// BEFORE move — lives in src/components/F0Button/__stories__/F0Button.stories.tsx
// Storybook renders it as: Components/F0Button
const meta: Meta<typeof F0Button> = {
  title: "F0Button",  // ← do not touch this
  ...
}

// AFTER move — now lives in src/kits/F0Button/__stories__/F0Button.stories.tsx
// Storybook renders it as: Kits/F0Button  ← section changes automatically
const meta: Meta<typeof F0Button> = {
  title: "F0Button",  // ← still unchanged
  ...
}

Step 3 — Add a deprecated re-export in the source section's `exports.ts`

This preserves backward compatibility for any consumer importing from the old path.

Locate (or create) the exports.ts file at the root of the source section folder and add a @deprecated re-export pointing to the new location.

Pattern:

/** @deprecated <ComponentName> has moved to @/<destination>/<ComponentName>. Import from there instead. */
export * from "../<destination>/<ComponentName>"

Example — after moving F0Button from components to kits:

// packages/react/src/components/exports.ts
/** @deprecated F0Button has moved to @/kits/F0Button. Import from there instead. */
export * from "../kits/F0Button"

If exports.ts does not exist in the source section, create it with only the deprecated re-export line above.

Step 4 — Update all imports across the codebase

4a — Update `@/` alias imports

Replace every occurrence of the old @/ alias import path with the new canonical path.

Dry-run first (lists affected files without modifying them):

grep -r "@/<source>/<ComponentName>" packages/react/src \
  --include="*.ts" --include="*.tsx" -l

Apply the replacement:

find packages/react/src -type f \( -name "*.ts" -o -name "*.tsx" \) \
  -exec sed -i '' 's|@/<source>/<ComponentName>|@/<destination>/<ComponentName>|g' {} +

Example — updating imports after moving F0Button from components to kits:

# Dry-run
grep -r "@/components/F0Button" packages/react/src --include="*.ts" --include="*.tsx" -l

# Apply
find packages/react/src -type f \( -name "*.ts" -o -name "*.tsx" \) \
  -exec sed -i '' 's|@/components/F0Button|@/kits/F0Button|g' {} +

The deprecated re-export added in Step 3 means existing consumers outside packages/react/src (e.g., the Factorial app) continue to work unchanged until they migrate to the new path.

4b — Check and fix relative imports inside the moved component

Files inside the moved component may use relative imports that point to sibling folders that stayed behind (e.g., ../../../components/Charts/utils/colors). These break silently because sed on @/ paths does not touch relative paths.

Find broken relative imports inside the moved component:

grep -r "\.\." packages/react/src/<destination>/<ComponentName> \
  --include="*.ts" --include="*.tsx" | grep "<source>"

Also check files that were NOT moved but imported FROM the moved component using relative paths:

grep -r "<source>/<ComponentName>" packages/react/src \
  --include="*.ts" --include="*.tsx" | grep "\.\."

Fix by converting broken relative paths to @/ alias paths:

# Example: inside the moved component, relative refs to a sibling that stayed behind
find packages/react/src/<destination>/<ComponentName> -type f \( -name "*.ts" -o -name "*.tsx" \) \
  -exec sed -i '' 's|\.\./\.\./\.\./\.<source>/SiblingFolder|@/<source>/SiblingFolder|g' {} +

Rule of thumb: after moving, all cross-component imports inside the destination folder should use @/ alias paths, never relative paths that cross folder boundaries outside the component itself.

Step 5 — Verify

Run all checks from packages/react/:

pnpm tsc        # type-check — catches broken imports
pnpm lint       # lint
pnpm vitest:ci  # unit tests

Fix any errors before committing.

Checklist

Use this before opening a PR:

Component folder moved to destination section
No title field modified in any .stories.tsx file
@deprecated re-export added to src/<source>/exports.ts
Re-export uses export * from "../<destination>/<ComponentName>"
All @/<source>/<ComponentName> imports updated to @/<destination>/<ComponentName>
Relative imports inside the moved component inspected — broken cross-boundary relative paths converted to @/ alias paths
pnpm tsc passes with no errors
pnpm lint passes with no errors
pnpm vitest:ci passes

Adding a new section

If the destination folder is not registered in main.ts, add an entry to the stories array before moving any component:

// packages/react/.storybook/main.ts
stories: [
  // ... existing entries ...
  {
    directory: "../src/<new-folder>",
    titlePrefix: "<New Section Label>",
  },
],

Create the folder if it does not exist:

mkdir -p packages/react/src/<new-folder>

Then continue from Step 1.

Real-world examples from the codebase

These existing deprecated re-exports follow the same pattern described above and can be used as reference:

// src/components/exports.ts
/** @deprecated UpsellingKit has moved to @/sds/UpsellingKit. Import from there instead. */
export * from "../sds/UpsellingKit/exports"

// src/experimental/exports.ts
/** @deprecated Banners has moved to @/sds/ai/Banners. Import from there instead. */
export * from "../sds/ai/Banners/exports"

// src/ai/exports.ts
/**
 * @deprecated This path is deprecated. Import from '@factorial/f0/sds/ai' instead.
 * This re-export will be removed in a future version.
 */
export * from "../sds/ai/exports"

f0-move-component

name: f0-move-component description: Use when moving an F0 component from one Storybook section to another. Covers folder moves, deprecated re-exports for backward compatibility, and bulk import updates across the codebase.