Monorepo vs polyrepo for a design system

WHAT THIS TESTS This checks whether you can weigh repository architecture against the concrete needs of a design system: many interdependent packages, shared docs, and coordinated releases.

A GOOD ANSWER COVERS Benefits of a monorepo. Atomic commits let you change a token, the component using it, and its docs in one reviewable PR, impossible across split repos. One shared toolchain, TypeScript config, ESLint, and test setup, removes duplication. Components, the docs site, and design tokens import each other directly without publishing intermediate versions. Tools like Turborepo or Nx add a task graph with remote caching and affected-detection so CI only rebuilds and tests what changed. Challenges. You must define and maintain a dependency graph and avoid circular deps. CI needs affected-package detection or it rebuilds everything. Releases require a deliberate strategy: fixed versioning bumps all packages together, independent versioning needs Changesets or Lerna to compute per-package bumps and changelogs. Onboarding and clone size grow, and tooling must scale to the repo.

COMMON WRONG ANSWERS Saying monorepos are always better while ignoring build orchestration and release complexity. Saying separate repos are simpler while ignoring the pain of coordinating cross-repo changes and version bumps. Forgetting caching and affected detection, leading to slow CI.

LIKELY FOLLOW-UPS Fixed versus independent versioning, and which suits a design system. How do you keep CI fast as packages grow. How do you prevent circular dependencies.

ONE CONCRETE EXAMPLE With Turborepo, changing a spacing token and the Card that consumes it lands in one PR; affected-detection rebuilds only tokens, Card, and the docs site, remote cache skips the rest, and Changesets generates the correct per-package version bumps on release.