Component Library

A library cannot know which languages its products ship in, so hardcoded text forces one language on every consumer. Elements should take complete, translatable messages from the app, which owns translation, and let every internal default string be overridden.

A literal freezes one decision inside the component, so no theme, mode or consumer can change it. A semantic token names the role a value plays, such as selected surface, and lets the active theme supply the value.

A new variant is MINOR because it adds backward-compatible capability; a spacing fix back to the documented design is PATCH; a renamed property is MAJOR, because code still passing the old name stops working.

Several boolean style flags let callers ask for combinations that make no sense, with the winner hidden in the implementation. One enum variant property makes the options mutually exclusive, exhaustively checkable and easy to extend; booleans stay for genuinely independent axes.

A compound component family is a root holding shared state plus named parts that read it implicitly. Consumers arrange the parts and write their contents, so new layouts need no new API; an item array turns every need into a field.

A headless component supplies behaviour — state, keyboard handling, focus and accessibility semantics — and ships no styling; a styled component adds the system's look on top. Choose headless when a product's visuals differ beyond what theming can express.

Thin wrappers put everything framework-free in a core and give each framework an idiomatic shell; custom elements ship one implementation any framework renders; shared behaviour logic writes interaction rules once while each framework renders its own markup.

Ship a static import-and-export format with one module per component, keep modules free of import-time work, and declare which files have side effects. Declaring everything side-effect free drops imported style files; declaring nothing keeps every component.

Interaction tests catch broken behavior and keyboard contracts; visual diffs across variants and themes catch rendering regressions; automated accessibility scans catch rule-detectable defects; consumer-contract tests catch breaks in real usage; manual assistive-technology review covers the rest.

Changing a default, removing a documented styling hook or stable markup part, changing focus order or keyboard behavior, changing a role or accessible name, and changing when an event fires all break consumers without touching a property.

Reach for the prebuilt recipe first: it encodes the approved layout, behaviour and edge cases for a common need and picks up fixes automatically. Drop to primitives only when no recipe fits, and compose them rather than restyling a recipe's internals.

Native apps share the design tokens, the component specs (anatomy, variants, states, behaviour, accessibility intent) and the naming, not the web code. Each platform rebuilds the components with its own UI toolkit, input model and accessibility services.

An app must run a single copy of its UI framework; declaring it a peer makes the app supply that copy, avoiding duplicate instances that break shared state and double the download, while the range states which versions work.

Isolation makes every state reachable on demand without the app's data, login or routes, lets teams build before pages exist, and exposes hidden dependencies. It cannot show real page layout or data, so it complements in-app review.

Role and accessible name are what assistive-technology users and consuming teams rely on, so querying by them tests the public contract, fails when a control loses its name, and survives internal refactors.

Live regions created on the fly are often not announced, and many regions talk over each other. One announcer mounted up front queues, deduplicates and throttles status messages, so every component announces reliably.

Tab enters the list on the active tab and leaves it for the panel; arrow keys move between tabs and wrap. Activation follows focus only when panels appear without noticeable latency; otherwise Space or Enter activates.

Offer both modes through one convention: a value input makes the component controlled, a default-value input seeds internal state for uncontrolled use, and a change callback fires in either mode. The mode is fixed at first render.

One package gives consumers a single coherent version and simple upgrades; per-component packages allow independent releases but let an app mix incompatible versions and duplicate shared internals. Many systems ship one package with per-component entry points.

Runtime injection needs no consumer setup but costs runtime work and complicates server rendering; one prebuilt stylesheet is simplest but ships every component's styles; per-component style files ship only what is used but need build support.

Start from the component's specified variants and states, add extreme data and setup-dependent states, and skip redundant combinations. Named examples are reviewable, linkable and reusable; states reachable only through controls are rarely seen.

Formatting rules — separators, currency placement, date order, digits — differ by locale, and only the app knows the user's locale. Elements should take raw values and format them through a formatter the app supplies, so every element in a product agrees.

Everything that expresses reading direction mirrors: element order, start and end alignment, back and next arrows, chevrons, steppers and progress. Icons of real objects, clocks, logos and usually media controls stay unflipped, and numbers keep their left-to-right order.

Elements should let text grow or wrap — no fixed widths or heights on text-bearing parts — because translations are often longer. Truncate only non-critical text in constrained spots, and keep the full text reachable; never truncate actions, amounts, dates or errors.

Scans check rule-detectable defects in isolated components; they cannot judge meaning, keyboard flow, or how components combine on a page. The library guarantees each part's semantics; the app owns label wording, page structure, focus order and overrides.

A component-scoped override token is a named hook on one component whose default references a semantic token. Setting it changes only that component, so it beats editing the semantic token when the rest of the product must stay as it is.

Each variant should resolve, per anatomy part and state, to a semantic token name, never to a value. One declared table makes every combination visible and checkable, keeps values in the theme, and turns a new variant into one reviewed row.

Publish versions such as 5.0.0-beta.1 that consumers must opt into explicitly; they sort below 5.0.0, promise no stability, may change between betas, and let pilot apps prove the migration guide first.

Replace per-component traps with one shared focus-layer stack: only the top layer contains focus, everything beneath is inert, Escape closes one layer, and closing returns focus to the opener, or a logical fallback if it is gone.