@codenhub/styles 0.6.0 → 0.7.0

package/docs/integrating/index.md

@@ -2,40 +2,45 @@
 title: Overview
 description: How the stylesheet loads in a framework build, and which guide to follow.
 group: Integrating
-order: 4
+order: 2
 ---
 
 # Integrating
 
-This package has no JavaScript and no framework bindings; see [Introduction](../index.md#what-it-does-not-do). Integrating it into a framework is entirely about where that framework lets you load a global stylesheet, and whether the project runs Tailwind CSS v4.
+This section is a detour from the main reading path, for projects whose framework decides where global CSS may go. The package has no JavaScript and no framework bindings (see [Introduction](../index.md#what-it-does-not-do)), so integrating it is only about two things: where your framework lets you load a global stylesheet, and whether the project runs Tailwind CSS v4. Follow the one guide that matches your stack, then return to [Building a screen](../concepts.md).
 
 ## The shared model
 
 Every stack does the same two imports, from the same kind of place — a root layout, an app entry file, or a global CSS file, never a page or a component further down the tree:
 
-1. One [entrypoint](../setup.md#import-paths) — the compiled `@codenhub/styles` for any build, or `@codenhub/styles/tw` when the project already runs Tailwind CSS v4.
+1. One [entrypoint](../setup.md#all-entrypoints) — the compiled `@codenhub/styles` for any build, or `@codenhub/styles/tw` when the project already runs Tailwind CSS v4.
 2. `@codenhub/styles/aesthetics` (or `/tw/aesthetics`) after it, only if the project uses an [aesthetic](../usage/aesthetics.md).
 
 Importing from one place matters for two reasons. Some frameworks only _allow_ global CSS from a designated root file and fail the build otherwise — Next.js's Pages Router is one, see [Next.js → Troubleshooting](./nextjs.md#troubleshooting). Where a framework allows it more broadly, as Next.js's App Router does, importing from the root remains the recommended choice for predictable CSS ordering — and importing per-component instead would load the same reset and token rules once per component rather than once per app.
 
 ## Which guide to follow
 
-| Stack                                    | Guide                            |
-| ---------------------------------------- | -------------------------------- |
-| A Tailwind CSS v4 project on any 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)              |
+| Stack                                                        | Guide                                       |
+| ------------------------------------------------------------ | ------------------------------------------- |
+| A Tailwind CSS v4 project on any 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)                         |
+| Plain HTML, Rails, Django, or any app with no CSS build step | [Without a bundler](./without-a-bundler.md) |
 
-A project with no framework — a plain Vite, webpack, or Parcel build — needs nothing beyond [Setup → Quick start](../setup.md#quick-start): import the compiled stylesheet from the project's existing global CSS entry.
+A project with no framework — a plain Vite, webpack, or Parcel build — needs nothing beyond [Setup → Import the stylesheet](../setup.md#import-the-stylesheet): import the compiled stylesheet from the project's existing global CSS entry.
 
 ## Verifying it worked
 
 After the import, render one styled element and confirm it picked up the package's tokens rather than the browser default:
 
 ```html
-<button class="btn primary">Continue</button>
+<button class="btn primary">Save changes</button>
 ```
 
-A rounded, filled button in the primary color means the stylesheet loaded. Unstyled browser-default text most often means the import specifier didn't resolve — check the [import paths table](../setup.md#import-paths) for the exact one your entrypoint needs, and confirm your build tooling resolves package CSS imports at all, see [Setup → Requirements](../setup.md#requirements).
+A rounded button filled with the primary color (near-black on a light page, near-white on a dark one) means the stylesheet loaded. Unstyled browser-default text most often means the import specifier didn't resolve — check the [entrypoint table](../setup.md#all-entrypoints) for the exact specifier to import, and confirm your build tooling resolves package CSS imports at all, see [Setup → Requirements](../setup.md#requirements). With no build tool, link the file by its path instead; see [Without a bundler](./without-a-bundler.md). [Setup → When nothing is styled](../setup.md#when-nothing-is-styled) lists the other common causes.
+
+## Next
+
+Once the button renders, go back to the main path: [Building a screen](../concepts.md) adds the first card and form to the settings page.

package/docs/integrating/nextjs.md

@@ -47,7 +47,7 @@ Running Tailwind CSS v4? `@import "@codenhub/styles/tw"` is a CSS directive, so
 
 ## Force a theme
 
-Apply `.dark` or `.light` on `<html>` to force a theme instead of following the system preference; see [Setup → Configuration](../setup.md#configuration).
+Apply `.dark` or `.light` on `<html>` to force a theme instead of following the system preference; see [Theming → Light and dark](../usage/theming.md#light-and-dark).
 
 ```tsx
 <html lang="en" className="dark">
@@ -61,7 +61,6 @@ Apply `.dark` or `.light` on `<html>` to force a theme instead of following the
 - **Why:** the Pages Router has no per-route CSS boundary the way the App Router does, so Next.js requires one predictable file for global stylesheets to avoid ordering conflicts between pages.
 - **Fix:** move the `import "@codenhub/styles"` line to `pages/_app.tsx`, and remove it from wherever it currently is.
 
-## See also
+## Next
 
-- [Setup → Import paths](../setup.md#import-paths): every entrypoint this package publishes.
-- [Usage](../usage/index.md): component classes to compose once the stylesheet is loaded.
+Return to the main path: [Building a screen](../concepts.md) adds the first card and form to the settings page. [Setup → All entrypoints](../setup.md#all-entrypoints) lists every other stylesheet you can import.

package/docs/integrating/svelte.md

@@ -6,6 +6,8 @@ order: 4
 
 # Svelte
 
+Svelte and SvelteKit let you import CSS from any component, but the package's reset and tokens should load once, before any component renders. This page shows where that one import goes in SvelteKit and in a plain Svelte app.
+
 ## Import the stylesheet
 
 **SvelteKit** — import from the root layout so it loads once for every route:
@@ -35,9 +37,8 @@ Running Tailwind CSS v4? Import `@codenhub/styles/tw` from the app's CSS entry i
 
 ## Force a theme
 
-Apply `.dark` or `.light` on `<html>` (edit `src/app.html` in SvelteKit) to force a theme instead of following the system preference; see [Setup → Configuration](../setup.md#configuration).
+Apply `.dark` or `.light` on `<html>` (edit `src/app.html` in SvelteKit) to force a theme instead of following the system preference; see [Theming → Light and dark](../usage/theming.md#light-and-dark).
 
-## See also
+## Next
 
-- [Setup → Import paths](../setup.md#import-paths): every entrypoint this package publishes.
-- [Usage](../usage/index.md): component classes to compose once the stylesheet is loaded.
+Return to the main path: [Building a screen](../concepts.md) adds the first card and form to the settings page. [Setup → All entrypoints](../setup.md#all-entrypoints) lists every other stylesheet you can import.

package/docs/integrating/tailwind.md

@@ -6,7 +6,7 @@ order: 1
 
 # Tailwind CSS v4
 
-A project that already runs Tailwind CSS v4 can process this package's source instead of its compiled output, so both sets of classes compile through the same Tailwind build.
+A project that already runs Tailwind CSS v4 can compile this package's source instead of loading its compiled output. Your app's utilities and the package's classes then come out of one build, share one theme, and use one `dark:` variant. This page covers the import, aesthetics, the focused entrypoints, and the build problems you are likely to meet.
 
 ## Why source instead of compiled
 
@@ -37,14 +37,13 @@ Add an aesthetic from the source entrypoint the same way as the compiled one, af
 
 ## Using a focused entrypoint
 
-Import a focused `/tw/*` entrypoint instead of the combined one — such as `/tw/button` or `/tw/form` — when a build only needs one component family; see the full [import path table](../setup.md#import-paths) for what each one composes.
+Import a focused `/tw/*` entrypoint instead of the combined one — such as `/tw/button` or `/tw/form` — when a build only needs one component family; see the full [entrypoint table](../setup.md#all-entrypoints) for what each one composes.
 
 Unlike `/tw`, the focused entrypoints and `/tw/native` do not import Tailwind, so keep your own import first:
 
 ```css
 @import "tailwindcss";
 @import "@codenhub/styles/tw/button";
-@import "@codenhub/styles/tw/loader";
 ```
 
 ## Troubleshooting
@@ -61,4 +60,18 @@ Unlike `/tw`, the focused entrypoints and `/tw/native` do not import Tailwind, s
 - **Why:** one of two things. Importing both a compiled entrypoint (`@codenhub/styles`) and a `/tw` entrypoint (`@codenhub/styles/tw`) in the same build compiles the same tokens and reset from two independent sources; Tailwind's build has no way to know they describe the same package. Or your stylesheet imports `tailwindcss` beside `/tw`, which already imports it, so Preflight is emitted twice.
 - **Fix:** pick one path per project — `/tw` entrypoints for a project running Tailwind CSS v4, compiled entrypoints everywhere else — and drop your own `@import "tailwindcss"` when you import `/tw`.
 
+**A class built at runtime has no styling**
+
+- **What happened:** `<button class="btn primary">` is styled, but a button whose intent comes from a variable, such as `` `btn ${tone}` ``, is not.
+- **Why:** Tailwind generates a class only when it finds the complete name in your source files. The package's own component and axis classes are always generated, but your own utilities are not, and a name assembled from strings is invisible to the scan.
+- **Fix:** write complete class names in your source, for example in a lookup object (`{ save: "btn primary", remove: "btn destructive" }`), or list the names your code can produce with `@source inline("...")` in your stylesheet.
+
 Every `/tw` entrypoint requires Tailwind CSS 4.3.2 or newer, below 5: the source uses `@source not` and `@source inline()`, which arrived in 4.1, and it is tested against 4.3.2.
+
+## The `dark:` variant
+
+The `/tw` entrypoints define their own `dark:` variant, so your utilities switch with the same light and dark selectors the package's tokens use. It has one known difference from the tokens when themes are nested; see [Theming → The dark: variant](../usage/theming.md#the-dark-variant).
+
+## Next
+
+Return to the main path: [Building a screen](../concepts.md) adds the first card and form to the settings page. Everything it shows works the same on `/tw`.

package/docs/integrating/vue.md

@@ -23,9 +23,8 @@ Running Tailwind CSS v4? Import `@codenhub/styles/tw` from a CSS entry file inst
 
 ## Force a theme
 
-Apply `.dark` or `.light` on the root element to force a theme instead of following the system preference; see [Setup → Configuration](../setup.md#configuration).
+Apply `.dark` or `.light` on the root element to force a theme instead of following the system preference; see [Theming → Light and dark](../usage/theming.md#light-and-dark).
 
-## See also
+## Next
 
-- [Setup → Import paths](../setup.md#import-paths): every entrypoint this package publishes.
-- [Usage](../usage/index.md): component classes to compose once the stylesheet is loaded.
+Return to the main path: [Building a screen](../concepts.md) adds the first card and form to the settings page. [Setup → All entrypoints](../setup.md#all-entrypoints) lists every other stylesheet you can import.

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

@@ -0,0 +1,114 @@
+---
+title: Without a bundler
+description: Linking the compiled stylesheets from plain HTML, Rails, Django, or any server-rendered app.
+order: 6
+---
+
+# Without a bundler
+
+The compiled stylesheets are finished CSS: each one is a single file with no `@import` and no reference to another file, and every image it draws is embedded as a `data:` URL: the checkbox tick and dash masks, and the SVG lens filters `.glass-liquid` uses. A page can load one with a plain `<link>` tag, from any server, with no build step, and the stylesheet makes no further requests.
+
+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.
+
+## Which file to link
+
+Each compiled import path is one file in the package's `dist/` folder:
+
+| Import path                     | File                                                              |
+| ------------------------------- | ----------------------------------------------------------------- |
+| `@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`, 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.
+
+## 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" />
+```
+
+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).
+
+## From your own server
+
+Install the package, then serve its `dist/` folder as static files:
+
+```sh
+npm install @codenhub/styles
+```
+
+How a framework serves a folder from `node_modules` differs, so each one is below. Where the framework reads the folder in place, as Rails and Django do, upgrading the package and redeploying is all an update takes.
+
+### Plain HTML
+
+Copy `node_modules/@codenhub/styles/dist` into the folder your server publishes, then link it:
+
+```html
+<link rel="stylesheet" href="/vendor/codenhub-styles/index.css" />
+```
+
+Repeat the copy after each upgrade, for example from an npm `postinstall` script.
+
+### Ruby on Rails
+
+A Rails app built with `cssbundling-rails` already runs a bundler: import the package from `app/assets/stylesheets/application.css` as in [Setup → Import the stylesheet](../setup.md#import-the-stylesheet).
+
+With Propshaft and no CSS bundler, add the package's folder to the asset paths:
+
+```ruby
+# config/initializers/assets.rb
+Rails.application.config.assets.paths << Rails.root.join("node_modules/@codenhub")
+```
+
+Then link it from the layout, by its path below that folder:
+
+```erb
+<%# app/views/layouts/application.html.erb %>
+<%= stylesheet_link_tag "styles/dist/index" %>
+<%= stylesheet_link_tag "styles/dist/aesthetics/pixel" %>
+```
+
+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.
+
+### Django
+
+Add the folder to `STATICFILES_DIRS` under a prefix, which keeps its file names apart from your own static files:
+
+```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' %}" />
+```
+
+### 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.
+
+## Verifying it worked
+
+Render one styled element, as in [Integrating → Verifying it worked](./index.md#verifying-it-worked):
+
+```html
+<button class="btn primary">Save changes</button>
+```
+
+A rounded button filled with the primary color means the stylesheet loaded. If the button looks like the browser default, open the browser's network panel: a `404` on the stylesheet means the path or the static-file setup is wrong.
+
+## Next
+
+Return to the main path: [Building a screen](../concepts.md) adds the first card and form to the settings page. [Setup → All entrypoints](../setup.md#all-entrypoints) lists every other stylesheet you can import.

package/docs/pt-BR/accessibility.md

@@ -0,0 +1,150 @@
+---
+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
+---
+
+# Acessibilidade
+
+A tela de configurações está pronta, e o CSS fez a sua parte no caminho: todo campo mostra onde está o foco, um email inválido fica vermelho e o spinner para para usuários que pedem menos movimento. O resto depende do seu HTML e JavaScript. Este pacote estiliza estados; ele não fornece elementos semânticos, atributos ARIA, comportamento de teclado, gerenciamento de foco, validação nem o momento dos anúncios.
+
+Esta página lista as duas metades: o que o CSS fornece e o que a sua aplicação precisa adicionar.
+
+## Fornecido pelo CSS
+
+### Foco e estado
+
+| Recurso                         | Comportamento                                                                                                                                                                                                                                                                                                                                              |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `:focus-visible`                | Um outline de foco em todo elemento, desenhado com `--focus-ring`, `--focus-ring-width` e `--focus-ring-offset`.                                                                                                                                                                                                                                           |
+| 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. |
+
+### Conteúdo visualmente oculto
+
+`.visually-hidden` esconde o conteúdo na tela e o mantém para leitores de tela, como faz a `<caption>` da tabela de chaves de API em [Conteúdo e layout → Tabelas](./usage/content-and-layout.md#tabelas). Ela vem com os utilitários de layout: em `.`, `./native`, `./tw`, `./tw/native` e `./tw/utilities`. Ela não está em `./components` nem nos entrypoints de componentes `./tw/components` e `./tw/*`.
+
+### Limites dos controles
+
+O WCAG 1.4.11 pede que o limite de um controle que você precisa ver para usá-lo tenha um contraste de pelo menos 3:1 em relação ao que está ao lado dele.
+
+| Recurso                           | Comportamento                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Controles de texto em repouso     | A borda de um controle de texto fica, em repouso, mais clara que a borda cheia da sua intenção, abaixo de 3:1 por escolha, para que o hover e o foco tenham um tom mais forte para onde mudar.                                                                                                                                                                                                                                                                                                        |
+| Toggles                           | `.checkbox`, `.radio` e `.switch` desenham a borda cheia, porque a borda é a única coisa que mostra uma caixa desmarcada. Um `.switch` com o seu próprio `.edgeless` é a exceção, abaixo.                                                                                                                                                                                                                                                                                                             |
+| `.edgeless` vindo de um contêiner | Ignorado por todo controle de texto e toggle: um contêiner não pode remover a borda de um campo ou toggle dentro dele.                                                                                                                                                                                                                                                                                                                                                                                |
+| `.edgeless` no próprio controle   | `.ipt`, `.textarea`, `.select` e `.switch` perdem a borda e deixam de atender ao 1.4.11 em repouso. `.switch.ghost` mantém a borda mesmo assim, porque, sem preenchimento e sem borda, nada mostraria o trilho.                                                                                                                                                                                                                                                                                       |
+| `.checkbox`, `.radio`             | Sempre desenham a borda, venha o `.edgeless` de um contêiner ou deles mesmos. `.edgeless` neles não é suportado.                                                                                                                                                                                                                                                                                                                                                                                      |
+| Trilho de progresso               | Por escolha, a parte preenchida carrega o valor e o trilho é um fundo discreto. O trilho padrão, `.soft.edgeless`, mede cerca de 1.1:1 a 1.3:1 em relação à página. A parte preenchida mede pelo menos 3:1 em relação a esse trilho em todas as intenções, exceto warning no claro (cerca de 2.7:1) e info no escuro (cerca de 2.9:1). Onde o próprio trilho precisa atender ao 1.4.11, use `.ghost.edged` com uma classe de intenção; veja [Contornos de progresso](#contornos-de-progresso) abaixo. |
+
+### Contornos de progresso
+
+Num `.progress.ghost.edged`, o trilho é a página, e o seu contorno e a parte preenchida são desenhados na cor da intenção. Medido em relação à página, sem estética:
+
+| Intenção       | Página clara | Página escura | Atende a 3:1                                                             |
+| -------------- | ------------ | ------------- | ------------------------------------------------------------------------ |
+| `.primary`     | 18.96:1      | 18.96:1       | Sim                                                                      |
+| `.secondary`   | 7.47:1       | 7.63:1        | Sim                                                                      |
+| `.success`     | 5.14:1       | 3.69:1        | Sim                                                                      |
+| `.warning`     | 3.06:1       | 6.20:1        | Sim                                                                      |
+| `.destructive` | 5.80:1       | 3.27:1        | Sim                                                                      |
+| `.info`        | 6.17:1       | 3.07:1        | Sim                                                                      |
+| Sem intenção   | 2.48:1       | 1.91:1        | Não: o contorno falha, embora a parte preenchida, na cor do texto, passe |
+
+Sem classe de intenção, o contorno é o cinza de borda discreto, `--color-border`. Para que um trilho neutro atenda ao 1.4.11, dê uma classe de intenção à barra, ou defina `--progress-edge` com uma cor mais forte, como `var(--color-accent)`, que mede 7.47:1 numa página clara e 7.63:1 numa escura. Warning numa página clara e info numa escura passam de 3:1 por pouco, então meça de novo se você mudar essas cores.
+
+### Movimento e transparência
+
+| Recurso                            | Comportamento                                                                                                                                                                                                |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Movimento reduzido, componentes    | Com `prefers-reduced-motion: reduce`, todo componente para as suas próprias transições e animações: o brilho do skeleton e do progresso, a barra indeterminada, o tooltip, as marcas dos toggles e o 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.                                                                                           |
+
+A regra de movimento reduzido de cada componente vem com o componente, então todo entrypoint que o inclui respeita o movimento reduzido sem o reset, incluindo `@codenhub/styles/components`, `@codenhub/styles/tw/components` e cada entrypoint de componente `/tw/*`. Os entrypoints completos e nativos adicionam a regra do reset para a página inteira.
+
+A regra do reset é `!important` dentro da camada `base`, e um `!important` com camada vence um sem camada, então o seu próprio `!important` não consegue religar uma animação. Para manter uma rodando para usuários que pedem movimento reduzido, como um spinner de upload que você considera essencial, declare-a `!important` numa camada ordenada antes de `base`. A primeira declaração `@layer` que o navegador lê define a ordem, então a sua vem antes do pacote:
+
+```css
+@layer essential-motion, theme, base, components, utilities;
+@import "@codenhub/styles";
+
+@layer essential-motion {
+  @media (prefers-reduced-motion: reduce) {
+    .upload-spinner {
+      animation-duration: 1s !important;
+      animation-iteration-count: infinite !important;
+    }
+  }
+}
+```
+
+Respeitar o movimento reduzido não é o requisito inteiro. Um movimento que continua ao lado do conteúdo, como um brilho deixado num card depois que ele carregou, precisa de uma forma de ser parado por qualquer usuário; veja [Feedback → Animação que não para](./usage/feedback.md#animação-que-não-para).
+
+### 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. |
+
+### 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.                                               |
+
+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.
+
+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.
+
+## O que fica fora do CSS
+
+Use o elemento HTML que corresponde ao que o componente faz e adicione o comportamento que o CSS não consegue.
+
+| Interface          | O que a sua aplicação adiciona                                                                                                                                                                                                             |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Botões             | `<button>` para ações e `<a href>` para navegação. Um nome acessível, como `aria-label`, em todo `.btn.icon`.                                                                                                                              |
+| Formulários        | Um `<label>` para cada controle, o `type` certo, validação e `aria-describedby` ligando dicas e erros. Mantenha dicas e erros fora do `<label>` e dê `role="switch"` a um `.switch`.                                                       |
+| Alertas            | `role="status"` para uma confirmação como "Profile saved", ou `role="alert"` para um erro que precisa de atenção imediata.                                                                                                                 |
+| Toasts             | Uma live region, uma forma de dispensá-lo, regras de foco e uma pausa em qualquer tempo limite.                                                                                                                                            |
+| Tooltips           | Um `id` real e `role="tooltip"` no balão, referenciado pelo `aria-describedby` do gatilho. Dispensa com Escape escrevendo `data-state="closed"`; veja [Tooltips](./usage/tooltips.md#hover-permanência-e-escape). O balão já aceita hover. |
+| Progresso          | Um elemento `<progress>`, ou `role="progressbar"` ou `role="meter"` com valores ARIA, quando o valor precisa ser anunciado.                                                                                                                |
+| Skeletons          | `aria-hidden="true"` nos visuais de carregamento, incluindo um spinner que você traga, e o estado de carregamento anunciado de outra forma quando necessário.                                                                              |
+| Movimento contínuo | Uma forma de pausar, parar ou esconder o movimento que não é essencial; veja [Feedback → Animação que não para](./usage/feedback.md#animação-que-não-para).                                                                                |
+| Popovers, modais   | Prender o foco, fechar com Escape, um fundo inerte, rótulos e roles.                                                                                                                                                                       |
+
+## Atributos de estado
+
+Prefira os atributos nativos:
+
+```html
+<button class="btn primary" disabled>Saving…</button> <input class="ipt" type="email" aria-invalid="true" aria-describedby="email-error" />
+```
+
+Use atributos ARIA ou data onde o elemento ou a sua biblioteca de componentes não tem um nativo:
+
+```html
+<a class="btn secondary" aria-disabled="true">Export data</a>
+<span class="tooltip" data-state="open">
+  <button type="button" class="tooltip-icon" aria-label="About public profiles" aria-describedby="public-profile-help">?</button>
+  <span class="tooltip-bubble" role="tooltip" id="public-profile-help">Anyone with the link can see your name and photo.</span>
+</span>
+```
+
+`aria-disabled="true"` informa às tecnologias assistivas que o controle está desabilitado, mas não impede um clique nem o pressionar de uma tecla. Use o atributo `disabled`, ou interrompa a ação no JavaScript.
+
+## A seguir
+
+Isso completa a ordem de leitura. A [Introdução](./index.md) tem links para todas as páginas, e [Composição](./usage/composing.md), [Personalização](./usage/customizing.md) e [Conteúdo e layout](./usage/content-and-layout.md) são as páginas de consulta para depois.