@softize/opus 21.0.1 → 22.1.0

package/docs/adr/0029-page-header-is-the-single-page-introduction.md

@@ -0,0 +1,71 @@
+# ADR 0029 — PageHeader é a única introdução estrutural da página
+
+- **Status:** aceita.
+- **Data:** 2026-09-28.
+- **Substitui:** ADR 0011, quanto à barra persistente e à separação entre `PageHeader` e
+  `PageIntro`.
+- **Relacionada:** ADR 0016, quanto ao cabeçalho próprio de coleções.
+
+## Contexto
+
+`PageShell` separou a navegação e as ações globais numa barra persistente, enquanto `PageIntro`
+manteve o título no conteúdo. A separação estabilizou a posição das ações, mas criou duas regiões
+para identificar a mesma página. Nas rotas simples, a barra passou a repetir o item já selecionado
+na navegação da aplicação. Nas rotas profundas, o breadcrumb ficou visualmente distante do título
+que ele contextualiza.
+
+Breadcrumb é uma exceção para hierarquias que a navegação persistente não revela. Ele não precisa
+reservar uma faixa em todas as páginas, e uma página de primeiro nível não ganha contexto ao repetir
+seu próprio nome acima do título.
+
+## Decisão
+
+`PageHeader` é a única introdução estrutural de `Page`:
+
+- o header participa da rolagem normal do conteúdo;
+- `PageNavigation` ou `PageBack`, quando presente, ocupa uma linha acima da linha principal;
+- `PageTitle` e `PageActions` compõem a linha principal;
+- páginas sem hierarquia adicional não renderizam nem reservam espaço para navegação;
+- `PageIntro` deixa de fazer parte da anatomia pública;
+- `PageShell` pode coordenar navegação e ações conhecidas pela aplicação, mas não desenha uma barra;
+  esses valores são compostos pelo `PageHeader` da página ativa;
+- `PageState` integral continua substituindo o header e fornece o único heading do estado;
+- uma coleção pode continuar fornecendo o heading principal por `Content level={1}` sem criar um
+  `PageHeader` redundante.
+
+## Consequências
+
+- breadcrumb, título e ações voltam a pertencer à mesma região visual;
+- páginas simples começam diretamente pelo título;
+- a altura inicial do conteúdo pode variar quando existe breadcrumb, porque a variação agora
+  comunica hierarquia real;
+- consumidores combinam navegação, título e ações em um único `PageHeader` ao migrar da composição
+  explícita;
+- `PageShell` deixa de garantir navegação durante estados integrais, pois o estado substitui a
+  introdução completa da página;
+- a remoção de `PageIntro` é uma mudança incompatível e requer migração coordenada dos consumidores.
+
+## Alternativas descartadas
+
+### Manter a barra persistente somente quando houver breadcrumb
+
+Evitaria a repetição em páginas simples, mas preservaria duas anatomias para o mesmo cabeçalho e
+manteria a navegação distante do título nas páginas profundas.
+
+### Manter `PageIntro` como região opcional abaixo de `PageHeader`
+
+Preservaria compatibilidade, mas continuaria exigindo que cada página decidisse qual das duas
+regiões contém o título e as ações.
+
+### Copiar a composição no consumidor
+
+Validaria uma tela isolada mais rapidamente, porém criaria um segundo contrato visual fora do
+catálogo e não provaria que páginas declarativas e `Presentation` mantêm a mesma anatomia.
+
+## Verificação
+
+- testes de `Page` cobrem breadcrumb acima da linha de título e ações;
+- shorthand e composição explícita produzem a mesma anatomia;
+- `PageShell` não renderiza barra e entrega navegação e ações ao `PageHeader` descendente;
+- `PageState` integral mantém um único heading e remove o header;
+- testes de `Presentation` cobrem a mesma composição dentro e fora de `PageShell`.

package/docs/adr/0030-framed-content-can-use-sectioned-anatomy.md

