Editing Openai/695d28c7-94c8-8006-836b-96dbe559b5eb (section)

=== This is a real pattern, but it has sharp edges. ===

===== - Zero-risk rollout for consumers: old stays old, new opts in =====
* Great for big redesigns where compatibility would be messy
* Good when migration needs to be gradual across many teams

===== - Permanent maintenance tax: bug fixes, a11y fixes, and behavior changes now have to be duplicated or backported across variants =====
* Inconsistent product UX: you end up with mixed button styles/behaviors across the app
* Harder to remove old versions: teams stop prioritizing migrations because “it still works”
* API fragmentation: docs, examples, and developer intuition get worse over time

===== Instead of Button.v2 as a naming convention, prefer one of these: =====
* Package major versions (@org/ui@1 vs @org/ui@2) with semver and a support window (cleaner contract)
* New component name when semantics change (PrimaryButton/Button2 is not great, but sometimes Button vs ActionButton is legitimately clearer)
* Adapter layer: keep Button as a thin wrapper over ButtonNext during migration

==== If I had to pick one approach that matches your constraints: ====
# Make shared UI a workspace package (or a few packages) with semantic versioning (Changesets is a common workflow). changesets-docs.vercel.app<ref>{{cite web|title=changesets-docs.vercel.app|url=https://changesets-docs.vercel.app/|publisher=changesets-docs.vercel.app|access-date=2026-01-06}}</ref>
# Consumers pin versions and update via automated bump PRs.
# Require Storybook stories for every component and run visual regression on PRs. Storybook<ref>{{cite web|title=Storybook|url=https://storybook.js.org/docs/writing-tests/visual-testing|publisher=storybook.js.org|access-date=2026-01-06}}</ref>
# Use affected-only CI so the default pipeline is fast. Nx<ref>{{cite web|title=Nx|url=https://nx.dev/docs/features/ci-features/affected|publisher=nx.dev|access-date=2026-01-06}}</ref>
# Establish a deprecation and support policy (for example: “we support the last 2 major UI versions; older majors get security/a11y fixes only, then are removed on a schedule”).

That combination gives you independence, reduces QA cost, and scales socially.

If you want, I can sketch a concrete repo layout + CI pipeline outline (GitHub Actions style) for this setup, including how teams consume a pinned UI version while still developing locally against workspace packages.