@softize/opus 29.0.0 → 31.0.0

package/src/ui/docs/content/compositions.md

@@ -1,491 +1,161 @@
----
-title: Composições
----
+## Uma estrutura para cada superfície
 
-# Composições
+Page, Dialog, Drawer e Surface compartilham cabeçalho, corpo e rodapé. Escolha a superfície
+pelo contexto da tarefa: Page ocupa a área principal, Dialog interrompe para uma tarefa,
+Drawer mantém o detalhe lateral e Surface agrupa uma região dentro do conteúdo.
 
-Use esta página para decidir como montar uma tela antes de escolher as propriedades de cada
-componente. `Page`, `Dialog`, `Drawer` e `Surface` se organizam da mesma forma: um cabeçalho, um
-corpo e um rodapé com a decisão da etapa. Cada família admite as ações e a navegação indicadas na
-tabela abaixo. Em `Page`, `Dialog` e `Drawer`, o corpo também pode começar por uma intro que leva o
-título. `Pane` fica fora dessa organização: ele só reserva, dentro de um `Split`, o espaço em que
-uma `Surface` aparece.
+| Região       | Page        | Dialog        | Drawer        | Surface        |
+| ------------ | ----------- | ------------- | ------------- | -------------- |
+| Cabeçalho    | PageHeader  | DialogHeader  | DrawerHeader  | SurfaceHeader  |
+| Título       | PageTitle   | DialogTitle   | DrawerTitle   | SurfaceTitle   |
+| Metadados    | PageMeta    | DialogMeta    | DrawerMeta    | SurfaceMeta    |
+| Ações gerais | PageActions | DialogActions | DrawerActions | SurfaceActions |
+| Corpo        | PageBody    | DialogBody    | DrawerBody    | SurfaceBody    |
+| Rodapé       | PageFooter  | DialogFooter  | DrawerFooter  | SurfaceFooter  |
 
-Todos os exemplos mostram a mesma tarefa, editar uma ordem de serviço, em superfícies diferentes.
-As propriedades de cada componente ficam nas páginas da família: [`Page`](/ui/page),
-[`Dialog`](/ui/dialog), [`Drawer`](/ui/drawer), [`Surface`](/ui/surface) e [`Pane`](/ui/pane).
-
-## As regiões de cada superfície
-
-Cada família dá um nome próprio a cada região. A tabela mostra a correspondência entre elas.
-
-| Região               | Page                                        | Dialog                        | Drawer                        | Surface                       |
-| -------------------- | ------------------------------------------- | ----------------------------- | ----------------------------- | ----------------------------- |
-| Navegação            | `PageNavigation` ou `PageBack`              | `DialogNavigation`            | `DrawerNavigation`            | Não existe                    |
-| Título no cabeçalho  | `PageTitle`                                 | `DialogTitle`                 | `DrawerTitle`                 | `SurfaceTitle`                |
-| Ações do cabeçalho   | `PageActions`                               | `DialogActions`               | `DrawerActions`               | `SurfaceActions`              |
-| Intro                | `PageIntro` no início do `PageBody` | `DialogIntro`                 | `DrawerIntro`                 | Não existe                    |
-| Ações da intro       | `PageIntroActions`                | `DialogIntroActions`          | `DrawerIntroActions`          | Não existe                    |
-| Corpo                | `PageBody`                                  | `DialogBody`                  | `DrawerBody`                  | `SurfaceBody`                 |
-| Rodapé               | `PageFooter`                                | `DialogFooter`                | `DrawerFooter`                | `SurfaceFooter`               |
-| Divisores            | Antes do `PageFooter`                       | `sectioned` (padrão)          | `sectioned` (padrão)          | `sectioned`                   |
-| Sem divisores        | Cabeçalho e corpo                           | `continuous`                  | `continuous`                  | `continuous` (padrão)         |
-
-`layout` escolhe entre as duas anatomias em `DialogContent`, `DrawerContent` e `Surface`. Em
-`sectioned`, uma linha separa as regiões vizinhas; em `continuous`, o espaço faz essa separação. Na
-`Surface`, `sectioned` exige `framed` ou `elevation="raised"`, para que a linha tenha um limite. A
-`Page` não oferece anatomia `sectioned`: cabeçalho e corpo são contínuos, enquanto o `PageFooter`
-é uma faixa própria, separada por sua borda superior. O `layout` da página decide apenas a ocupação
-de altura.
+O título pertence ao cabeçalho. Descrição opcional e metadados têm slots próprios. Cabeçalho
+e rodapé ficam fora da rolagem do corpo em Page e modais; a Surface acompanha o fluxo do conteúdo.
+Os divisores são automáticos, sem escolha de anatomia contínua ou compacta.
 
 ## Onde cada ação fica
 
