@codenhub/styles 0.6.0 → 0.8.0

package/docs/pt-BR/accessibility.md

@@ -0,0 +1,169 @@
+---
+title: Acessibilidade
+description: O que o CSS faz por foco, estados, movimento, contraste, cores forçadas e texto da direita para a esquerda, e o que a sua aplicação ainda deve aos seus usuários.
+order: 5
+source: 88ce6c4707ee04ac76cdb5e6b31dcca399a5327e
+---
+
+# Acessibilidade
+
+A tela de configurações está pronta, e o CSS fez a sua parte no caminho: todo campo mostra onde está o foco, um email inválido fica vermelho e o spinner para para usuários que pedem menos movimento. O resto depende do seu HTML e JavaScript. Este pacote estiliza estados; ele não fornece elementos semânticos, atributos ARIA, comportamento de teclado, gerenciamento de foco, validação nem o momento dos anúncios.
+
+Esta página lista as duas metades: o que o CSS fornece e o que a sua aplicação precisa adicionar.
+
+## Fornecido pelo CSS
+
+### Foco e estado
+
+| Recurso                         | Comportamento                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `:focus-visible`                | Um outline de foco em todo elemento, desenhado com `--focus-ring`, `--focus-ring-width` e `--focus-ring-offset`. Num componente com preenchimento acima da metade da intensidade, como um botão `.solid.primary`, uma linha de 2px da cor da página corre por dentro do anel, então o anel continua visível sobre um preenchimento da mesma cor.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Foco em controles de formulário | `.ipt`, `.textarea` e `.select` desenham o outline de foco e mudam a borda para a cor da intenção. O texto digitado num campo com classe de intenção fica no tom legível da intenção, `--intent-strong`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| Controles inválidos             | `aria-invalid="true"` num controle de formulário deixa a borda, a cor de foco e o texto digitado na cor destrutiva, com o texto no tom legível destrutivo. Um checkbox, radio ou switch é desenhado exatamente como a sua versão `.destructive`, marca de seleção incluída.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Controles desabilitados         | `disabled`, `aria-disabled="true"`, `data-disabled` e `.disabled` mostram o cursor e a opacidade de desabilitado, e um controle desabilitado não reage ao hover, inclusive dentro de um `.input-group`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Estado aberto                   | `data-state="open"` num `.tooltip` mostra o balão sem hover nem foco, e `data-state="closed"` o esconde durante o hover ou o foco. Nenhum outro componente lê nenhum dos dois.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `<dialog>` nativo               | Um `<dialog>` com `.card`, `.panel`, `.surface` ou uma classe sua que faz `@apply surface` fica escondido até ser aberto, e abre centralizado. Uma margem que você define no dialog, como utilitário ou no seu próprio CSS, ainda substitui a centralização, exceto que um utilitário de margem não substitui quando a sua classe aplica `surface` em CSS simples; veja [Personalização → Helpers de composição](./usage/customizing.md#helpers-de-composição). Com a [folha de estilos sem classes](./setup.md#html-sem-classes), um `<dialog>` puro é um `.card.floating` e se comporta do mesmo jeito; com os outros entrypoints, um dialog sem nenhuma dessas classes não é afetado. Prender o foco, fechar com Escape e tornar inerte a página por trás ficam por conta da sua aplicação. |
+
+### Conteúdo visualmente oculto
+
+`.visually-hidden` esconde o conteúdo na tela e o mantém para leitores de tela, como faz a `<caption>` da tabela de chaves de API em [Conteúdo e layout → Tabelas](./usage/content-and-layout.md#tabelas). Ela vem com os utilitários de layout: em `.`, `./native`, `./tw`, `./tw/native` e `./tw/utilities`. Ela não está em `./components` nem nos entrypoints de componentes `./tw/components` e `./tw/*`.
+
+### Limites dos controles
+
+O WCAG 1.4.11 pede que o limite de um controle que você precisa ver para usá-lo tenha um contraste de pelo menos 3:1 em relação ao que está ao lado dele.
+
+| Recurso                           | Comportamento                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Controles de texto em repouso     | A borda de um controle de texto fica, em repouso, mais clara que a borda cheia da sua intenção, abaixo de 3:1 por escolha, para que o hover e o foco tenham um tom mais forte para onde mudar. [Contraste aumentado](#contraste-aumentado) a desenha cheia.                                                                                                                                                                                                                                           |
+| Toggles                           | `.checkbox`, `.radio` e `.switch` desenham a borda cheia, porque a borda é a única coisa que mostra uma caixa desmarcada. Um `.switch` com o seu próprio `.edgeless` é a exceção, abaixo.                                                                                                                                                                                                                                                                                                             |
+| `.edgeless` vindo de um contêiner | Ignorado por todo controle de texto e toggle: um contêiner não pode remover a borda de um campo ou toggle dentro dele.                                                                                                                                                                                                                                                                                                                                                                                |
+| `.edgeless` no próprio controle   | `.ipt`, `.textarea`, `.select` e `.switch` perdem a borda e deixam de atender ao 1.4.11 em repouso. `.switch.ghost` mantém a borda mesmo assim, porque, sem preenchimento e sem borda, nada mostraria o trilho.                                                                                                                                                                                                                                                                                       |
+| `.checkbox`, `.radio`             | Sempre desenham a borda, venha o `.edgeless` de um contêiner ou deles mesmos. `.edgeless` neles não é suportado.                                                                                                                                                                                                                                                                                                                                                                                      |
+| Trilho de progresso               | Por escolha, a parte preenchida carrega o valor e o trilho é um fundo discreto. O trilho padrão, `.soft.edgeless`, mede cerca de 1.1:1 a 1.3:1 em relação à página. A parte preenchida mede pelo menos 3:1 em relação a esse trilho em todas as intenções, exceto warning no claro (cerca de 2.7:1) e info no escuro (cerca de 2.9:1). Onde o próprio trilho precisa atender ao 1.4.11, use `.ghost.edged` com uma classe de intenção; veja [Contornos de progresso](#contornos-de-progresso) abaixo. |
+
+### Contornos de progresso
+
+Num `.progress.ghost.edged`, o trilho é a página, e o seu contorno e a parte preenchida são desenhados na cor da intenção. Medido em relação à página, sem estética:
+
+| Intenção       | Página clara | Página escura | Atende a 3:1                                                             |
+| -------------- | ------------ | ------------- | ------------------------------------------------------------------------ |
+| `.primary`     | 18.96:1      | 18.96:1       | Sim                                                                      |
+| `.secondary`   | 7.47:1       | 7.63:1        | Sim                                                                      |
+| `.success`     | 5.14:1       | 3.69:1        | Sim                                                                      |
+| `.warning`     | 3.06:1       | 6.20:1        | Sim                                                                      |
+| `.destructive` | 5.80:1       | 3.27:1        | Sim                                                                      |
+| `.info`        | 6.17:1       | 3.07:1        | Sim                                                                      |
+| Sem intenção   | 2.48:1       | 1.91:1        | Não: o contorno falha, embora a parte preenchida, na cor do texto, passe |
+
+Sem classe de intenção, o contorno é o cinza de borda discreto, `--color-border`. Para que um trilho neutro atenda ao 1.4.11, dê uma classe de intenção à barra, ou defina `--progress-edge` com uma cor mais forte, como `var(--color-accent)`, que mede 7.47:1 numa página clara e 7.63:1 numa escura. Warning numa página clara e info numa escura passam de 3:1 por pouco, então meça de novo se você mudar essas cores.
+
+### Movimento e transparência
+
+| Recurso                            | Comportamento                                                                                                                                                                                                                                                                                                                                                         |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Movimento reduzido, componentes    | Com `prefers-reduced-motion: reduce`, todo componente para as suas próprias transições e animações: o brilho do skeleton e do progresso, a barra indeterminada, o tooltip, as marcas dos toggles e o movimento do clique. O clique em si ainda acontece, de imediato, no visual padrão e sob toda estética e classe solo, porque é o sinal de que ele foi registrado. |
+| Movimento reduzido, página inteira | O reset também encurta todas as outras animações e transições da página.                                                                                                                                                                                                                                                                                              |
+| Transparência reduzida             | Com `prefers-reduced-transparency: reduce`, e em cores forçadas, `.glass`, `.glass-liquid` e `.glass-solo` perdem o desfoque e a lente e ficam opacos.                                                                                                                                                                                                                |
+
+A regra de movimento reduzido de cada componente vem com o componente, então todo entrypoint que o inclui respeita o movimento reduzido sem o reset, incluindo `@codenhub/styles/components`, `@codenhub/styles/tw/components` e cada entrypoint de componente `/tw/*`. Os entrypoints completos e nativos adicionam a regra do reset para a página inteira.
+
+A regra do reset é `!important` dentro da camada `base`, e um `!important` com camada vence um sem camada, então o seu próprio `!important` não consegue religar uma animação. Para manter uma rodando para usuários que pedem movimento reduzido, como um spinner de upload que você considera essencial, declare-a `!important` numa camada ordenada antes de `base`. A primeira declaração `@layer` que o navegador lê define a ordem, então a sua vem antes do pacote:
+
+```css
+@layer essential-motion, theme, base, components, utilities;
+@import "@codenhub/styles";
+
+@layer essential-motion {
+  @media (prefers-reduced-motion: reduce) {
+    .upload-spinner {
+      animation-duration: 1s !important;
+      animation-iteration-count: infinite !important;
+    }
+  }
+}
+```
+
+Respeitar o movimento reduzido não é o requisito inteiro. Um movimento que continua ao lado do conteúdo, como um brilho deixado num card depois que ele carregou, precisa de uma forma de ser parado por qualquer usuário; veja [Feedback → Animação que não para](./usage/feedback.md#animação-que-não-para).
+
+### Contraste aumentado
+
+Com `prefers-contrast: more`, as bordas que o pacote desenha abaixo de 3:1 por escolha são desenhadas a 3:1 ou mais em relação ao que está ao lado, nos dois temas. O texto, os preenchimentos sólidos e os anéis de foco já atendem às suas proporções e não mudam. `prefers-contrast: less` não é lido.
+
+| Recurso             | Comportamento                                                                                                                                                                                                                                                                         |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Controles de texto  | `.ipt`, `.textarea`, `.select` e `.input-group` ficam em repouso com a borda cheia, então o hover e o foco não mudam mais o tom dela. O anel de foco é o mesmo.                                                                                                                       |
+| Bordas neutras      | `--color-border` assume um cinza mais forte, `neutral-600` no claro e `neutral-400` no escuro, então a borda de um card, um divisor, as linhas de uma tabela e a borda de um botão ou badge neutro atendem a 3:1. Se você mesmo define `--color-border`, a sua cor é mantida; meça-a. |
+| Bordas de intenção  | A borda de uma intenção assume o tom forte dela, `--color-<intent>-strong`, então `.edged` num `.alert`, `.panel`, `.badge`, `.kbd`, `.code` ou `.pre` `.soft` atende a 3:1 tanto em relação ao preenchimento quanto à página, em todas as intenções.                                 |
+| Trilho de progresso | O trilho desenha um contorno na sua cor de borda, que atende a 3:1 com ou sem classe de intenção. `.edgeless` na barra ou em um contêiner continua removendo o contorno.                                                                                                              |
+| Glass               | `.glass`, `.glass-liquid` e `.glass-solo` perdem o desfoque e a lente e ficam opacos, como na transparência reduzida, e a linha branca deles vira uma borda cinza.                                                                                                                    |
+| Chunky tile         | `.chunky-tile` desenha as peças e as superfícies com o cinza mais forte que os seus controles usam.                                                                                                                                                                                   |
+
+O que você remove continua removido: `.edgeless` num controle continua tirando a borda dele, e um `.panel` continua sem borda a menos que você adicione `.edged`.
+
+### Cor e contraste
+
+As medições abaixo são das cores entregues. Assim que você mudar um token de cor, meça de novo os seus próprios pares; [Temas → Mude a cor da marca](./usage/theming.md#mude-a-cor-da-marca) mostra quais pares conferir.
+
+| Recurso                       | Comportamento                                                                                                                                                                                                                                                                                                                                      |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Rótulos preenchidos           | O rótulo `.solid` de toda intenção atende a 4.5:1 (WCAG 1.4.3) como texto normal, nos dois temas. O menor é success, com 5.14:1.                                                                                                                                                                                                                   |
+| Texto em warning              | `--color-warning-contrast` é quase preto, e não a cor da página, porque um âmbar escuro o bastante para carregar texto branco deixa de parecer âmbar.                                                                                                                                                                                              |
+| Preenchimentos parciais       | A cor de texto de contraste só aparece em preenchimentos acima da metade da força, então o preenchimento limitado de um controle de texto mantém a cor de texto da própria intenção.                                                                                                                                                               |
+| Cor da intenção no escuro     | No modo escuro, um rótulo `.soft` ou `.ghost` usa o tom `-300` da sua intenção, para manter o matiz em vez de ficar branco.                                                                                                                                                                                                                        |
+| Texto sobre um pai preenchido | Um componente neutro que não é `.solid`, como um badge num `.btn.primary` ou um botão ghost num `.card.solid.primary`, imprime na cor de texto do pai em vez da cor da página, então mantém o contraste do pai.                                                                                                                                    |
+| Impressão                     | Uma página é impressa no tema claro, e componentes preenchidos imprimem o fundo (`print-color-adjust: exact`), então o texto de contraste nunca cai sobre o papel em branco. Um utilitário `dark:` continua valendo na impressão; veja [Temas → Impressão](./usage/theming.md#impressão).                                                          |
+| Marcas dos toggles            | Uma marca de marcado mede pelo menos 3:1 em relação a todo preenchimento que a sua apresentação pode dar a ela, nos dois temas.                                                                                                                                                                                                                    |
+| Preenchimentos soft com borda | `.edged` num `.alert`, `.panel`, `.badge`, `.kbd`, `.code` ou `.pre` `.soft` desenha uma borda que mede menos de 3:1 em relação ao preenchimento de 12% em algumas intenções, que variam conforme o tema. Meça o par antes de contar com essa borda como limite de um controle. [Contraste aumentado](#contraste-aumentado) leva todas elas a 3:1. |
+
+### Cores forçadas e direção
+
+| Recurso          | Comportamento                                                                                                                                                                                                                                                                                                                                                                               |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Cores forçadas   | Com `forced-colors: active`, as bordas, os estados marcados, a seta de um `.select` e o valor de uma barra de progresso continuam visíveis, desenhados nas cores do sistema, sob todas as estéticas. Uma estética que desenha a borda como sombra interna, como `.pixel`, desenha uma borda real no lugar. O glass fica opaco, porque as cores forçadas mantêm a transparência de um fundo. |
+| Direção do texto | Sob `dir="rtl"`, a barra da citação, o ícone do alerta, o preenchimento do progresso, o divisor vertical, o botão do switch, o alinhamento das tabelas e a seta de um select trocam de lado. Nenhuma classe é necessária.                                                                                                                                                                   |
+
+Em cores forçadas, `.text-control`, `.ipt`, `.textarea`, `.select`, os toggles e uma classe sua que faz `@apply text-control` mostram um outline de foco `Highlight` de 2px. Dentro de um `.input-group`, o grupo desenha o anel do campo e o controle dentro dele não desenha nenhum, então um campo focado mostra um único anel. O entrypoint nativo dá o mesmo outline a campos de texto, selects, textareas, checkboxes e radios sem classe.
+
+Checkboxes, radios e switches usam as cores do sistema `Canvas`, `CanvasText`, `Highlight` e `HighlightText`, para que marcado e desmarcado continuem distintos: um toggle marcado é preenchido com `Highlight` e a sua marca é `HighlightText`, tanto nas classes quanto no entrypoint nativo. Formato, tamanho e espaçamento não mudam.
+
+Uma barra `.progress` faz o mesmo: a parte preenchida é `CanvasText` sobre um trilho `Canvas` com contorno `CanvasText`, qualquer que seja a intenção ou a apresentação, para que uma barra pela metade não pareça vazia. O brilho de `.active` não é desenhado.
+
+## O que fica fora do CSS
+
+Use o elemento HTML que corresponde ao que o componente faz e adicione o comportamento que o CSS não consegue.
+
+| Interface          | O que a sua aplicação adiciona                                                                                                                                                                                                             |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Botões             | `<button>` para ações e `<a href>` para navegação. Um nome acessível, como `aria-label`, em todo `.btn.icon`.                                                                                                                              |
+| Formulários        | Um `<label>` para cada controle, o `type` certo, validação e `aria-describedby` ligando dicas e erros. Mantenha dicas e erros fora do `<label>` e dê `role="switch"` a um `.switch`.                                                       |
+| Alertas            | `role="status"` para uma confirmação como "Profile saved", ou `role="alert"` para um erro que precisa de atenção imediata.                                                                                                                 |
+| Toasts             | Uma live region, uma forma de dispensá-lo, regras de foco e uma pausa em qualquer tempo limite.                                                                                                                                            |
+| Tooltips           | Um `id` real e `role="tooltip"` no balão, referenciado pelo `aria-describedby` do gatilho. Dispensa com Escape escrevendo `data-state="closed"`; veja [Tooltips](./usage/tooltips.md#hover-permanência-e-escape). O balão já aceita hover. |
+| Progresso          | Um elemento `<progress>`, ou `role="progressbar"` ou `role="meter"` com valores ARIA, quando o valor precisa ser anunciado.                                                                                                                |
+| Skeletons          | `aria-hidden="true"` nos visuais de carregamento, incluindo um spinner que você traga, e o estado de carregamento anunciado de outra forma quando necessário.                                                                              |
+| Movimento contínuo | Uma forma de pausar, parar ou esconder o movimento que não é essencial; veja [Feedback → Animação que não para](./usage/feedback.md#animação-que-não-para).                                                                                |
+| Popovers, modais   | Prender o foco, fechar com Escape, um fundo inerte, rótulos e roles.                                                                                                                                                                       |
+
+## Atributos de estado
+
+Prefira os atributos nativos:
+
+```html
+<button class="btn primary" disabled>Saving…</button> <input class="ipt" type="email" aria-invalid="true" aria-describedby="email-error" />
+```
+
+Use atributos ARIA ou data onde o elemento ou a sua biblioteca de componentes não tem um nativo:
+
+```html
+<a class="btn secondary" aria-disabled="true">Export data</a>
+<span class="tooltip" data-state="open">
+  <button type="button" class="tooltip-icon" aria-label="About public profiles" aria-describedby="public-profile-help">?</button>
+  <span class="tooltip-bubble" role="tooltip" id="public-profile-help">Anyone with the link can see your name and photo.</span>
+</span>
+```
+
+`aria-disabled="true"` informa às tecnologias assistivas que o controle está desabilitado, mas não impede um clique nem o pressionar de uma tecla. Use o atributo `disabled`, ou interrompa a ação no JavaScript.
+
+## A seguir
+
+Isso completa a ordem de leitura. A [Introdução](./index.md) tem links para todas as páginas, e [Composição](./usage/composing.md), [Personalização](./usage/customizing.md) e [Conteúdo e layout](./usage/content-and-layout.md) são as páginas de consulta para depois.

package/docs/pt-BR/concepts.md

@@ -0,0 +1,212 @@
+---
+title: Montando uma tela
+description: Organize o layout da página de configurações, defina a tipografia e adicione cards e botões enquanto aprende intenção, preenchimento, borda e estética.
+order: 3
+source: 8fa5ed2f6fb9a2786f61301f94bbe806649d7e1d
+---
+
+# Montando uma tela
+
+Esta página transforma a estrutura vazia da [Configuração](./setup.md) na primeira parte de verdade da tela de configurações: um cabeçalho de página, um card de perfil com os botões de salvar e cancelar, e um resumo do plano ao lado de um card de uso. No caminho, ela apresenta as três escolhas que todo componente faz, intenção, apresentação e estética, no momento em que a tela precisa de cada uma. Todo o resto desta documentação se apoia nesse modelo.
+
+## A menor tela possível
+
+Um cabeçalho de página e um card com um botão:
+
+```html
+<main class="section">
+  <div class="section-content narrow stack">
+    <h1 class="text-title">Account settings</h1>
+    <section class="card stack">
+      <h2 class="text-title-sm">Profile</h2>
+      <p>Your name appears on invoices and shared projects.</p>
+      <button class="btn primary" type="button">Save changes</button>
+    </section>
+  </div>
+</main>
+```
+
+Cada classe faz uma coisa só:
+
+- `.section` dá espaçamento à página: uma margem lateral responsiva (de 1 a 2rem) e um espaço generoso acima e abaixo (de 4 a 7rem).
+- `.section-content` centraliza uma coluna com largura máxima; `.narrow` faz essa largura ser 48rem em vez de 80rem, uma largura confortável para um formulário.
+- `.stack` empilha os filhos na vertical com um espaçamento de 1rem.
+- `.text-title` e `.text-title-sm` definem tamanhos de título: 1.875rem em negrito e 1.25rem em seminegrito.
+- `.card` é um contêiner com borda, cantos arredondados e 1.25rem de padding.
+- `.btn` cria um botão, e `.primary` dá a ele a cor primária.
+
+Os títulos não são dimensionados pela tag: o reset dá a um `<h1>` sem classe de tipografia o mesmo tamanho e peso do texto ao redor. Isso mantém a estrutura do documento, ou seja, qual o nível de título de um elemento, separada do tamanho com que você quer que ele apareça. Se quiser títulos estilizados automaticamente, veja [Configuração → HTML sem classes](./setup.md#html-sem-classes).
+
+## Organize o layout da página
+
+Três utilitários de layout cobrem a maioria das telas, e os três usam o mesmo espaçamento, `--layout-gap` (1rem):
+
+- `.stack` para listas verticais de blocos.
+- `.cluster` para uma linha que quebra quando acaba o espaço, como um grupo de botões. Adicione `.between` para empurrar o primeiro e o último itens para as extremidades opostas.
+- `.auto-grid` para um grid de cards iguais que ganha ou perde colunas conforme o espaço muda. Uma coluna nunca fica mais estreita que `--layout-grid-min` (16rem), a menos que o próprio contêiner seja.
+
+`.tight` (0.5rem) e `.loose` (1.5rem) mudam o espaçamento do layout em que estão. Um layout aninhado mantém o seu próprio espaçamento.
+
+Adicione um cabeçalho e coloque os botões em linha:
+
+```html
+<main class="section">
+  <div class="section-content narrow stack loose">
+    <header class="stack tight">
+      <h1 class="text-title">Account settings</h1>
+      <p>Manage your profile, plan, and security.</p>
+    </header>
+
+    <section class="card stack" aria-labelledby="profile-title">
+      <h2 class="text-title-sm" id="profile-title">Profile</h2>
+      <p>Your name appears on invoices and shared projects.</p>
+      <div class="cluster">
+        <button class="btn primary" type="button">Save changes</button>
+        <button class="btn ghost" type="button">Cancel</button>
+      </div>
+    </section>
+  </div>
+</main>
+```
+
+[Conteúdo e layout](./usage/content-and-layout.md) lista todos os utilitários de layout, incluindo `.view`, `.divider` e `.visually-hidden`, e a escala tipográfica completa.
+
+## Intenção: qual cor
+
+O botão de salvar é `.primary` e o de cancelar não tem intenção, o que o deixa neutro. Uma classe de intenção escolhe um papel de cor:
+
+| Classe         | Use para                               | Cor padrão                                   |
+| -------------- | -------------------------------------- | -------------------------------------------- |
+| _nenhuma_      | Qualquer coisa sem significado próprio | Os cinzas de texto e de borda da página      |
+| `.primary`     | A ação principal de uma tela           | Quase preto no claro, quase branco no escuro |
+| `.secondary`   | Uma segunda ação, mais discreta        | Cinza médio                                  |
+| `.success`     | Confirmações e estados concluídos      | Verde esmeralda                              |
+| `.warning`     | Algo que precisa de atenção em breve   | Âmbar, com texto escuro                      |
+| `.destructive` | Exclusões, revogações e erros          | Vermelho rosado                              |
+| `.info`        | Avisos neutros e ajuda                 | Índigo                                       |
+
+A intenção fica no elemento que a carrega. Colocar `.destructive` numa `<section>` não deixa vermelhos todos os botões dentro dela; você escreve a classe em cada botão. Isso é proposital: um contêiner que recolorisse silenciosamente tudo o que tem dentro deixaria vermelho também o botão de cancelar de uma zona de perigo vermelha.
+
+`.neutral` declara o padrão explicitamente. Você raramente precisa dela, porque não ter classe de intenção já significa neutro; ela importa onde a cor viria de outro lugar, como numa linha de tabela, que herda a intenção da tabela.
+
+## Apresentação: quanta cor
+
+O botão de cancelar é `.ghost`: sem preenchimento, só o texto colorido, então ele parece menos importante que o de salvar. Esse é o eixo de apresentação, com duas escolhas independentes:
+
+- **Preenchimento:** `.solid` preenche o componente com a cor da intenção e troca o texto para a cor de contraste. `.soft` mistura um tom claro de 12% e mantém o texto na cor da intenção. `.ghost` não tem preenchimento em repouso.
+- **Borda:** `.edged` desenha uma borda na cor da intenção; `.edgeless` não desenha nenhuma.
+
+```html
+<button class="btn primary">Save changes</button>
+<button class="btn primary soft">Preview</button>
+<button class="btn primary ghost edged">Export data</button>
+<button class="btn ghost">Cancel</button>
+```
+
+Todo componente tem o seu próprio padrão quando nenhuma classe de apresentação se aplica. Um botão é sólido e sem borda. Um card não tem preenchimento e tem borda. Um campo de formulário não tem preenchimento e tem borda. [Composição](./usage/composing.md#padrões-dos-componentes) lista o padrão de cada componente.
+
+Diferente da intenção, a apresentação é herdada. Um `.soft` num contêiner deixa tudo dentro dele soft, a menos que um elemento diga o contrário, e uma classe no próprio elemento sempre vence uma herdada de um contêiner:
+
+```html
+<div class="cluster soft">
+  <button class="btn primary">Soft primary</button>
+  <button class="btn success">Soft success</button>
+  <button class="btn primary solid">Solid: its own class wins</button>
+</div>
+```
+
+Alguns componentes limitam o que a apresentação pode fazer, para proteger algo de que precisam. Um campo de formulário que herda de um contêiner `.solid` só é preenchido até 6%, para que o texto digitado continue legível. Um checkbox sempre mantém a borda, porque a borda é a única coisa que mostra uma caixa desmarcada. Esses limites aparecem junto com cada componente e estão reunidos em [Composição](./usage/composing.md).
+
+## Termine a primeira tela
+
+Adicione um resumo do plano ao lado de um card de uso num grid, e dê ao resumo um tom primário soft para que ele se destaque como o estado atual da conta:
+
+```html
+<main class="section">
+  <div class="section-content narrow stack loose">
+    <header class="stack tight">
+      <h1 class="text-title">Account settings</h1>
+      <p>Manage your profile, plan, and security.</p>
+    </header>
+
+    <section class="card stack" aria-labelledby="profile-title">
+      <h2 class="text-title-sm" id="profile-title">Profile</h2>
+      <p>Your name appears on invoices and shared projects.</p>
+      <div class="cluster">
+        <button class="btn primary" type="button">Save changes</button>
+        <button class="btn ghost" type="button">Cancel</button>
+      </div>
+    </section>
+
+    <div class="auto-grid">
+      <section class="card soft primary stack tight" aria-labelledby="plan-title">
+        <h2 class="text-label" id="plan-title">Current plan</h2>
+        <p class="text-title-sm">Team, billed yearly</p>
+        <p class="text-body">Renews on 12 March 2027.</p>
+      </section>
+      <section class="card stack tight" aria-labelledby="usage-title">
+        <h2 class="text-label" id="usage-title">Storage</h2>
+        <p class="text-title-sm">48 GB of 100 GB</p>
+        <p class="text-body">Shared by 6 members.</p>
+      </section>
+    </div>
+  </div>
+</main>
+```
+
+Numa janela larga, os dois cards ficam lado a lado; quando a coluna é estreita demais para duas colunas de 16rem mais o espaçamento entre elas, eles se empilham. A página de [Feedback](./usage/feedback.md) transforma o número do card de armazenamento numa barra de uso.
+
+Um `.card` fica em repouso a uma unidade de profundidade, mas no visual base essa profundidade não tem sombra visível; ela aparece quando uma estética desenha uma ou quando você adiciona `.raised` ou `.floating`. [Composição → Elevação](./usage/composing.md#elevação) trata da profundidade.
+
+## Estética: do que é feito
+
+O terceiro eixo muda o material de tudo o que estiver dentro dele: cantos, espessura de borda, sombras e, às vezes, a fonte. Ele precisa de um import próprio (veja [Configuração → Adicione uma estética](./setup.md#adicione-uma-estética-opcional)):
+
+```html
+<main class="section neobrutalism">
+  <!-- A mesma tela de configurações: cantos retos, linhas escuras grossas, sombras deslocadas e duras -->
+</main>
+```
+
+Assim como a apresentação, uma estética é herdada, e um componente dentro dela pode ter outra. Você não precisa dela para montar a tela; a página de [Estéticas](./usage/aesthetics.md) compara as seis.
+
+## Palavras que esta documentação usa
+
+Algumas páginas descrevem como um componente é pintado. Cada uma destas palavras tem um único significado:
+
+| Palavra              | Significado                                                                                                                                                                               |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Preenchimento (fill) | Quanto da cor da intenção cobre o componente, de 0% (`.ghost`) a 100% (`.solid`).                                                                                                         |
+| Teto (cap)           | O maior preenchimento que um componente permite. Um campo de formulário limita um preenchimento herdado a 6%, por exemplo.                                                                |
+| Placa (plate)        | O fundo pintado do componente: o preenchimento, misturado sobre o chão.                                                                                                                   |
+| Chão (ground)        | A cor sobre a qual o preenchimento é misturado. Normalmente é a própria página que aparece por trás; alguns componentes definem o seu, como o tom claro da intenção sob `.kbd` e `.code`. |
+| Borda (edge)         | O contorno em volta do componente. É diferente das linhas divisórias, as linhas dentro de uma tabela.                                                                                     |
+| Tinta (ink)          | Uma cor usada para desenhar linhas: a borda, as linhas divisórias de uma tabela, a marca de um checkbox. "Tinta do texto" é a cor do texto impresso sobre uma placa.                      |
+| Material             | O que uma estética muda: raio e formato dos cantos, espessura e estilo da borda, sombra e transparência.                                                                                  |
+| Bloco (slab)         | Uma sombra dura, sem desfoque, deslocada para baixo e para um lado, como as que `.neobrutalism` e `.chunky-tile` desenham.                                                                |
+| Elevação             | Quanto da sombra em vigor um elemento recebe: nenhuma (`.flat`), uma unidade (`.raised`) ou duas (`.floating`).                                                                           |
+
+## Os tokens por trás das classes
+
+Toda classe lê custom properties de CSS, chamadas de tokens, então você pode mudar o resultado sem reescrever uma classe:
+
+| Tipo         | Controla                                                                                    | Onde estão listados                                                                      |
+| ------------ | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Cor          | A paleta: cores de intenção, texto, bordas e fundos, para o claro e o escuro.               | [Temas → Tokens de cor](./usage/theming.md#tokens-de-cor)                                |
+| Fundamentais | Larguras e espaçamentos de layout, raios dos cantos, altura dos controles, foco, movimento. | [Temas → Tokens fundamentais](./usage/theming.md#tokens-fundamentais)                    |
+| Intenção     | Os slots de cor que um componente lê depois que uma classe de intenção escolhe um papel.    | [Temas → Tokens de intenção](./usage/theming.md#tokens-de-intenção)                      |
+| Apresentação | As porcentagens de preenchimento e de borda que as classes de apresentação definem.         | [Personalização → Tokens de apresentação](./usage/customizing.md#tokens-de-apresentação) |
+| Material     | Raio, espessura de borda, geometria da sombra e transparência.                              | [Personalização → Tokens de material](./usage/customizing.md#tokens-de-material)         |
+| Estética     | Um ajuste por estética, como `--pixel-unit` ou `--tile-lift`.                               | [Personalização → Tokens de estética](./usage/customizing.md#tokens-de-estética)         |
+
+Os tokens de cor e os fundamentais são o que a maioria das aplicações muda primeiro, para combinar com a marca. Os demais são de nível mais baixo: os componentes os leem, e as classes de apresentação e de estética os definem por você.
+
+## Limites para conhecer desde já
+
+- **A intenção não é herdada.** Escreva-a em cada elemento que a mostra. A única exceção são as linhas de tabela.
+- **As classes são só estilo.** `<div class="btn">` parece um botão, mas não pode receber foco nem ser acionado pelo teclado. Use `<button>` ou `<a href>` e veja [Acessibilidade](./accessibility.md).
+- **Uma combinação que a documentação não descreve não é suportada.** Ela pode até renderizar, mas pode mudar em qualquer versão; veja [Introdução → O que conta como suportado](./index.md#o-que-conta-como-suportado).
+
+## A seguir
+
+A tela tem uma ação primária e uma discreta. [Botões](./usage/buttons.md) acrescenta o resto: uma ação destrutiva para a zona de perigo, botões de ícone, tamanhos e estados desabilitados.

package/docs/pt-BR/index.md

@@ -0,0 +1,105 @@
+---
+title: Introdução
+description: Para que serve o @codenhub/styles, quanto ele custa e em que ordem ler esta documentação.
+source: 5f82b6a4d492bdb5ea73406f256d307f775fa1ea
+---
+
+# @codenhub/styles
+
+O `@codenhub/styles` permite montar uma interface consistente e com suporte a temas escrevendo nomes de classe em HTML puro. Você importa uma folha de estilos e ganha tokens, um reset, utilitários de layout e tipografia, e classes para botões, campos de formulário, alertas, cards, tabelas e tooltips. Não há JavaScript para carregar nem biblioteca de componentes para encapsular: um `<button class="btn primary">` é toda a integração.
+
+Esta documentação monta uma tela pequena do início ao fim: uma página de configurações de conta com um formulário de perfil, um resumo do plano e uma zona de perigo. Cada página acrescenta algo a ela, então no final você terá visto todas as partes do pacote funcionando juntas, e não isoladas.
+
+```html
+<main class="section">
+  <div class="section-content narrow stack">
+    <h1 class="text-title">Account settings</h1>
+    <form class="card stack">
+      <h2 class="text-title-sm">Profile</h2>
+      <div class="field">
+        <label class="label" for="display-name">Display name</label>
+        <input class="ipt" id="display-name" name="display-name" value="Ada Lovelace" />
+      </div>
+      <div class="cluster">
+        <button class="btn primary" type="submit">Save changes</button>
+        <button class="btn ghost" type="reset">Cancel</button>
+      </div>
+    </form>
+  </div>
+</main>
+```
+
+## Três escolhas por componente
+
+Todo componente responde a três perguntas independentes com classes, então um visual novo nunca exige uma nova variante de componente:
+
+- **Intenção: qual cor?** `.primary`, `.secondary`, `.success`, `.warning`, `.destructive` ou `.info`. Sem nenhuma, o componente fica neutro.
+- **Apresentação: quanto dessa cor?** `.solid`, `.soft` ou `.ghost` define o preenchimento; `.edged` ou `.edgeless` define a borda.
+- **Estética: do que ele é feito?** Uma classe opcional, como `.neobrutalism` ou `.glass`, muda cantos, espessura de borda, sombras e tipografia de tudo o que estiver dentro dela.
+
+`<button class="btn destructive ghost edged">Delete account</button>` é um botão vermelho com contorno, e envolver a página em `.pixel` o transforma num botão em pixel art sem mexer no botão. [Montando uma tela](./concepts.md) apresenta cada eixo no momento em que a página de configurações precisa dele.
+
+## CSS compilado ou código-fonte do Tailwind
+
+O pacote entrega as mesmas classes de duas formas:
+
+- **CSS compilado**, pronto para usar. Importe de qualquer bundler ou referencie o arquivo a partir de uma CDN. Você não precisa do Tailwind.
+- **Código-fonte do Tailwind CSS v4**, em `@codenhub/styles/tw`. Use quando o seu projeto já roda Tailwind v4, para que o seu build compile o pacote junto com os seus próprios utilitários e tema.
+
+A [Configuração](./setup.md) ajuda você a escolher.
+
+## O que ele não faz
+
+- **Nada de JavaScript.** Não há runtime, bindings para frameworks nem código gerado. Tudo o que precisa de script, como abrir um dialog, alternar o tema ou dispensar um tooltip, fica por conta do seu código.
+- **Nada de semântica ou comportamento.** As classes pintam elementos; elas não acrescentam semântica de HTML, ARIA, tratamento de teclado, gerenciamento de foco, validação nem anúncios. A página de [Acessibilidade](./accessibility.md) traça a linha exata.
+- **Nada de troca de tema.** Escolher entre claro e escuro é uma classe ou atributo que você define. O pacote separado `@codenhub/theme` pode lembrar e aplicar essa escolha para você.
+- **Nada de fontes ou ícones.** Nenhum arquivo de fonte é baixado. Estéticas que pedem uma fonte especial usam uma fonte do sistema até você fornecer uma. Ícones, incluindo spinners de carregamento, vêm do seu próprio conjunto de ícones, como o `@codenhub/icons`.
+- **Nada de aliases de compatibilidade.** Uma classe ou token removido aparece no changelog, não fica mantido com o nome antigo.
+
+## Trade-offs
+
+Conheça estes custos antes de adotar o pacote:
+
+- **Os nomes de classe são curtos e sem prefixo.** `.primary`, `.success`, `.dark`, `.label`, `.field`, `.section`, `.stack`, `.flat` e `.ghost` são nomes globais. Outra folha de estilos na mesma página que use esses nomes colide com esta. O pacote fica em [camadas de cascata](./setup.md#camadas-de-cascata), então o seu próprio CSS fora de camadas vence uma colisão, mas as regras de uma biblioteca de terceiros para o mesmo nome continuam valendo junto com as do pacote.
+- **As folhas de estilos completas são grandes antes da compressão.** No momento em que este texto foi escrito, minificada, a folha de estilos completa tem cerca de 198 KB, a `/native` cerca de 295 KB e a `/components` cerca de 159 KB. Servidas com gzip, ficam em cerca de 17 KB, 22 KB e 13 KB. Os arquivos específicos são bem menores: `/theme` tem cerca de 12 KB (3 KB com gzip) e cada estética tem de 4 a 14 KB (1 a 2 KB com gzip). A maior parte do tamanho é composição que todo componente repete, e é por isso que a compressão elimina tanto. Um arquivo compilado traz todas as classes, a página usando ou não. Para entregar só as classes que as suas páginas usam, compile o pacote no seu próprio build: pelo [Tailwind CSS v4](./integrating/tailwind.md) quando o projeto o usa, ou com o [comando `build`](./integrating/without-a-bundler.md#gere-só-as-classes-que-você-usa) do pacote em qualquer outro projeto. Assim, uma página com um botão recebe de 26 a 28 KB minificados, e cerca de 6 KB com gzip. Fora isso, importe o entrypoint mais restrito que cubra a página; veja [Configuração → Todos os entrypoints](./setup.md#todos-os-entrypoints).
+- **`--color-foreground` é um fundo, não uma cor de texto.** É o tom um passo distante da página, sobre o qual fica um card ou painel discreto. A cor do texto é `--color-text`.
+- **Quatro cores de hover são valores fixos.** `--color-success-hover`, `--color-warning-hover`, `--color-destructive-hover` e `--color-info-hover` são pré-calculadas, porque misturá-las em tempo real travava o WebKit. Se você sobrescrever só `--color-success`, o hover dela mantém o tom antigo, então substitua a família inteira; veja [Temas → Tokens de cor](./usage/theming.md#tokens-de-cor).
+- **Só navegadores modernos.** Chrome 123, Safari 17.5 ou Firefox 128 e mais recentes. Não há camada de fallback para navegadores mais antigos.
+
+## O que conta como suportado
+
+Uma combinação de classes é suportada quando esta documentação a descreve e a demo pública em [demo.codenhub.dev/styles](https://demo.codenhub.dev/styles/) a mostra. A demo renderiza as fixtures de teste do pacote, incluindo as matrizes completas de intenção, apresentação e estética, usando o CSS gerado pelo build. Uma combinação que não está documentada nem aparece na demo pode até gerar CSS, mas não é mantida e pode mudar em qualquer versão.
+
+A demo é reconstruída a partir da branch main, não a cada versão. Ela pode mostrar trabalho ainda não lançado, então, quando a demo e esta documentação discordarem sobre uma versão já lançada, valem a documentação e o [changelog](../changelog/index.md) daquela versão.
+
+## Versionamento
+
+O pacote está abaixo da 1.0 e segue a [regra do versionamento semântico para versões 0.x](https://semver.org/lang/pt-BR/#spec-item-4): a superfície pública ainda pode mudar entre versões minor.
+
+- Uma versão minor, como da 0.7.0 para a 0.8.0, pode quebrar compatibilidade. Ela pode renomear ou remover uma classe ou token, ou mudar um padrão. Toda quebra é listada em **Changed** ou **Removed** na página do [changelog](../changelog/index.md) daquela versão, com o que usar no lugar.
+- Uma versão patch, como da 0.7.0 para a 0.7.1, nunca quebra.
+
+O range padrão do npm para uma dependência nova, `^0.7.0`, já aceita apenas patches, porque abaixo da 1.0 um range com circunflexo não avança para a próxima versão minor. Leia o changelog antes de subir esse range. Ao referenciar um arquivo de uma CDN, coloque a versão exata na URL; veja [Sem bundler](./integrating/without-a-bundler.md).
+
+As quebras não são amenizadas com aliases porque o modelo ainda está se assentando, e manter cada nome antigo ao lado do substituto aumentaria a superfície a cada versão. Uma renomeação ou remoção costuma custar um localizar-e-substituir quando você atualiza; um padrão alterado pode exigir que você reajuste o seu próprio CSS.
+
+## Ordem de leitura
+
+Na primeira vez, leia nesta ordem. Cada página acrescenta algo à tela de configurações e termina indicando a próxima.
+
+1. [Configuração](./setup.md): instale o pacote, escolha entre CSS compilado ou código-fonte do Tailwind e renderize a estrutura vazia da página.
+2. [Integração](./integrating/index.md): só se você usa Next.js, Vue, Svelte, Astro, Tailwind v4 ou nenhum bundler. Cada guia devolve você ao caminho principal.
+3. [Montando uma tela](./concepts.md): organize o layout da página, defina a tipografia e adicione um card e um botão de salvar, aprendendo intenção, preenchimento e borda pelo caminho.
+4. [Uso](./usage/index.md): o resto da tela, nesta ordem:
+   - [Botões](./usage/buttons.md): ações secundárias e destrutivas, tamanhos, botões de ícone e estados desabilitados.
+   - [Formulários](./usage/forms.md): campos com rótulo, dicas, erros, ícones, selects, checkboxes, radios e switches.
+   - [Feedback](./usage/feedback.md): um estado de salvamento, um alerta de sucesso, um badge de plano, um placeholder de carregamento e uma barra de uso.
+   - [Tooltips](./usage/tooltips.md): ajuda de campo que funciona com mouse, teclado e leitor de tela.
+   - [Temas](./usage/theming.md): modo claro e escuro, cores da marca e suas próprias intenções.
+   - [Estéticas](./usage/aesthetics.md): mude o estilo da tela inteira com uma classe.
+   - [Classes solo](./usage/solo.md): aplique uma estética a um componente que este pacote não estiliza.
+   - [Composição](./usage/composing.md), [Personalização](./usage/customizing.md) e [Conteúdo e layout](./usage/content-and-layout.md): páginas de consulta com cada regra de eixo, token, padrão e classe utilitária.
+   - [Predefinições](./usage/presets.md): defina um visual uma única vez, para uma região, um tema ou a sua própria classe de componente, em vez de repeti-lo em cada elemento.
+5. [Acessibilidade](./accessibility.md): o que o CSS resolve por você e o que a sua aplicação ainda precisa fazer.
+
+O [changelog](../changelog/index.md) lista todas as versões e o que mudou em cada uma.

package/docs/pt-BR/integrating/astro.md

@@ -0,0 +1,35 @@
+---
+title: Astro
+description: Como carregar a folha de estilos numa aplicação Astro.
+order: 5
+source: 4f93b3a6e0d1cd24a0b7d0eb6050cc98690cd598
+---
+
+# Astro
+
+O Astro renderiza componentes de forma estática por padrão, mas o import de uma folha de estilos global ainda só precisa acontecer uma vez — a partir de um layout compartilhado, não de páginas ou islands individuais.
+
+## Importe a folha de estilos
+
+```astro
+---
+// src/layouts/Layout.astro
+import "@codenhub/styles";
+---
+
+<html lang="en">
+  <body>
+    <slot />
+  </body>
+</html>
+```
+
+Toda página que usa esse layout carrega a folha de estilos uma vez. Usa Tailwind CSS v4? Em vez disso, importe `@codenhub/styles/tw` pela integração de Tailwind do Astro — veja [Tailwind CSS v4](./tailwind.md), incluindo quando um `@source` explícito é realmente necessário.
+
+## Force um tema
+
+Aplique `.dark` ou `.light` no `<html>` para forçar um tema em vez de seguir a preferência do sistema; veja [Temas → Claro e escuro](../usage/theming.md#claro-e-escuro).
+
+## A seguir
+
+Volte para o caminho principal: [Montando uma tela](../concepts.md) adiciona o primeiro card e o primeiro formulário à página de configurações. [Configuração → Todos os entrypoints](../setup.md#todos-os-entrypoints) lista todas as outras folhas de estilos que você pode importar.