@softize/opus 23.0.0 → 24.0.1

package/docs/adr/0047-pane-is-only-a-split-layout-unit.md

@@ -0,0 +1,71 @@
+# ADR 0047 — Pane é somente uma unidade de layout do Split
+
+- **Status:** aceita.
+- **Data:** 2026-10-01.
+- **Substitui:** a anatomia visual de Pane definida pela ADR 0023.
+- **Complementa:** ADR 0045, quanto ao uso de `Surface` para regiões visuais.
+
+## Contexto
+
+`Pane` nasceu como filho dimensionável de `Split`, mas passou a acumular uma segunda função:
+oferecia header, body, footer, título, mídia, ações, divisores, inset e ritmo visual. Essa anatomia
+duplicava `Surface` e fazia a aparência de uma coluna depender do componente que deveria apenas
+distribuir espaço.
+
+A duplicação ficou visível quando uma mesma região precisou funcionar em página, drawer e split.
+Alterar o ritmo de todos os bodies incluiu `PaneBody`, embora a decisão vigente já fosse deixar a
+superfície visual a cargo de `Surface` ou de um pattern especializado, como `Sidebar`.
+
+## Decisão
+
+`Pane` representa exclusivamente uma unidade espacial aceita por `Split`. Sua API pública mantém:
+
+- `id`, para identidade e persistência do layout;
+- `initialSize`, `minSize` e `maxSize`, para dimensionamento;
+- `grow`, para ocupar o espaço remanescente;
+- `className` e `children`, para o contêiner de layout.
+
+`Pane` não aplica inset, fundo, borda, raio, divisor, orientação interna, rolagem nem anatomia de
+conteúdo. As propriedades `inset` e `layout` são removidas.
+
+Os slots `PaneHeader`, `PaneBody`, `PaneContent`, `PaneFooter`, `PaneMedia`, `PaneTitle`,
+`PaneDescription` e `PaneActions` também são removidos, sem aliases de compatibilidade. O único
+consumidor é migrado atomicamente:
+
+- regiões visuais usam `Surface` e seus slots;
+- barras laterais podem usar a anatomia própria de `Sidebar` ou conteúdo nativo;
+- rolagem e organização interna pertencem ao filho inserido no pane.
+
+## Consequências
+
+- `Pane` e `Split` passam a ter uma única responsabilidade observável: distribuir espaço.
+- `Surface` volta a ser a fonte única da anatomia visual compartilhada.
+- Uma região que precise de rolagem deve declará-la no seu conteúdo ou na superfície interna.
+- Consumidores antigos deixam de compilar até substituir os slots e remover `inset`/`layout`.
+- O checker orienta a migração de símbolos e propriedades removidos.
+
+## Alternativas descartadas
+
+### Manter apenas PaneBody
+
+Ainda deixaria `Pane` responsável por rolagem e ritmo, criando uma anatomia parcial concorrente com
+`SurfaceBody` e com o conteúdo especializado.
+
+### Manter os slots como aliases de Surface
+
+Preservaria dois vocabulários para a mesma estrutura e permitiria que novas telas voltassem a
+escolher a família errada. Como há um único consumidor migrado junto, a compatibilidade não traz
+benefício proporcional.
+
+### Incorporar a superfície visual ao Split
+
+Misturaria distribuição espacial com apresentação e impediria panes deliberadamente invisíveis.
+
+## Verificação
+
+- a API pública exporta apenas `Pane`, `PaneProps` e `PaneSize` dessa família;
+- `Pane` não contém tokens de padding, borda, fundo, raio, overflow ou anatomia flex interna;
+- `Split` continua aceitando somente `Pane` como filho e preserva dimensionamento e resize;
+- `opus check` reprova símbolos antigos e as propriedades removidas;
+- busca nos consumidores não encontra nenhum slot `Pane*`, `inset` ou `layout` aplicado a `Pane`;
+- testes renderizados cobrem split fixo, redimensionável e superfícies migradas.

package/docs/adr/0048-modal-intro-separates-content-from-chrome.md

