Migration guides

Windcraft is opinionated — it ships the design system, you don't bring your own. That means most "migration" is actually:

1. Run npx windcraft init in the repo
2. Let it overwrite tailwind.config.ts, app/globals.css, the RN theme, and windcraft.types.d.ts
3. Replace any hand-rolled tokens (raw hex, ad-hoc spacing scales) with token references
4. Run windcraft check and clean up the violations

ShipFast / Makerkit / SaaS starter

These typically ship with their own Tailwind config and a colour palette. After init, delete the starter's palette block and let Windcraft's config drive Tailwind. Keep route-level layouts and feature code as-is — Windcraft never touches your application logic.

Existing Tailwind project

Same flow. The riskiest change is the tailwind.config.ts — review it before merging the first sync PR. CSS variables in app/globals.css land inside a guarded block (look for the windcraft-vars markers) so your other CSS stays untouched.

React Native / Expo

init writes theme.ts next to your existing styles. Swap your hand-written theme imports to import { theme } from './theme'. The mirror engine (POST /projects/:id/mirror or the MCP tool) helps when porting individual components from web.

Dropping in mid-project

Windcraft does not require a clean slate. The static analyzer catches the worst offences (no-hardcoded-color, no-arbitrary-spacing) so you can prioritise fixes without grepping the whole repo. Use exceptions in .windcraft/config.json to silence anything you can't fix yet.