Migrating a custom project

With a coding agent#

The Koala skill carries this page, so an agent can run the whole migration. Install the skill in your project, then start a new session.

npx koalaui-cli@latest skill

Then ask for the audit first:

Migrate this project to Koala UI. Follow references/migrate.md in the koala-ui skill.
Start with the audit and write the plan to koala-migration.md. Change nothing until I approve it.

The agent stops at the plan so you can review it, then works through it and ticks off each surface. The plan lives in your repo, so a later session picks up where the last one stopped. Cursor, Codex and other agents need one line pointing at the skill, see AI and agents.

Before you start#

Step 1: Audit#

Read the project before touching it, and record what you find:

• The stack. Framework, React and Tailwind versions, the styling method (CSS Modules, Sass, styled-components, Emotion, a kit such as MUI, Chakra, Ant or Bootstrap), and the checks the project has: tests, type checking, lint, build.
• The surfaces. Every reusable UI component, or every kit component in use, with how many files import it. Usage count sets the order.
• The structure. The kind of product, each screen’s regions and their order, how navigation works, what scrolls, what happens on small screens, and whether it runs on touch.
• The brand. The primary color, neutrals, radius, fonts and any dark mode, read from the existing tokens or the most repeated values.
• What is yours. Domain components that mean something only in this product, such as a shipment timeline or a seat map. Koala does not replace them.

Step 2: Plan#

Write koala-migration.md at the project root and get it approved before any code changes. Each surface gets its Koala counterpart from the maps below, its tier from npx koalaui-cli@latest list, and a place in the order. Anything with no counterpart stays and moves to tokens only.

# Koala migration

Stack: Next.js 16, React 19, Tailwind 3, CSS Modules
Blockers: Tailwind 3 to 4

## Brand
Primary #0f766e, radius 12px, Inter

## Structure
Point of sale on a touch screen: density compact, controls size lg
Regions: top nav, open tickets, product grid, ticket panel
Decision: keep (approved by the owner)
Shell: LayoutTopbar + Navbar (Pro, ask), three LayoutPane columns

## Surfaces, in order
- [ ] Button (41 uses): src/components/Btn.tsx > Button
- [ ] Text field (18 uses): src/components/Input.tsx > Input, Field
- [ ] Modal (6 uses): src/components/Modal.tsx > Dialog
- [ ] Data grid (3 uses): react-table > Data Table (Pro, ask)

## Stays as it is
src/components/CashCount.tsx: domain component, tokens only

Mark every Pro item and let the project’s owner choose: buy a license, compose the free components, or keep what exists. Never rebuild a Pro component from its docs or preview.

The plan also records one decision the owner has to make about the structure:

Step 3: Set up the foundation#

init adds koala.css, lib/utils.ts, lib/tv.ts, the theme provider and koala.json, and leaves your components alone. Follow the steps it prints for the fonts and the provider, and resolve every warning it gives.

# Tokens, the lib helpers and the theme provider
npx koalaui-cli@latest init

# Only if the plan uses Pro components
npx koalaui-cli@latest login <your-key>

# The free components the plan needs
npx koalaui-cli@latest add button input field dialog

If you already have a lib/utils.ts, init keeps it. Merge Koala’s version in with npx koalaui-cli@latest diff utils: lib/tv.ts imports twMergeConfig from it. If you have a components/ui/button.tsx of your own, add refuses to run until it is moved. Move those files to components/legacy/, update their imports, and commit that on its own.

Step 4: Bring your brand#

Set your brand once, on the tokens, before swapping any component. After that every Koala component arrives in your colors. Put this after the import of koala.css:

:root {
  --brand: #0f766e;
  --radius: 0.75rem;
}

A light brand color also needs a dark --brand-foreground. Load your fonts as --font-sans and --font-heading. An app with one look pins it with <ThemeProvider forcedTheme="light">. For a palette of your own, see Theming.

Step 5: Swap one surface at a time#

1. Start at the bottom. Buttons and text fields first, then overlays, then the pieces inside navigation. Each layer leans on the one before it, and the shell comes last.
2. One surface, one commit. Add the component, read its reference, replace every use, and remove the old one. Run the project’s checks before moving on.
3. Translate props, keep behavior. Handlers, validation, routes, disabled conditions, analytics, test ids and copy all stay exactly as they were.
4. Move what stays to tokens. Replace hard-coded colors and radii in the domain components with the map below, so they follow the themes too.
5. Tick it off. Update koala-migration.md. When a step fails its checks, fix it or stop and say so: never skip a test to move on.

Step 6: Move the structure#

With the pieces in place, move each screen’s shell, one at a time. What the structure is follows from the parts you drop in. Layout and its Navbar and Sidebar are Pro. Without a license, build the free column with Tailwind between Koala components.

• Keep the routes. Every link, active state, permission check and badge count stays. Whatever a screen showed in its navigation, it still shows.
• Set the density once. compact for an app shell, comfortable for a marketing page, with a DensityProvider around the subtree. See Density.
• Size for the hand. Density tunes spacing, not control height. On a touch screen, pass size="lg" to the controls people hit all day.
• Keep what scrolls. A column that scrolled alone still does, and the action that was always in view stays in view. Check it at the smallest screen the product supports.

Component map#

What most projects have, whatever it is called there. Every Koala name links to its page, and the skill holds the same page as a reference for each free component.

Token map#

Keeping both working#

• Unlayered CSS wins. Tailwind’s utilities live in a cascade layer, so a global button { }, a { } or * { } rule in your old stylesheet beats every Koala class. Scope those rules to the old components, or move them into @layer base.
• Tailwind resets the page. On a project that had no Tailwind, its base styles strip the default look from headings, lists and links. Check the old pages right after adding it.
• Token names can collide. init warns about your own --background, --foreground and --radius. Rename yours or remove them, or they override Koala’s themes.
• A kit’s theme provider stays until its last component is gone. It can wrap the same tree as Koala’s ThemeProvider.

Step 7: Clean up#

Once nothing imports them, delete components/legacy/, the old stylesheets and the packages Koala replaced, then run the checks and the production build one last time. Keep koala.json in git: diff and update use it to bring in fixes without touching the files you edited.

FAQ#