Lesson 10: Operations, Migration, and Internal Registry

Migration strategy

When evolving wrappers, treat changes as API migrations:

1. identify behavior changes,
2. write migration notes,
3. provide codemods where possible,
4. run compatibility checks in sample apps,
5. deprecate before removal.

Behavioral changes are often more impactful than visual changes.

Rollout safety

Use staged rollout for critical interaction changes:

• canary package release,
• limited app adoption,
• keyboard/a11y verification,
• full release after validation.

For high-risk components (dialog/menu/select), prefer gradual rollout over big-bang upgrades.

Governance model

Define ownership clearly:

• who approves wrapper API changes,
• who maintains accessibility standards,
• who owns release notes and migration docs,
• who audits internal registry examples.

No ownership means silent drift.

Internal registry as a force multiplier

Create a dedicated internal registry for primitives and wrappers with production-ready examples.

In this repo, the starter location is:

• packages/registers/registry-internal/registry-internal.ts
• entries are typed as RegistryEntry[] and merged into registry_examples
• starter internal entries include dialog, popover, and dropdown-menu patterns

What each registry entry should include:

• source component and version,
• usage example (simple + advanced),
• accessibility guarantees,
• known limitations,
• test references,
• migration notes.

This allows teams to self-serve safe patterns.

Suggested registry layout

registry/
  primitives/
    dialog/
      basic.tsx
      guarded-async.tsx
      notes.md
    popover/
      filter-panel.tsx
      notes.md
    menu/
      actions.tsx
      selection.tsx
      notes.md

registry/
  primitives/
    dialog/
      basic.tsx
      guarded-async.tsx
      notes.md
    popover/
      filter-panel.tsx
      notes.md
    menu/
      actions.tsx
      selection.tsx
      notes.md

Pair the registry with docs pages and a small preview app.

Ongoing maintenance checklist

• quarterly accessibility audits,
• dependency and primitive version updates,
• flaky test cleanup,
• regression review for nested overlays,
• docs refresh for changed defaults.

Final capstone

Deliver a mini internal package that includes:

1. Dialog, Popover, and DropdownMenu wrappers.
2. Test suite with keyboard + a11y assertions.
3. Internal registry entries with examples and notes.
4. Migration note template for future breaking changes.

If this is in place, your primitives adoption is production-grade.