@codenhub/styles 0.6.0 → 0.8.0

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

@@ -0,0 +1,75 @@
+---
+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: 2028acef66a8ab3659cef35e08ecc0db1de7bdeb
+---
+
+# 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, Laravel, Django ou qualquer aplicação sem etapa de build de CSS com Node.js | [Sem bundler](./without-a-bundler.md) |
+
+Um projeto sem framework — um build simples com Vite, webpack ou Parcel — importa a folha de estilos compilada a partir do arquivo CSS global que o projeto já tem, como mostra [Configuração → Importe a folha de estilos](../setup.md#importe-a-folha-de-estilos). Vite e webpack resolvem o nome do pacote como ele é; Parcel e PostCSS com `postcss-import` precisam da mudança abaixo. A folha de estilos compilada traz todas as classes; para entregar só as que as suas páginas usam sem adotar o Tailwind, escreva uma folha de estilos reduzida com o [comando `build`](./without-a-bundler.md#gere-só-as-classes-que-você-usa) do pacote e importe-a no lugar.
+
+### Bundlers que precisam de um empurrão
+
+As duas ferramentas encontram a folha de estilos assim que alguém diz como; nenhuma precisa de outro entrypoint.
+
+**Parcel.** Ative o suporte ao mapa `exports` de um pacote no seu `package.json`:
+
+```json
+{
+  "@parcel/resolver-default": {
+    "packageExports": true
+  }
+}
+```
+
+Depois importe o pacote com o prefixo `npm:` do Parcel, que diz a ele que o nome é um pacote, e não um arquivo ao lado da folha de estilos:
+
+```css
+@import "npm:@codenhub/styles";
+```
+
+**PostCSS com `postcss-import`.** O plugin não lê o mapa `exports` de um pacote, então o nome do pacote sozinho não é resolvido. Importe em vez disso o arquivo compilado pelo caminho em disco, relativo à sua própria folha de estilos, o mesmo arquivo que um `<link>` apontaria:
+
+```css
+@import "../node_modules/@codenhub/styles/dist/index.css";
+```
+
+Os outros entrypoints compilados funcionam do mesmo jeito, como `@codenhub/styles/dist/aesthetics/neobrutalism.css`.
+
+## 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,148 @@
+---
+title: Tailwind CSS v4
+description: Como usar os entrypoints de código-fonte /tw num projeto com Tailwind CSS v4.
+order: 1
+source: a86fe5fa121db14ab917b10fb69e839111ddbc47
+---
+
+# 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, de como construir seus próprios componentes com `@apply`, de como descartar a paleta do Tailwind 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 da pasta `tw/` do pacote; 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 código-fonte do pacote nomeia todas as classes que ele define, então varrê-lo emite todas elas, quer as suas páginas as usem ou não.
+
+## 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";
+```
+
+## Construa seus próprios componentes com `@apply`
+
+No `/tw`, todo componente, helper e classe de eixo é um utilitário do Tailwind. Isso inclui as intenções (`neutral`, `primary`, `secondary`, `success`, `warning`, `destructive`, `info`), a apresentação (`solid`, `soft`, `ghost`, `edged`, `edgeless`), a elevação (`flat`, `raised`, `floating`), os padrões de canto (`cut-diagonal`, `cut-diagonal-reverse`) e os tamanhos (`sm`, `lg`). Assim, uma classe sua pode carregar uma receita inteira:
+
+```css
+@import "@codenhub/styles/tw";
+
+@utility btn-save {
+  @apply btn primary soft sm;
+}
+
+@utility btn-danger {
+  @apply btn destructive md:lg dark:solid;
+}
+```
+
+```html
+<button class="btn-save" type="submit">Salvar</button>
+```
+
+- **Um componente aplicado se comporta como a classe.** `btn-save` reage ao hover, é pressionado, recebe foco e segue uma estética do mesmo jeito que `class="btn primary soft sm"`.
+- **Variantes funcionam.** `hover:primary`, `md:lg` e `dark:solid` aplicam uma classe de eixo sob essa condição, no seu markup ou dentro do `@apply`.
+- **Escreva a sua classe como `@utility`.** Assim ela fica na camada `utilities`, e os seus outros utilitários no mesmo elemento continuam vencendo. Uma regra simples `.btn-save { @apply … }` também funciona, mas fica sem camada, então o que ela aplica vence todos os utilitários do elemento; [Personalização → Helpers de composição](../usage/customizing.md#helpers-de-composição) tem os detalhes.
+- **Modificadores também se aplicam.** Os modificadores de um componente, como `.tight` no `.stack`, `.icon` no `.btn` ou `.interactive` no `.card`, também são utilitários, então `@apply stack tight`, `@apply btn icon pill` e `md:tight` funcionam. O estado desabilitado é a exceção: continua sendo um atributo ou a classe `.disabled` no markup.
+- **O seu utilitário vence os padrões internos de um componente.** `p-0 text-center` numa célula de `.data-table`, `text-sm` num `.label` e `px-8` num `.btn.sm` são todos aplicados.
+
+A página de [Predefinições](../usage/presets.md) compara isso com as outras formas de definir um visual uma única vez.
+
+## Descarte a paleta do Tailwind
+
+O `/tw` é construído sobre o tema padrão do Tailwind, então os utilitários da paleta do Tailwind, como `bg-red-500`, continuam disponíveis. Se o seu design usa só os tokens do pacote, limpe os tons que você não usa:
+
+```css
+@import "@codenhub/styles/tw";
+
+@theme {
+  --color-red-*: initial;
+  --color-orange-*: initial;
+  --color-yellow-*: initial;
+  --color-lime-*: initial;
+  --color-green-*: initial;
+  --color-teal-*: initial;
+  --color-cyan-*: initial;
+  --color-sky-*: initial;
+  --color-blue-*: initial;
+  --color-violet-*: initial;
+  --color-purple-*: initial;
+  --color-fuchsia-*: initial;
+  --color-pink-*: initial;
+  --color-slate-*: initial;
+  --color-gray-*: initial;
+  --color-zinc-*: initial;
+  --color-stone-*: initial;
+  --color-black: initial;
+}
+```
+
+As cores do próprio pacote não mudam, e você ainda pode acrescentar cores suas no mesmo bloco.
+
+O bloco deixa de fora `neutral`, `emerald`, `amber`, `rose`, `indigo` e `white` de propósito: o tema constrói as cores dele a partir deles.
+
+- **Não limpe o namespace inteiro.** `--color-*: initial` também remove as cores semânticas do pacote, e o build para com um erro como `Cannot apply unknown utility class`.
+- **Não limpe uma escala que o tema lê.** Limpar `--color-emerald-*` compila sem erro, mas as cores de sucesso feitas com ela se perdem.
+
+## 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 classe vem de uma variável, como `"btn " + variant`, ou de conteúdo de um CMS, não é.
+- **Por quê:** o Tailwind emite só as classes que encontra escritas por extenso nos arquivos que varre. Isso vale também para as classes de componente do pacote: um build com `/tw` emite `.alert` só se `alert` aparecer em algum lugar que ele varre, o que mantém a folha de estilos restrita ao que as suas páginas usam. As classes de intenção, de apresentação, de elevação, de canto e de tamanho, como `.primary`, `.soft` e `.sm`, também são utilitários, então o mesmo vale para elas. As classes de estética, como `.glass`, são CSS comum e sempre emitidas. Um nome montado em tempo de execução nunca aparece inteiro num arquivo, então a varredura não o encontra.
+- **Como resolver:** escreva cada nome de classe completo em algum lugar que o Tailwind varre, por exemplo num objeto de consulta (`{ save: "btn primary", remove: "btn destructive" }`), ou liste na sua folha de estilos os nomes que o seu código ou o seu conteúdo podem produzir:
+
+```css
+@import "@codenhub/styles/tw";
+
+@source inline("btn alert badge primary destructive soft");
+```
+
+Todo entrypoint `/tw` exige Tailwind CSS 4.3.2 ou mais recente, abaixo da 5 (`>=4.3.2 <5`).
+
+## 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.

package/docs/pt-BR/integrating/without-a-bundler.md

@@ -0,0 +1,238 @@
+---
+title: Sem bundler
+description: Como referenciar as folhas de estilos compiladas a partir de HTML puro, Rails, Laravel, Django ou qualquer aplicação renderizada no servidor, e o build por linha de comando.
+order: 6
+source: 6289ea781c99dcda5c027a72fede9e2f1cab8414
+---
+
+# Sem bundler
+
+As folhas de estilos compiladas são CSS pronto: cada uma é um único arquivo, sem `@import` e sem referência a outro arquivo, e toda imagem que ela desenha vem embutida como uma URL `data:`: as máscaras do visto e do traço do checkbox e os filtros SVG de lente que o `.glass-liquid` usa. Uma página pode carregar qualquer uma delas com uma tag `<link>` simples, de qualquer servidor, sem etapa de build, e a folha de estilos não faz nenhuma requisição adicional.
+
+O que precisa de uma ferramenta de build é o _nome_ do import. `@import "@codenhub/styles"` nomeia um pacote, e encontrar o arquivo por trás desse nome — `node_modules/@codenhub/styles/dist/index.css` — é trabalho de ferramentas que conhecem o Node, como Vite, webpack ou a CLI do Tailwind, que leem o mapa `exports` do pacote. Um navegador não faz isso: ele resolve a URL de um `@import` em relação à folha de estilos que o contém, e um `<link href>` em relação à página, então um nome de pacote solto vira uma requisição para um caminho que não existe. Sem bundler, referencie o arquivo pelo caminho.
+
+Os entrypoints `/tw` são código-fonte do Tailwind e precisam de um build do Tailwind. O `/tw/aesthetics` é a exceção, CSS puro sem nada para o Tailwind processar, mas sem bundler referencie os arquivos compilados de `dist/aesthetics/`, como abaixo. Esta página é para uma página que não tem um build de CSS com Node.js: HTML puro, Rails, Laravel, Django ou qualquer aplicação renderizada no servidor. Há dois caminhos:
+
+1. **Referencie a folha de estilos compilada.** Funciona hoje, só com arquivos estáticos. Você entrega todas as classes, usadas ou não pelas suas páginas.
+2. **Gere uma folha de estilos com o comando `build` do pacote.** Ela varre os seus templates e escreve uma folha de estilos com só as classes que eles usam. Veja [Gere só as classes que você usa](#gere-só-as-classes-que-você-usa).
+
+## Qual arquivo referenciar
+
+Cada caminho de import compilado é um arquivo na pasta `dist/` do pacote:
+
+| Caminho de import               | Arquivo                                                        |
+| ------------------------------- | -------------------------------------------------------------- |
+| `@codenhub/styles`              | `dist/index.css`                                               |
+| `@codenhub/styles/theme`        | `dist/theme.css`                                               |
+| `@codenhub/styles/components`   | `dist/components.css`                                          |
+| `@codenhub/styles/native`       | `dist/native.css`                                              |
+| `@codenhub/styles/palette`      | `dist/palette.css`                                             |
+| `@codenhub/styles/aesthetics`   | `dist/aesthetics/index.css`                                    |
+| `@codenhub/styles/aesthetics/*` | `dist/aesthetics/<name>.css`, como `dist/aesthetics/pixel.css` |
+
+Referencie um arquivo base só, não vários, porque eles se sobrepõem, e as estéticas que você usar. A ordem entre eles não importa, porque todo arquivo declara as [camadas de cascata](../setup.md#camadas-de-cascata) antes de usar qualquer uma. [Configuração → Todos os entrypoints](../setup.md#todos-os-entrypoints) explica o que cada um contém.
+
+## A partir de uma CDN
+
+O jsDelivr e o unpkg servem todos os arquivos de todas as versões publicadas no npm, então uma página pode referenciar um deles sem instalar nada:
+
+```html
+<head>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@codenhub/styles@0.8.0/dist/index.css" />
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@codenhub/styles@0.8.0/dist/aesthetics/pixel.css" />
+</head>
+```
+
+Coloque a versão exata na URL. Sem ela, a CDN serve a versão mais recente, e abaixo da 1.0 uma versão minor pode renomear ou remover uma classe; veja [Versionamento](../index.md#versionamento).
+
+## A partir do seu próprio servidor
+
+Instale o pacote e depois sirva a pasta `dist/` dele como arquivos estáticos:
+
+```sh
+npm install @codenhub/styles
+```
+
+Cada framework serve uma pasta de `node_modules` de um jeito, então cada um aparece abaixo. Quando o framework lê a pasta no lugar onde ela está, como fazem o Rails e o Django, atualizar o pacote e fazer um novo deploy é tudo o que uma atualização exige.
+
+### HTML puro
+
+Copie `node_modules/@codenhub/styles/dist` para a pasta que o seu servidor publica e depois referencie o arquivo:
+
+```html
+<link rel="stylesheet" href="/vendor/codenhub-styles/index.css" />
+```
+
+Repita a cópia a cada atualização, por exemplo a partir de um script `postinstall` do npm.
+
+### Ruby on Rails
+
+Uma aplicação Rails criada com `cssbundling-rails` já roda um bundler: importe o pacote a partir de `app/assets/stylesheets/application.css`, como em [Configuração → Importe a folha de estilos](../setup.md#importe-a-folha-de-estilos).
+
+Com Propshaft e sem bundler de CSS, adicione a pasta do pacote aos caminhos de assets:
+
+```ruby
+# config/initializers/assets.rb
+Rails.application.config.assets.paths << Rails.root.join("node_modules/@codenhub")
+```
+
+Depois referencie o arquivo no layout, pelo caminho dele dentro dessa pasta:
+
+```erb
+<%# app/views/layouts/application.html.erb %>
+<%= stylesheet_link_tag "styles/dist/index" %>
+<%= stylesheet_link_tag "styles/dist/aesthetics/pixel" %>
+```
+
+Aponte o caminho para `node_modules/@codenhub`, e não para o próprio `dist/`. O Propshaft serve os arquivos pelo caminho dentro de cada pasta de assets, então adicionar `dist/` diretamente publicaria um `index.css` solto, que colide com qualquer `index.css` seu.
+
+Os arquivos que você referencia ficam em `dist/`, que guarda só CSS pronto, mais um `index.d.ts` vazio para o TypeScript. O código-fonte do Tailwind fica em `tw/`, fora de `dist/`, então um pipeline estático que serve `dist/` ou aplica fingerprint aos arquivos dele não encontra nenhum `@import` que não consiga resolver.
+
+### Django
+
+Adicione a pasta a `STATICFILES_DIRS` com um prefixo, o que mantém os nomes dos arquivos dela separados dos seus próprios arquivos estáticos:
+
+```python
+# settings.py
+STATICFILES_DIRS = [
+    ("codenhub-styles", BASE_DIR / "node_modules/@codenhub/styles/dist"),
+]
+```
+
+```django
+{% load static %}
+<link rel="stylesheet" href="{% static 'codenhub-styles/index.css' %}" />
+```
+
+Aponte o prefixo para `dist`, não para a pasta do pacote. `dist/` contém só CSS pronto, mais um `index.d.ts` vazio para o TypeScript que o storage copia como está, então o `collectstatic` também funciona com `ManifestStaticFilesStorage`, que coloca uma impressão digital (hash) no nome de cada arquivo e reescreve as referências dentro dele. A pasta do pacote também contém o código-fonte do Tailwind em `tw/`, com linhas `@import "tailwindcss/..."` que esse storage não consegue resolver.
+
+### Laravel
+
+Uma aplicação Laravel roda Vite por padrão, então ela tem um bundler: importe o pacote a partir de `resources/css/app.css`, como em [Configuração → Importe a folha de estilos](../setup.md#importe-a-folha-de-estilos), e carregue esse arquivo com a diretiva `@vite`, como de costume.
+
+## Gere só as classes que você usa
+
+O pacote traz um comando, `codenhub-styles`, que o compila para você. Ele lê os seus templates atrás de nomes de classe e escreve uma única folha de estilos minificada com só as classes do StyleKit e os utilitários do Tailwind que eles usam. Uma página que usa um botão recebe uma pequena fração da folha de estilos completa; o tamanho exato depende das classes que você usa, porque cada componente traz as regras compartilhadas de que depende.
+
+O comando também serve com um bundler. Um projeto cujo bundler não roda o Tailwind, como um build simples com Vite ou webpack, pode escrever a folha de estilos entre os seus fontes, `--output src/stylekit.css`, e importar esse arquivo onde importaria `@codenhub/styles`. Um projeto que usa o Tailwind CSS v4 tem a mesma redução pelo [entrypoint de código-fonte](./tailwind.md) e não precisa do comando.
+
+Ele precisa do Node.js 24 ou mais recente na máquina que gera o CSS, seja o seu notebook, um job de CI ou uma etapa do deploy. Ele compila com o Tailwind CSS, que o pacote não instala por você, então um projeto que só linka a folha de estilos compilada nunca o baixa. Instale os três pacotes como dependências de desenvolvimento a partir da raiz do projeto; o npm cria um `package.json` se você não tiver um, e nenhuma configuração do Tailwind é necessária:
+
+```sh
+npm install --save-dev @codenhub/styles @tailwindcss/cli tailwindcss
+```
+
+A folha de estilos que o comando escreve é CSS puro, então os servidores que servem o seu site não precisam nem do Node.js nem de nenhum desses pacotes. Rode a partir da raiz do projeto:
+
+```sh
+npx codenhub-styles build --content "app/views/**/*.erb" --output public/stylekit.css
+```
+
+Quando dá certo, o comando imprime uma linha: o caminho absoluto que escreveu e o tamanho do arquivo em bytes:
+
+```text
+/home/you/shop/public/stylekit.css 25782 bytes
+```
+
+Referencie esse arquivo no seu layout como qualquer folha de estilos estática.
+
+### Views do Rails
+
+```sh
+npx codenhub-styles build --content "app/views/**/*.erb" --content "app/helpers/**/*.rb" --output public/stylekit.css
+```
+
+```erb
+<%# app/views/layouts/application.html.erb %>
+<link rel="stylesheet" href="/stylekit.css" />
+```
+
+### Views Blade do Laravel
+
+```sh
+npx codenhub-styles build --content "resources/views/**/*.blade.php" --output public/css/stylekit.css
+```
+
+```blade
+{{-- resources/views/layouts/app.blade.php --}}
+<link rel="stylesheet" href="{{ asset('css/stylekit.css') }}" />
+```
+
+### Templates do Django
+
+Um projeto Django guarda os templates numa pasta `templates/` do projeto, na pasta `templates/` de cada app, ou nas duas. Passe um `--content` para cada lugar onde ficam os seus, e deixe de fora os que você não usa, porque um glob que não casa com nada faz o build falhar:
+
+```sh
+npx codenhub-styles build --content "templates/**/*.html" --content "shop/templates/**/*.html" --output static/stylekit.css
+```
+
+```django
+{% load static %}
+<link rel="stylesheet" href="{% static 'stylekit.css' %}" />
+```
+
+Escreva a saída numa pasta listada em `STATICFILES_DIRS`, aqui `static/`, para que o `collectstatic` a recolha. A configuração acima lista só a pasta do pacote, então adicione `BASE_DIR / "static"` a essa lista se o seu projeto ainda não a tiver.
+
+### Opções
+
+- `--content <glob>`, ou `-c <glob>`, indica os arquivos onde procurar nomes de classe. É obrigatório e pode ser repetido: passe uma vez por glob, e o build lê todo arquivo que casar com algum deles. Um glob relativo é resolvido em relação à pasta de onde você roda o comando, então rode a partir da raiz do projeto; um glob absoluto é usado como está. `**` casa com qualquer número de pastas, e `{rb,erb}` com qualquer uma das duas extensões. Qualquer arquivo de texto serve, seja qual for a extensão. Cada glob precisa casar com pelo menos um arquivo, senão o build falha e o nomeia, então um erro de digitação não consegue publicar uma folha de estilos vazia. Arquivos que o seu `.gitignore` exclui são lidos mesmo assim quando um glob casa com eles, e nada fora dos seus globs é lido.
+- Coloque cada glob entre aspas. Sem aspas, o seu shell pode expandir o glob numa lista de arquivos antes de o comando vê-lo, e só o primeiro arquivo conta como valor do `--content`. Quando isso deixa nomes de arquivo sobrando, o build os rejeita em vez de ler em silêncio menos do que você queria; quando o glob casou com um único arquivo, o build lê só esse arquivo e nada que os seus templates ganharem depois.
+- `--output <file>`, ou `-o <file>`, é a folha de estilos a escrever. É obrigatório. Um caminho relativo é resolvido em relação à pasta de onde você roda o comando, pastas-pai que faltam são criadas, e um arquivo existente é substituído.
+- `--aesthetic <name>` acrescenta uma das [estéticas](../usage/aesthetics.md): `neobrutalism`, `glass`, `pixel`, `chunky-tile`, `cyber` ou `sketch`. Repita para mais de uma; nomear uma duas vezes a inclui uma vez só. As estéticas precisam ser pedidas porque o build não tem como saber pelos seus templates qual você quer, então cada uma é escrita inteira quando você a pede, e nenhuma entra quando você não pede.
+- `--no-minify` escreve CSS legível e indentado no lugar. Útil para ler o que o build gerou; em produção, sirva o arquivo minificado.
+- `--help` imprime o uso, com as estéticas que esta versão traz. `--version` imprime a versão do pacote. Nenhum dos dois gera nada, e os dois terminam com status 0.
+
+A saída sempre traz o tema, os design tokens dele como propriedades personalizadas de CSS, o reset e as regras base de que todo componente depende. Por cima vêm cada classe do StyleKit que os seus templates usam, com as variantes com que você a combina, como `primary` ou `soft`, e cada utilitário do Tailwind que eles usam, como `flex` ou `mt-4`. A saída é gerada a partir da folha de estilos completa, não da `/native`, então não inclui os mapeamentos sem classes.
+
+### Como as classes são encontradas
+
+O build não executa os seus templates. Ele lê como texto puro cada arquivo que casa com os seus globs de `--content`, recolhe cada palavra que poderia ser um nome de classe e escreve as regras das palavras que são classes do StyleKit ou utilitários do Tailwind. É assim que o Tailwind CSS também lê o conteúdo.
+
+Uma classe precisa aparecer num arquivo como uma palavra inteira. `class="btn primary"`, `class: "btn primary"` e `classes = ["btn", "primary"]` funcionam. Uma palavra que só parece uma classe também conta: um comentário que diz "card" adiciona todas as regras do card à folha de estilos, o que aumenta o arquivo e não muda nada na página.
+
+Um nome de classe que o seu código monta na renderização nunca aparece inteiro em nenhum arquivo, então o build não consegue encontrá-lo. Em `class="btn <%= @order.priority %>"`, o `btn` é encontrado, mas a intenção é o que `priority` tiver na hora de renderizar; se for `destructive`, o botão aparece sem o vermelho dele. Há duas saídas:
+
+- **Escreva os nomes de classe inteiros.** Associe cada valor a um nome de classe completo num arquivo que o build leia, como `{ "urgent" => "destructive", "normal" => "neutral" }.fetch(@order.priority)` num helper.
+- **Liste-os num arquivo de safelist.** Um arquivo de texto puro com um nome de classe por linha, adicionado com o seu próprio `--content`, como `--content config/stylekit-classes.txt`. Guarde-o perto do código que monta os nomes de classe, para que quem mudar um veja o outro.
+
+### O que ele não faz
+
+- **Não tem modo watch.** Ele gera uma vez e termina. Rode de novo depois de mudar um template, a partir de um script ou de um observador de arquivos que o seu framework ou editor já tenha. Uma classe que a folha de estilos ainda não tem deixa o elemento sem estilo até o próximo build.
+- **Não tem arquivo de configuração nem CSS próprio.** Você não consegue acrescentar os seus próprios valores de `@theme`, definições de `@utility` nem plugins. Para mudar o visual, sobrescreva as propriedades personalizadas numa folha de estilos sua carregada depois desta, como [Personalização](../usage/customizing.md) descreve. Quando você precisar da configuração do próprio Tailwind, instale o Tailwind CSS e importe o entrypoint de código-fonte a partir da sua própria entrada do Tailwind, como [Tailwind CSS v4](./tailwind.md) mostra.
+- **Não tem outros comandos.** `build` é o único; `--help` e `--version` são as únicas flags que funcionam sem ele.
+- **Não traz uma versão do Tailwind própria.** Cada build usa os `@tailwindcss/cli` e `tailwindcss` instalados no seu projeto, dentro da faixa `>=4.3.2 <5` que o StyleKit suporta, então o seu lockfile os fixa.
+
+### Num deploy
+
+Gere a folha de estilos antes da etapa que recolhe ou aplica fingerprint aos seus assets, como `rails assets:precompile`, `php artisan optimize` ou `python manage.py collectstatic`. Você pode fazer commit da saída, e aí os servidores não precisam de Node.js nenhum, ao custo de um arquivo gerado que alguém precisa lembrar de regenerar; ou gerá-la no deploy, e aí a máquina de build precisa do Node.js 24 ou mais recente.
+
+Fixe a versão. Abaixo da 1.0 uma versão minor pode renomear ou remover uma classe, então o mesmo comando pode escrever outra folha de estilos com uma versão mais nova. Faça commit do `package.json` e do lockfile que o npm escreve, e instale com `npm ci` na máquina de build, para que cada build use as versões que você testou.
+
+### Quando o build falha
+
+Toda falha imprime uma linha começando com `codenhub-styles:` na saída de erro padrão e termina com status 1, sem escrever o arquivo de saída, então um script de deploy para em vez de publicar uma folha de estilos desatualizada ou vazia. A linha diz o que deu errado e o que fazer:
+
+- **`missing --content` ou `missing --output`.** Acrescente a que ela nomeia. Um `--output` vazio ou só com espaços conta como ausente.
+- **`--content "<glob>" matches no file in <folder>`.** Em geral é um erro de digitação no caminho, um comando rodado de outra pasta que não a raiz do projeto, ou um glob de um lugar que o seu projeto não usa. Gerar a partir de nada escreveria uma folha de estilos sem classes de componente, e o site perderia o estilo sem aviso.
+- **`unexpected argument "<file>"`.** Quase sempre é um glob de `--content` sem aspas, que o seu shell expandiu numa lista de arquivos. Coloque o glob entre aspas.
+- **`unknown option "<flag>"`.** Um erro de digitação, ou uma opção de outra ferramenta, como `--watch` ou `--config`. `--help` lista as opções.
+- **`option "<flag>" is missing its value or does not take one`.** Uma flag que leva valor foi a última coisa da linha, ou o `--no-minify` recebeu um valor, como em `--no-minify=true`.
+- **`unknown aesthetic "<name>"; choose from ...`.** Escolha um dos nomes listados. Eles são em minúsculas e com hífen, como `chunky-tile`.
+- **`missing command` ou `unknown command "<name>"`.** A primeira palavra depois de `codenhub-styles` precisa ser `build`.
+- **`this command needs @tailwindcss/cli and tailwindcss, which are not installed`.** A linha nomeia o que estiver faltando dos dois e termina com o comando que o instala. Rode esse comando a partir da raiz do projeto.
+- **`this command needs Node.js 24 or newer`.** Atualize o Node.js na máquina que gera o CSS.
+- **`Tailwind failed to build the stylesheet: <reason>`.** `<reason>` é a própria mensagem do Tailwind. `EISDIR` quer dizer que o `--output` nomeia uma pasta existente, então nomeie um arquivo dentro dela; `EACCES` ou `EPERM` quer dizer que você não pode escrever ali. Para qualquer outro motivo, rode o mesmo comando com `--no-minify` para descartar o minificador, e informe a mensagem junto com a versão que o `--version` imprime.
+
+## Conferindo se funcionou
+
+Renderize um elemento estilizado, como em [Integração → Conferindo se funcionou](./index.md#conferindo-se-funcionou):
+
+```html
+<button class="btn primary">Save changes</button>
+```
+
+Um botão arredondado preenchido com a cor primária significa que a folha de estilos carregou. Se o botão parecer o padrão do navegador, abra o painel de rede do navegador: um `404` na folha de estilos significa que o caminho ou a configuração de arquivos estáticos está errado.
+
+## 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.