@softize/opus 12.1.0 → 12.2.1

package/CHANGELOG.md

@@ -7,6 +7,23 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 12.2.1 — 2026-08-23
+
+O cabeçalho de `Page` passa a alinhar `actions` à base do bloco formado por título e descrição.
+Assim, os botões permanecem junto ao fim do contexto quando a página apresenta uma linha
+explicativa. Múltiplas ações conservam o espaçamento entre si. A API pública não muda.
+
+## 12.2.0 — 2026-08-23
+
+A escala de arredondamento ganha uma base mais presente sem transformar todo componente em uma
+superfície principal. `--radius` passa de `0.625rem` para `0.75rem`; os degraus de
+`rounded-xs` a `rounded-2xl` derivam dessa base e permanecem crescentes. Cards e modais continuam
+em `rounded-xl`, enquanto controles compactos e molduras estruturais preservam seus degraus.
+
+A mudança é visual e não exige migração de código. Aplicações que já sobrescrevem `--radius`
+mantêm sua própria identidade; as demais recebem automaticamente a nova escala. A documentação e
+a skill de UI explicam aninhamento, grupos conectados e a separação entre tamanho e forma.
+
 ## 12.1.0 — 2026-08-22
 
 Interfaces que combinam copy fixa com nomes, contagens ou opções vindas da aplicação não

package/docs/radius-scale.md

@@ -0,0 +1,66 @@
+# Escala de arredondamento
+
+> **Status: decidido (ago/2026).** A forma usa uma escala contínua do Tailwind; o nome do
+> componente não cria um segundo conjunto de tokens.
+
+## Contexto
+
+Cards e modais precisam ter presença suficiente para organizar a página sem parecerem caixas
+rígidas. Controles, itens internos e superfícies compactas precisam continuar menores para que a
+interface preserve hierarquia. A base anterior de `0.625rem` deixava o primeiro grupo adequado,
+mas mantinha os demais degraus visualmente mais retos do que a identidade desejada.
+
+Alterar cada componente isoladamente resolveria exemplos visíveis, mas deixaria consumidores e
+novos componentes sem uma referência comum. Reintroduzir tokens como `--radius-card` também
+voltaria a acoplar forma e tipo de componente, problema removido na versão 10.0.0.
+
+## Decisão
+
+- `--radius` passa a `0.75rem`. Aplicações podem sobrescrever essa base para ajustar a identidade
+  inteira sem forkar componentes.
+- `rounded-xs` até `rounded-2xl` formam uma progressão derivada da mesma base. `rounded-full`
+  continua reservado a círculos e variantes explicitamente pill.
+- Componentes escolhem o degrau pela escala visual. Em geral, detalhes e itens internos usam
+  `xs` ou `sm`; controles e superfícies compactas usam `md`; molduras estruturais usam `lg`; e
+  superfícies principais ou modais usam `xl`. Essa associação orienta o default, mas não cria um
+  token semântico por componente.
+- Superfícies aninhadas evitam moldura dupla e normalmente usam um degrau menor que o contêiner.
+  Elementos conectados removem os raios nas arestas internas.
+- Card, Dialog e AlertDialog permanecem em `xl`. Molduras estruturais com cantos, como a tabela
+  standalone, permanecem em `lg`; Page, Split e Sidebar não ganham uma moldura por essa regra.
+- Calendar e Command preservam a geometria embutível. Um consumidor standalone pode ajustar o
+  contêiner por `className` quando a composição pedir mais presença.
+- Tamanho e forma continuam eixos separados nos controles. Variantes `sm`, `default` e `lg` não
+  mudam o radius automaticamente; `shape="pill"` continua sendo a escolha explícita para pílulas.
+
+## Consequências
+
+- A mudança da base afeta todos os consumidores que não sobrescrevem `--radius`. O efeito é
+  visual e intencional; nenhuma migração de código é necessária.
+- A progressão derivada evita que `rounded-xl` ultrapasse `rounded-2xl` e faz a customização por
+  `--radius` alcançar também os extremos usados pelo Opus. `rounded-3xl` continua nativo do
+  Tailwind; aplicações que usam esse degrau precisam revisar a fronteira ao alterar a base.
+- Novos componentes podem escolher uma utility da escala sem inventar vocabulário próprio.
+- Drawer e outras superfícies presas à viewport não mudam neste entregável. Arredondar somente os
+  cantos expostos exige validar clipping, scroll e conteúdo full-bleed em uma mudança própria.
+
+## Alternativas descartadas
+
+- **Aplicar `rounded-xl` a toda superfície:** aproxima os componentes do Card, mas elimina a
+  diferença entre controles compactos, molduras estruturais e superfícies principais.
+- **Editar cada componente sem mudar a base:** oferece controle pontual, mas espalha a decisão e
+  não beneficia consumidores que usam diretamente a escala do Tailwind.
+- **Restaurar tokens por papel:** fixa defaults, mas volta a criar uma taxonomia paralela para a
+  mesma propriedade.
+- **Escalar radius junto com o tamanho de cada controle:** parece proporcional isoladamente, mas
+  quebra grupos conectados e mistura o eixo de forma com o eixo de densidade.
+
+## Verificação
+
+- Um teste de contrato lê o tema canônico e confirma a base, as fórmulas e a ordem crescente de
+  `rounded-xs` até `rounded-2xl`.
+- A documentação de tokens demonstra a escala completa e explica como uma aplicação altera a
+  identidade pelo token base.
+- A skill `build-opus-ui` orienta o uso da escala, o aninhamento e as junções sem prescrever tokens
+  por componente.
+- Os testes e o build da UI confirmam que as utilities continuam materializadas pelo Tailwind.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "12.1.0",
+  "version": "12.2.1",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

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