@@ -0,0 +1,34 @@
+# ADR 0048 — A intro do modal separa conteúdo e chrome
+
+- **Status:** aceita.
+- **Data:** 2026-10-01.
+- **Complementa:** ADR 0018, quanto à separação entre nome e contexto; ADR 0023, quanto à anatomia
+  de Dialog e Drawer; ADR 0046, quanto ao ritmo governado pelo body.
+
+## Contexto
+
+Dialog e Drawer podem ter uma barra persistente com navegação, ação global e fechamento. Nessa
+composição, colocar o título do recurso na barra mistura chrome e conteúdo; colocá-lo solto no body
+preserva o desenho, mas viola a anatomia pública e não nomeia a relação entre título e ações locais.
+
+## Decisão
+
+`DialogIntro` e `DrawerIntro` são o primeiro bloco opcional de seus respectivos bodies. Cada intro
+exige o título da família e aceita `DialogIntroActions` ou `DrawerIntroActions`. O título usa a
+escala principal da composição; o body continua responsável por inset, ritmo e rolagem.
+
+As ações do header continuam sendo chrome da superfície. As ações da intro se relacionam ao título
+e ao conteúdo. No formato compacto, título e ações permanecem no header e a intro é omitida.
+
+## Consequências
+
+- o mesmo conteúdo funciona em layout contínuo ou seccionado sem título órfão;
+- o fechamento e a navegação podem permanecer estáveis enquanto a intro rola com o conteúdo;
+- o checker exige intro dentro do body, título dentro de header ou intro e ações no slot correto;
+- exemplos e consumidores deixam de reconstruir a linha com `div` e classes locais.
+
+## Verificação
+
+- testes renderizados cobrem os dois modais e a escala do título;
+- `opus check` aceita as composições canônicas e reprova intro órfã ou sem título;
+- a documentação mostra as formas com intro e compacta.

package/docs/adr/0049-inline-navigation-groups-with-the-heading.md

