> ## Documentation Index
> Fetch the complete documentation index at: https://rodrigo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

> [!TIP]
>
> **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

> [accordion] 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`).

> [accordion] Strict separation of concerns
>
> Behavior (`.ts`), style (`.css`), and documentation (`.stories.ts`) live in separate files, with the same layout across every component.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [card] [Design Decisions](https://rodrigo.mintlify.site/arquitetura/decisoes-de-design.md)
>
> See the reasoning behind each choice (Lit vs. alternatives, Style Dictionary, Storybook, validation).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.