@codenhub/styles 0.7.0 → 0.8.0

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

@@ -1,6 +1,6 @@
 ---
 title: Without a bundler
-description: Linking the compiled stylesheets from plain HTML, Rails, Django, or any server-rendered app.
+description: Linking the compiled stylesheets from plain HTML, Rails, Laravel, Django, or any server-rendered app, and the command-line build.
 order: 6
 ---
 
@@ -10,7 +10,10 @@ The compiled stylesheets are finished CSS: each one is a single file with no `@i
 
 What needs a build tool is the import _name_. `@import "@codenhub/styles"` names a package, and finding the file behind that name — `node_modules/@codenhub/styles/dist/index.css` — is done by Node-aware tooling such as Vite, webpack, or the Tailwind CLI, which read the package's `exports` map. A browser does not: it resolves an `@import` URL against the stylesheet that contains it and a `<link href>` against the page, so a bare package name becomes a request for a path that does not exist. Without a bundler, link the file by its path instead.
 
-The `/tw` entrypoints are Tailwind source and need a Tailwind build. `/tw/aesthetics` is the exception, plain CSS with nothing for Tailwind to process, but without a bundler link the compiled `dist/aesthetics/` files instead, as below. This page covers the compiled entrypoints only, for a page that has no CSS build at all: plain HTML, Rails, Django, or any server-rendered app.
+The `/tw` entrypoints are Tailwind source and need a Tailwind build. `/tw/aesthetics` is the exception, plain CSS with nothing for Tailwind to process, but without a bundler link the compiled `dist/aesthetics/` files instead, as below. This page is for a page that has no Node.js CSS build: plain HTML, Rails, Laravel, Django, or any server-rendered app. There are two paths:
+
+1. **Link the compiled stylesheet.** Works today, with nothing but static files. You ship every class, whether your pages use it or not.
+2. **Build a stylesheet with the package's `build` command.** It scans your templates and writes a stylesheet with only the classes they use. See [Build only the classes you use](#build-only-the-classes-you-use).
 
 ## Which file to link
 
@@ -26,14 +29,17 @@ Each compiled import path is one file in the package's `dist/` folder:
 | `@codenhub/styles/aesthetics`   | `dist/aesthetics/index.css`                                       |
 | `@codenhub/styles/aesthetics/*` | `dist/aesthetics/<name>.css`, such as `dist/aesthetics/pixel.css` |
 
-Link the base file first and an aesthetic after it. [Setup → All entrypoints](../setup.md#all-entrypoints) explains what each one contains; link one base file, not several, since they overlap.
+Link one base file, not several, since they overlap, and any aesthetics you use. Their order does not matter, because every file declares the [cascade layers](../setup.md#cascade-layers) before using one. [Setup → All entrypoints](../setup.md#all-entrypoints) explains what each one contains.
 
 ## From a CDN
 
 jsDelivr and unpkg serve every file of every published npm version, so a page can link one with nothing installed:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@codenhub/styles@0.7.0/dist/index.css" /> <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@codenhub/styles@0.7.0/dist/aesthetics/pixel.css" />
+<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>
 ```
 
 Put the exact version in the URL. Without one, the CDN serves the latest release, and below 1.0 a minor release may rename or remove a class; see [Versioning](../index.md#versioning).
@@ -79,6 +85,8 @@ Then link it from the layout, by its path below that folder:
 
 Point the path at `node_modules/@codenhub` rather than at `dist/` itself. Propshaft serves files by their path below each asset folder, so adding `dist/` directly would publish a bare `index.css` that collides with any `index.css` of your own.
 
+The files you link are in `dist/`, which holds only finished CSS, plus an empty `index.d.ts` for TypeScript. The Tailwind source lives in `tw/`, outside `dist/`, so a static pipeline that serves or fingerprints `dist/` meets no `@import` it cannot resolve.
+
 ### Django
 
 Add the folder to `STATICFILES_DIRS` under a prefix, which keeps its file names apart from your own static files:
@@ -95,10 +103,125 @@ STATICFILES_DIRS = [
 <link rel="stylesheet" href="{% static 'codenhub-styles/index.css' %}" />
 ```
 
+Point the prefix at `dist`, not at the package folder. `dist/` holds only finished CSS, plus an empty `index.d.ts` for TypeScript that the storage copies as it is, so `collectstatic` also works with `ManifestStaticFilesStorage`, which fingerprints each file and rewrites the references inside it. The package folder also holds the Tailwind source in `tw/`, whose `@import "tailwindcss/..."` lines that storage cannot resolve.
+
 ### Laravel
 
 A Laravel app runs Vite by default, so it has a bundler: import the package from `resources/css/app.css` as in [Setup → Import the stylesheet](../setup.md#import-the-stylesheet), and load that file with the `@vite` directive as usual.
 
+## Build only the classes you use
+
+The package carries a command, `codenhub-styles`, that compiles it for you. It reads your templates for class names and writes one minified stylesheet with only the StyleKit classes and Tailwind utilities they use. A page that uses one button gets a small fraction of the full stylesheet; the exact size depends on which classes you use, since each component brings the shared rules it relies on.
+
+The command works with a bundler too. A project whose bundler does not run Tailwind, such as a plain Vite or webpack build, can write the stylesheet into its sources, `--output src/stylekit.css`, and import that file where it would import `@codenhub/styles`. A project that runs Tailwind CSS v4 gets the same trimming from the [source entrypoint](./tailwind.md) and does not need the command.
+
+It needs Node.js 24 or newer on the machine that builds the CSS, whether that is your laptop, a CI job, or a deploy step. It compiles with Tailwind CSS, which the package does not install for you, so a project that only links the compiled stylesheet never downloads it. Install the three packages as development dependencies from your project root; npm creates a `package.json` if you have none, and you need no Tailwind configuration:
+
+```sh
+npm install --save-dev @codenhub/styles @tailwindcss/cli tailwindcss
+```
+
+The stylesheet the command writes is plain CSS, so the servers that serve your site need neither Node.js nor any of these packages. Run it from your project root:
+
+```sh
+npx codenhub-styles build --content "app/views/**/*.erb" --output public/stylekit.css
+```
+
+On success the command prints one line, the absolute path it wrote and the file's size in bytes:
+
+```text
+/home/you/shop/public/stylekit.css 25782 bytes
+```
+
+Link that file from your layout like any static stylesheet.
+
+### Rails views
+
+```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" />
+```
+
+### Laravel Blade views
+
+```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') }}" />
+```
+
+### Django templates
+
+A Django project keeps templates in a project-level `templates/` folder, in each app's own `templates/` folder, or both. Give one `--content` for each place yours live, and leave out any place you do not use, since a glob that matches nothing fails the build:
+
+```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' %}" />
+```
+
+Write the output into a folder listed in `STATICFILES_DIRS`, here `static/`, so `collectstatic` picks it up. The settings above list only the package's folder, so add `BASE_DIR / "static"` to that list if your project does not have it yet.
+
+### Options
+
+- `--content <glob>`, or `-c <glob>`, names the files to read for class names. It is required and repeatable: pass it once per glob, and the build reads every file any of them matches. A relative glob is resolved against the folder you run the command in, so run it from your project root; an absolute glob is used as given. `**` matches any number of folders, and `{rb,erb}` either extension. Any text file works, whatever its extension. Each glob has to match at least one file, or the build fails and names it, so a typo cannot ship an empty stylesheet. Files your `.gitignore` excludes are still read when a glob matches them, and nothing outside your globs is read.
+- Quote every glob. Without quotes, your shell may expand the glob into a list of files before the command sees it, and only the first file counts as the `--content` value. When that leaves extra file names behind, the build rejects them rather than silently reading less than you meant; when the glob matched a single file, the build reads just that file and nothing your templates add later.
+- `--output <file>`, or `-o <file>`, is the stylesheet to write. It is required. A relative path is resolved against the folder you run the command in, missing parent folders are created, and an existing file is replaced.
+- `--aesthetic <name>` adds one of the [aesthetics](../usage/aesthetics.md): `neobrutalism`, `glass`, `pixel`, `chunky-tile`, `cyber`, or `sketch`. Repeat it for more than one; naming one twice includes it once. Aesthetics are opt-in because the build cannot tell from your templates which one you want, so each is written in full when you ask for it, and none is included when you do not.
+- `--no-minify` writes readable, indented CSS instead. Useful for reading what the build produced; serve the minified file.
+- `--help` prints the usage, with the aesthetics this version ships. `--version` prints the package version. Both build nothing and exit with status 0.
+
+The output always holds the theme, its design tokens as CSS custom properties, the reset, and the base rules every component relies on. On top of that come each StyleKit class your templates use, with the variants you combine it with, such as `primary` or `soft`, and each Tailwind utility they use, such as `flex` or `mt-4`. The output is built from the complete stylesheet, not from `/native`, so it has no classless mappings.
+
+### How classes are found
+
+The build does not run your templates. It reads each file your `--content` globs match as plain text, collects every word that could be a class name, and writes the rules for the words that are StyleKit classes or Tailwind utilities. This is how Tailwind CSS reads content too.
+
+A class has to appear in a file as one whole word. `class="btn primary"`, `class: "btn primary"`, and `classes = ["btn", "primary"]` all work. A word that only looks like a class also counts: a comment that says "card" adds the card's full rules to the stylesheet, which makes the file larger and changes nothing on the page.
+
+A class name your code assembles while rendering never appears whole in any file, so the build cannot find it. In `class="btn <%= @order.priority %>"`, `btn` is found, but the intent is whatever `priority` holds at render time; if that is `destructive`, the button renders without its red. Two ways out:
+
+- **Write class names whole.** Map each value to a complete class name in a file the build reads, such as `{ "urgent" => "destructive", "normal" => "neutral" }.fetch(@order.priority)` in a helper.
+- **List them in a safelist file.** A plain text file with one class name per line, added with its own `--content`, such as `--content config/stylekit-classes.txt`. Keep it next to the code that builds the class names, so whoever changes one sees the other.
+
+### What it does not do
+
+- **No watch mode.** It builds once and exits. Run it again after you change a template, from a script, or from a file watcher your framework or editor already has. A class the stylesheet does not have yet leaves its element unstyled until the next build.
+- **No configuration file and no custom CSS.** You cannot add your own `@theme` values, `@utility` definitions, or plugins. To change the look, override the custom properties in a stylesheet of your own loaded after this one, as [Customizing](../usage/customizing.md) describes. When you need Tailwind's own configuration, install Tailwind CSS and import the source entrypoint from your own Tailwind input, as [Tailwind CSS v4](./tailwind.md) shows.
+- **No other commands.** `build` is the only one; `--help` and `--version` are the only flags that run without it.
+- **No Tailwind version of its own.** Each build uses the `@tailwindcss/cli` and `tailwindcss` installed in your project, within the `>=4.3.2 <5` range StyleKit supports, so your lockfile pins them.
+
+### In a deploy
+
+Build the stylesheet before whatever step collects or fingerprints your assets, such as `rails assets:precompile`, `php artisan optimize`, or `python manage.py collectstatic`. Either commit the output, so the servers need no Node.js at all at the cost of a generated file someone has to remember to rebuild, or build it on deploy, so the build machine needs Node.js 24 or newer.
+
+Pin the version. Below 1.0 a minor release may rename or remove a class, so the same command can write a different stylesheet with a newer version. Commit `package.json` and the lockfile npm writes, and install with `npm ci` on the build machine, so every build uses the versions you tested.
+
+### When the build fails
+
+Every failure prints one line starting with `codenhub-styles:` to standard error and exits with status 1, without writing the output file, so a deploy script stops instead of shipping a stale or empty stylesheet. The line says what went wrong and what to do:
+
+- **`missing --content` or `missing --output`.** Add the one it names. An `--output` that is empty or only spaces counts as missing.
+- **`--content "<glob>" matches no file in <folder>`.** Usually a typo in the path, a command run from another folder than your project root, or a glob for a place your project does not use. Building from nothing would write a stylesheet with no component classes, and the site would quietly lose its styling.
+- **`unexpected argument "<file>"`.** Almost always a `--content` glob without quotes, which your shell expanded into a list of files. Quote the glob.
+- **`unknown option "<flag>"`.** A typo, or an option from another tool, such as `--watch` or `--config`. `--help` lists the options.
+- **`option "<flag>" is missing its value or does not take one`.** A flag that takes a value was the last thing on the line, or `--no-minify` was given one, as in `--no-minify=true`.
+- **`unknown aesthetic "<name>"; choose from ...`.** Pick one of the names listed. They are lowercase and hyphenated, as in `chunky-tile`.
+- **`missing command` or `unknown command "<name>"`.** The first word after `codenhub-styles` has to be `build`.
+- **`this command needs @tailwindcss/cli and tailwindcss, which are not installed`.** The line names whichever of the two is missing and ends with the command that installs it. Run that from your project root.
+- **`this command needs Node.js 24 or newer`.** Update Node.js on the machine that builds the CSS.
+- **`Tailwind failed to build the stylesheet: <reason>`.** `<reason>` is Tailwind's own message. `EISDIR` means `--output` names an existing folder, so name a file inside it; `EACCES` or `EPERM` means you cannot write there. For any other reason, run the same command with `--no-minify` to rule out the minifier, and report the message with the version from `--version`.
+
 ## Verifying it worked
 
 Render one styled element, as in [Integrating → Verifying it worked](./index.md#verifying-it-worked):

package/docs/pt-BR/accessibility.md

@@ -2,7 +2,7 @@
 title: Acessibilidade
 description: O que o CSS faz por foco, estados, movimento, contraste, cores forçadas e texto da direita para a esquerda, e o que a sua aplicação ainda deve aos seus usuários.
 order: 5
-source: dc1a745e9e6853a31ca4a8cf7a334031bab1ec7d
+source: 88ce6c4707ee04ac76cdb5e6b31dcca399a5327e
 ---
 
 # Acessibilidade
@@ -15,14 +15,14 @@ Esta página lista as duas metades: o que o CSS fornece e o que a sua aplicaçã
 
 ### Foco e estado
 
-| Recurso                         | Comportamento                                                                                                                                                                                                                                                                                                                                              |
-| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `:focus-visible`                | Um outline de foco em todo elemento, desenhado com `--focus-ring`, `--focus-ring-width` e `--focus-ring-offset`.                                                                                                                                                                                                                                           |
-| Foco em controles de formulário | `.ipt`, `.textarea` e `.select` desenham o outline de foco e mudam a borda para a cor da intenção. O texto digitado num campo com classe de intenção fica no tom legível da intenção, `--intent-strong`.                                                                                                                                                   |
-| Controles inválidos             | `aria-invalid="true"` num controle de formulário deixa a borda, a cor de foco e o texto digitado na cor destrutiva, com o texto no tom legível destrutivo.                                                                                                                                                                                                 |
-| Controles desabilitados         | `disabled`, `aria-disabled="true"`, `data-disabled` e `.disabled` mostram o cursor e a opacidade de desabilitado, e um controle desabilitado não reage ao hover, inclusive dentro de um `.input-group`.                                                                                                                                                    |
-| Estado aberto                   | `data-state="open"` num `.tooltip` mostra o balão sem hover nem foco, e `data-state="closed"` o esconde durante o hover ou o foco. Nenhum outro componente lê nenhum dos dois.                                                                                                                                                                             |
-| `<dialog>` nativo               | Um `<dialog>` com `.card`, `.panel` ou `.surface` fica escondido até ser aberto, e abre centralizado. Uma margem que você define no dialog, como utilitário ou no seu próprio CSS, ainda substitui a centralização. Outros dialogs não são afetados. Prender o foco, fechar com Escape e tornar inerte a página por trás ficam por conta da sua aplicação. |
+| Recurso                         | Comportamento                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `:focus-visible`                | Um outline de foco em todo elemento, desenhado com `--focus-ring`, `--focus-ring-width` e `--focus-ring-offset`. Num componente com preenchimento acima da metade da intensidade, como um botão `.solid.primary`, uma linha de 2px da cor da página corre por dentro do anel, então o anel continua visível sobre um preenchimento da mesma cor.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Foco em controles de formulário | `.ipt`, `.textarea` e `.select` desenham o outline de foco e mudam a borda para a cor da intenção. O texto digitado num campo com classe de intenção fica no tom legível da intenção, `--intent-strong`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| Controles inválidos             | `aria-invalid="true"` num controle de formulário deixa a borda, a cor de foco e o texto digitado na cor destrutiva, com o texto no tom legível destrutivo. Um checkbox, radio ou switch é desenhado exatamente como a sua versão `.destructive`, marca de seleção incluída.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Controles desabilitados         | `disabled`, `aria-disabled="true"`, `data-disabled` e `.disabled` mostram o cursor e a opacidade de desabilitado, e um controle desabilitado não reage ao hover, inclusive dentro de um `.input-group`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Estado aberto                   | `data-state="open"` num `.tooltip` mostra o balão sem hover nem foco, e `data-state="closed"` o esconde durante o hover ou o foco. Nenhum outro componente lê nenhum dos dois.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `<dialog>` nativo               | Um `<dialog>` com `.card`, `.panel`, `.surface` ou uma classe sua que faz `@apply surface` fica escondido até ser aberto, e abre centralizado. Uma margem que você define no dialog, como utilitário ou no seu próprio CSS, ainda substitui a centralização, exceto que um utilitário de margem não substitui quando a sua classe aplica `surface` em CSS simples; veja [Personalização → Helpers de composição](./usage/customizing.md#helpers-de-composição). Com a [folha de estilos sem classes](./setup.md#html-sem-classes), um `<dialog>` puro é um `.card.floating` e se comporta do mesmo jeito; com os outros entrypoints, um dialog sem nenhuma dessas classes não é afetado. Prender o foco, fechar com Escape e tornar inerte a página por trás ficam por conta da sua aplicação. |
 
 ### Conteúdo visualmente oculto
 
@@ -34,7 +34,7 @@ O WCAG 1.4.11 pede que o limite de um controle que você precisa ver para usá-l
 
 | Recurso                           | Comportamento                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Controles de texto em repouso     | A borda de um controle de texto fica, em repouso, mais clara que a borda cheia da sua intenção, abaixo de 3:1 por escolha, para que o hover e o foco tenham um tom mais forte para onde mudar.                                                                                                                                                                                                                                                                                                        |
+| Controles de texto em repouso     | A borda de um controle de texto fica, em repouso, mais clara que a borda cheia da sua intenção, abaixo de 3:1 por escolha, para que o hover e o foco tenham um tom mais forte para onde mudar. [Contraste aumentado](#contraste-aumentado) a desenha cheia.                                                                                                                                                                                                                                           |
 | Toggles                           | `.checkbox`, `.radio` e `.switch` desenham a borda cheia, porque a borda é a única coisa que mostra uma caixa desmarcada. Um `.switch` com o seu próprio `.edgeless` é a exceção, abaixo.                                                                                                                                                                                                                                                                                                             |
 | `.edgeless` vindo de um contêiner | Ignorado por todo controle de texto e toggle: um contêiner não pode remover a borda de um campo ou toggle dentro dele.                                                                                                                                                                                                                                                                                                                                                                                |
 | `.edgeless` no próprio controle   | `.ipt`, `.textarea`, `.select` e `.switch` perdem a borda e deixam de atender ao 1.4.11 em repouso. `.switch.ghost` mantém a borda mesmo assim, porque, sem preenchimento e sem borda, nada mostraria o trilho.                                                                                                                                                                                                                                                                                       |
@@ -59,11 +59,11 @@ Sem classe de intenção, o contorno é o cinza de borda discreto, `--color-bord
 
 ### Movimento e transparência
 
