@codenhub/styles 0.6.0 → 0.8.0

package/docs/pt-BR/usage/theming.md

@@ -0,0 +1,309 @@
+---
+title: Temas
+description: Modo claro e escuro, como trocar a paleta pelas cores da marca, como definir uma intenção própria, e cada token de cor, de intenção, fundamental e de fonte com o seu padrão.
+order: 5
+source: faefe01e9a435bd2630c846cc365f3c8783107df
+---
+
+# Temas
+
+A tela de configurações funciona e tem a cara dos padrões do pacote: ações quase pretas numa página quase branca. Esta página a deixa com a sua cara. Ela trata do modo claro e escuro, depois troca a cor primária por uma cor da marca nos dois modos e, por fim, define uma intenção que o pacote não entrega. A segunda metade é a referência de consulta: cada token de cor, de intenção, fundamental e de fonte, com o seu padrão.
+
+## Claro e escuro
+
+De fábrica, a página segue o sistema operacional: clara quando o sistema do usuário está no claro, escura quando está no escuro. Você não precisa fazer nada para isso.
+
+Para deixar o usuário escolher, coloque um seletor de tema no elemento raiz:
+
+```html
+<html data-theme="dark">
+  …
+</html>
+```
+
+| Tema   | Seletores equivalentes                           |
+| ------ | ------------------------------------------------ |
+| Claro  | `.light`, `.theme-light`, `[data-theme="light"]` |
+| Escuro | `.dark`, `.theme-dark`, `[data-theme="dark"]`    |
+
+Uma tela de configurações com a escolha "Sistema / Claro / Escuro" remove o atributo para Sistema e o define para as outras duas opções.
+
+Como isso é resolvido:
+
+- Um seletor de tema define a propriedade CSS `color-scheme` e a cor do texto do elemento como `--color-text`. Cada token de cor guarda o seu valor claro e o seu valor escuro ao mesmo tempo, por meio de `light-dark()`, e o `color-scheme` do elemento escolhe um deles.
+- `color-scheme` é herdado, então um seletor aplica o tema a tudo o que está dentro dele. Um seletor em qualquer elemento aplica o tema àquela parte da página: uma barra lateral escura numa página clara é `<aside class="dark">`, e o texto dentro dela recebe a cor de texto do tema escuro.
+- Um seletor não define fundo. Dê você mesmo o fundo da região, como `background: var(--color-background)`. Qualquer classe utilitária ou de componente no mesmo elemento substitui a cor de texto do seletor.
+- O seletor mais próximo vence, em qualquer profundidade. Um card `.light` dentro de uma página `.dark` é claro.
+- Sem seletor, a raiz tem `color-scheme: light dark`, que segue o sistema.
+- Coloque um único tema por elemento. Se um elemento tiver um seletor claro e um escuro, o escuro vence, mas não conte com isso.
+- Definir você mesmo o `color-scheme` num elemento aplica o tema aos tokens do mesmo jeito, porque ele é a única coisa que a paleta lê. Isso também aplica o tema a partes nativas, como barras de rolagem e o interior de controles de formulário. O texto simples dentro dele mantém a cor que herdou até você definir também `color: var(--color-text)`.
+
+Toda cor de componente vem de um token ou de `currentColor`, então os componentes seguem o tema sem regras próprias de modo escuro. As marcas que o pacote desenha, como o visto do checkbox e a seta do select, também usam `currentColor`. Ícones e imagens que você adiciona ficam por sua conta.
+
+`light-dark()` funciona a partir do Chrome 123, Safari 17.5 e Firefox 120. O pacote como um todo exige Firefox 128; veja [Configuração → Requisitos](../setup.md#requisitos).
+
+### Impressão
+
+Uma página é impressa no tema claro, seja qual for o tema que ela mostra na tela. Dentro de `@media print`, a raiz e todo seletor escuro definem `color-scheme: light`, então todo token é resolvido para o seu valor claro, inclusive o de uma barra lateral forçada para o escuro. O papel é claro, e texto escuro sobre ele gasta menos tinta do que uma página escura impressa.
+
+Componentes preenchidos imprimem o seu fundo. Por padrão, o navegador tira os fundos de uma página impressa, o que deixa o texto de contraste de um botão sólido sobre o nada, então todo componente define `print-color-adjust: exact`. A propriedade é herdada, de modo que o conteúdo de um componente também mantém as suas cores.
+
+Um limite: um utilitário `dark:` continua valendo na impressão. Ele casa pelo seletor, não pelo `color-scheme`, então com `<html class="dark">` e `dark:bg-black` num elemento, esse fundo sai preto no papel. Escreva um utilitário `print:` ao lado dele se a página impressa importar.
+
+### A variante `dark:`
+
+Com os entrypoints de código-fonte do Tailwind (`/tw`), o pacote substitui a variante `dark:` do Tailwind para que os seus próprios utilitários sigam o mesmo tema que os tokens. Um utilitário `dark:` se aplica sob um seletor escuro explícito no elemento ou num ancestral, ou sob uma preferência de sistema escura quando nenhum ancestral define um tema:
+
+```html
+<html>
+  <body>
+    <p class="dark:text-white">Follows the system preference</p>
+    <div class="light">
+      <p class="dark:text-white">Stays light: this part of the page chose a theme</p>
+    </div>
+  </body>
+</html>
+```
+
+Ela difere dos tokens em um caso: um tema explícito aninhado dentro do tema oposto. Um elemento `.light` dentro de um `.dark` tem tokens claros, porque o `color-scheme` mais próximo vence. Mas `dark:` casa por seletor, e `.dark *` casa com todo elemento dentro de `.dark`, então um utilitário `dark:` dentro daquele elemento `.light` ainda se aplica. Se uma página usa tanto tokens quanto utilitários `dark:`, não aninhe temas opostos.
+
+Os entrypoints compilados não definem uma variante `dark:`; eles não têm um build do Tailwind em que defini-la.
+
+## Mude a cor da marca
+
+A cor primária é quase preta numa página clara e quase branca numa escura. Para transformá-la numa cor da marca, substitua a família primária inteira: a cor base e as suas quatro companheiras. Cada uma guarda um valor claro e um escuro:
+
+```css
+:root {
+  --color-primary: light-dark(#0f766e, #2dd4bf);
+  --color-primary-contrast: light-dark(#ffffff, #042f2e);
+  --color-primary-hover: light-dark(#115e59, #5eead4);
+  --color-primary-subtle: light-dark(#ccfbf1, #134e4a);
+  --color-primary-strong: light-dark(#115e59, #5eead4);
+}
+```
+
+Para que serve cada uma:
+
+| Token                      | Papel                                                                                         | Verificação                                         |
+| -------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| `--color-primary`          | O preenchimento de um botão primário sólido, de um toggle marcado, de uma barra de progresso. | Texto em `-contrast` sobre ela chega a 4.5:1.       |
+| `--color-primary-contrast` | Texto e ícones sobre um preenchimento primário total.                                         | Veja acima.                                         |
+| `--color-primary-hover`    | O preenchimento sob o ponteiro.                                                               | Texto em `-contrast` sobre ela ainda chega a 4.5:1. |
+| `--color-primary-subtle`   | O tom claro por trás dos componentes soft.                                                    | Texto em `-strong` sobre ela chega a 4.5:1.         |
+| `--color-primary-strong`   | Texto, ícones e bordas onde o preenchimento não é total: soft e ghost.                        | Chega a 4.5:1 sobre a página e sobre `-subtle`.     |
+
+Os valores em verde-azulado acima medem, no modo claro e no escuro: 5.47:1 e 7.77:1 para o preenchimento e o seu texto, 7.27:1 e 13.38:1 para o tom forte sobre a página, e 6.73:1 e 6.41:1 para o tom forte sobre o tom suave.
+
+Substitua a família inteira. Mudar só `--color-primary` deixa as companheiras no antigo quase preto, então um badge primário soft mantém o texto cinza e um botão com hover pisca em preto. O anel de foco é desenhado a partir de `--color-primary` com 64% de opacidade, então ele acompanha a cor da marca sem precisar de mudança própria.
+
+O mesmo padrão funciona para todas as famílias em [Tokens de cor](#tokens-de-cor): `--color-accent` é o que `.secondary` lê, e as quatro famílias de status são `success`, `warning`, `destructive` e `info`. Defina-as no `:root` para a página inteira, ou em qualquer elemento para mudar o tema só do que está dentro dele.
+
+Os valores precisam ser cores completas: hex, `rgb()`, `oklch()` ou uma variável que você mesmo declarou. Variáveis da paleta do Tailwind, como `--color-teal-700`, existem num build `/tw`, vindas do seu tema do Tailwind, mas o CSS compilado declara só as cores da paleta que o próprio pacote usa. Com CSS compilado, uma referência a qualquer outra variável da paleta fica vazia, e a cor que ela alimenta se perde.
+
+Com `/tw`, você pode descartar os tons do Tailwind que o seu design não usa, para que `bg-red-500` e companhia deixem de ser classes. Mantenha os que o tema lê, `neutral`, `emerald`, `amber`, `rose`, `indigo` e `white`: apagados, as cores construídas a partir deles se perdem sem nenhum erro. [Tailwind CSS v4 → Descarte a paleta do Tailwind](../integrating/tailwind.md#descarte-a-paleta-do-tailwind) tem o bloco para copiar.
+
+## Sua própria intenção
+
+O pacote entrega seis intenções, `.primary`, `.secondary`, `.success`, `.warning`, `.destructive` e `.info`, mais o padrão, `.neutral`. Para adicionar uma, como uma cor "Beta" para funcionalidades em prévia, escreva uma classe que define os sete slots de intenção. Use cores completas, com `light-dark()` para tudo o que muda entre os temas:
+
+```css
+.beta {
+  --intent-color: #7c3aed;
+  --intent-contrast: #ffffff;
+  --intent-hover: #6d28d9;
+  --intent-strong: light-dark(#5b21b6, #c4b5fd);
+  --intent-subtle: light-dark(#ede9fe, #4c1d95);
+  --intent-border: light-dark(#7c3aed, #a78bfa);
+  --intent-fill-max: 100%;
+}
+```
+
+```html
+<span class="badge beta">Beta</span> <button class="btn beta" type="button">Try the new editor</button>
+```
+
+Esses valores medem 5.7:1 para branco sobre o preenchimento, 7.1:1 para branco sobre a cor de hover, 8.61:1 (claro) e 10.72:1 (escuro) para o tom forte sobre a página, e 7.57:1 e 5.93:1 para o tom forte sobre o tom suave.
+
+**Defina todos os slots**, incluindo `--intent-fill-max`. Cada componente redefine os sete slots para os valores neutros na sua própria raiz, então um slot que você deixa de fora fica com o valor do neutro e, sem `--intent-fill-max: 100%`, a sua intenção só preenche até 20%, como o neutro. O que cada slot faz está em [Tokens de intenção](#tokens-de-intenção).
+
+A classe funciona em tudo o que aceita intenção: botões, badges, campos e toggles, cards sólidos e ghost, barras de progresso, skeletons, balões de tooltip e o resto. Alguns comportamentos foram escritos para os seis nomes embutidos, e uma intenção personalizada não os recebe:
+
+- **Um repouso discreto, sem tom.** Um `.card.soft`, um `.panel` e um `.alert` neutros ficam sobre o tom de fundo discreto, e só reconhecem uma intenção pelas seis classes embutidas. `.card.soft.beta`, `.panel.beta` e `.alert.beta` são desenhados como o neutro: o tom de fundo discreto em vez de um tom violeta. A sua intenção ainda colore o texto e a borda deles.
+- **O tom dos chips.** Uma tecla `.kbd` ou um bloco de código `.beta` mostra o seu tom `--intent-subtle`, mas não os 12% extras de `--intent-color` que uma intenção embutida acrescenta por cima.
+- **Classes solo.** Uma [classe solo](./solo.md) como `.neobrutalism-solo` só aceita intenção das seis classes embutidas, então `.neobrutalism-solo.beta` é desenhado como neutro.
+- **O texto do hint.** Um [`.hint`](./forms.md#mostre-um-erro-de-validação) só aparece no tom legível de uma intenção com as seis classes embutidas, então `.hint.beta` continua na cor secundária.
+- **Linhas de tabela.** Uma linha do corpo muda a cor do texto, da linha divisória e do hover só com as classes de intenção embutidas. `<tr class="beta">` fica igual ao resto da sua tabela.
+
+Se você precisa disso, há dois caminhos:
+
+- **Mude o tema de uma intenção embutida.** Defina a família `--color-info` (ou outra) com as suas cores, como em [Mude a cor da marca](#mude-a-cor-da-marca), e escreva `.info`. Tudo, incluindo os casos acima, passa a funcionar. O custo é que a mudança alcança todo `.info` dentro do elemento em que você a definiu, então defina-a no elemento mais restrito que funcione, e não faça isso com uma intenção que a página já usa com outro significado.
+- **Pinte você mesmo.** Escreva o seu próprio CSS para aquele componente, como um `background-color` em `.panel.beta`.
+
+> **A intenção não é herdada.** Cada componente redefine os slots de intenção na sua própria raiz, então um contêiner `.success` não recolore um botão destrutivo dentro dele. Coloque a classe de intenção no elemento que mostra a cor.
+
+## Tokens de cor
+
+Cada token de cor guarda um valor claro e um escuro por meio de `light-dark()`; um único valor significa que os dois temas o usam. Nomes de paleta como `neutral-950` são da paleta padrão do Tailwind, que o CSS compilado do pacote declara para as cores que usa.
+
+Cada linha é um ponto de sobrescrita: defina-a no `:root` para mudar o tema da página, ou em qualquer elemento para mudar o tema do que está dentro dele. As linhas `-hover`, `-subtle`, `-strong` e `-contrast` são companheiras da cor base da sua família e não a acompanham, então mude o tema da família inteira. A família `text` não tem linha `-subtle`: a intenção neutra pega o seu tom suave de `--color-surface`.
+
+| Token                          | Claro, escuro                | Finalidade                                                                                                          |
+| ------------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `--color-primary`              | `neutral-950`, `neutral-50`  | Preenchimento de `.primary`.                                                                                        |
+| `--color-primary-contrast`     | `neutral-50`, `neutral-950`  | Texto e ícones sobre um preenchimento primário total.                                                               |
+| `--color-primary-hover`        | `neutral-700`, `neutral-200` | Preenchimento primário sob o ponteiro.                                                                              |
+| `--color-primary-subtle`       | `neutral-200`, `neutral-900` | Tom primário por trás dos componentes soft.                                                                         |
+| `--color-primary-strong`       | `neutral-900`, `neutral-100` | Texto, ícones e bordas primários onde o preenchimento não é total.                                                  |
+| `--color-accent`               | `neutral-600`, `neutral-400` | Preenchimento de `.secondary`.                                                                                      |
+| `--color-accent-contrast`      | `neutral-50`, `neutral-950`  | Texto e ícones sobre um preenchimento secundário total.                                                             |
+| `--color-accent-hover`         | `neutral-700`, `neutral-300` | Preenchimento secundário sob o ponteiro.                                                                            |
+| `--color-accent-subtle`        | `neutral-100`, `neutral-800` | Tom secundário por trás dos componentes soft.                                                                       |
+| `--color-accent-strong`        | `neutral-800`, `neutral-200` | Texto, ícones e bordas secundários onde o preenchimento não é total.                                                |
+| `--color-border`               | `neutral-400`, `neutral-700` | Borda de superfícies neutras, tabelas, divisores e teclas.                                                          |
+| `--color-border-hover`         | `neutral-600`, `neutral-500` | Borda sob o ponteiro.                                                                                               |
+| `--color-control-border`       | `neutral-500`                | Borda em repouso de controles de texto e toggles neutros, desenhada com uma fração da força nos controles de texto. |
+| `--color-background`           | `neutral-50`, `neutral-950`  | A página.                                                                                                           |
+| `--color-foreground`           | `neutral-100`, `neutral-900` | O tom de fundo discreto um passo distante da página: cards soft, painéis e alertas neutros.                         |
+| `--color-surface`              | `neutral-200`, `neutral-800` | Mais um passo: superfícies aninhadas e esmaecidas, e o tom da intenção neutra.                                      |
+| `--color-text`                 | `neutral-950`, `neutral-50`  | Texto do corpo, e a cor da intenção neutra.                                                                         |
+| `--color-text-secondary`       | `neutral-700`, `neutral-400` | Texto secundário, como o `.hint`.                                                                                   |
+| `--color-text-contrast`        | `neutral-50`, `neutral-950`  | Texto sobre um preenchimento total de `--color-text`, como a marca de um toggle neutro marcado.                     |
+| `--color-text-hover`           | `neutral-700`, `neutral-200` | Cor neutra sob o ponteiro.                                                                                          |
+| `--color-text-strong`          | `neutral-900`, `neutral-100` | Texto, ícones e bordas neutros onde o preenchimento não é total.                                                    |
+| `--color-tooltip`              | `white`, `neutral-700`       | Fundo de um balão de tooltip sem intenção. Escolhido por tema para parecer elevado nos dois.                        |
+| `--color-tooltip-contrast`     | `neutral-900`, `neutral-100` | Texto sobre `--color-tooltip`.                                                                                      |
+| `--color-success`              | `emerald-700`                | Preenchimento de `.success`.                                                                                        |
+| `--color-success-contrast`     | `neutral-50`                 | Texto sobre um preenchimento de sucesso total: 5.14:1.                                                              |
+| `--color-success-hover`        | `#007552`, `#008e66`         | Preenchimento de sucesso sob o ponteiro.                                                                            |
+| `--color-success-subtle`       | `emerald-100`, `emerald-900` | Tom de sucesso por trás dos componentes soft.                                                                       |
+| `--color-success-strong`       | `emerald-800`, `emerald-300` | Texto, ícones e bordas de sucesso onde o preenchimento não é total.                                                 |
+| `--color-warning`              | `amber-600`                  | Preenchimento de `.warning`.                                                                                        |
+| `--color-warning-contrast`     | `neutral-950`                | Texto sobre um preenchimento de aviso total: quase preto, não a cor da página. 6.19:1.                              |
+| `--color-warning-hover`        | `#d46700`, `#e78300`         | Preenchimento de aviso sob o ponteiro.                                                                              |
+| `--color-warning-subtle`       | `amber-100`, `amber-900`     | Tom de aviso por trás dos componentes soft.                                                                         |
+| `--color-warning-strong`       | `amber-800`, `amber-300`     | Texto, ícones e bordas de aviso onde o preenchimento não é total.                                                   |
+| `--color-destructive`          | `rose-700`                   | Preenchimento de `.destructive`.                                                                                    |
+| `--color-destructive-contrast` | `neutral-50`                 | Texto sobre um preenchimento destrutivo total: 5.78:1.                                                              |
+| `--color-destructive-hover`    | `#c00036`, `#d1054b`         | Preenchimento destrutivo sob o ponteiro.                                                                            |
+| `--color-destructive-subtle`   | `rose-100`, `rose-900`       | Tom destrutivo por trás dos componentes soft.                                                                       |
+| `--color-destructive-strong`   | `rose-800`, `rose-300`       | Texto, ícones e bordas destrutivos onde o preenchimento não é total.                                                |
+| `--color-info`                 | `indigo-600`                 | Preenchimento de `.info`.                                                                                           |
+| `--color-info-contrast`        | `neutral-50`                 | Texto sobre um preenchimento informativo total: 6.19:1.                                                             |
+| `--color-info-hover`           | `#4b36e9`, `#5e4ff9`         | Preenchimento informativo sob o ponteiro.                                                                           |
+| `--color-info-subtle`          | `indigo-100`, `indigo-900`   | Tom informativo por trás dos componentes soft.                                                                      |
+| `--color-info-strong`          | `indigo-800`, `indigo-300`   | Texto, ícones e bordas informativos onde o preenchimento não é total.                                               |
+
+Mudanças de tema pertencem a esses valores, não a regras de componente que verificam o tema.
+
+## Tokens de intenção
+
+Uma classe de intenção define estes sete slots, e os componentes os leem. Como todo componente lê os mesmos sete nomes, uma classe que define os sete funciona como intenção, como mostra [Sua própria intenção](#sua-própria-intenção).
+
+| Token               | Finalidade                                                                                                                                                                                                                                   |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--intent-color`    | A cor base da intenção, aquilo de que um preenchimento é feito.                                                                                                                                                                              |
+| `--intent-contrast` | Texto sobre um preenchimento total de `--intent-color`.                                                                                                                                                                                      |
+| `--intent-hover`    | A cor base sob o ponteiro.                                                                                                                                                                                                                   |
+| `--intent-strong`   | A intenção como texto, ícone ou borda sempre que o preenchimento não é total.                                                                                                                                                                |
+| `--intent-subtle`   | O tom claro por trás dos componentes soft e dos trilhos de progresso. O neutro usa `--color-surface`.                                                                                                                                        |
+| `--intent-border`   | Cor das linhas. Sem intenção, é o `--ui-ink` da estética e, depois, `--color-border`; controles de texto e toggles leem `--ui-control-ink`, depois `--ui-ink` e depois `--color-control-border`, e as tabelas leem `--ui-rule-ink` primeiro. |
+| `--intent-fill-max` | Até onde um preenchimento dessa intenção pode ir. `100%` para toda intenção, exceto a neutra.                                                                                                                                                |
+
+`--intent-color` e `--intent-strong` não são intercambiáveis. A cor base é escolhida para preencher; o tom forte é escolhido para ser lido sobre a página. Um componente soft ou ghost imprime o tom forte, e é por isso que um aviso soft aparece em amber-800 enquanto um sólido é preenchido com amber-600.
+
+O tom forte também precisa continuar reconhecível como o seu próprio matiz. Numa página escura, a tonalidade `-100` de cada família é um tom pálido quase sem cor em tamanhos pequenos: um badge de sucesso soft e um destrutivo soft pareceriam ambos brancos. Por isso, os tons fortes do escuro são `-300`, e os tons por baixo deles são `-900`, que medem 5.0:1 ou mais onde quer que um preenchimento parcial tenha texto, e mais de 9:1 sobre a página.
+
+`--intent-border` existe para que uma borda neutra continue no cinza discreto de borda, e não na cor do texto. Tudo o que desenha uma linha o lê: bordas de controles, linhas divisórias de tabelas, divisores, teclas e barras de citação.
+
+`--intent-fill-max` existe para a intenção neutra, cuja cor é a própria cor do texto da página. Todas as outras intenções são um matiz, legível como um tom pálido a 12% e saturado a 100%; um cinza preenchido a 100% é um bloco preto ou branco, o elemento que mais chama atenção na página justamente para a intenção que não significa nada em particular. O neutro para em `20%`, então `.solid` dá a ele um cinza discreto que ainda fica um passo além do `.soft`. O hover soma o seu passo por cima do teto, então um preenchimento limitado ainda fica mais intenso sob o ponteiro.
+
+A cor do texto acompanha o preenchimento. `--intent-contrast` é a cor do texto para um preenchimento total; impressa sobre um quinto de preenchimento, seria branco sobre cinza-claro. Por isso, o texto de contraste só aparece depois que o preenchimento passa da metade, e chega à força total com o preenchimento total; abaixo disso, o componente imprime `--intent-strong`. Um neutro limitado, portanto, imprime o tom forte. Um estado que levanta o teto de propósito, como um checkbox marcado, chega ao preenchimento total e imprime a cor de contraste.
+
+## Tokens fundamentais
+
+Os tokens fundamentais definem layout, formato, movimento, foco, profundidade e empilhamento. Sobrescreva-os no `:root`, ou num elemento para o que está dentro dele.
+
+As quatro sombras `--elevation-*` são para elementos que você mesmo estiliza. Elas são separadas das classes `.flat`, `.raised` e `.floating`, que escalam a sombra do próprio componente e não desenham nada até que uma estética ou uma dessas classes peça profundidade; veja [Composição → Elevação](./composing.md#elevação). Ambas usam os pesos nenhum, pequeno, médio e grande, mas uma é um valor fixo e a outra escala partes da sombra, então elas nem sempre têm a mesma aparência.
+
+| Token                      | Padrão                                                         | Finalidade                                                                                                                 |
+| -------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `--font-default`           | `"Segoe UI", system-ui, sans-serif`                            | Fonte da página. Veja [Fontes](#fontes).                                                                                   |
+| `--container-narrow`       | `48rem`                                                        | Largura de `.section-content.narrow`.                                                                                      |
+| `--container-max`          | `80rem`                                                        | Largura de `.section-content`.                                                                                             |
+| `--container-wide`         | `90rem`                                                        | Largura de `.section-content.wide`.                                                                                        |
+| `--layout-gutter`          | `clamp(1rem, 4vw, 2rem)`                                       | Padding lateral de `.section`, que cresce com a janela.                                                                    |
+| `--layout-section-block`   | `clamp(4rem, 9vw, 7rem)`                                       | Padding superior e inferior de `.section`, que cresce com a janela.                                                        |
+| `--layout-gap`             | `1rem`                                                         | Espaçamento de `.view`, `.stack`, `.cluster` e `.auto-grid`.                                                               |
+| `--layout-grid-min`        | `16rem`                                                        | Coluna mais estreita de `.auto-grid`.                                                                                      |
+| `--radius-small`           | `0.25rem`                                                      | Canto de chips pequenos: `.kbd` e `.code`.                                                                                 |
+| `--radius-control`         | `0.5rem`                                                       | Canto de botões, campos e balões de tooltip.                                                                               |
+| `--radius-surface`         | `0.875rem`                                                     | Canto de cards, painéis e alertas.                                                                                         |
+| `--control-height`         | `2.5rem`                                                       | Altura mínima de um botão padrão e de um controle de texto.                                                                |
+| `--border-width`           | `1px`                                                          | Espessura da borda.                                                                                                        |
+| `--elevation-color`        | `rgb(15 23 42 / 0.08)` no claro, `rgb(0 0 0 / 0.55)` no escuro | A cor de sombra que as quatro elevações usam. Mais forte numa página escura, onde uma sombra leve não apareceria.          |
+| `--elevation-none`         | `none`                                                         | Sem sombra.                                                                                                                |
+| `--elevation-sm`           | `0 1px 2px`, `0 1px 3px`                                       | Uma sombra leve para as suas próprias superfícies, como um card.                                                           |
+| `--elevation-md`           | `0 4px 6px -1px`, `0 2px 4px -2px`                             | Uma sombra para os seus próprios elementos elevados, como um menu dropdown.                                                |
+| `--elevation-lg`           | `0 20px 25px -5px`, `0 8px 10px -6px`                          | Uma sombra para as suas próprias sobreposições, como um dialog modal.                                                      |
+| `--focus-ring`             | Não definido                                                   | Cor do anel de foco do teclado. Quando não está definido, `--color-primary` com 64% de opacidade, no elemento focado.      |
+| `--focus-ring-offset`      | Não definido                                                   | Distância entre o anel e o elemento. Quando não está definido, o anel fica sobre a borda do elemento em qualquer estética. |
+| `--focus-ring-width`       | `3px`                                                          | Espessura do anel de foco do teclado.                                                                                      |
+| `--motion-duration-fast`   | `120ms`                                                        | O hover de uma linha de tabela.                                                                                            |
+| `--motion-duration-normal` | `200ms`                                                        | Transições de cor, borda, sombra e clique, marcas de toggles e o balão de tooltip.                                         |
+| `--motion-duration-slow`   | `400ms`                                                        | Mudanças de valor de progresso, e a base do ciclo de brilho do skeleton e do progresso.                                    |
+| `--motion-ease`            | `cubic-bezier(0.2, 0, 0, 1)`                                   | Easing de todas as transições.                                                                                             |
+| `--z-popover`              | `40`                                                           | Ordem de empilhamento dos balões de tooltip. Use nos seus próprios popovers para que eles empilhem do mesmo jeito.         |
+| `--breakpoint-xs`          | `30rem`                                                        | O breakpoint responsivo `xs:`. Só num build `/tw`; os entrypoints compilados não o declaram.                               |
+
+Cada sombra `--elevation-*` é composta das partes listadas, cada uma em `--elevation-color`. As quatro sombras são compostas uma única vez, na raiz, então um `--elevation-color` que você define num contêiner não chega até elas: defina-o em `:root`, ou defina o próprio token `--elevation-*` no contêiner. As classes de elevação, como `.card.raised`, leem `--elevation-color` no elemento e seguem o valor de um contêiner, com uma exceção: toda classe de estética define o seu próprio `--elevation-color` na sua região. Um valor definido acima de uma região `.glass` ou `.pixel` não chega dentro dela. Defina-o no próprio elemento da estética, onde o seu utilitário ou CSS sem camada vence a classe, ou num elemento dentro da região. No glass, a sombra de uma superfície é montada no elemento `.glass`, então só um valor definido ali a muda. No `.neobrutalism` a sombra é desenhada na intenção ou na tinta, e o `.cyber` não desenha profundidade, então nenhum dos dois lê o token. O passo de hover que intensifica um preenchimento sob o ponteiro é um token de apresentação, `--hover-step`; veja [Personalização](./customizing.md#tokens-de-apresentação).
+
+## Fontes
+
+O pacote não entrega arquivos de fonte e não faz requisições de rede. Cada token de fonte nomeia fontes já instaladas no dispositivo de quem lê, até você fornecer as suas.
+
+| Token            | Lido por                                                                                      | Sem o seu valor                                                                                                                                   |
+| ---------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--font-default` | O reset, em `html` e `body`, e as regiões `.glass` e `.neobrutalism`. Os controles o herdam.  | `"Segoe UI", system-ui, sans-serif`                                                                                                               |
+| `--font-mono`    | Os utilitários de conteúdo `kbd`, `code` e `pre`, e `<kbd>`, `<code>` e `<pre>` com `/native` | `ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace`. Com `/tw`, o valor do seu tema do Tailwind. |
+| `--font-pixel`   | [`.pixel`](./aesthetics.md#pixel) e `.pixel-solo`                                             | Não declarado. Cai numa pilha monoespaçada.                                                                                                       |
+| `--font-rounded` | [`.chunky-tile`](./aesthetics.md#chunky-tile) e `.chunky-tile-solo`                           | Não declarado. Cai em `--font-default` e, depois, numa pilha sans-serif.                                                                          |
+| `--font-cyber`   | [`.cyber`](./aesthetics.md#cyber) e `.cyber-solo`                                             | Não declarado. Cai numa pilha monoespaçada.                                                                                                       |
+| `--font-sketch`  | [`.sketch`](./aesthetics.md#sketch) e `.sketch-solo`                                          | Não declarado. Cai na família `cursive` da plataforma.                                                                                            |
+
+`--font-default` só chega à página pelo reset, que `@codenhub/styles`, `/native`, `/tw`, `/tw/native` e `/tw/reset` incluem. Usando só `/theme` ou `/components`, defina você mesmo o `font-family` no `body` e defina `--font-default` com a mesma fonte: as regiões `.glass` e `.neobrutalism` definem o próprio `font-family` a partir do token, então uma fonte definida só no `body` não chega dentro delas. Ou defina só o token e escreva `font-family: var(--font-default)` no `body`. Os tokens das estéticas são lidos pela classe da própria estética, então funcionam com qualquer entrypoint.
+
+Para usar uma web font, carregue-a como você carrega qualquer fonte e depois nomeie-a no token. Defina o token no `:root` para a página inteira, ou em qualquer elemento para aquela parte dela:
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400..700&display=swap" />
+```
+
+```css
+:root {
+  --font-default: "Inter", system-ui, sans-serif;
+}
+```
+
+Uma fonte hospedada por você é declarada com `@font-face` e nomeada do mesmo jeito:
+
+```css
+@font-face {
+  font-family: "Pixelify Sans";
+  src: url("/fonts/pixelify-sans.woff2") format("woff2");
+  font-weight: 400 700;
+  font-display: swap;
+}
+
+:root {
+  --font-pixel: "Pixelify Sans", monospace;
+}
+```
+
+Carregue os pesos de 400 a 700, e 800 para `--font-rounded`: os componentes definem `font-weight` de 400 a 700, e `.chunky-tile` usa 800 nos rótulos. Um navegador que não tem um peso o simula engrossando o regular, o que borra uma fonte pixelada ou manuscrita. Sempre termine a pilha com uma família genérica, como `sans-serif` ou `monospace`, para que o texto continue renderizando enquanto a fonte carrega ou se ela falhar.
+
+## A seguir
+
+A tela tem as suas cores nos dois temas. [Estéticas](./aesthetics.md) muda do que ela é feita: contornos pretos grossos, vidro fosco, pixels e muito mais.

package/docs/pt-BR/usage/tooltips.md

@@ -0,0 +1,127 @@
+---
+title: Tooltips
+description: Ajuda de campo que abre no hover e no foco, como ligá-la a leitores de tela e à tecla Escape, e onde um tooltip é cortado.
+order: 4
+source: ea0dd81935063e3e02f0b4d84e51fafab0511cc3
+---
+
+# Tooltips
+
+O switch "Public profile" da tela de configurações merece uma explicação curta: o que fica visível quando ele está ligado. Esta página acrescenta um botão de ajuda ao lado dele que mostra um tooltip no hover e no foco pelo teclado. O CSS mostra, esconde e desenha a mensagem; você a liga ao gatilho para os leitores de tela, adiciona a tecla Escape e confere se nada em volta a corta.
+
+## Um tooltip de ajuda
+
+```html
+<div class="cluster tight">
+  <label class="cluster tight">
+    <input class="switch primary" type="checkbox" role="switch" name="public-profile" />
+    Public profile
+  </label>
+  <span class="tooltip">
+    <button class="tooltip-icon" type="button" 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, photo, and public projects.</span>
+  </span>
+</div>
+```
+
+As três partes:
+
+- `.tooltip` envolve o gatilho e a mensagem. Ele posiciona a mensagem e não pinta nada.
+- `.tooltip-bubble` é a mensagem. É um elemento de verdade, então pode ter um `id` para o qual o gatilho aponta.
+- `.tooltip-icon` é um gatilho pequeno e redondo, para uma mensagem sem mais nada a que se prender. Qualquer elemento focável pode ser o gatilho no lugar dele: envolva um `.btn` existente em `.tooltip` e ele mantém o próprio visual.
+
+Faça a ligação você mesmo: um `id` no balão, `aria-describedby` no gatilho apontando para esse `id` e `role="tooltip"` no balão. Assim, um leitor de tela lê a mensagem como a descrição do gatilho. O CSS não consegue fazer essa ligação e, sem ela, a mensagem é só visual.
+
+O gatilho precisa ser focável, como um `<button>`, para que quem usa teclado alcance a mensagem. O balão abre quando qualquer coisa dentro de `.tooltip` tem foco, então ele também abre depois de um clique do mouse no gatilho.
+
+## Posicionamento
+
+O balão abre acima do gatilho, centralizado na horizontal, com um espaçamento de 0.5rem. Defina `data-tooltip-position` no `.tooltip` para escolher outro lado:
+
+```html
+<span class="tooltip" data-tooltip-position="bottom">
+  <button class="btn ghost sm" type="button" aria-describedby="renewal-help">Renews 12 March 2027</button>
+  <span class="tooltip-bubble" role="tooltip" id="renewal-help">Your card is charged on this date.</span>
+</span>
+```
+
+| `data-tooltip-position` | Balão                                            |
+| ----------------------- | ------------------------------------------------ |
+| _nenhum_ ou `"top"`     | Acima do gatilho, centralizado.                  |
+| `"bottom"`              | Abaixo do gatilho, centralizado.                 |
+| `"left"`                | À esquerda do gatilho, centralizado na vertical. |
+| `"right"`               | À direita do gatilho, centralizado na vertical.  |
+
+Um balão tem a largura do texto, até 18rem, e a partir daí quebra a linha.
+
+### Onde um tooltip é cortado
+
+O balão é posicionado só com CSS, no lado que você escolheu. Nada mede a página: ele não se move para ficar dentro da janela, não vira para o outro lado quando falta espaço e não vai para a camada superior (top layer) da página. Isso tem três consequências:
+
+- **Um contêiner com rolagem ou recorte o corta.** Um ancestral com `overflow: hidden`, `auto` ou `scroll` recorta o balão na borda dele. A tabela de chaves de API da tela de configurações fica num `.table-wrap`, que tem rolagem, então um tooltip acima da primeira linha é cortado no topo do wrapper. Aumentar o `z-index` não ajuda: ele muda sobre o que o balão é pintado, não se o contêiner o recorta.
+- **A borda da janela o corta.** Um tooltip acima da primeira linha de uma página, ou um tooltip à direita perto da borda direita, sai da tela.
+- **Esquerda e direita são lados físicos.** Numa página da direita para a esquerda, `"left"` continua significando o lado esquerdo da tela.
+
+O que fazer:
+
+- Escolha um lado com espaço: na primeira linha de uma tabela, use `data-tooltip-position="bottom"`.
+- Tire o gatilho do tooltip de dentro do contêiner que recorta, ou remova o `overflow` de um contêiner que não precisa dele.
+- Se a posição do gatilho não puder ser conhecida de antemão, como numa lista com rolagem ou num painel redimensionável, use uma biblioteca de posicionamento ou o componente de popover do seu framework, que consegue medir e virar. Você ainda pode dar ao elemento da mensagem as classes de `.tooltip-bubble` para o visual, mas mostrar, esconder e posicionar, como descrito nesta página, passam a ser trabalho dessa biblioteca, e não do `.tooltip`.
+
+## Hover, permanência e Escape
+
+O WCAG 1.4.13 pede três coisas de um conteúdo que aparece no hover ou no foco. O pacote resolve duas:
+
+- **Sobrevoável (hoverable).** Quando o ponteiro sai do gatilho, o balão continua visível por `--tooltip-linger` (300ms) e depois desaparece aos poucos, para que o ponteiro consiga atravessar o espaço até ele. Ele continua aberto enquanto o ponteiro estiver em cima dele. Um balão fechado fica com `visibility: hidden`, então ele nunca captura o ponteiro.
+- **Persistente.** Ele continua aberto até o ponteiro e o foco saírem.
+- **Dispensável.** O usuário precisa conseguir fechá-lo sem mover o ponteiro nem o foco, normalmente com Escape. O CSS não consegue escutar uma tecla, então essa parte é sua.
+
+Para mudar o tempo de permanência, defina `--tooltip-linger` no elemento `.tooltip`, por exemplo `style="--tooltip-linger: 500ms"`. O wrapper declara o seu próprio padrão, então um valor definido num elemento pai do `.tooltip` não tem efeito. Deixe o tempo longo o bastante para o ponteiro alcançar o balão. Ela é uma das seis [variáveis públicas de componente](./customizing.md#variáveis-de-componente).
+
+Para o Escape, escreva `data-state="closed"` no `.tooltip`: isso esconde o balão mesmo enquanto ele está com hover ou com foco. Remova o atributo só quando o ponteiro e o foco tiverem saído do tooltip, para que o próximo hover ou foco o abra de novo. Removê-lo antes, enquanto o gatilho ainda tem foco, faz a mensagem reaparecer sem que o usuário faça nada.
+
+```js
+for (const tooltip of document.querySelectorAll(".tooltip")) {
+  let pointerInside = tooltip.matches(":hover");
+
+  tooltip.addEventListener("pointerenter", () => {
+    pointerInside = true;
+  });
+
+  tooltip.addEventListener("pointerleave", () => {
+    pointerInside = false;
+    if (!tooltip.contains(document.activeElement)) tooltip.removeAttribute("data-state");
+  });
+
+  tooltip.addEventListener("focusout", (event) => {
+    const focusStaysInside = tooltip.contains(event.relatedTarget);
+    if (!focusStaysInside && !pointerInside) tooltip.removeAttribute("data-state");
+  });
+}
+
+document.addEventListener("keydown", (event) => {
+  if (event.key !== "Escape") return;
+  for (const tooltip of document.querySelectorAll(".tooltip:hover, .tooltip:focus-within")) {
+    tooltip.dataset.state = "closed";
+  }
+});
+```
+
+`data-state="open"` faz o contrário: mostra o balão sem hover nem foco, para uma mensagem que deve ficar visível, ou para um teste ou uma captura de tela.
+
+## Como o balão aparece
+
+Sem classe de intenção, o balão usa `--color-tooltip`, um fundo escolhido por tema: quase branco numa página clara, cinza médio numa escura, com `--color-tooltip-contrast` como cor do texto. Quase branco mede só 1.04:1 em relação a uma página clara, então o balão também desenha uma borda fina, e um `.edgeless` de um contêiner não consegue removê-la. Um `.edgeless` no próprio balão ainda consegue. O fundo continua opaco com qualquer apresentação, para que o balão continue legível sobre o que quer que ele cubra.
+
+Uma classe de intenção preenche o balão com a cor dessa intenção e troca o texto para a cor de contraste correspondente:
+
+- `.tooltip-bubble.primary` tem fundo quase preto com texto quase branco numa página clara, e fundo quase branco com texto quase preto numa escura.
+- `.tooltip-bubble.destructive` tem fundo vermelho com texto claro nos dois temas.
+
+Coloque as classes de intenção, apresentação, estética e elevação no `.tooltip-bubble`, o elemento que é pintado, e não no `.tooltip`. O balão é plano por padrão, mesmo numa estética que desenha profundidade; adicione `.raised` ou `.floating` ao balão para elevá-lo. Uma estética em vigor dá forma ao balão como a qualquer outro componente; com `.glass`, ele fica fosco como um card. O `.tooltip-icon` assume o canto da estética: quadrado com `.neobrutalism` e `.pixel`, um losango com `.cyber`.
+
+O balão aparece sem o efeito de crescer quando o usuário pede movimento reduzido.
+
+## A seguir
+
+A tela de configurações está completa no visual padrão. [Temas](./theming.md) dá a ela um modo escuro e as cores da sua marca.