@softize/opus 23.0.0 → 24.0.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "23.0.0",
+  "version": "24.0.0",
   "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);
+  }
+}

package/src/ui/components/patterns/action-form-card.tsx

@@ -1,19 +1,19 @@
 /**
- * <ActionFormCard /> — o ActionForm dentro de um Card do Opus (header / conteúdo / rodapé),
- * pra estruturar uma seção da página como painel. Segue o padrão do CARD (não a chrome de
- * modal): sem divisor nem faixa, com o respiro do Card. Pra form em overlay, use o
- * ActionFormDialog; pra form cru (sem chrome), o ActionForm direto.
+ * <ActionFormCard /> — o ActionForm dentro de uma Surface elevada (header / conteúdo /
+ * rodapé), pra estruturar uma seção da página como painel. Segue o layout contínuo (não a
+ * chrome de modal): sem divisor nem faixa. Pra form em overlay, use o ActionFormDialog; pra
+ * form cru (sem chrome), o ActionForm direto.
  */
-import {
-  Card,
-  CardBody,
-  CardDescription,
-  CardFooter,
-  CardHeader,
-  CardTitle,
-} from "../primitives/card.tsx";
 import { ActionForm, type ActionFormProps } from "./form.tsx";
 import type { HeadingLevel } from "./heading-level.ts";
+import {
+  Surface,
+  SurfaceBody,
+  SurfaceDescription,
+  SurfaceFooter,
+  SurfaceHeader,
+  SurfaceTitle,
+} from "./surface.tsx";
 import { ButtonGroup } from "../primitives/button-group.tsx";
 
 export interface ActionFormCardProps<
@@ -23,49 +23,62 @@ export interface ActionFormCardProps<
   /** Título do header do card. Sem ele, o card começa direto no conteúdo. */
   title?: string;
   /**
-   * Nível semântico do título (`h1`–`h6`), repassado ao `CardTitle` como `level`. Sem
-   * ele vale o `h3` do Card. Muda só a hierarquia do documento; a escala visual continua
-   * a do Card.
+   * Nível semântico do título (`h1`–`h6`), repassado à `Surface` como `level`. Sem ele
+   * vale `h3`: o card costuma ser uma seção dentro de uma página que já tem `h1` e `h2`.
    */
   titleLevel?: HeadingLevel;
-  /** Subtítulo opcional, abaixo do título. */
+  /** Subtítulo opcional, abaixo do título. Exige `title`. */
   description?: string;
-  /** Classes do Card (a superfície). `className` vai pro <form>. */
+  /** Classes da superfície. `className` vai pro <form>. */
   cardClassName?: string;
 }
 
 export function ActionFormCard<TInput extends Record<string, unknown>, TData>({
   title,
-  titleLevel,
+  titleLevel = 3,
   description,
   cardClassName,
   ...rest
 }: ActionFormCardProps<TInput, TData>) {
+  if (description !== undefined && title === undefined) {
+    throw new Error(
+      "ActionFormCard exige title quando description é informada.",
+    );
+  }
   return (
-    <Card className={cardClassName}>
-      {(title !== undefined || description !== undefined) && (
-        <CardHeader>
-          {title !== undefined && (
-            <CardTitle level={titleLevel}>{title}</CardTitle>
-          )}
-          {description !== undefined && (
-            <CardDescription>{description}</CardDescription>
-          )}
-        </CardHeader>
-      )}
+    <Surface
+      framed
+      elevation="raised"
+      level={titleLevel}
+      className={cardClassName}
+    >
+      {/* As três regiões são irmãs dentro do <form>: o ritmo e o respiro de cada uma
+          derivam da vizinhança, e os botões precisam ficar dentro do form. */}
       <ActionForm
         {...rest}
-        body={(fields) => <CardBody>{fields}</CardBody>}
+        body={(fields) => (
+          <>
+            {title !== undefined && (
+              <SurfaceHeader>
+                <SurfaceTitle>{title}</SurfaceTitle>
+                {description !== undefined && (
+                  <SurfaceDescription>{description}</SurfaceDescription>
+                )}
+              </SurfaceHeader>
+            )}
+            <SurfaceBody>{fields}</SurfaceBody>
+          </>
+        )}
         footer={(actions) => (
-          <CardFooter className="justify-end">
+          <SurfaceFooter>
             {rest.onCancel === undefined ? (
               actions
             ) : (
               <ButtonGroup mode="spaced">{actions}</ButtonGroup>
             )}
-          </CardFooter>
+          </SurfaceFooter>
         )}
       />
-    </Card>
+    </Surface>
   );
 }

package/src/ui/components/patterns/action-list-dialog.tsx

@@ -86,14 +86,12 @@ export function ActionListDialog<
         </DialogHeader>
         <DialogBody>
           {intro !== undefined && (
-            <div id={introId} className="mb-4">
-              {intro}
-            </div>
+            <div id={introId}>{intro}</div>
           )}
           {(note !== undefined || actions !== undefined) && (
             <div
               data-slot="action-list-dialog-toolbar"
-              className="mb-2 flex min-h-8 items-center justify-between gap-4"
+              className="flex min-h-8 items-center justify-between gap-4"
             >
               <div className="min-w-0 text-xs text-muted-foreground/70">{note}</div>
               {actions}

package/src/ui/components/patterns/confirm.tsx

@@ -284,7 +284,9 @@ export function DialogHost(): React.ReactElement {
             <DialogTitle>{current.title}</DialogTitle>
           </DialogHeader>
           {current.body !== undefined && (
-            <DialogBody id={bodyId}>{current.body}</DialogBody>
+            <DialogBody id={bodyId}>
+              <div>{current.body}</div>
+            </DialogBody>
           )}
           {current.kind === "prompt" && (
             <Input