-A posição de uma ação informa a que ela se refere. Escolha o lugar pelo alcance da ação, não pelo
-espaço livre na tela.
-
-| Lugar      | Use para                                                                                                   |
-| ---------- | ---------------------------------------------------------------------------------------------------------- |
-| Navegação  | Sair ou voltar na estrutura: a trilha da página, a etapa anterior de um fluxo modal ou recolher o painel.  |
-| Cabeçalho  | Ações que valem para a superfície inteira, como abrir uma conversa sobre o registro.                       |
-| Intro      | Ações ligadas ao título e ao conteúdo, como ver o histórico do registro.                                    |
-| Rodapé     | A decisão da etapa: **Cancelar** em `ghost` e a ação principal sólida, alinhadas à direita.                |
-
-Em `Dialog` e `Drawer`, a navegação abre a linha do cabeçalho e fica junto do título, a `0.5rem`
-dele. As ações ficam no extremo oposto, antes do botão de fechar, e mantêm a distância maior da
-família até o título. Na `Page`, a navegação fica acima do título; quando o título está na intro,
-ela divide a linha com as ações da página.
-
-Em `Dialog` e `Drawer`, cabeçalho e rodapé permanecem visíveis enquanto o corpo rola; a intro rola
-junto com o conteúdo.
-
-## Título no cabeçalho ou na intro
-
-O título pode ficar em dois lugares, e essa escolha define a composição:
+| Ação                                                  | Região                    |
+| ----------------------------------------------------- | ------------------------- |
+| Retorno, histórico ou configuração do recurso inteiro | Ações do cabeçalho        |
+| Criar, importar, exportar ou operar a coleção         | ActionList.toolbarActions |
+| Operar os registros selecionados                      | ActionList.batchActions   |
+| Operar um registro da lista                           | ActionList.rowActions     |
+| Salvar ou cancelar uma etapa                          | Rodapé                    |
 
-- **Com intro:** o cabeçalho guarda só a navegação, as ações da superfície e o fechamento. O título
-  abre o corpo junto das ações do conteúdo. Use quando esses controles da superfície precisam
-  continuar estáveis e separados do registro aberto.
-- **Compacta:** título, ações do conteúdo e ações da superfície dividem a linha do cabeçalho, e a
-  intro é omitida. Use quando uma linha basta para nomear a tarefa e agir sobre ela.
+O botão de criação mostra **Criar**. Seu nome acessível e o título do formulário identificam
+o recurso. Menus com vários tipos de criação mantêm nomes específicos.
 
-Na composição compacta, coloque as ações do conteúdo antes das ações da superfície, no mesmo slot de
-ações. Em `Dialog` e `Drawer`, o título no cabeçalho trunca quando não cabe na linha; na intro, ele
-usa uma escala maior e quebra em mais de uma linha.
+## Página
 
-## Dialog
+A página usa a largura disponível. Para uma lista preencher a altura restante, declare
+`layout="fill"`; para conteúdo que rola no corpo, mantenha `flow`.
 
