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

=== Assistant: You can make this scale in a monorepo, but you usually need two things at the same time: ===
You can make this scale in a monorepo, but you usually need two things at the same time:
# A real “package boundary” for the shared UI library (or libraries) so consumers do not silently pick up breaking changes.
# A CI strategy that only tests what is affected, plus strong component-level automated checks, so you stop paying “full product QA” for every change.

Below are patterns that actually work in large React + TS monorepos.

==== What it is: Keep one repo, but model components/ as one or more workspace packages, published to an internal registry (or at least versioned and consumed like packages). Use semantic versioning and a release tool (Changesets is a common choice in TS monorepos). 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> ====

Key property: A feature team only gets a component change when they choose to bump the dependency.

===== - Teams work independently: Component changes do not immediately affect every consumer. Consumers update on their timeline. =====
* No default full regression: Your default is “component tests + affected consumer tests,” not “entire product QA.”
* Scales to many teams: Versioning + changelog + deprecation policy becomes the coordination mechanism.

===== - packages/ui (design system components) =====
* optionally packages/ui-tokens, packages/ui-icons, packages/ui-utils
* apps/features depend on @org/ui with a pinned semver range
* updates happen via automated “dependency bump” PRs (Renovate-style workflow)

===== - Blast radius control (biggest win) =====
* Clear contracts: public API surface becomes explicit
* Natural deprecation/migration: old versions can live while teams migrate

===== - You are signing up to maintain versions (release notes, deprecations, support window) =====
* Local dev ergonomics can be trickier if you are not using workspace tooling well
* Potential for version skew: different parts of the product on different UI versions (you mitigate this with “supported versions” policy and scheduled migrations)

==== Even with package boundaries, you still want to avoid massive CI runs. ====

Tools like Nx compute “affected projects” (changed projects plus dependents) so CI only runs the relevant builds/tests. Nx<ref>{{cite web|title=Nx|url=https://nx.dev/docs/features/ci-features/affected|publisher=nx.dev|access-date=2026-01-06}}</ref>
In Bazel ecosystems, the same idea exists via dependency queries and “diff-to-affected-targets” tooling (for example, bazel-diff). GitHub<ref>{{cite web|title=GitHub|url=https://github.com/Tinder/bazel-diff|publisher=github.com|access-date=2026-01-06}}</ref>

Reality check: if you change a core Button that everything depends on, “affected” might still be huge. That is not a tooling failure, it is telling you the truth about coupling. The fix is usually more boundaries (split packages) and/or more backward compatibility.

==== If the fear is “we will break unknown screens,” you need fast, trustworthy signals closer to the component library: ====
* Storybook as the contract surface
* Visual regression on stories (Chromatic, Percy, etc.). Chromatic integrates with Storybook and adds PR checks for UI changes. chromatic.com<ref>{{cite web|title=chromatic.com|url=https://www.chromatic.com/storybook|publisher=chromatic.com|access-date=2026-01-06}}</ref>
* Component unit tests (Testing Library), accessibility checks (axe), and type-level API tests (for TS public props)

This does not eliminate all integration risk, but it dramatically reduces “manual QA for every tweak.”

==== In big orgs, the technical setup fails without governance: ====
* Component owners/maintainers (not necessarily gatekeepers, but accountable)
* Backward-compatibility rule by default
* Breaking-change RFC and a defined support window
* Deprecation workflow: warn in console/dev builds, codemods, migration guide
* “No breaking changes on Friday” style operational rules if needed

This is how you keep velocity without making the shared library radioactive.