@@ -0,0 +1,89 @@
+# ADR 0030 — Content com moldura pode usar anatomia seccionada
+
+- **Status:** aceita.
+- **Data:** 2026-09-28.
+- **Substitui parcialmente:** ADR 0023, nas afirmações de que `Content` não expõe `layout` e é
+  sempre contínuo.
+- **Complementa:** ADR 0025.
+
+## Contexto
+
+`Content` já representa uma região nomeada como `section` ou `fieldset`, com header, body e moldura
+opcional. Quando o body é uma estrutura que possui o próprio recuo — como `DetailGroup` com
+divisores, uma lista ou uma tabela — o acabamento contínuo acrescenta padding ao redor dessa
+estrutura e impede que suas linhas alcancem a moldura.
+
+O protótipo do detalhe de Veículo no Evento de Pós-vendas confirmou uma composição útil: header com
+mídia, título, recuo de `0.75rem` e divisor; body sem recuo; conteúdo interno responsável por suas
+células. Produzir esse desenho exigiu classes no consumidor para remover o padding da raiz, recortar
+os cantos e reconstruir o header.
+
+As forças em tensão são:
+
+- reutilizar o vocabulário `continuous | sectioned` de Card, Dialog, Drawer e Pane;
+- preservar `Content` como região semântica interna, sem transformá-lo em Card;
+- manter `frameVariant="legend"` como acabamento da borda, sem misturá-lo à anatomia;
+- impedir combinações em que o body encosta nas bordas sem existir uma moldura para recortá-lo.
+
+## Decisão
+
+`Content` passa a aceitar `layout="continuous" | "sectioned"`, com `continuous` como default.
+
+O layout `sectioned` exige `framed` e forma um pacote indivisível:
+
+- A raiz desenha a moldura, recorta os cantos e não aplica padding geral.
+- `ContentHeader` aplica `p-3` e o divisor inferior.
+- `ContentBody` não aplica padding; seu filho direto responde pelo recuo interno.
+- Shorthand e composição explícita produzem a mesma anatomia.
+- `ContentMedia`, título, descrição, contador e ações preservam seus contratos atuais.
+
+`frameVariant` continua escolhendo somente o acabamento da moldura contínua. A combinação
+`layout="sectioned"` com `frameVariant="legend"` é inválida: o primeiro coloca o header dentro da
+moldura, enquanto o segundo o integra ao traço externo.
+
+O layout não altera a semântica. `as="section"` continua emitindo section com heading e
+`as="fieldset"` continua emitindo fieldset com legend nativa.
+
+### Emenda de 2026-09-28 — a moldura usa o raio das superfícies estruturais
+
+Quando `framed` está ativo, `Content` desenha uma moldura estrutural completa e usa `rounded-xl`,
+o mesmo degrau de `Card`. A semântica das duas famílias continua diferente, mas essa diferença não
+produz uma geometria externa menor. Em composições aninhadas, evitar a moldura dupla em vez de
+reduzir globalmente o raio de `Content`.
+
+## Consequências
+
+- DetailGroup, listas e tabelas podem ocupar o body de ponta a ponta sem classes estruturais no
+  consumidor.
+- Conteúdo livre que precisa de recuo continua usando o layout `continuous`, ou declara sua própria
+  região interna quando o body de ponta a ponta for deliberado.
+- `Content` passa a compartilhar o vocabulário de anatomia das demais superfícies, mas continua sem
+  footer e sem assumir o papel de uma superfície autônoma.
+- A API rejeita `sectioned` sem `framed` e rejeita a combinação com `legend`.
+
+## Alternativas consideradas
+
+### Adicionar `frameVariant="sectioned"`
+
+Foi descartado porque misturaria anatomia de regiões com o acabamento da linha externa. Card,
+Dialog, Drawer e Pane já usam `layout` para essa decisão.
+
+### Criar propriedades de borda e padding
+
+Propriedades como `headerDivider` e `bodyInset` permitiriam combinações arbitrárias e devolveriam a
+anatomia ao consumidor. O resultado validado é um pacote, não dois controles independentes.
+
+### Criar DetailCard
+
+Foi descartado porque duplicaria a semântica e os slots de `Content` para um único tipo de filho.
+A anatomia também é válida para listas e tabelas.
+
+## Verificação
+
+- Testes de UI cobrem shorthand, composição explícita, section e fieldset.
+- Testes confirmam header com divisor e `p-3`, body sem padding e raiz com recorte.
+- Testes confirmam `rounded-xl` nas molduras `default`, `legend` e `sectioned`.
+- Testes reprovam `sectioned` sem moldura e a combinação com `frameVariant="legend"`.
+- A documentação demonstra o caso com `DetailGroup` e diferencia anatomia de acabamento.
+- O consumidor de Pós-vendas usa somente props públicas do Opus, sem classes que reconstruam a
+  anatomia.

package/docs/adr/0031-detail-dividers-own-the-tabular-label-treatment.md