-| Recurso                            | Comportamento                                                                                                                                                                                                |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Movimento reduzido, componentes    | Com `prefers-reduced-motion: reduce`, todo componente para as suas próprias transições e animações: o brilho do skeleton e do progresso, a barra indeterminada, o tooltip, as marcas dos toggles e o clique. |
-| Movimento reduzido, página inteira | O reset também encurta todas as outras animações e transições da página.                                                                                                                                     |
-| Transparência reduzida             | Com `prefers-reduced-transparency: reduce`, `.glass` e `.glass-liquid` perdem o desfoque e a lente e ficam opacos.                                                                                           |
+| Recurso                            | Comportamento                                                                                                                                                                                                                                                                                                                                                         |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Movimento reduzido, componentes    | Com `prefers-reduced-motion: reduce`, todo componente para as suas próprias transições e animações: o brilho do skeleton e do progresso, a barra indeterminada, o tooltip, as marcas dos toggles e o movimento do clique. O clique em si ainda acontece, de imediato, no visual padrão e sob toda estética e classe solo, porque é o sinal de que ele foi registrado. |
+| Movimento reduzido, página inteira | O reset também encurta todas as outras animações e transições da página.                                                                                                                                                                                                                                                                                              |
+| Transparência reduzida             | Com `prefers-reduced-transparency: reduce`, e em cores forçadas, `.glass`, `.glass-liquid` e `.glass-solo` perdem o desfoque e a lente e ficam opacos.                                                                                                                                                                                                                |
 
 A regra de movimento reduzido de cada componente vem com o componente, então todo entrypoint que o inclui respeita o movimento reduzido sem o reset, incluindo `@codenhub/styles/components`, `@codenhub/styles/tw/components` e cada entrypoint de componente `/tw/*`. Os entrypoints completos e nativos adicionam a regra do reset para a página inteira.
 
