/tamagui-upgrade-v3

name: tamagui-upgrade-v3
description: |
  Migrate an app from Tamagui v2 (or v1) to v3. Use when upgrading Tamagui versions,
  removing `$` token prefixes, converting `hoverStyle`/`pressStyle`/media/theme/platform
  condition objects to flat values, running the flat-values codemod, or fixing v3
  breaking changes. Triggers: "upgrade tamagui", "migrate to v3", "flat values",
  "$ tokens", "hoverStyle", "codemod", "tamagui v3 breaking changes".
version: 1.1.0

Upgrading to Tamagui v3

V3 moves every style condition into the value of the property it changes and removes the `$` sigil. There is no compatibility setting and no legacy runtime path: the codemod plus the manual work in this skill is the entire migration.

// v2
<View bg="$background" hoverStyle={{ bg: '$backgroundHover' }} p="$4" $sm={{ p: '$6' }} />

// v3
<View bg="background hover:background-hover" p="4 sm:6" />

The rules that make v3 readable once you know them:

• Quoted values resolve config-first: `p="4"` is the space token, `p={4}` is a

raw platform value (CSS px on web, points on native). Strings are grammar, numbers are raw.

• A value is `base? clause*`. Clause modifiers match Tailwind spelling:

`hover:`, `press:`, `dark:`, `sm:`, `web:`, `group-hover/card:`, `@sm/card:`. More-specific matching conditions win; authored order breaks equal-specificity ties. `dark:hover:x` requires both.

• Multi-word built-in names are kebab-case: `$backgroundHover` is now

`background-hover`. User-defined token names keep their authored spelling.

• A configured name wins over a same-spelled CSS literal; anything not in the

config is literal CSS.

How to run this migration

Most of the mechanical work is owned by two tools you drive rather than re-implement:

• `npx tamagui migrate --from v2` (or `--from v1`) prints the canonical

step-by-step migration prompt: dependency updates, config and theme moves, the Sheet anatomy migration, and every deprecated-API replacement with before/after. That prompt is the checklist of record. This skill tells you how to sequence it, what the codemod cannot do, and how to prove the result.

• `npx @tamagui/codemod-flat-values` converts `$` tokens and condition objects

transactionally and reports everything it cannot prove safe.

Real-corpus measurement across two apps: 80% of sites converted cleanly on the Bento corpus (1,681 of 2,113) and 67% on a mid-size control-room app (1,007 of 1,504). Budget for a third of sites needing human judgement, not a fifth.

The variance is worth predicting before you start, because one authoring habit dominates it. In the 67% corpus, 272 of the 497 flagged sites were a single cause: fractional space tokens (`$0.5`, `$1.5`, `$2.5`, `$3.5`), which flag as `legacy-token-dot-path`. Count them first (`rg -o '"\$[0-9]+\.[0-9]+"'`); an app that leans on half-steps lands near 67%, one that does not lands near 80%.

The flagged third is where apps break, and it is what most of this skill is about. The section below on silent value drift is where they break WITHOUT being flagged, which is worse.

First checkpoint: V3 APIs, existing design values

Record the runtime version and config version separately. For a V2 app, migrate required APIs while preserving its resolved token, theme, font, media, and animation values. For an app on Config v5 or v5-subtle, keep that config. If the app already runs V3 with Config v5, inventory remaining API work before applying codemods; this is a supported checkpoint, not a failed upgrade.

Finish this checkpoint with the report reviewed, typecheck/build passing, and real screens and interactions compared with their baseline. Do not automatically begin Config v6, wholesale `html.*` conversion, Tailwind adoption, or a redesign after those checks pass. List optional changes as separate follow-ups. Preserve custom configs too; an unsupported old import is not permission to substitute v6 values.

Gate 1: preserve generated v5 themes

Check the theme-generation imports before editing:

rg "createV5Theme|subtleChildrenThemes|@tamagui/theme-builder|themes/v5-builder|v5-subtle-builder"

V3 keeps the v5 output packs as frozen static themes. The old dynamic generation imports moved out of the default packages. An app that generates v5 themes can still reach the intermediate checkpoint without rebuilding its design on v6.

Three ways out, cheapest first:

1. **Freeze the generated themes.** The builder is a value generator, and most apps have long since stopped changing its inputs. Run it once on the CURRENT version, serialize the output to a static literal, and the app stops importing the removed API while every resolved value survives byte-identical. This decouples the theme question from the v3 upgrade entirely, and it is the right first move whenever the palette is settled or, especially, when its values were measured or tuned against a visual reference. 2. **`@tamagui/config-v5`**, if it is available in your version: the dynamic builders published as a separate opt-in package so they stay out of the default install. 3. **Rebuild on the v6 recipe API** (`createThemes`, `levels`, scales, treatments from `@tamagui/themes/builder`), when a v6 design migration is separately requested. This is where a v6 app expresses what `childrenThemes` and `componentThemes` used to do.

Do not combine 3 with the flat-values migration. A theme rebuild and a syntax rewrite in one diff leaves nothing to bisect when the app looks wrong.

Only in the separately chosen v6 migration, if the app reads the adaptive ramp, note that v6 has 11 steps where v5 had 12. `npx tamagui migrate --from v2` prints the approximate remap; the endpoints are exact and `color6`/`color7` merge into `color6`, so everything from `color8` up shifts down one. Inspect contrast in the compressed middle rather than trusting the shift.

Phase 0: inventory before touching anything

Real v2 apps measured between 5,0