Migrate from another library
Moving to motif from another styling library is an incremental job, not a rewrite. Each source library has its own recipe; they all share the same shape — install alongside, port family by family, remove the old library when nothing imports it.
Pick your starting point
Each migration has a dedicated recipe with a mapping table, a worked component, and the idioms that do not carry over one-to-one.
| Coming from | Recipe | The core shift |
|---|---|---|
| styled-components | Migrate from styled-components | Template literals become typed objects |
| Emotion | Migrate from Emotion | The css prop becomes style props on Box |
| Tailwind | Migrate from Tailwind | Utility classes become typed style props |
| Tamagui | Migrate from Tamagui | A near-rename — styled and variants line up |
If you are moving between motif's own package versions instead — the @motif-js/* to
@usemotif/* renames — see v1 → v2 and v2 → v3.
The shape every migration shares
The four recipes differ in their mapping tables, but the process is the same in each.
Install alongside. motif injects its own styles and does not collide with another styling library's output. Add motif to a project that still runs styled-components, Emotion, or Tailwind and both work at once. There is no big-bang cut-over.
Port primitives first. Box, Stack, Text, the typography — these have the most call
sites, so converting them moves the most code for the least risk. Components that depend on a
primitive move after the primitive does.
One family per pull request. A migration diff is loud but mechanical. Keeping each component family in its own pull request makes the review tractable and the rollback cheap.
Remove the old library last. When a project-wide search for the old import turns up nothing, uninstall the package and delete its provider. That is the migration done.
After the migration
A migrated codebase runs entirely on motif's runtime — correct, and fast enough for most apps. When you want the build-time optimisation, add a bundler plugin; the runtime keeps working unchanged underneath it.