Migration

Migrate screen by screen. The legacy package is frozen, but it reads the same provider and the same tokens, so both trees can live in one app without a break in the theme.

Install the legacy bridge

pnpm add @xaui/native@beta --save-exact @xaui/native-legacy@0.2.11

Pin @xaui/native-legacy to an exact version. It is frozen and it depends on the @xaui/native provider — never mount a second one.

Move the imports

// Before: keep the old component for now
import { Button } from '@xaui/native-legacy/button'

// After: adopt the current one
import { Button } from '@xaui/native/button'

Variants and colours

Legacy	@xaui/native
solid + primary	variant="primary"
flat + primary	variant="secondary"
bordered + primary	variant="tertiary"
light + primary	variant="ghost"
faded + primary	variant="secondary" + border via style
solid + danger	variant="danger"
flat + danger	variant="danger-soft"
themeColor="default"	variant="secondary"
themeColor="secondary" \| "tertiary"	dropped — those were levels, not colours

The same conversion applies to the success, warning and danger families wherever a component exposes them. A free hue becomes color="#…".

Configuration becomes composition

// Legacy
<Button
  startContent={<SaveIcon />}
  customAppearance={{ container: containerStyle, text: labelStyle }}
>
  Save
</Button>

// Current
<Button style={containerStyle}>
  <Button.Icon as={SaveIcon} />
  <Button.Label style={labelStyle}>Save</Button.Label>
</Button>

startContent and endContent become slots, placed in JSX order.
customAppearance.container becomes style on the root.
Every other key becomes style on its slot.
fullWidth becomes the explicit style prop width="100%".

Suggested order

Mount one XAUIProvider at the root.
Point the old imports at the frozen package.
Migrate a screen and its components together.
Check light, dark, VoiceOver/TalkBack and the gestures.
Drop the legacy package once no import is left.