@@ -24,7 +24,12 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
    `bg-card text-card-foreground` e `bg-popover text-popover-foreground`. Não depender da
    igualdade atual com `--foreground`, porque o app pode sobrescrever cada par.
 7. Usar diretamente a escala `rounded-*`; não criar radius por nome de componente quando
-   `rounded-sm` a `rounded-xl` já expressam a forma.
+   `rounded-xs` a `rounded-2xl` já expressam a forma. Escolher o degrau pela escala visual:
+   detalhes e itens internos tendem a `xs`/`sm`, controles e flutuantes compactos a `md`,
+   molduras estruturais a `lg`, e superfícies principais ou modais a `xl`. Essa associação
+   orienta o default, não cria uma restrição semântica. Em aninhamento, evitar moldura dupla e
+   reduzir o raio interno; em grupos conectados, remover os raios das arestas internas. Tamanho
+   e forma permanecem eixos separados; usar `shape="pill"` quando a pílula for intencional.
 8. Testar estados de loading, vazio, erro, sucesso, permissão e interação relevante.
 
 ## Verificação

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

@@ -3,5 +3,9 @@
 - Dispara: “Monte a tela de edição usando a form action do Opus.”
 - Não dispara: “Ajuste o CSS de um e-mail estático.”
 - Execução: implementar uma lista com modal roteável e provar loading, erro, vazio e back.
+- Execução de forma: compor uma tabela dentro de Card sem moldura duplicada, manter a moldura
+  estrutural standalone em `rounded-lg` e os controles internos em `rounded-md`.
 - 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
+  manter cantos arredondados nas arestas internas de um grupo conectado.

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

@@ -8,4 +8,10 @@
 - Superfície semântica e foreground são um par local (`bg-card text-card-foreground`,
   `bg-popover text-popover-foreground`); herança do foreground global não substitui o par.
 - Forma usa a escala `rounded-*`; nome de componente não cria uma segunda escala de radius.
+  Detalhes e itens internos tendem a `xs`/`sm`, controles e flutuantes compactos a `md`,
+  molduras estruturais a `lg`, e superfícies principais ou modais a `xl`. Essa associação é
+  um default visual, não uma restrição semântica.
+- Superfície aninhada evita moldura dupla e normalmente usa um degrau abaixo do contêiner.
+  Grupos conectados removem os raios internos. O tamanho do controle não muda sua forma;
+  `shape="pill"` declara a pílula quando ela for intencional.
 - Catálogo e API efetivos vêm dos exports da versão instalada, não de memória ou exemplo antigo.

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

@@ -3,7 +3,8 @@
  *
  * Padroniza o que toda página repete: <main> + container de largura CHEIA (o caso
  * comum do back-office; quem quiser estreito passa `className="max-w-5xl"`) + header
- * (título, descrição e a ação à direita — em geral o botão de criar). O conteúdo é
+ * (título, descrição e ações à direita, alinhadas ao fim desse bloco — em geral o botão
+ * de criar). O conteúdo é
  * children, sem nada imposto. Presentacional (sem contrato) de propósito: uma página
  * agrega N fontes; o que é action-driven mora dentro (ActionList, listas query-backed).
  */