@@ -0,0 +1,61 @@
+# ADR 0031 — Divisórias de DetailGroup definem o tratamento tabular dos rótulos
+
+- **Status:** aceita.
+- **Data:** 2026-09-28.
+
+## Contexto
+
+`DetailGroup` separa três decisões: orientação dos pares, divisórias internas e moldura externa.
+Apesar disso, o fundo sutil dos rótulos horizontais era ativado por `variant="framed"`. Assim, a
+mesma grade com divisórias mudava de aparência ao ser hospedada por um `Content` seccionado, onde a
+moldura pertence ao `Content`, e um grupo independente, onde a moldura pertence ao próprio
+`DetailGroup`.
+
+O fundo do rótulo é um acabamento da grade tabular: ele ajuda a distinguir chave e valor quando os
+campos formam células conectadas. Não comunica que o grupo possui uma borda externa.
+
+## Decisão
+
+Na orientação horizontal, `dividers` ativa a composição tabular completa de cada campo:
+
+- rótulo e valor recebem padding próprio;
+- a coluna de rótulos usa fundo sutil;
+- a largura padrão dos rótulos passa a `8.5rem`;
+- as divisórias continuam delimitando as células.
+
+`variant="framed"` controla somente a moldura externa do grupo. Sem `dividers`, um grupo horizontal
+emoldurado mantém rótulo e valor sobre o mesmo fundo. Na orientação vertical, `dividers` continua
+adicionando somente as separações entre campos, sem pintar o rótulo.
+
+## Consequências
+
+- Grades horizontais com divisórias têm a mesma aparência dentro de `Content layout="sectioned"`
+  e como bloco principal independente.
+- Moldura externa, orientação e acabamento tabular permanecem decisões combináveis.
+- Não é necessária uma nova prop apenas para reproduzir um enfeite que já acompanha a grade.
+- Consumidores que usavam `framed + horizontal` sem divisórias deixam de receber fundo no rótulo.
+
+## Alternativas consideradas
+
+### Manter o fundo associado a `framed`
+
+Preservaria o comportamento atual, mas continuaria fazendo a moldura externa alterar o interior da
+grade e manteria inconsistentes os grupos hospedados por outra superfície.
+
+### Criar `labelVariant="muted"`
+
+Tornaria o acabamento explícito, mas adicionaria uma decisão a todos os consumidores sem haver um
+caso de produto que precise variar o fundo independentemente das divisórias.
+
+### Aplicar o fundo a toda orientação horizontal
+
+Uniformizaria os rótulos, mas daria aparência tabular também a grupos simples, sem células ou
+divisórias que sustentem essa leitura.
+
+## Verificação
+
+- Testes de UI confirmam fundo e padding separados em `horizontal + dividers`, com e sem moldura.
+- Testes de UI confirmam ausência de fundo em `horizontal + framed` sem divisórias.
+- Testes de UI confirmam que divisórias verticais não pintam o rótulo.
+- A documentação de `DetailGroup` descreve `framed`, `dividers` e `orientation` como eixos
+  independentes.

package/docs/adr/0032-tab-baseline-respects-the-container-inset.md

