Architecture and coexistence

v1 remains the stable product. vNext is an additive evolution and may become primary only after proving coverage, accessibility, consumption, and migration.

Recorded decision

ADR-021 records additive evolution. ADR-022 introduced three coexisting outputs and ADR-023 added native Angular as the fourth output. The ADRs are maintained in Brazilian Portuguese. This page summarizes them without replacing the canonical decisions.

Coexisting lines

Line	State	Responsibility
v1 · Web CSS	Stable	Tokens, CSS, opt-in runtimes, the current catalog, and framework-agnostic consumption.
vNext	In development	Technology-specific documentation, native adapters, and a new behavioral base.

vNext does not change v1 contracts silently. Each component must declare its availability by technology, and migration will be decided only with evidence from real consumption.

Repository responsibilities

ds-tis/
├── css/ + js/ + docs/ + stories/      # stable v1
├── apps/docs/                          # Astro + Starlight
├── packages/react/                     # React adapter in development
├── packages/angular/                   # native Angular beta library
├── packages/theme-schema/              # JSON contract
├── packages/theme-engine/              # bridge to js/theme
├── .storybook/                         # v1 HTML/Vite
├── .storybook-vnext/                   # internal React/Vite validation
└── .storybook-angular/                 # isolated Angular validation

Four outputs per component

The DS does not seek one implementation or a winning provider. Each component may be delivered through four independent outputs:

Output	Role	Distribution
HTML/CSS/JS	Framework-agnostic implementation and opt-in runtime	ds-tis package
Ark/Zag	Headless implementations by technology	dedicated adapters and releases
React · shadcn/Base UI	React source composed with shadcn and Base UI primitives	@tis shadcn registry
Angular	Native Angular library with Angular Aria/CDK when needed	local beta package @tis/angular

All four share tokens, visual language, intent, and accessibility requirements. Source, dependencies, technical APIs, installation, and tests are not merged. An unavailable output remains visible as unavailable and never borrows another output’s code to simulate coverage.

Documentation choice

Every component page must allow the user to choose:

[ HTML/CSS/JS ] [ Ark/Zag ] [ React · shadcn/Base UI ] [ Angular ]

The choice switches preview, installation, imports, API, example, dependencies, compatibility, limitations, and evidence. Shared design, usage, and accessibility content is not duplicated. Comparison measures parity and legitimate differences; it never removes an output.

Theme and tokens

Theme JSON is the engine input, not a dump from a specific library. @tis/theme-schema validates the configuration; @tis/theme-engine maps it to CSS variables, contrast, radius, and typography.

Figma

The current file remains associated with v1. The future vNext library will be a controlled copy in a separate file. A plugin may apply validated JSON to the copy’s Variables, but it will not publish or update libraries automatically.

Gates

1. Documentation foundation and Storybook.
2. Ark/Zag output validated internally.
3. React/shadcn/Base UI output validated through the registry.
4. Native Angular output validated through package, Storybook, and a real consumer.
5. Pilot component brief.
6. Approved Figma spec and contract matrix.
7. Separate implementation of authorized outputs.
8. Parity, accessibility, and real consumption per output.
9. Documentation selector exposing the real state of all four outputs.
10. v1 × vNext comparison and promotion decision.