Migration and Upgrade Guide

Treat the public DOM contract like API. Slot names, data-* attributes, state values, ARIA relationships, schema fields, validator rule behavior, and adapter callback semantics are compatibility-sensitive.

Small internal refactors are safe only when rendered behavior, generated catalogs, and tests remain stable.

Record:

• Current package versions.
• Adapter routes in use.
• Primitive list in production.
• Controlled state owners.
• Custom wrappers around primitive parts.
• Contract snapshots or equivalent DOM assertions.
• SSR routes that render primitives.

Then upgrade in a branch and run focused checks before broad visual QA.

Use a staged lifecycle:

1. Announce the upcoming change and preferred replacement.
2. Mark old behavior deprecated in docs and validator suggestions.
3. Keep compatibility for at least the agreed minor-version window.
4. Remove only with migration notes and tests.

Do not silently remove public contract fields.

When an adapter surface changes:

• Provide before/after examples.
• Explain whether behavior or only syntax changed.
• Preserve ARIA and data-* contracts where possible.
• Add parity tests for all supported adapters.
• Update quick-start, installation, integration, examples, and generated artifacts.

For Svelte and Vanilla, call out lifecycle cleanup changes explicitly. For React, Vue, and Solid, call out SSR/hydration implications.

Run:

pnpm content:build
pnpm content:check
pnpm typecheck
pnpm test:contracts
pnpm test

For app upgrades, also run your route-level interaction tests and inspect at least one primitive of each category: navigation, overlay, selection, input, and disclosure.

Rollback or hotfix when:

• ARIA relationships break on production routes.
• Keyboard operation regresses.
• Controlled state no longer updates.
• SSR hydration mismatches affect primitive state.
• Generated docs artifacts point to nonexistent routes.
• Validator reports widespread false positives after a rule change.

• Breaking contract changes are documented.
• Deprecation plan exists before removal.
• Adapter overlays are updated.
• Generated catalogs are regenerated.
• Contract, interaction, a11y, and SSR checks pass.