-Abra cada combinação para comparar. As linhas trocam o `layout` de `DialogContent`; as colunas
-trocam o lugar do título. O campo e o rodapé são os mesmos nos quatro casos.
-
-```tsx preview
-function OrderField() {
-  const id = useId();
-  return (
-    <div className="space-y-2">
-      <Label htmlFor={id}>Responsável</Label>
-      <Input id={id} defaultValue="Marina Alves" />
-    </div>
-  );
-}
-
-function DialogWithIntro({ layout, label }) {
-  return (
-    <Dialog>
-      <DialogTrigger asChild>
-        <Button variant="outline">{label}</Button>
-      </DialogTrigger>
-      <DialogContent layout={layout}>
-        <DialogHeader>
-          <DialogActions>
-            <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
-              <MessageCircle />
-            </Button>
-          </DialogActions>
-        </DialogHeader>
-        <DialogBody>
-          <DialogIntro>
-            <DialogTitle>Editar ordem de serviço</DialogTitle>
-            <DialogIntroActions>
-              <Button variant="outline" size="sm">
-                Ver histórico
-              </Button>
-            </DialogIntroActions>
-          </DialogIntro>
-          <OrderField />
-        </DialogBody>
-        <DialogFooter>
-          <ButtonGroup mode="spaced">
-            <DialogClose asChild>
-              <Button variant="ghost">Cancelar</Button>
-            </DialogClose>
-            <Button>Salvar</Button>
-          </ButtonGroup>
-        </DialogFooter>
-      </DialogContent>
-    </Dialog>
-  );
-}
-
-function CompactDialog({ layout, label }) {
-  return (
-    <Dialog>
-      <DialogTrigger asChild>
-        <Button variant="outline">{label}</Button>
-      </DialogTrigger>
-      <DialogContent layout={layout}>
-        <DialogHeader>
-          <DialogMedia>
-            <Wrench />
-          </DialogMedia>
-          <DialogTitle>Editar ordem de serviço</DialogTitle>
-          <DialogActions>
-            <Button variant="outline" size="sm">
-              Ver histórico
-            </Button>
-            <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
-              <MessageCircle />
-            </Button>
-          </DialogActions>
-        </DialogHeader>
-        <DialogBody>
-          <OrderField />
-        </DialogBody>
-        <DialogFooter>
-          <ButtonGroup mode="spaced">
-            <DialogClose asChild>
-              <Button variant="ghost">Cancelar</Button>
-            </DialogClose>
-            <Button>Salvar</Button>
-          </ButtonGroup>
-        </DialogFooter>
-      </DialogContent>
-    </Dialog>
-  );
-}
-
-render(
-  <div className="grid grid-cols-2 gap-3">
-    <DialogWithIntro layout="sectioned" label="Seccionado com intro" />
-    <CompactDialog layout="sectioned" label="Seccionado compacto" />
-    <DialogWithIntro layout="continuous" label="Contínuo com intro" />
-    <CompactDialog layout="continuous" label="Contínuo compacto" />
-  </div>,
-);
+```tsx preview col
+<Page>
+  <PageHeader>
+    <PageTitle>Evento</PageTitle>
+    <PageActions>
+      <PageBack href="/events">Eventos</PageBack>
+      <Button variant="ghost" size="icon" aria-label="Histórico">
+        <History />
+      </Button>
+    </PageActions>
+  </PageHeader>
+  <PageBody>
+    <p>Dados do evento.</p>
+  </PageBody>
+  <PageFooter>
+    <ButtonGroup mode="spaced">
+      <Button variant="ghost">Cancelar</Button>
+      <Button>Salvar</Button>
+    </ButtonGroup>
+  </PageFooter>
+</Page>
 ```
 
-Prefira `continuous` para uma tarefa curta, em que a linha entre as regiões seria ruído. O `Dialog`
-não recebe navegação neste exemplo: use `DialogNavigation` quando o modal trocar de etapa e a pessoa
-precisar voltar à anterior.
+`PageShell` fornece ações conhecidas pelo shell sem criar outra barra. Subpáginas usam
+`PageBack` como primeiro ícone das ações, com destino explícito.
 
-## Drawer
+## Diálogo
 
-O `Drawer` segue a mesma grade. A navegação aparece aqui como o controle de recolher o painel: um
-`DrawerClose` dentro de `DrawerNavigation`, com `showCloseButton={false}` para que o painel não tenha
-dois controles de fechamento.
+O diálogo preserva a mesma ordem das regiões. Fechar, Escape e o clique fora dispensam
+uma tarefa comum; use `closeDisabled` durante uma operação que não possa ser interrompida.
 
 ```tsx preview