@@ -0,0 +1,59 @@
+# ADR 0032 — A linha-base das abas respeita o recuo do contêiner
+
+- **Status:** aceita.
+- **Data:** 2026-09-28.
+- **Relacionada:** ADR 0023, quanto ao alinhamento horizontal dentro de superfícies.
+
+## Contexto
+
+A variante horizontal `line` de `TabsList` estendia a linha-base para fora da própria lista usando
+o recuo de `DrawerBody` e `DialogBody`. Os rótulos permaneciam alinhados ao conteúdo, mas a linha
+alcançava as laterais da superfície e rompia o contorno visual formado pelo corpo.
+
+A tela de detalhes do Evento tornou a divergência evidente: cards, detalhes e conteúdo respeitam o
+mesmo recuo lateral, enquanto apenas a navegação por abas terminava nas bordas do drawer.
+
+## Decisão
+
+A linha-base horizontal ocupa somente a largura de `TabsList`. Ela respeita o recuo aplicado pelo
+contêiner e acompanha o alinhamento do corpo em qualquer superfície.
+
+`DrawerBody` e `DialogBody` deixam de publicar uma variável de gutter exclusiva para Tabs. O recuo
+continua pertencendo à anatomia da superfície, e Tabs apenas ocupa a largura que recebe no fluxo.
+
+### Emenda de 2026-09-28 — a aba combina uma área de botão e o indicador
+
+Na variante horizontal `line`, o gatilho mantém duas camadas: uma área interna com os estados
+interativos e a mesma altura de um Button do tamanho correspondente, e o indicador ancorado na
+linha-base da lista. A área interna permanece transparente e recebe fundo apenas no hover; a aba
+ativa se distingue pelo indicador primário. Um respiro de `0.375rem` separa as duas camadas no uso
+comum; dentro de `Tabs framed`, ele aumenta para `0.5rem` e acompanha o padding superior da moldura.
+
+Essa apresentação pertence ao Opus: consumidores escolhem `variant="line"` e não repetem classes
+de fundo, raio, padding ou interação para obter o estado selecionado.
+
+## Consequências
+
+- A linha e os rótulos das abas compartilham os limites horizontais do corpo.
+- A seleção permanece indicada pela linha inferior, sem manter um segundo fundo persistente.
+- Drawer e Dialog não mantêm uma integração implícita com Tabs.
+- Um consumidor que realmente precise de uma linha até as bordas deve compor essa apresentação de
+  forma explícita, pois ela não é mais o comportamento padrão da variante `line`.
+
+## Alternativas descartadas
+
+### Manter a linha até as bordas
+
+Preservaria o comportamento anterior, mas manteria uma exceção visual exclusiva das abas e uma
+dependência oculta entre as primitivas de corpo e Tabs.
+
+### Adicionar uma propriedade de full bleed
+
+Permitiria escolher os dois comportamentos, mas aumentaria a API para preservar uma apresentação
+sem consumidor conhecido. A composição explícita é suficiente caso essa necessidade apareça.
+
+## Verificação
+
+O teste da variante `line` verifica que a linha usa `inset-inline: 0`, inclusive quando Tabs está
+dentro de `DrawerBody`. O mesmo teste verifica a separação estrutural entre a superfície interna e
+o indicador da aba ativa. A documentação viva demonstra a variante com os limites do contêiner.

package/docs/adr/0033-drawer-uses-an-inset-structural-frame.md

@@ -0,0 +1,72 @@
+# ADR 0033 — Drawer usa uma moldura estrutural recuada
+
+- **Status:** aceita.
+- **Data:** 2026-09-28.
+- **Substitui:** a decisão da ADR 0005 que prendia a moldura externa do Drawer à borda da viewport.
+
+## Contexto
+
+O `Drawer` ocupava toda a altura ou largura da viewport e desenhava somente a borda voltada para o
+conteúdo. No consumidor, o shell principal já delimita as superfícies de trabalho com recuo de
+`0.5rem`, borda completa, fundo base e raio `xl`. Ao abrir um Drawer sobre esse shell, o painel
+voltava à geometria antiga de uma lâmina presa à janela: perdia os cantos, encostava em três bordas
+e não parecia pertencer ao mesmo sistema de molduras.
+
+O painel continua precisando comunicar de qual lado entra, preservar sua animação e aproveitar a
+altura disponível. Ao mesmo tempo, a moldura não pode ser reconstruída por cada consumidor, porque
+posição, recorte e animação pertencem à primitive.
+
+## Decisão
+
+`DrawerContent` passa a ser uma superfície recuada da viewport em todos os lados:
+
+- usa `0.25rem` de distância das bordas aplicáveis;
+- usa borda completa, fundo base, `rounded-xl` e `overflow-hidden`;
+- calcula a dimensão que antes ocupava `100%` descontando o recuo dos dois lados;
+- mantém `side` responsável pela direção, dimensão principal e animação de entrada e saída;
+- mantém largura e altura extensíveis por `className`, como antes.
+
+O princípio durável é que uma superfície modal lateral possui moldura própria e não se confunde
+com a viewport. O valor do recuo e o degrau de raio continuam materializações substituíveis da
+escala visual vigente.
+
+## Consequências
+
+- Drawer e shell passam a compartilhar a mesma leitura de moldura estrutural.
+- Header, body e footer full-bleed são recortados pelos cantos do painel.
+- A área útil do Drawer perde `0.5rem` no eixo que antes preenchia a viewport.
+- Consumidores deixam de precisar adicionar borda, raio ou margem para obter essa composição.
+- A mudança visual alcança `top`, `right`, `bottom` e `left`, evitando quatro geometrias distintas
+  para a mesma primitive.
+
+## Alternativas descartadas
+
+### Manter o Drawer preso à viewport
+
+Preservaria a geometria histórica, mas manteria a divergência mais visível justamente quando o
+painel aparece sobre um shell emoldurado.
+
+### Ajustar somente o Drawer do consumidor
+
+Validaria a tela atual com menor alcance, mas espalharia posição e recorte por `className` e
+deixaria outros Drawers fora do mesmo contrato visual.
+
+### Arredondar apenas os cantos expostos
+
+Manteria o painel preso à borda de entrada, mas produziria uma moldura incompleta e continuaria sem
+o respiro que distingue a superfície da viewport.
+
+### Alterar somente o lado direito
+
+Resolveria o caso mais frequente, mas faria `side` trocar também o contrato visual da superfície,
+sem uma razão de produto para essa diferença.
+
+## Verificação
+
+- Testes de `DrawerContent` verificam borda completa, raio, recorte e recuo para os quatro valores
+  de `side`.
+- Os testes existentes continuam cobrindo anatomia interna, fechamento e animação.
+- A documentação do Drawer descreve a moldura recuada e continua demonstrando a extensão de
+  largura por `className`.
+- Um teste do consumidor confirma que o Drawer de Evento usa o default do Opus, sem reconstruir a
+  moldura localmente.

