Design a Large component library

01Concrete scale assumptions

02Architecture decisions and rationale

03Client contracts and data boundaries

1type DialogProps = { open?: boolean; defaultOpen?: boolean;2  onOpenChange?: (open: boolean) => void;3  title: React.ReactNode; description?: React.ReactNode;4  children: React.ReactNode; };5// Focus, Escape, labelling, and portal behavior remain library-owned.

04Failure-mode analysis

05Observability and operations

• Track package and component adoption, version distribution, upgrade lag, deprecation use, and support incidents.
• Gate bundle-size, public-type, visual-diff, accessibility, SSR, and interaction budgets in CI.
• Run a matrix against supported React, browser, theme, locale, direction, and rendering environments.
• Canary releases in representative applications and make rollback or dist-tag reversal immediate.

06Security and accessibility boundaries

• Protect publishing with provenance, least-privilege tokens, review, dependency scanning, and an incident revocation path.
• Accessible names, roles, focus, keyboard behavior, contrast, motion, zoom, and forced-colors support are component acceptance criteria.
• Prefer semantic HTML; use ARIA only where native semantics cannot express the required interaction.
• Document accessibility responsibilities shared with consumers, such as meaningful labels and heading hierarchy.

ANSOne full answer, start to finish

Drive the discussion yourself first. This is one strong answer delivered the way you would say it in the room — a model, not the only correct design.

This one is a distribution and versioning problem more than a components problem. The components are the easy part; the hard part is that dozens of teams consume them on their own schedules, so every decision is about not breaking those teams. Frame it around the monorepo, semantic versioning, and design tokens.

1. Step 1 · Clarify

   Ask: 'How many consuming teams and applications? One framework or several? Do they all upgrade together or independently? And is there a design system with tokens already, or are we defining that too?' Assumptions: 'Dozens of teams, primarily one framework, teams upgrade on their own schedule, and we own the tokens as well.' Independent upgrades is the constraint that shapes everything.

2. Step 2 · Requirements

   User-facing (the consuming developers): components that are accessible by default, themeable, and documented, that they can adopt without a big-bang migration. Hidden: a change must be shippable without forcing every team to update the same day, the bundle impact must be predictable, and breaking changes must come with a migration path.

3. Step 3 · Monorepo with three things in it

   'One repository holds the component packages, a shared design-token package (colors, spacing, type as data, not hard-coded in each component), and a documentation and playground site built from the same source. Keeping them together means the docs cannot drift from the code and the tokens are the single place visual decisions live.'

4. Step 4 · Headless-first components

   'Where it makes sense, components are built on composable headless primitives, so the behavior — keyboard handling, focus management, accessible roles — is separate from the visual styling. That makes them easier to theme and means the accessibility work is done once in the primitive, not re-litigated per skin.'

5. Step 5 · Versioning and release discipline

   'Semantic versioning with automated changelog generation. Every change ships with a changeset declaring whether it is a patch, minor, or breaking. CI runs visual regression, unit, and accessibility tests against every component and gates the release. A breaking change is deprecated first with console warnings, ships with a migration guide and ideally a codemod, gets canaried against a few consumers, and only then goes out as a major after a declared window.'

6. Step 6 · How teams adopt

   'Consuming teams update their dependency when they choose, guided by the changelog and by deprecation warnings that appear well before a breaking release. Nobody is forced to move on the library's schedule. The library owns interaction mechanics and controlled-state support; product data and business logic stay with the consumer.'

7. Step 7 · Bundle and theming

   'Packages use ES module exports with accurate side-effect metadata and narrow entry points so consumers only ship what they import. Theming is semantic tokens — a component asks for surface and text, not a specific hex — so a new theme is a token file, not a component rewrite.'

QAInterview questions and model answers