Arquitetura e coexistência

A v1 continua sendo o produto estável. A vNext é uma evolução aditiva e pode se tornar principal somente depois de provar cobertura, acessibilidade, consumo e migração.

Decisão registrada

A ADR-021 registra a evolução aditiva. A ADR-022 introduziu três saídas coexistentes e a ADR-023 acrescentou Angular nativo como quarta saída. Esta página resume as decisões sem substituí-las.

Linhas em coexistência

Linha	Estado	Responsabilidade
v1 · Web CSS	Estável	Tokens, CSS, runtimes opt-in, catálogo atual e consumo agnóstico de framework.
vNext	Em construção	Documentação por tecnologia, adapters nativos e nova base comportamental.

A vNext não altera contratos da v1 silenciosamente. Cada componente deve ter disponibilidade explícita por tecnologia, e a migração será decidida somente com evidência de uso real.

Responsabilidades no repositório

ds-tis/
├── css/ + js/ + docs/ + stories/      # v1 estável
├── apps/docs/                          # Astro + Starlight
├── packages/react/                     # adapter React em construção
├── packages/angular/                   # biblioteca Angular nativa beta
├── packages/theme-schema/              # contrato JSON
├── packages/theme-engine/              # ponte para js/theme
├── .storybook/                         # v1 HTML/Vite
├── .storybook-vnext/                   # validação interna React/Vite
└── .storybook-angular/                 # validação Angular isolada

Quatro saídas por componente

O DS não procura uma implementação única nem um provider vencedor. Cada componente pode ser entregue em quatro saídas independentes:

Saída	Papel	Distribuição
HTML/CSS/JS	Implementação agnóstica e runtime opt-in	pacote ds-tis
Ark/Zag	Implementações headless por tecnologia	adapters e releases próprios
React · shadcn/Base UI	Source React composto pelo shadcn, com primitives Base UI	registry shadcn @tis
Angular	Biblioteca Angular nativa com Angular Aria/CDK quando necessário	pacote @tis/angular, atualmente em beta local

As quatro compartilham tokens, linguagem visual, intenção e requisitos de acessibilidade. Source, dependências, API técnica, instalação e testes não são fundidos. Uma saída indisponível continua visível como tal e não reutiliza código de outra para simular cobertura.

Escolha na documentação

Cada página de componente deve permitir escolher:

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

A escolha troca preview, instalação, imports, API, exemplo, dependências, compatibilidade, limitações e evidências. Design, uso e acessibilidade comuns permanecem compartilhados. A comparação entre saídas mede paridade e diferenças legítimas; não elimina nenhuma delas.

Tema e tokens

O JSON de tema é entrada do motor, não um dump de uma biblioteca específica. @tis/theme-schema valida a configuração; @tis/theme-engine traduz essa configuração para CSS variables, contraste, radius e tipografia.

Figma

O arquivo atual permanece associado à v1. A futura biblioteca vNext será uma cópia controlada em outro arquivo. Um plugin poderá aplicar o JSON validado às Variables da cópia, mas não publicará nem atualizará bibliotecas automaticamente.

Gates

1. Fundação documental e Storybook.
2. Saída Ark/Zag validada internamente.
3. Saída React/shadcn/Base UI validada pelo registry.
4. Saída Angular nativa validada por pacote, Storybook e consumer real.
5. Brief do componente piloto.
6. Spec Figma e matriz de contrato aprovadas.
7. Implementação separada das saídas autorizadas.
8. Paridade, acessibilidade e consumo real por saída.
9. Seletor documental com estado real das quatro saídas.
10. Comparação v1 × vNext e decisão de promoção.