package/docs/adr/0034-tabs-can-own-a-frame-without-owning-a-surface.md

@@ -0,0 +1,60 @@
+# ADR 0034 — Tabs pode ter moldura sem criar uma superfície
+
+- **Status:** aceita.
+- **Data:** 2026-09-28.
+- **Relacionadas:** ADR 0023, quanto à anatomia das superfícies; ADR 0032, quanto à linha-base das abas.
+
+## Contexto
+
+Uma composição em que a navegação por abas e seus painéis formam um único bloco precisa de borda,
+raio e recorte compartilhados. Até aqui, consumidores obtinham essa forma envolvendo `Tabs` em um
+`Card`.
+
+O `Card`, porém, não é apenas uma moldura: ele aplica `bg-card text-card-foreground` e cria uma
+superfície semântica própria. Em um `Drawer`, essa superfície pode se distinguir do
+`bg-background`, especialmente no tema escuro, embora a intenção seja somente delimitar as abas
+dentro da superfície já existente.
+
+## Decisão
+
+`Tabs` aceita a propriedade booleana `framed`, desativada por padrão.
+
+Quando ativa, `framed` aplica ao root a moldura estrutural canônica para esse bloco: borda, raio
+`rounded-xl` e recorte do conteúdo. Ela não aplica token de fundo nem de foreground. O conjunto
+herda a superfície do contêiner em que foi composto.
+
+Essa propriedade não altera a apresentação de `TabsList`, a seleção, o tamanho nem a orientação. O
+consumidor continua escolhendo esses comportamentos nas APIs existentes, inclusive
+`TabsList variant="line"`.
+
+## Consequências
+
+- Abas podem formar um bloco único sem serem promovidas a `Card`.
+- Em Drawer, Dialog ou Pane, a moldura acompanha o fundo da superfície externa nos temas claro e
+  escuro.
+- `Card` continua correto quando as abas realmente precisarem de uma superfície semântica própria.
+- `framed` permanece independente de `TabsList variant`, que descreve apenas a apresentação da
+  lista.
+
+## Alternativas descartadas
+
+### Manter Card como wrapper obrigatório
+
+Preservaria a API atual, mas continuaria acoplando uma necessidade estrutural ao token de superfície
+do Card.
+
+### Aplicar classes no consumidor
+
+Resolveria uma tela, mas repetiria borda, raio e clipping sem registrar o contrato visual da
+composição.
+
+### Fazer toda Tabs ser emoldurada
+
+Removeria a escolha, mas quebraria usos em que Tabs participa do fluxo de uma página ou toolbar sem
+formar um bloco autônomo.
+
+## Verificação
+
+Testes da primitiva verificam que o padrão permanece sem moldura e que `framed` aplica borda, raio e
+recorte sem qualquer classe de fundo. O teste da view de Evento verifica que a composição usa o
+root emoldurado diretamente, sem um `Card` intermediário.

package/docs/adr/0035-button-group-separates-frame-relationship-and-distribution.md

