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

# Design Decisions

> A record of key architecture decisions and their trade-offs

This page documents **why** the system was built the way it is — not just what exists today, but the alternatives considered and the reasoning behind each choice. Useful to revisit decisions when the context changes.

## Base library: why Lit?

> [tab] Lit ✅
>
> \~5 KB, declarative reactivity, maintained by Google, no proprietary compiler — it's a thin layer over the platform standard. Easy to hire for and learn. If Lit disappeared tomorrow, the components would still be valid custom elements.

> [tab] Stencil
>
> Good, but introduces a **proprietary compiler** and more build magic — tooling lock-in we'd rather avoid.

> [tab] Plain vanilla
>
> No dependencies, but requires reimplementing reactivity, attribute↔property sync, and efficient re-rendering — boilerplate that becomes a maintenance cost.

Lit is the middle ground: productivity without leaving the platform standard.

## Design tokens: Style Dictionary as the source of truth

Tokens are authored once as plain JSON (`src/colors.json`, `src/size.json`, `src/font.json`) and compiled by **Style Dictionary** into CSS, SCSS, JS, TS, and JSON — one source feeding every consumption style (CSS custom properties, SCSS maps, typed JS/TS constants, or a flat JSON for APIs/config).

> [!NOTE]
>
> This is a stronger starting point than a single hand-written `tokens.css`: adding a new output platform (e.g. a future React Native or mobile target) means adding a new Style Dictionary platform entry in `config.json`, not hand-maintaining a parallel file.

## CSS separated from behavior, per component

Each component's style lives in its own `style.css`, imported with the `?inline` Vite suffix and applied via Lit's `unsafeCSS()` — instead of a `css` tagged-template string embedded inside the component's `.ts` file.

> [!TIP]
>
> Keeping style in a real `.css` file means editor tooling (syntax highlighting, linting, autocomplete) works normally, and a change to visual design never touches the behavior file's diff.

## Unit tests: real browser instead of a simulated DOM

Vitest runs unit tests in **real Chromium** via Playwright, not `jsdom`. Web components depend on platform APIs (Shadow DOM, custom elements) that DOM simulators implement incompletely — testing in a real browser removes a whole class of false positives/negatives.

> [!WARNING]
>
> Storybook's `addon-vitest` (which turns story play functions into interaction tests) is not wired in yet: as of this writing it assumes Vitest 4's `@vitest/browser-playwright` architecture, and Vitest 4 is still in beta. Revisit once Vitest 4 stabilizes.

## Validation: an exported utility, not a Lit dependency

`@root-axis/design-system` exports Zod schemas (`nameSchema`, `emailSchema`, `passwordSchema`, `createPasswordSchema`) and a `validationErrorMessage(schema, value)` helper — but **no component imports Zod**.

> [!NOTE]
>
> The validation rule lives in one place so it isn't duplicated (and doesn't drift) across React, Next, Vue, Solid, and Svelte consumers, but the design system itself stays framework- and validation-library-agnostic. A consuming app calls `schema.safeParse(value)` (or `validationErrorMessage`) and passes the resulting message into whichever error-display prop a future input component exposes.

## Versioning and distribution

* Each repository (`design-system`, `design-tokens`, `docs`, `examples`) is versioned and published independently — there's no unified monorepo today, so `design-system` and `design-tokens` can be on different release cadences.
* Published to the public npm registry under the `@root-axis` scope — these are open-source packages, not internal-only.


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