@@ -0,0 +1,95 @@
+# ADR 0049 — Navegação inline forma um grupo com o título
+
+- **Status:** aceita.
+- **Data:** 2026-10-01.
+- **Complementa:** ADR 0023, quanto à linha do cabeçalho de Dialog e Drawer; ADR 0048, quanto ao
+  formato compacto, com título no cabeçalho.
+
+## Contexto
+
+`StructuralHeader` monta a linha do cabeçalho de Dialog e Drawer com `leadingPlacement="inline"`:
+a navegação abre a linha, a mídia e o título vêm em seguida, as ações ficam no extremo oposto e o
+botão de fechar entra por último. Até a 24.0.0, todos esses nós eram irmãos da mesma linha flex e
+recebiam o intervalo da família, que em Dialog e Drawer é `gap-4` (`1rem`).
+
+Com um único intervalo, o voltar ou o recolher ficava tão longe do título quanto o título ficava das
+ações. A proximidade não distinguia duas relações diferentes:
+
+- a navegação diz de onde a pessoa veio ou como sair da etapa, e só faz sentido lida junto com o
+  nome da tela;
+- as ações operam sobre a superfície inteira e formam um conjunto próprio, com ritmo interno denso
+  (`gap-2`, de `surfaceActionsClasses`).
+
+A ADR 0048 fixou a escolha entre a intro e o formato compacto, em que o título permanece no
+cabeçalho. A página **Composições** passou a mostrar as duas formas lado a lado, e a distância
+uniforme ficou evidente no Drawer compacto, em que o recolher do painel precede o título.
+
+## Decisão
+
+Quando um `StructuralHeader` com `leadingPlacement="inline"` recebe navegação e heading, os dois
+formam um grupo contextual:
+
+1. Um wrapper `data-slot="<slot>-header-context"` (`flex min-w-0 flex-1 items-center gap-2`)
+   envolve a navegação e o heading. O intervalo entre eles passa a ser `gap-2` (`0.5rem`).
+2. As ações e o botão de fechar ficam fora do grupo, como irmãos dele na linha
+   `<slot>-header-row`, e continuam separados pelo intervalo da família (`gap-4` em Dialog e
+   Drawer). O ritmo interno das ações não muda.
+3. O grupo ocupa a folga (`flex-1`) e aceita compressão (`min-w-0`): as ações seguem no extremo
+   oposto e o título continua truncando quando não cabe.
+4. Quando há mídia na linha, mídia e heading ficam num wrapper `<slot>-header-identity` que
+   reaplica as classes da linha da família. A aproximação vale só entre a navegação e o que vem
+   depois dela; a distância da mídia até o título é a mesma que existiria sem navegação.
+5. A navegação mantém `data-slot="<slot>-navigation"` dentro do grupo, para que seletores de teste
+   e de CSS continuem encontrando a região nas duas apresentações.
+
+Fora dessa combinação nada muda: navegação sem título, título sem navegação,
+`leadingPlacement="above"`, usado pela `Page`, e o `Dialog mode="alert"`, cujo cabeçalho não usa
+`StructuralHeader`. `SurfaceHeader` não tem slot de navegação, e as intros (`DialogIntro` e
+`DrawerIntro`) também não aceitam navegação.
+
+A regra mora uma vez em `structural-header.tsx`. Dialog e Drawer a herdam porque ambos declaram
+`leadingPlacement="inline"` e passam `surfaceHeaderRowClasses(family)` como `rowClassName`; nenhuma
+família reescreve o intervalo.
+
+## Consequências
+
+- Em Dialog e Drawer com navegação e título, o voltar ou o recolher passa de `1rem` para `0.5rem`
+  do título, ou da mídia que o antecede. Ações e fechamento mantêm a mesma posição e o mesmo ritmo.
+- A API pública não muda, por isso a correção sai como patch (24.0.1).
+- O DOM ganha um nível nessa combinação, e dois quando há mídia: a navegação deixa de ser filha
+  direta de `<slot>-header-row` e passa a ser filha de `<slot>-header-context`. Seletores que
+  dependiam do filho direto, como `[data-slot=drawer-header-row] > [data-slot=drawer-navigation]`,
+  precisam usar o descendente; seletores pelo `data-slot` da navegação continuam válidos.
+- Uma família nova que adote a linha inline com navegação herda o agrupamento sem configuração. Se
+  ela precisar de outra relação entre navegação e título, a mudança é desta ADR, não de um
+  `className` local.
+
+## Alternativas consideradas
+
+- **Manter o intervalo único.** Não exige mudança, mas iguala duas relações diferentes.
+  Descartada.
+- **Reduzir o intervalo da linha inteira para `gap-2`.** Aproximaria navegação e título, mas também
+  aproximaria as ações do título, que é a separação que a família precisa preservar. Descartada.
+- **Ajustar a margem no slot de navegação de cada família**, por exemplo com `-mr-2` em
+  `DrawerNavigation`. Resolveria o caso visual, mas espalharia uma decisão da anatomia
+  compartilhada por cada família e dependeria de compensar um intervalo que continua existindo.
+  Descartada.
+- **Levar a navegação para dentro do wrapper do heading.** Misturaria uma região de controle com o
+  bloco que nomeia a superfície e mudaria o elemento que absorve a compressão do título. Descartada.
+- **Aplicar `gap-2` também entre mídia e título quando houver navegação.** Seria mais simples, mas
+  faria a distância da mídia até o título depender da presença da navegação. Descartada.
+- **Expor o intervalo como propriedade pública.** Abriria uma variação por consumidor para uma
+  relação que deve ser igual em todas as superfícies. Descartada.
+
+## Verificação
+
+- `tests/ui/drawer.test.tsx` fixa a regra no Drawer: com navegação, título e ações, a linha mantém
+  `gap-4`, o grupo `drawer-header-context` usa `gap-2` e contém o título, `drawer-actions` mantém
+  `gap-2` e não há wrapper de identidade sem mídia. Com mídia, `drawer-header-identity` fica dentro
+  do grupo, mantém `gap-4` e reúne mídia e título, sem a navegação.
+- `tests/ui/dialog.test.tsx` cobre a mesma regra no Dialog com navegação, mídia, título e ações,
+  inclusive as ações como filhas diretas da linha, fora do grupo.
+- Os testes existentes cobrem as combinações que não mudam: navegação e ações sem título continuam
+  na mesma linha, e ações isoladas continuam no extremo final.
+- Na página **UI > Design > Composições**, o Drawer compacto exibe o recolher e o título no
+  cabeçalho e serve de verificação visual da regra.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "23.0.0",
+  "version": "24.0.1",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -205,6 +205,10 @@
       "types": "./src/ui/meta.ts",
       "default": "./src/ui/meta.ts"
     },