@@ -85,30 +85,49 @@ A regra do reset é `!important` dentro da camada `base`, e um `!important` com
 
 Respeitar o movimento reduzido não é o requisito inteiro. Um movimento que continua ao lado do conteúdo, como um brilho deixado num card depois que ele carregou, precisa de uma forma de ser parado por qualquer usuário; veja [Feedback → Animação que não para](./usage/feedback.md#animação-que-não-para).
 
+### Contraste aumentado
+
+Com `prefers-contrast: more`, as bordas que o pacote desenha abaixo de 3:1 por escolha são desenhadas a 3:1 ou mais em relação ao que está ao lado, nos dois temas. O texto, os preenchimentos sólidos e os anéis de foco já atendem às suas proporções e não mudam. `prefers-contrast: less` não é lido.
+
+| Recurso             | Comportamento                                                                                                                                                                                                                                                                         |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Controles de texto  | `.ipt`, `.textarea`, `.select` e `.input-group` ficam em repouso com a borda cheia, então o hover e o foco não mudam mais o tom dela. O anel de foco é o mesmo.                                                                                                                       |
+| Bordas neutras      | `--color-border` assume um cinza mais forte, `neutral-600` no claro e `neutral-400` no escuro, então a borda de um card, um divisor, as linhas de uma tabela e a borda de um botão ou badge neutro atendem a 3:1. Se você mesmo define `--color-border`, a sua cor é mantida; meça-a. |
+| Bordas de intenção  | A borda de uma intenção assume o tom forte dela, `--color-<intent>-strong`, então `.edged` num `.alert`, `.panel`, `.badge`, `.kbd`, `.code` ou `.pre` `.soft` atende a 3:1 tanto em relação ao preenchimento quanto à página, em todas as intenções.                                 |
+| Trilho de progresso | O trilho desenha um contorno na sua cor de borda, que atende a 3:1 com ou sem classe de intenção. `.edgeless` na barra ou em um contêiner continua removendo o contorno.                                                                                                              |
+| Glass               | `.glass`, `.glass-liquid` e `.glass-solo` perdem o desfoque e a lente e ficam opacos, como na transparência reduzida, e a linha branca deles vira uma borda cinza.                                                                                                                    |
+| Chunky tile         | `.chunky-tile` desenha as peças e as superfícies com o cinza mais forte que os seus controles usam.                                                                                                                                                                                   |
+
+O que você remove continua removido: `.edgeless` num controle continua tirando a borda dele, e um `.panel` continua sem borda a menos que você adicione `.edged`.
+
 ### Cor e contraste
 
 As medições abaixo são das cores entregues. Assim que você mudar um token de cor, meça de novo os seus próprios pares; [Temas → Mude a cor da marca](./usage/theming.md#mude-a-cor-da-marca) mostra quais pares conferir.
 
-| Recurso                       | Comportamento                                                                                                                                                                                                                                                                   |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Rótulos preenchidos           | O rótulo `.solid` de toda intenção atende a 4.5:1 (WCAG 1.4.3) como texto normal, nos dois temas. O menor é success, com 5.14:1.                                                                                                                                                |
-| Texto em warning              | `--color-warning-contrast` é quase preto, e não a cor da página, porque um âmbar escuro o bastante para carregar texto branco deixa de parecer âmbar.                                                                                                                           |
-| Preenchimentos parciais       | A cor de texto de contraste só aparece em preenchimentos acima da metade da força, então o preenchimento limitado de um controle de texto mantém a cor de texto da própria intenção.                                                                                            |
-| Cor da intenção no escuro     | No modo escuro, um rótulo `.soft` ou `.ghost` usa o tom `-300` da sua intenção, para manter o matiz em vez de ficar branco.                                                                                                                                                     |
-| Marcas dos toggles            | Uma marca de marcado mede pelo menos 3:1 em relação a todo preenchimento que a sua apresentação pode dar a ela, nos dois temas.                                                                                                                                                 |
-| Preenchimentos soft com borda | `.edged` num `.alert`, `.panel`, `.badge`, `.kbd`, `.code` ou `.pre` `.soft` desenha uma borda que mede menos de 3:1 em relação ao preenchimento de 12% em algumas intenções, que variam conforme o tema. Meça o par antes de contar com essa borda como limite de um controle. |
+| Recurso                       | Comportamento                                                                                                                                                                                                                                                                                                                                      |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Rótulos preenchidos           | O rótulo `.solid` de toda intenção atende a 4.5:1 (WCAG 1.4.3) como texto normal, nos dois temas. O menor é success, com 5.14:1.                                                                                                                                                                                                                   |
+| Texto em warning              | `--color-warning-contrast` é quase preto, e não a cor da página, porque um âmbar escuro o bastante para carregar texto branco deixa de parecer âmbar.                                                                                                                                                                                              |
+| Preenchimentos parciais       | A cor de texto de contraste só aparece em preenchimentos acima da metade da força, então o preenchimento limitado de um controle de texto mantém a cor de texto da própria intenção.                                                                                                                                                               |
+| Cor da intenção no escuro     | No modo escuro, um rótulo `.soft` ou `.ghost` usa o tom `-300` da sua intenção, para manter o matiz em vez de ficar branco.                                                                                                                                                                                                                        |
+| Texto sobre um pai preenchido | Um componente neutro que não é `.solid`, como um badge num `.btn.primary` ou um botão ghost num `.card.solid.primary`, imprime na cor de texto do pai em vez da cor da página, então mantém o contraste do pai.                                                                                                                                    |
+| Impressão                     | Uma página é impressa no tema claro, e componentes preenchidos imprimem o fundo (`print-color-adjust: exact`), então o texto de contraste nunca cai sobre o papel em branco. Um utilitário `dark:` continua valendo na impressão; veja [Temas → Impressão](./usage/theming.md#impressão).                                                          |
+| Marcas dos toggles            | Uma marca de marcado mede pelo menos 3:1 em relação a todo preenchimento que a sua apresentação pode dar a ela, nos dois temas.                                                                                                                                                                                                                    |
+| Preenchimentos soft com borda | `.edged` num `.alert`, `.panel`, `.badge`, `.kbd`, `.code` ou `.pre` `.soft` desenha uma borda que mede menos de 3:1 em relação ao preenchimento de 12% em algumas intenções, que variam conforme o tema. Meça o par antes de contar com essa borda como limite de um controle. [Contraste aumentado](#contraste-aumentado) leva todas elas a 3:1. |
 
 ### Cores forçadas e direção
 
-| Recurso          | Comportamento                                                                                                                                                                                                                                                           |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Cores forçadas   | Com `forced-colors: active`, as bordas, os estados marcados e a seta de um `.select` continuam visíveis, desenhados nas cores do sistema, sob todas as estéticas. Uma estética que desenha a borda como sombra interna, como `.pixel`, desenha uma borda real no lugar. |
-| Direção do texto | Sob `dir="rtl"`, a barra da citação, o ícone do alerta, o preenchimento do progresso, o divisor vertical, o botão do switch, o alinhamento das tabelas e a seta de um select trocam de lado. Nenhuma classe é necessária.                                               |
+| Recurso          | Comportamento                                                                                                                                                                                                                                                                                                                                                                               |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Cores forçadas   | Com `forced-colors: active`, as bordas, os estados marcados, a seta de um `.select` e o valor de uma barra de progresso continuam visíveis, desenhados nas cores do sistema, sob todas as estéticas. Uma estética que desenha a borda como sombra interna, como `.pixel`, desenha uma borda real no lugar. O glass fica opaco, porque as cores forçadas mantêm a transparência de um fundo. |
+| Direção do texto | Sob `dir="rtl"`, a barra da citação, o ícone do alerta, o preenchimento do progresso, o divisor vertical, o botão do switch, o alinhamento das tabelas e a seta de um select trocam de lado. Nenhuma classe é necessária.                                                                                                                                                                   |
 
-Em cores forçadas, `.text-control`, `.ipt`, `.textarea`, `.select` e os toggles mostram um outline de foco `Highlight` de 2px. O entrypoint nativo dá o mesmo outline a campos de texto, selects, textareas, checkboxes e radios sem classe.
+Em cores forçadas, `.text-control`, `.ipt`, `.textarea`, `.select`, os toggles e uma classe sua que faz `@apply text-control` mostram um outline de foco `Highlight` de 2px. Dentro de um `.input-group`, o grupo desenha o anel do campo e o controle dentro dele não desenha nenhum, então um campo focado mostra um único anel. O entrypoint nativo dá o mesmo outline a campos de texto, selects, textareas, checkboxes e radios sem classe.
 
 Checkboxes, radios e switches usam as cores do sistema `Canvas`, `CanvasText`, `Highlight` e `HighlightText`, para que marcado e desmarcado continuem distintos: um toggle marcado é preenchido com `Highlight` e a sua marca é `HighlightText`, tanto nas classes quanto no entrypoint nativo. Formato, tamanho e espaçamento não mudam.
 
+Uma barra `.progress` faz o mesmo: a parte preenchida é `CanvasText` sobre um trilho `Canvas` com contorno `CanvasText`, qualquer que seja a intenção ou a apresentação, para que uma barra pela metade não pareça vazia. O brilho de `.active` não é desenhado.
+
 ## O que fica fora do CSS
 
 Use o elemento HTML que corresponde ao que o componente faz e adicione o comportamento que o CSS não consegue.

package/docs/pt-BR/index.md

@@ -1,7 +1,7 @@
 ---
 title: Introdução
 description: Para que serve o @codenhub/styles, quanto ele custa e em que ordem ler esta documentação.
-source: 238cac2f0ca6132818c99d938219a6c537bc837a
+source: 5f82b6a4d492bdb5ea73406f256d307f775fa1ea
 ---
 
 # @codenhub/styles
@@ -61,7 +61,7 @@ A [Configuração](./setup.md) ajuda você a escolher.
 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).
+- **As folhas de estilos completas são grandes antes da compressão.** No momento em que este texto foi escrito, minificada, a folha de estilos completa tem cerca de 198 KB, a `/native` cerca de 295 KB e a `/components` cerca de 159 KB. Servidas com gzip, ficam em cerca de 17 KB, 22 KB e 13 KB. Os arquivos específicos são bem menores: `/theme` tem cerca de 12 KB (3 KB com gzip) e cada estética tem de 4 a 14 KB (1 a 2 KB com gzip). A maior parte do tamanho é composição que todo componente repete, e é por isso que a compressão elimina tanto. Um arquivo compilado traz todas as classes, a página usando ou não. Para entregar só as classes que as suas páginas usam, compile o pacote no seu próprio build: pelo [Tailwind CSS v4](./integrating/tailwind.md) quando o projeto o usa, ou com o [comando `build`](./integrating/without-a-bundler.md#gere-só-as-classes-que-você-usa) do pacote em qualquer outro projeto. Assim, uma página com um botão recebe de 26 a 28 KB minificados, e cerca de 6 KB com gzip. Fora isso, importe o entrypoint mais restrito que cubra a página; veja [Configuração → Todos os entrypoints](./setup.md#todos-os-entrypoints).
 - **`--color-foreground` é um fundo, não uma cor de texto.** É o tom um passo distante da página, sobre o qual fica um card ou painel discreto. A cor do texto é `--color-text`.
 - **Quatro cores de hover são valores fixos.** `--color-success-hover`, `--color-warning-hover`, `--color-destructive-hover` e `--color-info-hover` são pré-calculadas, porque misturá-las em tempo real travava o WebKit. Se você sobrescrever só `--color-success`, o hover dela mantém o tom antigo, então substitua a família inteira; veja [Temas → Tokens de cor](./usage/theming.md#tokens-de-cor).
 - **Só navegadores modernos.** Chrome 123, Safari 17.5 ou Firefox 128 e mais recentes. Não há camada de fallback para navegadores mais antigos.
@@ -99,6 +99,7 @@ Na primeira vez, leia nesta ordem. Cada página acrescenta algo à tela de confi
    - [Estéticas](./usage/aesthetics.md): mude o estilo da tela inteira com uma classe.
    - [Classes solo](./usage/solo.md): aplique uma estética a um componente que este pacote não estiliza.
    - [Composição](./usage/composing.md), [Personalização](./usage/customizing.md) e [Conteúdo e layout](./usage/content-and-layout.md): páginas de consulta com cada regra de eixo, token, padrão e classe utilitária.
+   - [Predefinições](./usage/presets.md): defina um visual uma única vez, para uma região, um tema ou a sua própria classe de componente, em vez de repeti-lo em cada elemento.
 5. [Acessibilidade](./accessibility.md): o que o CSS resolve por você e o que a sua aplicação ainda precisa fazer.
 
 O [changelog](../changelog/index.md) lista todas as versões e o que mudou em cada uma.

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

@@ -3,7 +3,7 @@ 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
+source: 2028acef66a8ab3659cef35e08ecc0db1de7bdeb
 ---
 
 # Integração
@@ -21,16 +21,44 @@ Importar de um único lugar importa por dois motivos. Alguns frameworks só _per
 
 ## 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) |
+| 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 — 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.
+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
 

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

@@ -2,16 +2,16 @@
 title: Tailwind CSS v4
 description: Como usar os entrypoints de código-fonte /tw num projeto com Tailwind CSS v4.
 order: 1
-source: 7988dc023c91950991a720ea7da7edfe3378d4d7
+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 e dos problemas de build que você provavelmente vai encontrar.
+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 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.
+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
 
@@ -23,7 +23,7 @@ Os entrypoints `/tw` publicam uma cópia do código-fonte não compilado de `dis
 
 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.
+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
 
@@ -47,6 +47,70 @@ Diferente do `/tw`, os entrypoints específicos e o `/tw/native` não importam o
 @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**
@@ -63,11 +127,17 @@ Diferente do `/tw`, os entrypoints específicos e o `/tw/native` não importam o
 
 **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.
+- **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: o código-fonte usa `@source not` e `@source inline()`, que chegaram na 4.1, e é testado com a 4.3.2.
+Todo entrypoint `/tw` exige Tailwind CSS 4.3.2 ou mais recente, abaixo da 5 (`>=4.3.2 <5`).
 
 ## A variante `dark:`