@@ -0,0 +1,63 @@
+# ADR 0035 — ButtonGroup separa moldura, relação e distribuição
+
+- **Status:** aceita.
+- **Data:** 2026-09-28.
+- **Relacionadas:** ADR 0015, quanto à escala dos controles; ADR 0017, quanto à distribuição igual explícita.
+
+## Contexto
+
+Um conjunto de ações do Evento foi composto com `Card`, `ButtonGroup mode="spaced"`, separadores
+manuais e `flex-1` repetido em cada botão. O resultado visual é um único grupo emoldurado, com
+ações de mesma largura e divisores entre elas, mas o consumidor precisa reconstruir essas três
+decisões em componentes e classes diferentes.
+
+`ButtonGroup` já distingue a relação entre controles com `mode` e a ocupação da largura com
+`distribution`. Tratar os divisores como uma propriedade booleana criaria combinações sem sentido,
+como controles conectados e divididos ao mesmo tempo. Usar `Card` apenas como borda também cria uma
+superfície semântica e um fundo que não pertencem ao grupo de ações.
+
+## Decisão
+
+`ButtonGroup` passa a aceitar:
+
+- `framed`, booleano independente que aplica borda, raio estrutural e padding sem definir fundo;
+- `mode="divided"`, além de `connected` e `spaced`, para preservar a forma individual dos
+  controles e inserir automaticamente um divisor com respiro entre filhos adjacentes;
+- `distribution="equal"`, já existente, para dividir o espaço disponível somente entre os
+  controles, sem incluir os divisores no cálculo.
+
+O modo `divided` deriva a orientação dos separadores da orientação do grupo. Em grupos horizontais,
+os divisores são verticais; em grupos verticais, são horizontais. `ButtonGroupSeparator` continua
+público para composições conectadas ou divisões seletivas.
+
+## Consequências
+
+- Consumidores expressam o conjunto em uma única raiz: `<ButtonGroup framed mode="divided"
+distribution="equal">`.
+- A moldura herda a superfície externa e não substitui `Card` quando uma superfície semântica for
+  realmente necessária.
+- Os botões não repetem classes de largura, e separadores uniformes não são montados manualmente.
+- `mode` continua sendo o único eixo que descreve a relação visual entre controles.
+
+## Alternativas descartadas
+
+### Manter Card e separadores explícitos
+
+Preservaria a API, mas manteria no consumidor uma composição repetitiva que representa uma única
+decisão visual.
+
+### Adicionar `dividers` como booleano
+
+Permitiria ativar os traços, mas faria dois mecanismos independentes disputarem a relação entre os
+controles e aceitaria combinações contraditórias.
+
+### Criar uma variante visual única
+
+Uma variante como `variant="framed-divided-equal"` reduziria a chamada, mas acoplaria três eixos
+que têm usos independentes e impediria novas combinações legítimas.
+
+## Verificação
+
+Testes da primitiva verificam moldura sem fundo, divisores automáticos nas duas orientações e
+distribuição igual restrita aos controles. O teste da view de Evento verifica que o grupo usa a API
+canônica sem `Card`, `ButtonGroupSeparator` ou classes de distribuição nos filhos.

package/docs/adr/0036-tabs-declares-trigger-distribution.md

@@ -0,0 +1,58 @@
+# ADR 0036 — Tabs declara a distribuição dos gatilhos
+
+- **Status:** aceita.
+- **Data:** 2026-09-28.
+- **Relacionadas:** ADR 0032, quanto à composição da variante `line`; ADR 0034, quanto à moldura de Tabs; ADR 0035, quanto ao eixo de distribuição em grupos de controles.
+
+## Contexto
+
+Uma lista de abas pode abraçar a largura dos rótulos ou repartir a largura disponível igualmente
+entre os gatilhos. A view de Evento usa quatro abas no cabeçalho de um bloco emoldurado; larguras
+derivadas do texto deixam esse cabeçalho visualmente desequilibrado, embora todas as seções tenham o
+mesmo nível.
+
+Hoje, a variante horizontal `line` força cada gatilho a usar a largura do próprio conteúdo. Um
+consumidor que precise de larguras iguais teria de sobrescrever o `flex` interno ou reconstruir a
+lista com grid, duplicando uma decisão que já existe em `ButtonGroup` como
+`distribution="content" | "equal"`.
+
+## Decisão
+
+`Tabs` aceita `distribution="content" | "equal"`, com `content` como padrão. A propriedade fica no
+root porque descreve o conjunto de abas e, como `size` e `orientation`, flui por contexto até a
+lista e os gatilhos.
+
+Na orientação horizontal, `equal` faz a lista ocupar a largura disponível e atribui a cada gatilho
+a mesma fração flexível, com largura mínima zero. A área interativa interna ocupa toda essa fração,
+incluindo o fundo de hover. `content` preserva o comportamento atual. A distribuição não altera a
+largura nem o layout dos painéis de conteúdo.
+
+## Consequências
+
+- Consumidores escolhem a mesma linguagem de distribuição usada por `ButtonGroup`.
+- `TabsList variant="line"` continua responsável pela linha e pelos estados visuais; não recebe
+  classes de layout no consumidor.
+- A view de Evento declara `distribution="equal"` no `Tabs` sem alterar cada `TabsTrigger`.
+- Usos existentes preservam a distribuição pelo conteúdo.
+
+## Alternativas descartadas
+
+### Declarar a propriedade em TabsList
+
+É a parte que organiza os gatilhos, mas faria a distribuição escapar do mesmo contrato de conjunto
+em que `Tabs` já declara tamanho e orientação.
+
+### Usar grid e número de colunas no consumidor
+
+Exigiria conhecer a quantidade de abas e repetiria classes de layout em cada tela.
+
+### Tornar larguras iguais o padrão
+
+Atenderia a view de Evento, mas esticaria navegações curtas e barras que deliberadamente abraçam os
+rótulos.
+
+## Verificação
+
+Testes da primitiva verificam o default `content`, a largura total da lista e a fração igual dos
+gatilhos quando `equal` está ativo. O teste da view de Evento verifica a propriedade no root e a
+distribuição dos quatro gatilhos sem classes locais equivalentes.

