Architecture

Why web components, how the system is organized, and how it evolves

Root Axis is built as web components (Lit) + design tokens (Style Dictionary), consumed identically across React, Next, Vue, Solid, and Svelte — a single source of truth for any stack.

​

Why Web Components?

Web components are a platform standard (W3C): they don’t depend on any framework’s lifecycle, which protects the investment long-term — frameworks change, the web standard remains.

Shadow DOM guarantees real style encapsulation: the consuming application’s CSS doesn’t break the component, and vice-versa.

Practical result: visual consistency across apps regardless of framework, a single place to fix bugs, and freedom for each team to pick their own stack.

​

Repository layout

Repository	Description
root-axis-design-system	@root-axis/design-system — Lit components
root-axis-design-tokens	@root-axis/design-tokens — Style Dictionary tokens (CSS, SCSS, JS, TS, JSON)
root-axis-examples	Example apps: React, Next, Vue, Solid, Svelte
root-axis-docs	This documentation site (Mintlify)

Each repository is versioned and published independently — there is no unified monorepo today.

Each component follows the same file anatomy:

root-axis-design-system/src/components/button/
├── index.ts            # behavior (Lit)
├── style.css            # style (consumes only tokens)
└── index.stories.ts     # living documentation (Storybook, CSF3)

​

Code design principles

Immutable props

Data flows from outside in (attributes/props); the component never mutates what it receives. Communication back out happens through native DOM events (e.g. ra-toggle on the accordion) or callback props (onClick, onChange).

Strict separation of concerns

Behavior (.ts), style (.css), and documentation (.stories.ts) live in separate files, with the same layout across every component.

Accessible by default

Components wrap native elements (a real <button> inside ra-button, a real <label for>/<input> pair inside ra-checkbox), inheriting semantics, focus, and keyboard navigation from the browser for free.

Minimal dependencies

Runtime dependencies are Lit (~5 KB) and Motion (used only by the accordion’s open/close animation). Fewer dependencies means fewer vulnerabilities and fewer breaking changes from third parties.

Minimal API

Few props (type, size, dark…), always with sensible defaults.

​

State management

Components are stateless by design: they reflect the props they receive. Internal state, when it exists, is minimal, ephemeral, and local (Lit reactive properties — e.g. the accordion’s open/closed state). Application state belongs to the application: the design system doesn’t embed or prescribe a state manager, and communicates exclusively via props down and DOM events up.

​

Testing

Unit tests run with Vitest in browser mode — tests execute in real Chromium via Playwright, not a simulated DOM. Web components rely on platform APIs (Shadow DOM, custom elements) that DOM simulators implement incompletely, so testing in a real browser removes a whole class of false positives/negatives. Tests cover public API, rendering, variants, and basic accessibility of each component.

Design Decisions

See the reasoning behind each choice (Lit vs. alternatives, Style Dictionary, Storybook, validation).