@@ -17,7 +18,7 @@ export interface PageProps {
   count?: number
   /** Linha de contexto sob o título. */
   description?: ReactNode
-  /** Ação à direita do header — em geral o botão de criar. */
+  /** Ações à direita do header, alinhadas ao fim do bloco de contexto. */
   actions?: ReactNode
   /** Classes do container. Default: largura cheia; `max-w-5xl` estreita e centra. */
   className?: string
@@ -28,16 +29,22 @@ export function Page({ title, count, description, actions, className, children }
   return (
     <main data-slot="page" className="min-w-0 flex-1">
       <div className={cn('mx-auto px-8 py-8', className)}>
-        {/* As ações alinham com o TÍTULO; a descrição vem abaixo, em linha própria. */}
+        {/* As ações acompanham o fim do contexto, mesmo quando há uma descrição sob o título. */}
         <div data-slot="page-header" className="mb-6">
-          <div className={cn(actions !== undefined && 'flex items-center justify-between gap-4')}>
-            <h1 className="flex items-baseline gap-2 text-2xl font-semibold tracking-tight">
-              {title}
-              {count !== undefined && <span className="font-mono text-base text-muted-foreground/60">{count}</span>}
-            </h1>
-            {actions}
+          <div className={cn(actions !== undefined && 'flex items-end justify-between gap-4')}>
+            <div data-slot="page-heading" className="min-w-0">
+              <h1 className="flex items-baseline gap-2 text-2xl font-semibold tracking-tight">
+                {title}
+                {count !== undefined && <span className="font-mono text-base text-muted-foreground/60">{count}</span>}
+              </h1>
+              {description !== undefined && <p className="mt-1 text-sm text-muted-foreground">{description}</p>}
+            </div>
+            {actions !== undefined && (
+              <div data-slot="page-actions" className="flex shrink-0 items-center gap-4">
+                {actions}
+              </div>
+            )}
           </div>
-          {description !== undefined && <p className="mt-1 text-sm text-muted-foreground">{description}</p>}
         </div>
         {children}
       </div>

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

@@ -21,10 +21,13 @@ divergência declarada), pra valer pra casa toda.
 :root {
   --primary: hsl(262 83% 58%); /* A cor da marca do projeto. */
   --ring: hsl(262 83% 58%);
-  --radius: 0.5rem;            /* Cantos mais retos, se for a praia do projeto. */
+  --radius: 0.5rem;            /* Uma base menor deixa toda a escala mais contida. */
 }
 ```
 
+O Opus deriva de `rounded-xs` a `rounded-2xl` dessa base. Assim, a marca muda a presença dos
+cantos sem substituir as utilities escolhidas pelos componentes nem criar tokens por papel.
+
 ## 2 · className em tudo
 
 > Todo componente termina em `cn(base, className)` com tailwind-merge: o utilitário do consumidor

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

@@ -1,6 +1,10 @@
 ## Esqueleto de página
 
-O que toda página do back-office repete, num pattern só: `<main>` + container de largura cheia (o caso comum; `className="max-w-5xl"` estreita e centra) + header com título, descrição e a ação à direita. O conteúdo é children, sem nada imposto. Presentacional de propósito — uma página agrega N fontes; o que é action-driven (listas, forms) mora dentro.
+Use `Page` para manter título, contexto, ações e conteúdo no mesmo ritmo visual nas telas do
+back-office. As ações ficam à direita e acompanham a base do conjunto formado pelo título e pela
+descrição. O componente ocupa a largura disponível; passe `className="max-w-5xl"` quando a tela
+pedir conteúdo mais estreito e centralizado. A área abaixo do cabeçalho permanece livre para
+tabelas, cards ou outras composições.
 
 ```tsx preview col
 render(
@@ -8,6 +12,7 @@ render(
     <Page
       title="Workspaces"
       count={3}
+      description="Ambientes compartilhados pela equipe."
       actions={
         <Button>
           <Plus /> Novo workspace
@@ -29,6 +34,6 @@ render(
 | `title` | `string` | | O h1 da página. |
 | `count` | `number` | | Total de itens ao lado do título (mono, esmaecido). |
 | `description` | `ReactNode` | | Linha de contexto sob o título (ex.: "N no total · X ativos"). |
-| `actions` | `ReactNode` | | Ação à direita do header — em geral o botão de criar. |
+| `actions` | `ReactNode` | | Ações à direita do cabeçalho, alinhadas à base do título e da descrição. |
 | `className` | `string` | largura cheia | Classes do container (`max-w-5xl` estreita e centra). |
 | `children` | `ReactNode` | | O conteúdo — espaçamento e diagramação são seus. |

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

@@ -109,19 +109,21 @@ render(
 
 ## Radius
 
-> Escala mapeada no `@theme inline` preservando o sentido pré-v4 dos utilitários `rounded-*`
-> (neutraliza o rename do Tailwind v4). Componentes e superfícies usam diretamente essa
-> escala: a forma não cria uma segunda taxonomia por componente. A identidade por app
-> sobrescreve `--radius` e escala tudo junto.
+> A escala mapeada no `@theme inline` preserva o sentido pré-v4 dos utilitários `rounded-*`
+> e mantém uma progressão contínua de `xs` a `2xl`. Componentes e superfícies escolhem um
+> degrau pela escala visual; a forma não cria uma segunda taxonomia por componente. A
+> identidade por app sobrescreve `--radius` e move esses degraus em conjunto.
 
 ```tsx preview
 render(
   <div className="flex flex-wrap gap-4">
     {[
+      ['rounded-xs', 'radius − 6px'],
       ['rounded-sm', 'radius − 4px'],
       ['rounded-md', 'radius − 2px'],
-      ['rounded-lg', 'radius (0.625rem)'],
+      ['rounded-lg', 'radius (0.75rem)'],
       ['rounded-xl', 'radius + 4px'],
+      ['rounded-2xl', 'radius + 8px'],
     ].map(([cls, calc]) => (
       <div key={cls} className="flex items-center gap-3">
         <div className={'h-12 w-12 border-2 border-foreground/30 bg-muted ' + cls} />
@@ -144,7 +146,9 @@ render(
    valores acompanham o upstream, só o formato difere.
 2. Elevação no dark: `--card`/`--popover` ficam ACIMA de `--background` (10% vs 3.9%) — identidade
    da casa; dialog e card "sobem" da página de verdade.
-3. Radius mapeado (sm/md/lg/xl) preservando o sentido pré-v4 dos utilitários `rounded-*`.
+3. Radius mapeado (`xs` a `2xl`) preservando o sentido pré-v4 dos utilitários `rounded-*`. Esse
+   trecho derivado permanece monotônico quando a base muda; aplicações que também usam `3xl`
+   precisam revisar a transição para esse degrau nativo ao customizar `--radius`.
 
 4. Escala `shadow-*` recomposta em duas camadas claras e difusas — preserva os degraus do
    Tailwind e troca somente o peso visual. Os aliases antigos por papel foram removidos;
@@ -153,6 +157,11 @@ render(
 5. Bordas mais leves no light: `--border`/`--input` em 92.5% (upstream 89.8%) — par do canvas
    quase-branco do body; superfícies elevadas usam essa mesma borda real.
 
+6. Radius base em `0.75rem` — superfícies principais ganham cantos mais presentes sem aproximar
+   controles compactos de modais. A decisão detalhada acompanha o pacote em
+   `docs/radius-scale.md`, com os defaults, o comportamento de superfícies aninhadas e as
+   alternativas descartadas.
+
 ## Identidade por app
 
 > O tema do Opus é a base; cada app sobrescreve as vars pra ter a própria identidade sem forkar componente.

package/src/ui/theme.css

@@ -10,13 +10,15 @@
  *    nossas; os VALORES acompanham o upstream, só o formato difere.
  * 2. Elevação dark: --card/--popover ACIMA de --background (10% vs 3.9%) — identidade
  *    da casa (upstream v4 também elevou; calibramos pelo site deles em 2026-06).
- * 3. Radius mapeado (sm/md/lg/xl em @theme inline) preservando o sentido pré-v4 dos
- *    utilitários `rounded-*` — neutraliza o rename do v4.
+ * 3. Radius mapeado (xs a 2xl em @theme inline) preservando o sentido pré-v4 dos
+ *    utilitários `rounded-*` — neutraliza o rename do v4 e mantém a escala monotônica.
  * 4. Escala shadow-* recomposta diretamente em duas camadas claras, difusas e com spread
  *    negativo — preserva inclusive modifiers como `shadow-lg/30` (ver docs/elevation-scale.md).
  * 5. Bordas mais leves no light: --border/--input em 92.5% (upstream 89.8%) — par do
  *    canvas quase-branco; superfícies elevadas usam a mesma borda real dos demais papéis.
- * Tudo o mais (escala neutra, radius base 0.625rem, semânticas) segue o upstream.
+ * 6. Radius base em 0.75rem — identidade mais arredondada; os componentes continuam usando
+ *    diretamente a escala Tailwind, sem tokens por papel (ver docs/radius-scale.md).
+ * Tudo o mais (escala neutra, semânticas) segue o upstream.
  */
 @import 'tailwindcss';
 @import 'tw-animate-css';
@@ -50,7 +52,7 @@
   /* Ring de foco LEVE (pedido da casa): aro sutil, não um halo. Com ring-[3px] + /50,
      ~86% encosta na borda (89.8%) — um sussurro de foco. */
   --ring: hsl(0 0% 86%);
-  --radius: 0.625rem;
+  --radius: 0.75rem;
 }
 
 .dark {
@@ -132,10 +134,12 @@
   --color-input: var(--input);
   --color-ring: var(--ring);
 
+  --radius-xs: calc(var(--radius) - 6px);
   --radius-sm: calc(var(--radius) - 4px);
   --radius-md: calc(var(--radius) - 2px);
   --radius-lg: var(--radius);
   --radius-xl: calc(var(--radius) + 4px);
+  --radius-2xl: calc(var(--radius) + 8px);
 
   /* Escala Tailwind, com receita direta para o compilador preservar modifiers `/opacity`.
      `light-dark()` mantém o peso adequado em cada tema sem uma variável intermediária. */