@codenhub/styles 0.5.0 → 0.7.0

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,104 @@
+---
+title: Introdução
+description: Para que serve o @codenhub/styles, quanto ele custa e em que ordem ler esta documentação.
+source: 238cac2f0ca6132818c99d938219a6c537bc837a
+---
+
+# @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 410 KB, a `/native` cerca de 575 KB e a `/components` cerca de 320 KB. Servidas com gzip, ficam em cerca de 19 KB, 25 KB e 15 KB. Os arquivos específicos são bem menores: `/theme` tem cerca de 10 KB (2 KB com gzip) e cada estética tem de 4 a 21 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. 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.
+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.

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

@@ -0,0 +1,47 @@
+---
+title: Visão geral
+description: Como a folha de estilos é carregada no build de um framework e qual guia seguir.
+group: Integração
+order: 2
+source: f2ccb27bbdbe15278726278864c01a586505eb16
+---
+
+# Integração
+
+Esta seção é um desvio do caminho principal de leitura, para projetos em que o framework decide onde o CSS global pode ficar. O pacote não tem JavaScript nem bindings para frameworks (veja a [Introdução](../index.md#o-que-ele-não-faz)), então integrá-lo se resume a duas coisas: onde o seu framework deixa você carregar uma folha de estilos global e se o projeto roda Tailwind CSS v4. Siga o guia que corresponde à sua stack e depois volte para [Montando uma tela](../concepts.md).
+
+## O modelo comum
+
+Toda stack faz os mesmos dois imports, a partir do mesmo tipo de lugar — um layout raiz, o arquivo de entrada da aplicação ou um arquivo CSS global, nunca uma página ou um componente mais abaixo na árvore:
+
+1. Um [entrypoint](../setup.md#todos-os-entrypoints) — o `@codenhub/styles` compilado para qualquer build, ou `@codenhub/styles/tw` quando o projeto já roda Tailwind CSS v4.
+2. `@codenhub/styles/aesthetics` (ou `/tw/aesthetics`) depois dele, só se o projeto usar uma [estética](../usage/aesthetics.md).
+
+Importar de um único lugar importa por dois motivos. Alguns frameworks só _permitem_ CSS global a partir de um arquivo raiz designado e falham no build caso contrário — o Pages Router do Next.js é um deles; veja [Next.js → Solução de problemas](./nextjs.md#solução-de-problemas). Onde o framework permite de forma mais ampla, como faz o App Router do Next.js, importar a partir da raiz continua sendo a escolha recomendada para uma ordem de CSS previsível — e importar por componente carregaria as mesmas regras de reset e de tokens uma vez por componente, em vez de uma vez por aplicação.
+
+## Qual guia seguir
+
+| Stack                                                                    | Guia                                  |
+| ------------------------------------------------------------------------ | ------------------------------------- |
+| Um projeto com Tailwind CSS v4 em qualquer bundler                       | [Tailwind CSS v4](./tailwind.md)      |
+| Next.js / React                                                          | [Next.js](./nextjs.md)                |
+| Vue                                                                      | [Vue](./vue.md)                       |
+| Svelte / SvelteKit                                                       | [Svelte](./svelte.md)                 |
+| Astro                                                                    | [Astro](./astro.md)                   |
+| HTML puro, Rails, Django ou qualquer aplicação sem etapa de build de CSS | [Sem bundler](./without-a-bundler.md) |
+
+Um projeto sem framework — um build simples com Vite, webpack ou Parcel — não precisa de nada além de [Configuração → Importe a folha de estilos](../setup.md#importe-a-folha-de-estilos): importe a folha de estilos compilada a partir do arquivo CSS global que o projeto já tem.
+
+## Conferindo se funcionou
+
+Depois do import, renderize um elemento estilizado e confirme que ele pegou os tokens do pacote, e não o padrão do navegador:
+
+```html
+<button class="btn primary">Save changes</button>
+```
+
+Um botão arredondado preenchido com a cor primária (quase preto numa página clara, quase branco numa escura) significa que a folha de estilos carregou. Texto com o padrão do navegador, sem estilo, na maioria das vezes significa que o especificador do import não foi resolvido — confira na [tabela de entrypoints](../setup.md#todos-os-entrypoints) o especificador exato a importar, e confirme que o ferramental do seu build resolve imports de CSS de pacotes; veja [Configuração → Requisitos](../setup.md#requisitos). Sem ferramenta de build, referencie o arquivo pelo caminho; veja [Sem bundler](./without-a-bundler.md). [Configuração → Quando nada é estilizado](../setup.md#quando-nada-é-estilizado) lista as outras causas comuns.
+
+## A seguir
+
+Quando o botão renderizar, volte para o caminho principal: [Montando uma tela](../concepts.md) adiciona o primeiro card e o primeiro formulário à página de configurações.

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

@@ -0,0 +1,67 @@
+---
+title: Next.js
+description: Como carregar a folha de estilos numa aplicação Next.js / React.
+order: 2
+source: fd8dc12652c64995638c5b902a1ca35787f9a37c
+---
+
+# Next.js
+
+O Next.js tem duas arquiteturas de roteamento, e elas tratam o CSS global de formas diferentes:
+
+- **App Router** (um diretório `app/`): o CSS global — incluindo a folha de estilos de um pacote externo como este — pode ser importado de qualquer layout, página ou componente dentro de `app/`. Importar a partir do layout raiz é só uma recomendação, para uma ordem de CSS previsível entre as rotas; o Next.js não impõe isso e nenhum erro acontece se você importar em outro lugar.
+- **Pages Router** (um diretório `pages/`, sem `app/`): o CSS global fica restrito a `pages/_app.tsx`. Importar de qualquer outro lugar faz o build falhar — quem impõe isso é o próprio Next.js, não este pacote; veja [Solução de problemas](#solução-de-problemas).
+- **Os dois diretórios presentes** (no meio de uma migração): importe a folha de estilos nos dois arquivos raiz. Os dois roteadores servem as suas próprias rotas de forma independente, então uma rota em `pages/` nunca vê uma folha de estilos importada só em `app/layout.tsx`, e vice-versa.
+
+## Importe a folha de estilos
+
+Adicione o import ao arquivo raiz do seu roteador:
+
+**App Router**
+
+```tsx
+// app/layout.tsx
+import "@codenhub/styles";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+**Pages Router**
+
+```tsx
+// pages/_app.tsx
+import "@codenhub/styles";
+import type { AppProps } from "next/app";
+
+export default function App({ Component, pageProps }: AppProps) {
+  return <Component {...pageProps} />;
+}
+```
+
+Usa Tailwind CSS v4? `@import "@codenhub/styles/tw"` é uma diretiva de CSS, então o lugar dele é num arquivo CSS, não num import solto em `layout.tsx`/`_app.tsx` — adicione-o (com `@source`, se precisar; `/tw` já importa o próprio Tailwind, então deixe de fora o seu `@import "tailwindcss"`) ao seu arquivo CSS global e, em vez disso, importe esse arquivo a partir do mesmo arquivo raiz mostrado acima. Veja [Tailwind CSS v4](./tailwind.md).
+
+## 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).
+
+```tsx
+<html lang="en" className="dark">
+```
+
+## Solução de problemas
+
+**O build com Pages Router falha com "Global CSS cannot be imported from files other than your Custom `<App>`"**
+
+- **O que aconteceu:** o Next.js rejeitou uma instrução `import` de CSS global fora de `pages/_app.tsx`. Essa restrição é específica do Pages Router — quem a impõe é o próprio Next.js, não este pacote, e ela vale para qualquer import de CSS global, não especificamente para o `@codenhub/styles`. Ela não vale para o App Router, em que o mesmo import funciona a partir de qualquer layout, página ou componente.
+- **Por quê:** o Pages Router não tem uma fronteira de CSS por rota como o App Router tem, então o Next.js exige um único arquivo previsível para as folhas de estilos globais, para evitar conflitos de ordem entre as páginas.
+- **Como resolver:** mova a linha `import "@codenhub/styles"` para `pages/_app.tsx` e remova-a de onde ela estiver agora.
+
+## 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.

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

@@ -0,0 +1,45 @@
+---
+title: Svelte
+description: Como carregar a folha de estilos numa aplicação Svelte / SvelteKit.
+order: 4
+source: 9c8bc0fee69e4b2bf1edd85c784b7df8ff1e883d
+---
+
+# Svelte
+
+O Svelte e o SvelteKit deixam você importar CSS de qualquer componente, mas o reset e os tokens do pacote devem carregar uma vez, antes de qualquer componente renderizar. Esta página mostra onde fica esse único import no SvelteKit e numa aplicação Svelte simples.
+
+## Importe a folha de estilos
+
+**SvelteKit** — importe a partir do layout raiz, para carregar uma vez em todas as rotas:
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+  import "@codenhub/styles";
+  let { children } = $props();
+</script>
+
+{@render children()}
+```
+
+**Svelte simples + Vite** — importe a partir do arquivo de entrada:
+
+```ts
+// main.ts
+import "@codenhub/styles";
+import { mount } from "svelte";
+import App from "./App.svelte";
+
+mount(App, { target: document.getElementById("app")! });
+```
+
+Usa Tailwind CSS v4? Em vez disso, importe `@codenhub/styles/tw` a partir do arquivo CSS de entrada da aplicação — veja [Tailwind CSS v4](./tailwind.md).
+
+## Force um tema
+
+Aplique `.dark` ou `.light` no `<html>` (edite `src/app.html` no SvelteKit) 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.

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

@@ -0,0 +1,78 @@
+---
+title: Tailwind CSS v4
+description: Como usar os entrypoints de código-fonte /tw num projeto com Tailwind CSS v4.
+order: 1
+source: 7988dc023c91950991a720ea7da7edfe3378d4d7
+---
+
+# Tailwind CSS v4
+
+Um projeto que já roda Tailwind CSS v4 pode compilar o código-fonte deste pacote em vez de carregar a saída compilada. Os utilitários da sua aplicação e as classes do pacote saem então de um único build, compartilham um único tema e usam uma única variante `dark:`. Esta página trata do import, das estéticas, dos entrypoints específicos e dos problemas de build que você provavelmente vai encontrar.
+
+## Por que código-fonte em vez de compilado
+
+Os entrypoints `/tw` publicam uma cópia do código-fonte não compilado de `dist/tw`; o seu próprio build do Tailwind o compila junto com a sua aplicação, então as diretivas `@theme`, `@utility` e `@apply` dele são resolvidas junto com as suas. Os entrypoints compilados (`@codenhub/styles`) continuam funcionando num projeto com Tailwind, mas aí dois pipelines de CSS separados rodam lado a lado em vez de um — use `/tw`, a menos que um motivo específico o descarte.
+
+## Importe o entrypoint de código-fonte
+
+```css
+@import "@codenhub/styles/tw";
+
+@source "./src";
+```
+
+O `/tw` importa o próprio Tailwind, então ele substitui o seu `@import "tailwindcss"` em vez de se somar a ele: com os dois, o Preflight do Tailwind é emitido duas vezes. Todos os outros entrypoints `/tw/*` esperam que o seu import venha antes; veja [Usando um entrypoint específico](#usando-um-entrypoint-específico).
+
+O Tailwind CSS v4 varre o seu projeto automaticamente — a maioria dos projetos não precisa de nada além do import acima. Os caminhos de `@source` são resolvidos a partir do arquivo CSS que os declara, não da raiz do projeto, então `./src` aqui significa "o `src/` ao lado desta folha de estilos"; ajuste para onde a sua folha de estilos global realmente está. Adicione `@source` só para markup que a varredura automática do Tailwind não alcança sozinha: um caminho excluído por padrão (listado no `.gitignore`, ou dentro de `node_modules` — uma biblioteca de componentes externa, por exemplo) ou, num monorepo, um caminho fora da árvore de diretórios deste arquivo. Aponte para o markup da sua aplicação, não para este pacote — o `/tw` já entrega a definição de todas as classes que publica, então varrê-lo também só deixa o build mais lento, sem acrescentar classes.
+
+## Adicione estéticas
+
+Adicione uma estética a partir do entrypoint de código-fonte do mesmo jeito que no compilado, depois do import base:
+
+```css
+@import "@codenhub/styles/tw";
+@import "@codenhub/styles/tw/aesthetics";
+
+@source "./src";
+```
+
+## Usando um entrypoint específico
+
+Importe um entrypoint `/tw/*` específico em vez do combinado — como `/tw/button` ou `/tw/form` — quando um build só precisa de uma família de componentes; veja a [tabela de entrypoints](../setup.md#todos-os-entrypoints) completa para saber o que cada um reúne.
+
+Diferente do `/tw`, os entrypoints específicos e o `/tw/native` não importam o Tailwind, então mantenha o seu próprio import primeiro:
+
+```css
+@import "tailwindcss";
+@import "@codenhub/styles/tw/button";
+```
+
+## Solução de problemas
+
+**As classes não resultam em nenhum estilo**
+
+- **O que aconteceu:** os componentes usam classes documentadas como `.btn.primary`, mas nenhum estilo aparece, mesmo com `@import "@codenhub/styles/tw"` na folha de estilos.
+- **Por quê:** raramente o problema é o próprio `@source` — o Tailwind já varre o seu projeto automaticamente. A causa mais comum é markup que fica num lugar que a varredura automática exclui por padrão: um caminho listado no `.gitignore` ou um componente vindo de `node_modules`. O Tailwind pode não ver uma classe usada só ali e deixa de gerar a regra dela.
+- **Como resolver:** adicione um `@source` explícito apontando para esse diretório, resolvido a partir desta folha de estilos — como no [exemplo acima](#importe-o-entrypoint-de-código-fonte).
+
+**Regras de token e de reset duplicadas**
+
+- **O que aconteceu:** a folha de estilos gerada está maior do que o esperado, e as devtools do navegador mostram as mesmas custom properties ou regras de reset definidas duas vezes.
+- **Por quê:** uma de duas coisas. Importar um entrypoint compilado (`@codenhub/styles`) e um entrypoint `/tw` (`@codenhub/styles/tw`) no mesmo build compila os mesmos tokens e o mesmo reset a partir de duas fontes independentes; o build do Tailwind não tem como saber que elas descrevem o mesmo pacote. Ou então a sua folha de estilos importa `tailwindcss` ao lado do `/tw`, que já o importa, e o Preflight é emitido duas vezes.
+- **Como resolver:** escolha um caminho por projeto — entrypoints `/tw` para um projeto que roda Tailwind CSS v4, entrypoints compilados em todos os outros — e remova o seu próprio `@import "tailwindcss"` quando importar o `/tw`.
+
+**Uma classe montada em tempo de execução fica sem estilo**
+
+- **O que aconteceu:** `<button class="btn primary">` é estilizado, mas um botão cuja intenção vem de uma variável, como `` `btn ${tone}` ``, não é.
+- **Por quê:** o Tailwind só gera uma classe quando encontra o nome completo nos seus arquivos de código. As classes de componente e de eixo do próprio pacote são sempre geradas, mas os seus próprios utilitários não, e um nome montado a partir de strings é invisível para a varredura.
+- **Como resolver:** escreva os nomes de classe completos no seu código, por exemplo num objeto de consulta (`{ save: "btn primary", remove: "btn destructive" }`), ou liste os nomes que o seu código pode produzir com `@source inline("...")` na sua folha de estilos.
+
+Todo entrypoint `/tw` exige Tailwind CSS 4.3.2 ou mais recente, abaixo da 5: o código-fonte usa `@source not` e `@source inline()`, que chegaram na 4.1, e é testado com a 4.3.2.
+
+## A variante `dark:`
+
+Os entrypoints `/tw` definem a sua própria variante `dark:`, então os seus utilitários trocam de tema com os mesmos seletores de claro e escuro que os tokens do pacote usam. Ela tem uma diferença conhecida em relação aos tokens quando há temas aninhados; veja [Temas → A variante dark:](../usage/theming.md#a-variante-dark).
+
+## 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. Tudo o que ela mostra funciona do mesmo jeito com `/tw`.

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

@@ -0,0 +1,31 @@
+---
+title: Vue
+description: Como carregar a folha de estilos numa aplicação Vue / Vite.
+order: 3
+source: 9cc23f66518b0aa3ce886602f39d05820b2b8bcf
+---
+
+# Vue
+
+O Vue não impõe restrição sobre de onde o CSS é importado, mas importá-lo uma vez, a partir do arquivo de entrada da aplicação, evita que o reset e os tokens carreguem mais de uma vez e garante que eles estejam no lugar antes de qualquer componente renderizar.
+
+## Importe a folha de estilos
+
+```ts
+// main.ts
+import "@codenhub/styles";
+import { createApp } from "vue";
+import App from "./App.vue";
+
+createApp(App).mount("#app");
+```
+
+Usa Tailwind CSS v4? Importe `@codenhub/styles/tw` a partir de um arquivo CSS de entrada em vez do `main.ts`, usando o plugin `@tailwindcss/vite` — veja [Tailwind CSS v4](./tailwind.md).
+
+## Force um tema
+
+Aplique `.dark` ou `.light` no elemento raiz 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.