package/docs/adr/0037-design-data-lives-outside-the-contract.md

@@ -0,0 +1,117 @@
+# ADR 0037 — Dados do modo design ficam fora do contrato
+
+- **Status:** aceita; a primeira etapa saiu na 22.1.0, e a remoção fica para a 23.0.0.
+- **Data:** 2026-09-28.
+- **Relacionadas:** ADR 0002 (seeds estruturados).
+
+## Contexto
+
+O modo design serve para desenhar e revisar telas sem backend: `opusDesign()` monta o runtime
+dentro do dev server, e cada action responde pelo `mockHandler` declarado no contrato. O preview de
+sessão do Maestro depende desse modo e não tem outro propósito além de design.
+
+Em setembro de 2026, o único consumidor, a Grand Brasil, tinha 233 `mockHandler` para 256
+contratos, cerca de 3.200 linhas entre handlers, fixtures e estado simulado. A medição mostrou três
+problemas:
+
+- **O mock viaja com o contrato.** O contrato é a fatia compartilhada com a interface, então o
+  build de produção da aplicação leva os handlers simulados e suas fixtures. Um build de produção
+  da Grand Brasil continha textos das fixtures e os próprios handlers.
+- **Metade dos mocks não acrescenta nada ao schema.** Cerca de 110 handlers devolvem um literal
+  fixo (`{ id: 'mock-x' }`) ou uma lista vazia, o que o `fake` já gera a partir do `output`.
+- **A outra metade replica o domínio.** Cerca de 95 handlers simulam um CRUD em memória e
+  reimplementam regras do handler real, como o significado de cada filtro operacional de uma
+  listagem. Em setembro, 19 commits de funcionalidade tiveram de alterar mocks junto com o código
+  real, e nada garante que as duas versões da regra continuem iguais.
+
+Forças em tensão:
+
+- a aplicação real deve carregar o mínimo possível de algo que só existe para design;
+- o preview precisa responder a qualquer action, inclusive às criadas durante a sessão;
+- às vezes o design precisa de coerência entre respostas, como um item em cada situação ou algo
+  criado que aparece na lista em seguida;
+- no preview, variar entre sessões é aceitável, porque dado de design não é evidência. Os seeds da
+  ADR 0002 são evidência e continuam determinísticos;
+- o Opus é protocolo e SDK: onde os cenários ficam e se são versionados é escolha do projeto.
+
+## Decisão
+
+1. **O contrato deixa de declarar dados de design.** `mockHandler` sai de `ActionBase`, do
+   contrato, do `ActionDef` e do `runAction`. O runtime de produção não lê mais `OPUS_MODE` nem
+   tem ramo de design. Toda a lógica de design fica em `@softize/opus/vite`.
+2. **Toda action responde por padrão no modo design.** O plugin registra cada contrato com um
+   executor de design que, na ausência de cenário, devolve dado gerado pelo `fake` a partir do
+   `output`:
+   - `list` devolve três páginas geradas por `fakeMany`, com `items`, `cursor` e `total`, do
+     tamanho pedido em `limit` (20 quando a entrada não pede, até 100), e respeita a paginação
+     declarada. Busca e filtros não filtram o dado gerado, porque sobre dado
+     sorteado o resultado não mostraria nada útil; quando o filtro importar para o design, o
+     caminho é um cenário;
+   - a semente é derivada do nome da action e da entrada canônica, então a mesma requisição recebe
+     a mesma resposta;
+   - quando a entrada e a saída têm `id`, a saída ecoa o `id` da entrada, desde que o schema da
+     saída aceite esse valor, para que abrir um item listado mostre o mesmo identificador;
+   - uma action ligada a um handler real (`bindAction`) mantém esse handler, como hoje.
+3. **Cenários são registrados fora do contrato, pelo nome da action.** O plugin ganha a opção
+   `scenarios`, com um ou mais globs. Os módulos casados exportam cenários criados por
+   `defineDesignScenario(contrato, resposta)`, e a resposta pode ser um valor ou uma função tipada
+   pela entrada e pela saída do contrato. O cenário vence a resposta padrão. Um cenário para uma
+   action inexistente é erro visível no preview, não um silêncio.
+4. **O Opus não decide onde os cenários ficam.** A opção não tem default dentro do código da
+   aplicação. O consumidor escolhe, por exemplo, uma pasta ignorada pelo git que o agente da sessão
+   preenche sob demanda. Cenários começam descartáveis: só vale discutir versionar um cenário no
+   repositório do consumidor quando o mesmo for recriado em sessões diferentes.
+5. **Stubs de rotas externas continuam como estão.** A opção `stubs` segue atendendo superfícies
+   fora do protocolo de actions, como autenticação e motores externos.
+
+## Consequências
+
+- A aplicação deixa de carregar mocks. O contrato volta a descrever só a capacidade, e o build de
+  produção não inclui dados de design.
+- Uma action nova aparece no preview sem nenhuma linha de mock.
+- O dado padrão tem o formato certo, mas não a regra de negócio: valores de enum são sorteados, e
+  campos de uma listagem e de um detalhe só coincidem no `id`. Quando isso atrapalhar o design, o
+  caminho é um cenário.
+- Sem cenário, não há estado entre chamadas: criar um item não o faz aparecer na lista.
+- É uma versão major. Quem declara `mockHandler` precisa remover a declaração ou transformá-la em
+  cenário, e testes que usam `OPUS_MODE=design` com `runAction` precisam de outra forma de
+  exercitar o contrato.
+- O template de `opus create`, a documentação "Prototipar com dados simulados", as skills
+  `create-opus-action` e `test-opus-action` e o gate de ordem de campos (`check.mjs`) mudam junto.
+- No Maestro, que fica fora deste pacote, o preview continua igual. O agente da sessão passa a
+  escrever cenários quando precisar, orientado por uma skill própria.
+
+## Alternativas descartadas
+
+- **Manter o estado atual.** Preserva cenários prontos entre sessões, mas mantém o mock no bundle,
+  a regra de negócio duplicada e o custo de cada funcionalidade nova.
+- **Remover `mockHandler` apenas no build de produção.** Resolve o bundle e nada mais. O contrato
+  continua misturando capacidade e simulação, e a duplicação de regra permanece.
+- **Preview com backend real e dados dos seeds.** Mostra o comportamento verdadeiro e elimina os
+  mocks, mas exige banco, API e isolamento por sessão num preview que só serve a design, além de
+  rever as decisões do Maestro de manter o preview isolado e sem Postgres.
+- **CRUD em memória genérico a partir de metadado novo no contrato.** Exigiria declarar entidade e
+  operação em cada action e, mesmo assim, não cobriria regras de negócio, que continuariam
+  escritas à mão.
+- **Somente a resposta padrão, sem cenários.** É o mínimo absoluto, mas deixaria o design sem saída
+  quando a coerência importa. O custo do mecanismo de cenários é pequeno perto disso.
+
+## Transição
+
+A saída acontece em duas versões. A 22.1.0 adiciona a resposta padrão e os cenários, com
+`mockHandler` ainda aceito e precedendo a resposta gerada, e o `check` passa a contar o campo como
+obsoleto. O consumidor remove seus mocks domínio a domínio. A 23.0.0 remove o campo e o ramo de
+design do runtime.
+
+## Verificação
+
+- testes do plugin: resposta padrão por `kind` (`view`, `list`, `form`, `simple`), páginas do
+  tamanho pedido em `limit` com a paginação declarada, mesma resposta para a mesma entrada, eco do
+  `id`, precedência do cenário e erro para cenário sem action ou duplicado;
+- teste de tipos: `defineDesignScenario` infere entrada e saída do contrato e rejeita resposta
+  incompatível;
+- busca estática: nenhum `OPUS_MODE` nem `mockHandler` em `src/core` e `src/testing` depois da
+  major;
+- no consumidor: nenhum `mockHandler` nos contratos, e o build de produção sem textos das fixtures
+  antigas;
+- typecheck, suíte do pacote, `opus check` e os gates de materialização verdes.