+    "./ui/appearance": {
+      "types": "./src/ui/appearance.ts",
+      "default": "./src/ui/appearance.ts"
+    },
     "./ui/docs": {
       "types": "./src/ui/docs/index.ts",
       "default": "./src/ui/docs/index.ts"

package/registry/skills/build-opus-ui/SKILL.md

@@ -46,26 +46,26 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
 8. Compor superfícies pela gramática estrutural do catálogo: `PageHeader` é a única introdução
    estrutural e reúne navegação contextual opcional, título e ações; `PageBody` contém o conteúdo.
    Na composição explícita, declare exatamente um heading principal com `PageTitle` no header,
-   `Content level={1}` ou um `PageState` ativo no body. `PageShell` pode fornecer navegação e ações
-   conhecidas pela aplicação, mas não cria uma barra visual. `Content` contém `ContentHeader` e `ContentBody`; Card,
-   Drawer e Pane usam seus
-   respectivos `*Body`. Para o caso direto, usar a sintaxe abreviada de `Page` (`title`,
-   `actions`) ou de `Content` (`title`, `description`, `actions` e `count`); não misturá-la com o
+   `Surface level={1}` ou um `PageState` ativo no body. `PageShell` pode fornecer navegação e ações
+   conhecidas pela aplicação, mas não cria uma barra visual. `Surface` contém `SurfaceHeader` e
+   `SurfaceBody`; Drawer e Pane usam seus respectivos `*Body`. Para o caso direto, usar a sintaxe
+   abreviada de `Page` (`title`, `actions`) ou de `Surface` (`title`, `description`, `actions` e
+   `count`); não misturá-la com o
    header explícito. O título da página não carrega contador. Ajustar o
    nível do heading pela hierarquia semântica, não pelo destaque visual. O `Page` mantém seu teto
    centralizado padrão de `80rem`.
-   Em `Content framed`, usar `layout="sectioned"` quando o filho direto já controlar o recuo do
-   body, como `DetailGroup` com divisores, lista ou tabela; não reconstruir divisor, padding ou
-   recorte por classes no consumidor. `frameVariant="legend"` continua sendo um acabamento da
-   borda contínua e não combina com o layout seccionado.
+   Em `Surface framed`, usar `layout="sectioned"` e `SurfaceBody flush` quando o filho direto já
+   controlar o recuo do body, como `DetailGroup` com divisores, lista ou tabela; não reconstruir
+   divisor, padding ou recorte por classes no consumidor. Em grupos de formulário,
+   `as="fieldset"` transforma o header em `legend` nativa sem variante visual paralela.
 9. Manter margem e posicionamento no consumidor; componente reutilizável controla apenas
    seu interior.
 10. Não definir a fonte raiz em uma biblioteca ou componente. O navegador e a aplicação são
     responsáveis por `font-size` em `html`; medidas escaláveis da UI usam `rem` ou a escala
     relativa do Tailwind. Reservar `px` a hairlines e compensações presas à geometria da borda,
     com justificativa e cobertura explícitas.
-11. Em uma página centrada em coleção, compor `Content + ActionList`: título e criação ficam em
-    extremos opostos do `ContentHeader`; a criação usa botão textual `default`, sem ícone, com
+11. Em uma página centrada em coleção, compor `Surface + ActionList`: título e criação ficam em
+    extremos opostos do `SurfaceHeader`; a criação usa botão textual `default`, sem ícone, com
     `Criar recurso`. Busca, filtros, atualização, estados e paginação permanecem no `ActionList`.
     Reservar `toolbarActions` a operações ligadas ao recorte atual.
 12. Evoluir um pattern compartilhado apenas quando a recorrência e o contrato estiverem claros.

package/registry/skills/build-opus-ui/references/evaluations.md

@@ -6,8 +6,8 @@
 - Execução estrutural: montar uma página de relatório isolada com `Page > PageHeader + PageBody`,
   outra em `PageShell` com navegação contextual acima de `Page > PageHeader + PageBody`, garantindo
   exatamente um `PageTitle` no header, e uma coleção nomeada com
-  `Content > ContentHeader + ContentBody > ActionList`. Provar que criação fica em
-  `ContentActions`, no extremo oposto ao título, como botão textual `default` sem ícone e com
+  `Surface > SurfaceHeader + SurfaceBody > ActionList`. Provar que criação fica em
+  `SurfaceActions`, no extremo oposto ao título, como botão textual `default` sem ícone e com
   `Criar recurso`, enquanto uma operação dependente do recorte usa `toolbarActions`; incluir
   `ActionFilterBar` separado do renderer, `ItemGroup` para
   uma coleção secundária e um `ActionFormDialog`; provar teto padrão de `80rem`, hierarquia por
@@ -18,13 +18,14 @@
 - Execução roteável: declarar Page, criação e edição com `Presentation.route`; provar deep link,
   hidratação do registro, fechamento para a lista e projeção integral no manifest.
 - Execução abreviada: montar outra página com `<Page title actions>` e uma seção com
-  `<Content title description actions>`, provando que ambas produzem a mesma anatomia e que o lint
+  `<Surface title description actions>`, provando que ambas produzem a mesma anatomia e que o lint
   rejeita a mistura entre props abreviadas e headers explícitos.
-- Execução de forma: compor uma tabela dentro de Card sem moldura duplicada, manter a moldura
+- Execução de forma: compor uma tabela dentro de `Surface` sem moldura duplicada, manter a moldura
   estrutural standalone em `rounded-lg` e os controles internos em `rounded-md`.
-- Execução de Content seccionado: compor `Content framed layout="sectioned"` com mídia e
-  `DetailGroup` com divisores; provar header com divisor, body sem recuo e ausência de classes no
-  consumidor que reconstruam essa anatomia. Reprovar a combinação com `frameVariant="legend"`.
+- Execução de Surface seccionada: compor `Surface framed layout="sectioned"` com mídia e
+  `DetailGroup` com divisores; provar header com divisor, `SurfaceBody flush` sem recuo e ausência
+  de classes no consumidor que reconstruam essa anatomia. Provar `as="fieldset"` com `legend`
+  nativa sem `frameVariant`.
 - Reprova: criar uma casca `bg-card` que herda o texto global ou introduzir `rounded-widget`
   quando a escala `rounded-*` atende ao papel.
 - Reprova: trocar automaticamente o radius de um controle quando apenas seu tamanho muda ou
@@ -32,8 +33,8 @@
 - Reprova: reconstruir manualmente o container de página, usar `Empty` tracejado como vazio de
   tabela, alinhar toda coluna numérica à direita por inferência ou destacar “Cancelar” como ação
   primária em modal.
-- Reprova: deixar `ContentHeader` fora de `Content`, omitir `PageBody`/`ContentBody` na composição
-  explícita, usar `CardContent`/`PaneContent` em código novo ou tratar `DialogContent` como Body.
+- Reprova: deixar `SurfaceHeader` fora de `Surface`, omitir `PageBody`/`SurfaceBody` na composição
+  explícita, usar `Card*` ou `Content*` em código novo ou tratar `DialogContent` como Body.
 - Execução de dicionários: montar a lista de clientes com “Pessoa física/Empresa” e
   “Prospect/Cliente”; provar que o tipo ocupa a coluna “Tipo” como classificação (badge `outline`
   com os ícones declarados `user` e `building`), que o estágio ocupa a coluna “Estágio” como badge

package/registry/skills/build-opus-ui/references/ui-patterns.md

@@ -9,7 +9,7 @@
   lista; não reconstruir essa decisão com condicionais no componente da página.
 - `Page` fornece o `<main>` e o container centralizado com teto padrão de `80rem`. Sua forma
   explícita exige `PageBody`, exatamente um heading principal e aceita `PageHeader` e `PageFooter`.
-  Declare esse heading com `PageTitle` no header, `Content level={1}` ou um `PageState` ativo no
+  Declare esse heading com `PageTitle` no header, `Surface level={1}` ou um `PageState` ativo no
   body. `PageHeader` é a única introdução estrutural e reúne navegação, título e ações. `title` e `actions` no
   próprio `Page` são a abreviação para o caso direto.
   Não misturar as duas formas. Alterar `className` apenas quando a superfície tiver uma necessidade
@@ -26,8 +26,8 @@
   ações somente com ícone de chrome usam `icon`. O tamanho `sm` fica para ações operacionais em
   toolbar, seção ou coleção densa, e `xs`/`icon-xs` para ações internas de linha ou célula. Contexto
   e variante resolvem a hierarquia visual sem alterar essa medida. Em uma coleção, a ação de
-  criar usa botão textual `default`, sem ícone, no extremo oposto do `ContentHeader`. Não monte
-  `PaneHeader`, portal ou seletor global para reconstruir essa composição.
+  criar usa botão textual `default`, sem ícone, no extremo oposto do `SurfaceHeader`. Não monte
+  cabeçalho paralelo, portal ou seletor global para reconstruir essa composição.
 - `PageState` substitui todo o conteúdo principal quando a página carrega, falha ou está vazia. Na
   forma curta ele pode ser escrito como filho direto de `Page`, que cria o `PageBody`; na forma
   explícita, fica sozinho dentro de `PageBody`. Nos três estados ativos, o cabeçalho da Page
@@ -37,22 +37,23 @@
   `role="alert"`, usa a mesma composição central e sem moldura dos demais estados e apresenta a
   recuperação como botão `outline` textual. Estados de seção ou coleção continuam em `DataState`,
   `ActionView`, `ActionList` ou `Alert`; não elevar uma falha parcial a estado da página.
-- `Content` delimita uma seção e segue a mesma anatomia: `Content > ContentHeader (ContentTitle,
-ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader` nunca fica
-  solto. `title`, `description`, `count` e `actions` no `Content` são a abreviação para o caso
-  direto e não podem ser misturados ao header explícito. Na variante `page`, ações da coleção ficam
-  no extremo oposto ao título; a criação usa botão textual `default`, sem ícone, com `Criar recurso`.
+- `Surface` delimita uma região e segue a anatomia `Surface > SurfaceHeader (SurfaceMedia,
+SurfaceTitle, SurfaceDescription, SurfaceMeta, SurfaceActions) + SurfaceBody + SurfaceFooter`.
+  Os slots nunca ficam soltos. `title`, `description`, `count`, `media` e `actions` são a abreviação
+  para o caso direto e não podem ser misturados ao header explícito. Em `level={1}`, ações da
+  coleção ficam no extremo oposto ao título; a criação usa botão textual `default`, sem ícone, com
+  `Criar recurso`.
   O diálogo de criação usa `Criar recurso` e o de edição, `Editar recurso`. `level` preserva a
-  hierarquia semântica do heading. `Content framed` aceita `layout="sectioned"` quando o filho
-  direto já possui recuo interno, como `DetailGroup` com divisores, lista ou tabela: o header recebe
-  divisor e o body fica sem padding. `frameVariant="legend"` trata a borda contínua e não combina
-  com esse layout.
-- Uma página centrada em coleção compõe `Content + ActionList`. O `ContentHeader` recebe título e
+  hierarquia semântica do heading. `Surface framed` aceita `layout="sectioned"`; declare
+  `SurfaceBody flush` quando o filho direto já possui recuo interno, como `DetailGroup` com
+  divisores, lista ou tabela. `as="fieldset"` cria a `legend` nativa sem variante de moldura.
+- Uma página centrada em coleção compõe `Surface + ActionList`. O `SurfaceHeader` recebe título e
   criação; o `ActionList` mantém busca, filtros, atualização, resultados, estados e paginação.
   `toolbarActions` fica reservado a operações que dependem do recorte atual.
-- Card, Drawer e Pane nomeiam a região principal como `CardBody`, `DrawerBody` e `PaneBody`.
-  `*Content` permanece reservado a raízes técnicas ou painéis cujo papel não é o corpo de uma
-  estrutura, como `DialogContent`, `PopoverContent` e `TabsPanel`.
+- `Surface` e Drawer nomeiam a região principal como `SurfaceBody` e `DrawerBody`. `Pane` é apenas
+  uma unidade dimensionável de `Split` e não possui anatomia interna. `*Content` permanece
+  reservado a raízes técnicas ou painéis cujo papel não é o corpo de uma estrutura, como
+  `DialogContent`, `PopoverContent` e `TabsPanel`.
 - Componentes compartilhados não impõem margem externa; páginas e shells compõem layout.
 - A UI assume layout desktop fixo e largura mínima suportada de `64rem`. Não introduzir
   breakpoints de viewport ou container queries isoladas; uma futura responsividade precisa começar

package/registry/templates/app/src/App.tsx

@@ -1,8 +1,13 @@
-import type { z } from 'zod'
-import { Badge, Card, DataState, useListAction } from '@softize/opus/ui/react'
-import { Task, taskList } from './domains/tasks/actions/list.ts'
+import type { z } from "zod";
+import {
+  Badge,
+  DataState,
+  Surface,
+  useListAction,
+} from "@softize/opus/ui/react";
+import { Task, taskList } from "./domains/tasks/actions/list.ts";
 
-type TaskItem = z.infer<typeof Task>
+type TaskItem = z.infer<typeof Task>;
 
 /** Página inicial do esqueleto: prova a fundação (tema + componentes do Opus) e o
  *  domínio-exemplo. Troque tudo — este arquivo é seu. */
@@ -10,14 +15,16 @@ export function App(): React.ReactElement {
   // O front consome o CONTRATO via /api — o plugin opusDesign (vite.config.ts)
   // serve o backend no próprio dev server: dev normal executa o handler real;
   // `pnpm dev:design` responde com dado gerado a partir do contrato, isolado de qualquer backend.
-  const { items, isLoading, error, refetch } = useListAction<TaskItem>(taskList)
+  const { items, isLoading, error, refetch } =
+    useListAction<TaskItem>(taskList);
 
   return (
     <main className="flex min-h-full items-center justify-center bg-background p-6">
-      <Card className="w-full max-w-md p-6">
-        <h1 className="mb-1 text-lg font-semibold">{'{{APP_NAME}}'}</h1>
+      <Surface framed elevation="raised" className="w-full max-w-md p-6">
+        <h1 className="mb-1 text-lg font-semibold">{"{{APP_NAME}}"}</h1>
         <p className="mb-4 text-sm text-muted-foreground">
-          Esqueleto criado pelo opus create. A spec vive nas declarações do domínio.
+          Esqueleto criado pelo opus create. A spec vive nas declarações do
+          domínio.
         </p>
         {/* Carregando, erro e vazio saem do DataState; a lista só cuida dos itens. */}
         <DataState
@@ -29,14 +36,19 @@ export function App(): React.ReactElement {
         >
           <ul className="space-y-2">
             {items.map((t) => (
-              <li key={t.id} className="flex items-center justify-between gap-2 text-sm">
+              <li
+                key={t.id}
+                className="flex items-center justify-between gap-2 text-sm"
+              >
                 <span>{t.title}</span>
-                <Badge context={t.done ? 'success' : 'neutral'}>{t.done ? 'Feita' : 'Aberta'}</Badge>
+                <Badge context={t.done ? "success" : "neutral"}>
+                  {t.done ? "Feita" : "Aberta"}
+                </Badge>
               </li>
             ))}
           </ul>
         </DataState>
-      </Card>
+      </Surface>
     </main>
-  )
+  );
 }

package/src/ui/appearance.ts

@@ -0,0 +1,149 @@
+/**
+ * @softize/opus/ui/appearance — personalização de aparência sem React (ADR 0044).
+ *
+ * O tema deriva a escala neutra de quatro eixos inteiros (0 a 100) declarados por modo em
+ * `theme.css`: `--appearance-light-*` e `--appearance-dark-*`. Este módulo publica os tipos, os
+ * presets oficiais e o helper que converte overrides parciais nas custom properties que o
+ * consumidor aplica onde quiser (em geral, inline em `<html>`).
+ *
+ * Reset não pertence ao Opus UI: um eixo sem override vira `null`, e o consumidor remove a
+ * propriedade para voltar ao cascade — ou seja, ao preset do tema ou ao CSS do próprio app.
+ * Persistência e interface de ajuste também ficam com o consumidor.
+ */
+
+export type AppearanceMode = "light" | "dark";
+
+export const appearanceModes = [
+  "light",
+  "dark",
+] as const satisfies readonly AppearanceMode[];
+
+export type AppearanceAxis =
+  "colorIntensity" | "contrast" | "surfaceBrightness" | "layerContrast";
+
+/** Ordem canônica dos eixos: a mesma usada em documentação, presets e custom properties. */
+export const appearanceAxes = [
+  "colorIntensity",
+  "contrast",
+  "surfaceBrightness",
+  "layerContrast",
+] as const satisfies readonly AppearanceAxis[];
+
+/** Valor completo de um modo: todo eixo é um inteiro entre `APPEARANCE_MIN` e `APPEARANCE_MAX`. */
+export type AppearanceSettings = Readonly<Record<AppearanceAxis, number>>;
+
+/** Override parcial: eixo ausente (ou não finito) segue o cascade em vez de ser reescrito. */
+export type AppearanceOverrides = Partial<
+  Record<AppearanceAxis, number | null | undefined>
+>;
+
+export const APPEARANCE_MIN = 0;
+export const APPEARANCE_MAX = 100;
+
+/**
+ * Presets oficiais por modo — reproduzem exatamente os valores do tema sem personalização.
+ * Intensidade, contraste e contraste entre camadas partem de zero: o preset é o piso, e o ajuste
+ * só acrescenta cor ou separação. No claro, a superfície elevada já é branca; o brilho parte do
+ * máximo e só pode diminuir. No escuro, o brilho fica no meio para permitir um escuro mais
+ * profundo ou mais suave.
+ */
+export const appearancePresets: Readonly<
+  Record<AppearanceMode, AppearanceSettings>
+> = {
+  light: {
+    colorIntensity: 0,
+    contrast: 0,
+    surfaceBrightness: 100,
+    layerContrast: 0,
+  },
+  dark: {
+    colorIntensity: 0,
+    contrast: 0,
+    surfaceBrightness: 50,
+    layerContrast: 0,
+  },
+};
+
+const AXIS_PROPERTY: Record<AppearanceAxis, string> = {
+  colorIntensity: "color-intensity",
+  contrast: "contrast",
+  surfaceBrightness: "surface-brightness",
+  layerContrast: "layer-contrast",
+};
+
+export type AppearanceCustomProperty =
+  `--appearance-${AppearanceMode}-${string}`;
+
+/** Nome da custom property que `theme.css` lê para um eixo de um modo. */
+export function appearanceCustomProperty(
+  mode: AppearanceMode,
+  axis: AppearanceAxis,
+): AppearanceCustomProperty {
+  return `--appearance-${mode}-${AXIS_PROPERTY[axis]}`;
+}
+
+/**
+ * Normaliza um valor de eixo: arredonda para inteiro e limita ao intervalo. Retorna `undefined`
+ * para o que não é um número finito — o consumidor pode ter lido um valor corrompido de
+ * persistência, e a resposta correta é seguir o cascade, não travar a interface.
+ */
+export function normalizeAppearanceValue(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+  return Math.min(APPEARANCE_MAX, Math.max(APPEARANCE_MIN, Math.round(value)));
+}
+
+/** Preset do modo com os overrides válidos aplicados por cima. */
+export function resolveAppearance(
+  mode: AppearanceMode,
+  overrides: AppearanceOverrides = {},
+): AppearanceSettings {
+  const preset = appearancePresets[mode];
+  const resolved = { ...preset } as Record<AppearanceAxis, number>;
+  for (const axis of appearanceAxes) {
+    const value = normalizeAppearanceValue(overrides[axis]);
+    if (value !== undefined) resolved[axis] = value;
+  }
+  return resolved;
+}
+
+/**
+ * Converte overrides parciais nas custom properties do modo. Todo eixo aparece no resultado:
+ * com valor normalizado quando há override e `null` quando não há, para o consumidor remover a
+ * propriedade e deixar o cascade valer. Assim, o mesmo mapa serve para aplicar e para desfazer.
+ */
+export function appearanceCustomProperties(
+  mode: AppearanceMode,
+  overrides: AppearanceOverrides = {},
+): Record<AppearanceCustomProperty, string | null> {
+  const properties = {} as Record<AppearanceCustomProperty, string | null>;
+  for (const axis of appearanceAxes) {
+    const value = normalizeAppearanceValue(overrides[axis]);
+    properties[appearanceCustomProperty(mode, axis)] =
+      value === undefined ? null : String(value);
+  }
+  return properties;
+}
+
+/** Alvo mínimo para aplicar propriedades: `CSSStyleDeclaration` satisfaz, e um stub de teste também. */
+export interface AppearanceStyleTarget {
+  setProperty(name: string, value: string): void;
+  removeProperty(name: string): string | void;
+}
+
+/**
+ * Aplica os overrides de um modo num alvo de estilo. Eixos sem override são removidos, então
+ * chamar sem overrides devolve o elemento ao cascade — é o reset, feito pelo consumidor, sem
+ * estado no Opus.
+ */
+export function applyAppearanceCustomProperties(
+  target: AppearanceStyleTarget,
+  mode: AppearanceMode,
+  overrides: AppearanceOverrides = {},
+): void {
+  for (const [name, value] of Object.entries(
+    appearanceCustomProperties(mode, overrides),
+  )) {
+    if (value === null) target.removeProperty(name);
+    else target.setProperty(name, value);
+  }
+}