-function OrderField() {
-  const id = useId();
-  return (
-    <div className="space-y-2">
-      <Label htmlFor={id}>Responsável</Label>
-      <Input id={id} defaultValue="Marina Alves" />
-    </div>
-  );
-}
-
-function CollapseButton() {
-  return (
-    <DrawerClose asChild>
-      <Button variant="ghost" size="icon-sm" aria-label="Recolher painel">
-        <ChevronsRight />
-      </Button>
-    </DrawerClose>
-  );
-}
-
-function DrawerWithIntro({ layout, label }) {
-  return (
-    <Drawer>
-      <DrawerTrigger asChild>
-        <Button variant="outline">{label}</Button>
-      </DrawerTrigger>
-      <DrawerContent layout={layout} showCloseButton={false}>
-        <DrawerHeader>
-          <DrawerNavigation>
-            <CollapseButton />
-          </DrawerNavigation>
-          <DrawerActions>
-            <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
-              <MessageCircle />
-            </Button>
-          </DrawerActions>
-        </DrawerHeader>
-        <DrawerBody>
-          <DrawerIntro>
-            <DrawerTitle>Editar ordem de serviço</DrawerTitle>
-            <DrawerIntroActions>
-              <Button variant="outline" size="sm">
-                Ver histórico
-              </Button>
-            </DrawerIntroActions>
-          </DrawerIntro>
-          <OrderField />
-        </DrawerBody>
-        <DrawerFooter>
-          <ButtonGroup mode="spaced">
-            <DrawerClose asChild>
-              <Button variant="ghost">Cancelar</Button>
-            </DrawerClose>
-            <Button>Salvar</Button>
-          </ButtonGroup>
-        </DrawerFooter>
-      </DrawerContent>
-    </Drawer>
-  );
-}
-
-function CompactDrawer({ layout, label }) {
-  return (
-    <Drawer>
-      <DrawerTrigger asChild>
-        <Button variant="outline">{label}</Button>
-      </DrawerTrigger>
-      <DrawerContent layout={layout} showCloseButton={false}>
-        <DrawerHeader>
-          <DrawerNavigation>
-            <CollapseButton />
-          </DrawerNavigation>
-          <DrawerTitle>Editar ordem de serviço</DrawerTitle>
-          <DrawerActions>
-            <Button variant="outline" size="sm">
-              Ver histórico
-            </Button>
-            <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
-              <MessageCircle />
-            </Button>
-          </DrawerActions>
-        </DrawerHeader>
-        <DrawerBody>
-          <OrderField />
-        </DrawerBody>
-        <DrawerFooter>
-          <ButtonGroup mode="spaced">
-            <DrawerClose asChild>
-              <Button variant="ghost">Cancelar</Button>
-            </DrawerClose>
-            <Button>Salvar</Button>
-          </ButtonGroup>
-        </DrawerFooter>
-      </DrawerContent>
-    </Drawer>
-  );
-}
-
-render(
-  <div className="grid grid-cols-2 gap-3">
-    <DrawerWithIntro layout="sectioned" label="Seccionado com intro" />
-    <CompactDrawer layout="sectioned" label="Seccionado compacto" />
-    <DrawerWithIntro layout="continuous" label="Contínuo com intro" />
-    <CompactDrawer layout="continuous" label="Contínuo compacto" />
-  </div>,
-);
+<Dialog>
+  <DialogTrigger asChild>
+    <Button variant="outline">Abrir diálogo</Button>
+  </DialogTrigger>
+  <DialogContent aria-describedby={undefined}>
+    <DialogHeader>
+      <DialogTitle>Editar evento</DialogTitle>
+      <DialogActions>
+        <Button variant="ghost" size="icon" aria-label="Histórico">
+          <History />
+        </Button>
+      </DialogActions>
+    </DialogHeader>
+    <DialogBody>
+      <p>Dados do evento.</p>
+    </DialogBody>
+    <DialogFooter>
+      <ButtonGroup mode="spaced">
+        <DialogClose asChild>
+          <Button variant="ghost">Cancelar</Button>
+        </DialogClose>
+        <Button>Salvar</Button>
+      </ButtonGroup>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
 ```
 
-Mantenha `DrawerNavigation`, `DrawerTitle` e `DrawerActions` como filhos diretos de
-`DrawerHeader`: o cabeçalho reconhece os slots pelo componente e interrompe a renderização diante de
-qualquer outro nó, inclusive um componente local que devolva um slot. Por isso, o exemplo extrai
-apenas o botão de recolher. Sem o botão de fechar, Esc e o clique no overlay continuam fechando o
-painel.
-
-## Page
+`Dialog mode="alert"` conserva sua composição de resposta obrigatória. É uma diferença de
+comportamento, não uma opção de densidade do formulário.
 
-Na composição com intro, o `PageHeader` guarda a navegação e as ações da
-página, e uma `PageIntro` abre o `PageBody` com o título e as ações do conteúdo. A página
-precisa de exatamente um heading principal, por isso o `PageHeader` dessa composição não leva
-`PageTitle`.
-
-```tsx preview col
-render(
-  <div className="w-full overflow-hidden rounded-lg border border-border">
-    <Page>
-      <PageHeader>
-        <PageNavigation>
-          <Breadcrumb>
-            <BreadcrumbList>
-              <BreadcrumbItem>Oficina</BreadcrumbItem>
-              <BreadcrumbSeparator />
-              <BreadcrumbItem>Ordens de serviço</BreadcrumbItem>
-              <BreadcrumbSeparator />
-              <BreadcrumbPage>OS-1842</BreadcrumbPage>
-            </BreadcrumbList>
-          </Breadcrumb>
-        </PageNavigation>
-        <PageActions>
-          <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
-            <MessageCircle />
-          </Button>
-        </PageActions>
-      </PageHeader>
-      <PageBody>
-        <PageIntro>
-          <PageTitle>Editar ordem de serviço</PageTitle>
-          <PageIntroActions><Button variant="outline" size="sm">Ver histórico</Button></PageIntroActions>
-        </PageIntro>
-          <div className="space-y-2">
-            <Label htmlFor="page-intro-owner">Responsável</Label>
-            <Input id="page-intro-owner" defaultValue="Marina Alves" />
-          </div>
-      </PageBody>
-      <PageFooter>
-        <ButtonGroup mode="spaced">
-          <Button variant="ghost">Cancelar</Button>
-          <Button>Salvar</Button>
-        </ButtonGroup>
-      </PageFooter>
-    </Page>
-  </div>,
-);
-```
+## Painel lateral
 
-Na composição compacta, `PageTitle` entra no `PageHeader` e as ações do conteúdo passam para
-`PageActions`, antes das ações da página. A forma curta, `<Page title actions>`, produz esse mesmo
-cabeçalho; nela, a navegação vem do [`PageShell`](/ui/page).
+O drawer usa o mesmo cabeçalho e mantém seu corpo rolável até a altura disponível.
 
-```tsx preview col
-render(
-  <div className="w-full overflow-hidden rounded-lg border border-border">
-    <Page>
-      <PageHeader>
-        <PageNavigation>
-          <Breadcrumb>
-            <BreadcrumbList>
-              <BreadcrumbItem>Oficina</BreadcrumbItem>
-              <BreadcrumbSeparator />
-              <BreadcrumbItem>Ordens de serviço</BreadcrumbItem>
-              <BreadcrumbSeparator />
-              <BreadcrumbPage>OS-1842</BreadcrumbPage>
-            </BreadcrumbList>
-          </Breadcrumb>
-        </PageNavigation>
-        <PageTitle>Editar ordem de serviço</PageTitle>
-        <PageActions>
-          <Button variant="outline" size="sm">
-            Ver histórico
-          </Button>
-          <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
-            <MessageCircle />
-          </Button>
-        </PageActions>
-      </PageHeader>
-      <PageBody>
-        <div className="space-y-2">
-          <Label htmlFor="page-compact-owner">Responsável</Label>
-          <Input id="page-compact-owner" defaultValue="Marina Alves" />
-        </div>
-      </PageBody>
-      <PageFooter>
-        <ButtonGroup mode="spaced">
+```tsx preview
+<Drawer>
+  <DrawerTrigger asChild>
+    <Button variant="outline">Abrir painel</Button>
+  </DrawerTrigger>
+  <DrawerContent aria-describedby={undefined}>
+    <DrawerHeader>
+      <DrawerTitle>Evento</DrawerTitle>
+      <DrawerActions>
+        <Button variant="ghost" size="icon" aria-label="Histórico">
+          <History />
+        </Button>
+      </DrawerActions>
+    </DrawerHeader>
+    <DrawerBody>
+      <p>Dados do evento.</p>
+    </DrawerBody>
+    <DrawerFooter>
+      <ButtonGroup mode="spaced">
+        <DrawerClose asChild>
           <Button variant="ghost">Cancelar</Button>
-          <Button>Salvar</Button>
-        </ButtonGroup>
-      </PageFooter>
-    </Page>
-  </div>,
-);
+        </DrawerClose>
+        <Button>Salvar</Button>
+      </ButtonGroup>
+    </DrawerFooter>
+  </DrawerContent>
+</Drawer>
 ```
 
-Use `PageFooter` quando a página for uma etapa com decisão própria, como esta edição.
-
 ## Pane com Surface
 
-`Pane` declara uma coluna de um [`Split`](/ui/split) e não desenha nada: não tem cabeçalho, corpo,
-rodapé, recuo, borda nem fundo. Quando a coluna precisa dessas regiões, componha uma `Surface`
-dentro dela. A `Surface` não tem intro, então o título fica no `SurfaceHeader`, como na composição
-compacta.
+Pane distribui espaço; Surface fornece a apresentação. Moldura e elevação continuam
+independentes da composição do cabeçalho, corpo e rodapé.
 
 ```tsx preview col
-render(
-  <div className="h-80 w-full overflow-hidden rounded-lg border border-border">
-    <Split>
-      <Pane initialSize="14rem">
-        <Sidebar className="w-full">
-          <SidebarNav
-            navLabel="Ordens de serviço"
-            activeId="os-1842"
-            groups={[
-              {
-                items: [
-                  { id: "os-1842", label: "OS-1842" },
-                  { id: "os-1839", label: "OS-1839" },
-                  { id: "os-1835", label: "OS-1835" },
-                ],
-              },
-            ]}
-          />
-        </Sidebar>
-      </Pane>
-      <Pane grow>
-        <Surface
-          as="section"
-          framed
-          elevation="raised"
-          layout="sectioned"
-          className="flex h-full flex-col"
-        >
-          <SurfaceHeader>
-            <SurfaceMedia>
-              <Wrench />
-            </SurfaceMedia>
-            <SurfaceTitle>Editar ordem de serviço</SurfaceTitle>
-            <SurfaceActions>
-              <Button variant="outline" size="sm">
-                Ver histórico
-              </Button>
-              <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
-                <MessageCircle />
-              </Button>
-            </SurfaceActions>
-          </SurfaceHeader>
-          <SurfaceBody className="min-h-0 flex-1 overflow-y-auto">
-            <div className="space-y-2">
-              <Label htmlFor="pane-owner">Responsável</Label>
-              <Input id="pane-owner" defaultValue="Marina Alves" />
-            </div>
-          </SurfaceBody>
-          <SurfaceFooter>
-            <ButtonGroup mode="spaced">
-              <Button variant="ghost">Cancelar</Button>
-              <Button>Salvar</Button>
-            </ButtonGroup>
-          </SurfaceFooter>
-        </Surface>
-      </Pane>
-    </Split>
-  </div>,
-);
+<Pane>
+  <Surface framed title="Evento">
+    <SurfaceBody>
+      <p>Dados do evento.</p>
+    </SurfaceBody>
+    <SurfaceFooter>
+      <Button>Salvar</Button>
+    </SurfaceFooter>
+  </Surface>
+</Pane>
 ```
 
-Os dois panes recebem conteúdos diferentes sem mudar de componente: o primeiro hospeda uma
-[`Sidebar`](/ui/sidebar), que já tem anatomia própria, e o segundo, uma `Surface` completa. A
-rolagem também pertence ao conteúdo: a `Surface` ocupa a altura do pane com `flex h-full flex-col`,
-e o `SurfaceBody` declara `min-h-0 flex-1 overflow-y-auto` para rolar entre o cabeçalho e o rodapé.
-
-## Ritmo entre regiões e blocos
-
-Surface (incluindo cards e seções), Page, Dialog, Drawer e Tabs organizam o conteúdo
-com intervalos de `1rem`. Os bodies separam seus blocos diretos; grupos internos podem
-ter densidade própria. DetailGroup e Separator não criam margens externas.
-
-Sem delimitação, Surface e Tabs não adicionam padding inferior. Uma Surface com moldura
-ou elevação, assim como Dialog e Drawer, reserva `1rem` até a borda. No layout contínuo,
-o intervalo vem da região anterior. No seccionado, há `1rem` entre cada divisória e o
-conteúdo adjacente. Não some padding e gap para expressar o mesmo intervalo.
+## Abas e espaçamento
 
-Page conserva os recuos laterais e a largura de leitura. Seu body não acrescenta padding
-inferior quando termina a página; antes de um footer seccionado, reserva `1rem` até a linha.
-O modo `flush` remove recuos do body para uma lista ou tabela controlar sua própria borda,
-mas mantém o intervalo entre blocos.
+O header de cada família aceita `tabs`, com uma `TabsList` governada por `Tabs` ancestral.
+Os painéis ficam no body. Ações de listagem permanecem dentro do painel correspondente.
 
-Ao migrar, remova `space-y`, `gap`, `pt` e `pb` locais que apenas reconstruíam esses defaults
-nos slots. Preserve classes de layout internas, como uma grade ou um grupo de campos compacto.
+Superfícies delimitadas usam recuo de `1rem` em cada região. A linha de cabeçalho reserva
+`2,25rem`, com ou sem ações, e recebe botões `default` ou `icon`. O corpo separa blocos diretos
+por `1rem`; grupos com ritmo próprio ficam em um wrapper filho. `flush` permite que um conteúdo
+controle seu próprio recuo. Surface sem moldura ou elevação mantém alinhamento lateral com
+o hospedeiro, sem padding inferior extra. Não reescreva essas medidas em cada tela.