alouette/skills/alouette-migration/SKILL.md

A modern, customizable design system built on top of NativeWind v5 with configurable defaults

---
name: alouette-migration
description: >
  Upgrade an app to a newer alouette. Each major has a reference listing its
  breaking changes with before/after code, then what changed within that major
  without breaking (deprecations to migrate ahead of the next one,
  recommended replacements). Apply them in order from the installed version to
  the target, never skipping one. alouette-codemod rewrites the mechanical
  part (the removed Surface and stacks); the rest is by hand, guided by the
  type errors and by the screens a changed appearance names. Load when bumping
  alouette or alouette-icons, fixing type errors or console warnings after an
  upgrade, running alouette-codemod, or replacing a removed component, prop,
  variant or token (Surface, HStack, VStack, EditableSurface, a contained,
  ghost or list variant).
sources:
  - packages/alouette/bin/alouette-codemod.mjs
  - packages/alouette/bin/codemods/surface-and-stacks.mjs
---

# alouette — Migration

## Upgrade, one major at a time

1. Read the installed version (the app's lockfile, or
   `node_modules/alouette/package.json`) and the target.
2. Open every reference from the installed major to the target, in order, and
   apply each section above the target version. Going from 22 to 24 is
   [22.md](references/22.md)'s "Within 22.x", then [23.md](references/23.md),
   then [24.md](references/24.md): a later major assumes the earlier one done
   (23 removes what 22 deprecated, and its codemod only knows the 22 names).
3. Bump the peers a section names with alouette (`alouette-icons` in 24,
   `nativewind` and `react-native-css` in 22.x), and regenerate a custom
   palette when a section says so: a palette generated by an older
   `alouette/theme-generator` keeps the old token names.
4. Run the app's type check. A removed or renamed export, prop or variant is a
   type error; a changed appearance is not, so review the screens each
   "Changed appearance" list names.

| Upgrading to | Reference                 | In short                                                                                             |
| ------------ | ------------------------- | ---------------------------------------------------------------------------------------------------- |
| 19.0.0       | [19.md](references/19.md) | the `$` spacing and text-size tokens become classes                                                  |
| 22.x         | [22.md](references/22.md) | NativeWind rc; `Surface`, the stacks and `EditableSurface` deprecated (codemod)                      |
| 23.0.0       | [23.md](references/23.md) | `tonal` button material, variants renamed, deprecated aliases removed, tokens renamed, palette regen |
| 24.0.0, 24.x | [24.md](references/24.md) | `FormItem` render params, one `alouette-icons` module per glyph; `DecisionBar` recommended           |
| 25.0.0       | [25.md](references/25.md) | `system` theme resolved in CSS: palette regen, pass the preference to `ScopedTheme` as is            |

## Codemod

```sh
npx alouette-codemod surface-and-stacks --dry-run src
npx alouette-codemod surface-and-stacks src
```

Run it from the app with `typescript` installed, then the formatter and the
linter. It prints a `file:line` warning for what it leaves to you (a dynamic
`size` on a `Surface`, spread props, a re-export): options and warnings in
[22.md](references/22.md).

Source: packages/alouette/bin/alouette-codemod.mjs; bin/codemods/surface-and-stacks.mjs

## Common Mistakes

### HIGH Skipping a major

Wrong: bumping from 22 to 24 and fixing only what [24.md](references/24.md)
lists.

Correct: apply 22.x's deprecations, then 23, then 24. The 23 removals are type
errors only where the app used the removed names; the renamed variants and
tokens of 23 written as strings (`className`, a variant held in a variable)
type-check and silently lose their styling.

### HIGH Mapping every `contained` to `filled`

Wrong: a search-and-replace of `variant="contained"` to `variant="filled"`.

Correct: `filled` is the one action that must dominate; every other button
drops its `variant` and takes the `tonal` default, and the secondary action of
a pair is `accent="neutral" variant="soft"`. The full mapping is in
[23.md](references/23.md).

Source: packages/alouette/src/ui/actions/PressableBox.tsx

### MEDIUM Keeping a palette generated by the previous major

Wrong: upgrading alouette and keeping the committed `palette.css` and
`themeVariables.ts`.

Correct: rerun the app's `writeTheme` build script when a reference says the
palette changed (23.0.0 renamed the interactive tokens, so an old palette has no
ground for any button).

Source: packages/alouette/src/theme-generator/writeTheme.ts