fokus-styles 2.0.0

package/docs/components/tooltip.md

@@ -0,0 +1,77 @@
+# Tooltip
+
+Rótulo curto que aparece ao passar o mouse ou focar um elemento —
+substitui o `title` nativo do navegador (lento, sem estilo, inacessível a
+teclado em alguns navegadores).
+
+## Visão geral
+
+```html
+<button type="button" class="fs-btn" data-fs="tooltip" title="Copiar para a área de transferência">
+  Copiar
+</button>
+```
+
+O texto vem do atributo `title` (ou `data-title`) — o JS o remove do DOM
+na inicialização (pra não duplicar com o tooltip nativo do navegador) e o
+recria como conteúdo do tooltip.
+
+## Anatomia
+
+Gerado inteiramente pelo JS: `.fs-tooltip` (`role="tooltip"`) >
+`.fs-tooltip-arrow` + `.fs-tooltip-inner` (texto). Não escreva essa
+marcação manualmente — só o elemento de referência com `title`/`data-fs="tooltip"`.
+
+## Variações
+
+`data-placement` (`top` — padrão, `bottom`, `left`, `right`) no elemento
+de referência. Reposiciona automaticamente se não couber.
+
+```html
+<button class="fs-btn" data-fs="tooltip" data-placement="right" title="Mais opções">⋮</button>
+```
+
+## Estados
+
+`.is-open` — controlado pelo JS ao mostrar/esconder; não defina
+manualmente.
+
+## A11y
+
+O JS aplica `aria-describedby` no elemento de referência, apontando pro
+`id` do tooltip — leitor de tela anuncia o conteúdo ao focar o elemento.
+Mostra em `mouseenter`/`focus`, esconde em `mouseleave`/`blur`/`Escape` —
+funciona por mouse e por teclado igualmente (ao contrário do `title`
+nativo, que só mostra no hover).
+
+## API JS
+
+Auto-init via `data-fs="tooltip"` **ou** instanciação manual
+(`new FokusStyles.Tooltip(el, { title, placement })` — útil quando o texto vem
+de outro lugar, não de um atributo estático; é assim que
+[Breadcrumb](breadcrumb.md) anexa tooltips a labels truncados).
+`Tooltip.getInstance(el)`.
+
+| Método | Descrição |
+|---|---|
+| `show()` | Mostra o tooltip, posicionado relativo à referência. |
+| `hide()` | Esconde. |
+| `toggle()` | Alterna. |
+| `dispose()` | Remove listeners, `aria-describedby` e o elemento do tooltip do DOM; desregistra a instância. |
+
+| Evento (no elemento de referência) | Cancelável | Quando |
+|---|---|---|
+| `fs:tooltip:shown` | Não | Depois de mostrar. |
+| `fs:tooltip:hidden` | Não | Depois de esconder. |
+
+## Tokens
+
+`--fs-tooltip-bg`, `--fs-tooltip-text`, `--fs-radius-sm`.
+
+## Exemplo
+
+```html
+<button type="button" class="fs-btn-close" data-fs="tooltip" title="Fechar" aria-label="Fechar"></button>
+```
+
+Mockup: [laboratório do componente](../../mockup/overlays-commands.html#tooltip).

package/docs/components/tree-view.md

@@ -0,0 +1,118 @@
+# Tree View
+
+Lista hierárquica navegável (arquivos, categorias, organogramas), seguindo
+o padrão [WAI-ARIA Tree View](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/).
+Marcação nativa `<ul>`/`<li>` aninhada — o JS só adiciona os papéis ARIA,
+o botão de expandir/colapsar e a navegação por teclado.
+
+## Visão geral
+
+```html
+<ul class="fs-tree" data-fs="tree-view">
+  <li>
+    <span class="fs-tree-label">src</span>
+    <ul>
+      <li><span class="fs-tree-label">index.js</span></li>
+      <li>
+        <span class="fs-tree-label">components</span>
+        <ul>
+          <li><span class="fs-tree-label">Button.js</span></li>
+        </ul>
+      </li>
+    </ul>
+  </li>
+  <li><span class="fs-tree-label">README.md</span></li>
+</ul>
+```
+
+Cada `<li>` precisa de um `<span class="fs-tree-label">` como filho direto
+(o texto do nó) — nós com filhos somam um `<ul>`/`<ol>` aninhado logo
+depois do label. O JS injeta automaticamente o `.fs-tree-toggle` (a seta)
+dentro do label de cada nó que tiver filhos; nós-folha não recebem seta.
+
+## Anatomia
+
+`ul.fs-tree[role="tree"]` > `li[role="treeitem"]` (recursivo) >
+`span.fs-tree-label` (com `.fs-tree-toggle` auto-injetado se houver
+filhos) + opcionalmente `ul[role="group"]` (o próximo nível).
+
+## Variações
+
+- `data-value` num `<li>` define o valor "de verdade" reportado em
+  `fs:tree:selected` (`event.detail.value`); sem ele, o valor é o texto
+  visível do nó.
+- `aria-expanded="true"` pré-existente num `<li>` com filhos abre esse
+  ramo já expandido na renderização inicial (por padrão, todo ramo nasce
+  colapsado).
+
+## Estados
+
+- Colapsado (padrão) / expandido (`aria-expanded="true"` no `<li>`,
+  `hidden` removido do `<ul>` filho) — alternado por clique na
+  label/seta ou por teclado.
+- Selecionado: `aria-selected="true"` (só no nó mais recente; os demais
+  voltam a `"false"`) — clicar num nó com filhos expande/colapsa **e**
+  seleciona ao mesmo tempo (como um explorador de arquivos).
+
+## A11y
+
+`role="tree"` na raiz, `role="treeitem"` em cada `<li>`, `role="group"` no
+`<ul>`/`<ol>` aninhado, `aria-expanded` nos nós com filhos. Roving
+`tabindex`: só o nó tabulável atual tem `tabindex="0"`; os demais (visíveis)
+ficam em `"-1"` — nós dentro de um ramo colapsado não são alcançáveis por
+Tab. `aria-selected` reflete a seleção atual.
+
+Teclado (com foco num nó da árvore):
+- `ArrowDown`/`ArrowUp`: move o foco pro próximo/anterior nó **visível**
+  (não desce em ramos colapsados).
+- `ArrowRight`: nó fechado → expande (foco não se move); nó já aberto →
+  move o foco pro primeiro filho; folha → sem efeito.
+- `ArrowLeft`: nó aberto → colapsa; nó fechado ou folha → move o foco pro
+  nó pai.
+- `Home`/`End`: primeiro/último nó visível da árvore inteira.
+- `Enter`/`Espaço`: alterna expansão (se houver filhos) e seleciona o nó.
+
+## API JS
+
+Auto-init via `data-fs="tree-view"` na raiz (`<ul>`/`<ol>`).
+`TreeView.getInstance(rootEl)`.
+
+| Método | Descrição |
+|---|---|
+| `expand(item)` | Expande o `<li>` informado (sem efeito se já expandido ou sem filhos). |
+| `collapse(item)` | Colapsa o `<li>` informado. |
+| `toggle(item)` | Alterna expandido/colapsado. |
+| `select(item)` | Marca `aria-selected="true"` no `<li>` informado (e `"false"` nos demais), dispara `fs:tree:selected`. |
+| `dispose()` | Remove listeners e desregistra a instância. |
+
+| Evento (na raiz) | Cancelável | Quando |
+|---|---|---|
+| `fs:tree:expanded` | Não | Após expandir um nó, com `event.detail.item`. |
+| `fs:tree:collapsed` | Não | Após colapsar um nó, com `event.detail.item`. |
+| `fs:tree:selected` | Não | Após selecionar um nó, com `event.detail.value`/`event.detail.item`. |
+
+## Tokens
+
+`--fs-color-text`, `--fs-color-subtle` (hover da label),
+`--fs-color-primary` (nó selecionado, com `color-contrast()` pro texto),
+`--fs-radius-sm`.
+
+## Exemplo
+
+```html
+<ul class="fs-tree" data-fs="tree-view" aria-label="Arquivos do projeto">
+  <li>
+    <span class="fs-tree-label">src</span>
+    <ul>
+      <li><span class="fs-tree-label">index.js</span></li>
+    </ul>
+  </li>
+</ul>
+<script>
+  document.querySelector(".fs-tree").addEventListener("fs:tree:selected", (e) => {
+    console.log("selecionado:", e.detail.value);
+  });
+</script>
+```
+
+Mockup: [laboratório do componente](../../mockup/navigation-disclosure.html#tree-view).

package/docs/contributing/contributing.md

@@ -0,0 +1,18 @@
+# Contribuindo
+
+O guia de contribuição vive na raiz do repositório —
+[`CONTRIBUTING.md`](../../CONTRIBUTING.md) — para o GitHub linkar
+automaticamente em issues/PRs. Cobre:
+
+- Pré-requisitos e setup local.
+- Scripts (`build`, `lint`, `test`, `test:visual`, `test:a11y`, `contrast`,
+  `size`, `docs:check`).
+- Convenções de SCSS e o fluxo pra criar um componente novo.
+- Contrato editorial: cada componente precisa manter implementação, exemplo,
+  documentação, testes e acessibilidade alinhados.
+- Semver e política de depreciação.
+- Checklist de Pull Request.
+
+Ver também: [Código de Conduta](../../CODE_OF_CONDUCT.md),
+[templates de issue](../../.github/ISSUE_TEMPLATE/) e o
+[template de Pull Request](../../.github/PULL_REQUEST_TEMPLATE.md).

package/docs/getting-started/installation.md

@@ -0,0 +1,70 @@
+# Instalação
+
+## Via npm
+
+```bash
+npm install fokus-styles
+```
+
+## Via CDN
+
+Sem instalar nada, direto do jsDelivr ou unpkg:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/fokus-styles/dist/css/fokus.css">
+<script src="https://cdn.jsdelivr.net/npm/fokus-styles/dist/js/fokus.js"></script>
+```
+
+Troque `fokus.css`/`fokus.js` por `fokus.min.css`/`fokus.min.js` para as
+versões minificadas em produção.
+
+## Fontes self-hosted
+
+Plus Jakarta Sans (sans) e Source Code Pro (mono) são distribuídas à parte,
+em `fonts.css`, para não forçar o download das fontes em quem prefere usar
+as próprias. Inclua **antes** do CSS principal:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/fokus-styles/dist/css/fonts.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/fokus-styles/dist/css/fokus.css">
+```
+
+Sem `fonts.css`, a tipografia cai no fallback `sans-serif`/`monospace` do
+sistema — nada quebra, só muda a fonte.
+
+## Distribuições disponíveis
+
+O pacote publica o bundle completo (`fokus.css`) e distribuições granulares,
+para quem não precisa do framework inteiro:
+
+| Arquivo | Conteúdo |
+|---|---|
+| `dist/css/fokus.css` | Bundle completo: tokens, reset, layout, forms, components, utilities, tema escuro. |
+| `dist/css/layout.css` | Só grid/containers (+ tokens/reset/tema). |
+| `dist/css/forms.css` | Só formulários (+ tokens/reset/tema). |
+| `dist/css/components.css` | Só componentes prontos (+ tokens/reset/tema). |
+| `dist/css/helpers.css` | Só utilitários atômicos (+ tokens/reset/tema). |
+| `dist/css/fonts.css` | Só os `@font-face` self-hosted (opcional, ver acima). |
+| `dist/js/fokus.js` | Todo o JavaScript dos componentes interativos, IIFE global `FokusStyles`. |
+
+Cada distribuição CSS granular já inclui tokens, reset e tema escuro
+completos — pode ser usada isoladamente sem quebrar variáveis ou dark mode.
+
+## Import via Sass
+
+Para compilar com suas próprias variáveis Sass (sobrescrever antes de
+compilar, em vez de sobrescrever CSS Custom Properties depois):
+
+```scss
+@use "fokus-styles/scss/fokus" with (
+  $radius-md: 10px
+);
+```
+
+Ver [`docs/reference/scss-architecture.md`](../reference/scss-architecture.md)
+para a lista completa de variáveis e a organização dos módulos.
+
+## Próximo passo
+
+[Formas de uso](usage.md) — como inicializar componentes interativos e a
+convenção de nomenclatura de classes.

package/docs/getting-started/usage.md

@@ -0,0 +1,105 @@
+# Formas de uso
+
+## Convenção de nomenclatura
+
+| Prefixo | Papel | Exemplo |
+|---|---|---|
+| `.fs-*` | Componente (estrutura/aparência) | `.fs-btn`, `.fs-card`, `.fs-modal` |
+| `.fs-u-*` | Utilitário atômico | `.fs-u-d-flex`, `.fs-u-mt-3`, `.fs-u-gx-2` |
+| `.is-*` | Estado, controlado por você ou por JS | `.is-active`, `.is-disabled`, `.is-open` |
+| `--fs-*` | Token CSS (Custom Property) | `--fs-color-primary`, `--fs-radius-md` |
+| `data-fs` | Auto-init de componente interativo | `data-fs="modal"` |
+| `data-fs-target`/`data-fs-dismiss` | Alvo/dispensa de componente interativo | `data-fs-target="#meuModal"` |
+| `fs:*` | Evento DOM customizado disparado por um componente | `fs:modal:shown` |
+
+Essa separação existe para o framework nunca colidir com classes de outras
+bibliotecas/CSS na mesma página — ver
+[`docs/reference/scss-architecture.md`](../reference/scss-architecture.md#cascade-layers-layer)
+para como isso se reflete em cascade layers.
+
+## Auto-init de componentes interativos
+
+Todo componente que precisa de JavaScript se inicializa sozinho ao carregar
+a página, a partir do atributo `data-fs="<nome>"` no elemento raiz — não é
+preciso chamar `new FokusStyles.Algo(...)` manualmente:
+
+```html
+<button type="button" class="fs-btn" data-fs-target="#meuModal">Abrir</button>
+
+<div class="fs-modal" data-fs="modal" id="meuModal">
+  <div class="fs-modal-dialog">
+    <div class="fs-modal-content">
+      <div class="fs-modal-body">Conteúdo.</div>
+    </div>
+  </div>
+</div>
+
+<script src="dist/js/fokus.js"></script>
+```
+
+O auto-init roda em `DOMContentLoaded` (ou imediatamente, se o script for
+carregado depois que o DOM já terminou) e é idempotente — chamar de novo não
+cria uma segunda instância no mesmo elemento.
+
+## API comum aos componentes interativos
+
+A maioria segue a mesma forma, acessível via `getInstance()`:
+
+```js
+const modal = FokusStyles.Modal.getInstance(document.getElementById("meuModal"));
+modal.show();
+modal.hide();
+modal.toggle();
+modal.dispose(); // remove listeners e o registro da instância
+```
+
+- `getInstance(el)` — retorna a instância já criada para aquele elemento
+  (`undefined` se não houver, ou se `data-fs` nunca esteve presente e você
+  precisa instanciar manualmente com `new FokusStyles.Nome(el)`).
+- `show()`/`hide()`/`toggle()` — nem todo componente tem os três (ex.:
+  Tabs usa `show(tabEl)` para trocar a aba ativa; Tag só tem `dismiss()`).
+  Ver a página de cada componente em [Componentes](../README.md#componentes)
+  para a API exata.
+- `dispose()` — remove os listeners e desregistra a instância; o elemento
+  em si não é removido do DOM (exceto onde a própria natureza do componente
+  implica remoção, como `Tag.dismiss()`).
+
+Uma exceção à regra: **Alert Dialog** não usa `data-fs`/`getInstance()` — é
+100% programático, via `FokusStyles.confirm({ title, message, ... })`, que
+retorna uma Promise. Ver
+[`../components/alert-dialog.md`](../components/alert-dialog.md).
+
+## Eventos
+
+Componentes disparam eventos DOM customizados, no padrão
+`fs:<componente>:<ação>` (particípio: `shown`/`hidden`/`changed`...),
+sempre com `bubbles: true` — escute no documento ou em qualquer ancestral:
+
+```js
+document.addEventListener("fs:modal:shown", (event) => {
+  console.log("modal aberto:", event.target);
+});
+```
+
+Alguns eventos são **canceláveis** (`cancelable: true`) — chamar
+`event.preventDefault()` no handler impede a ação (ex.: `fs:tag:dismissed`
+cancela a remoção da tag). A documentação de cada componente lista quais
+eventos existem e se são canceláveis.
+
+## Import via ES modules
+
+Além do bundle IIFE (`dist/js/fokus.js`, global `FokusStyles`), os módulos
+individuais são importáveis via `fokus-styles/js/*`:
+
+```js
+import { Modal } from "fokus-styles/js/modal.js";
+```
+
+Útil para bundlers que fazem tree-shaking — importar só o que usa em vez do
+JS inteiro.
+
+## Próximo passo
+
+[Componentes](../README.md#componentes) — catálogo completo, ou
+[Theming](../guides/theming.md) para customizar cores/tipografia/raio sem
+fork.

package/docs/guides/accessibility.md

@@ -0,0 +1,102 @@
+# Acessibilidade
+
+Acessibilidade não é um retrofit no Fokus Styles — foco, teclado e ARIA fazem
+parte da API de todo componente interativo desde a primeira versão. Este
+guia documenta os padrões **compartilhados** entre componentes; o
+comportamento específico de cada um está na sua página em
+[Componentes](../README.md#componentes), seção "A11y".
+
+## Foco visível
+
+Todo elemento interativo (botões, links, inputs, itens de menu) usa
+`:focus-visible` (não `:focus`) para o anel de destaque — aparece só na
+navegação por teclado, não em cliques de mouse, evitando o "flash" de foco
+indesejado ao clicar. O mixin `focus-ring` (`packages/fokus-core/scss/tools/_mixins.scss`)
+centraliza esse estilo; todo componente novo deve reusá-lo em vez de
+desenhar um anel de foco próprio.
+
+## Focus trap (modal, offcanvas)
+
+Componentes que sobrepõem a página inteira (Modal, Offcanvas) prendem o
+foco dentro de si enquanto abertos — `Tab` no último elemento focável volta
+pro primeiro, `Shift+Tab` no primeiro vai pro último
+(`packages/fokus-js/js/core/focus.js`, `createFocusTrap()`). Ao abrir, o
+foco vai para o primeiro elemento focável do painel; ao fechar, volta para o
+elemento que abriu (o gatilho).
+
+## Escape e clique fora
+
+Overlays (Modal, Offcanvas, Dropdown, Popover, Nested Menu) fecham com
+`Escape` e com clique fora do painel, por padrão. Componentes com um modo
+"preso" (`data-backdrop="static"` no Modal/Offcanvas) desativam essas duas
+saídas deliberadamente — para fluxos que exigem uma decisão explícita
+(confirmar/cancelar) antes de sair.
+
+## Navegação por teclado em grupos (Tabs, Accordion, Nested Menu)
+
+Grupos de itens relacionados seguem o padrão de "roving tabindex" do
+[WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/): só o item
+ativo tem `tabindex="0"`, os demais `tabindex="-1"` — `Tab` entra/sai do
+grupo de uma vez, e as setas navegam **dentro** dele:
+
+- **Tabs**: `ArrowLeft`/`ArrowRight` move entre abas, `Home`/`End` vai pra
+  primeira/última.
+- **Nested Menu**: `ArrowDown`/`ArrowUp` navegam no nível atual,
+  `ArrowRight` abre um submenu, `ArrowLeft`/`Escape` fecham.
+
+## ARIA injetado automaticamente
+
+Alguns atributos ARIA são calculados e aplicados pelo próprio JS na
+inicialização (não precisam ser escritos manualmente no HTML) — por
+exemplo, Tabs aplica `role="tablist"`/`role="tab"`/`aria-selected`/
+`aria-controls` aos elementos com `data-fs="tabs"`. Onde isso acontece, a
+página do componente avisa explicitamente; o resto (`aria-label` em botões
+sem texto visível, `alt` em imagens, etc.) é responsabilidade de quem
+escreve o HTML — o framework não adivinha texto alternativo.
+
+## `prefers-reduced-motion`
+
+Toda transição de altura acionada por JS (Collapse, Accordion, Toast via
+`packages/fokus-js/js/core/transition.js`) verifica
+`window.matchMedia("(prefers-reduced-motion: reduce)")` e pula direto para
+o estado final — sem animação — quando o usuário pediu menos movimento no
+sistema operacional. A camada base do CSS também reduz automaticamente
+transições e animações declaradas pelo framework quando essa preferência está
+ativa. Se você adicionar uma animação própria, preserve o estado final e
+teste o comportamento com `prefers-reduced-motion: reduce`.
+
+## Contraste de cor
+
+Botões/badges/alerts sólidos calculam a cor de texto automaticamente
+(`color-contrast()`) para garantir contraste AA (≥ 4.5:1 texto normal, ≥
+3:1 texto grande/UI) contra a cor de fundo escolhida — nunca é preciso
+escolher manualmente entre texto branco ou preto. O relatório
+`npm run contrast` (ver [`docs/reference/contrast-report.md`](../reference/contrast-report.md))
+audita os pares texto/fundo de tokens nos temas claro e escuro; rode-o
+depois de qualquer mudança de cor de token.
+
+## Formulários
+
+Inputs de validação (`.is-valid`/`.is-invalid`) e os textos de apoio
+(`.fs-valid-feedback`/`.fs-invalid-feedback`, `.fs-form-text`) são
+elementos visuais — associe-os ao input via `aria-describedby` no seu HTML
+para que leitores de tela anunciem a mensagem ao focar o campo. O
+framework não injeta esse atributo automaticamente, porque o `id` do texto
+de apoio é definido por você.
+
+## Testes automatizados
+
+A regressão visual (`npm run test:visual`, Playwright) cobre
+carregamento/interação sem erros de console, mas não é um gate de
+acessibilidade. `npm run test:a11y` roda o axe-core (regras WCAG 2.1 A/AA)
+ contra cada laboratório em `mockup/*.html` (claro e escuro) e contra as
+ fontes executáveis em `mockup/examples/*.html`; o build falha ao encontrar
+violações (nome acessível ausente, contraste insuficiente, papel ARIA
+inválido etc.) — roda no CI a cada PR. Veja a cobertura por componente na
+[matriz de acessibilidade](../reference/accessibility-matrix.md).
+
+Mesmo com o gate automatizado, valide manualmente com um leitor de tela e
+navegação só por teclado antes de considerar um componente pronto — axe
+cobre um subconjunto de regras verificáveis por máquina (contraste, nomes,
+papéis), não a experiência real de uso (ordem de leitura, clareza dos
+anúncios, foco percebido).

package/docs/guides/charts.md

@@ -0,0 +1,73 @@
+# Gráficos (tokens agnósticos de biblioteca)
+
+O FokusStyles **não inclui um wrapper de nenhuma biblioteca de gráficos** — em
+vez disso, expõe um conjunto pequeno de tokens (`--fs-chart-*`) que
+qualquer lib (Chart.js, ECharts, Recharts, D3, Highcharts…) pode consumir
+via `getComputedStyle`. Zero dependência nova, zero manutenção atrelada à
+API de uma lib de terceiro que muda com o tempo, e o gráfico acompanha
+`data-theme`/`data-fs-brand` automaticamente porque os tokens são aliases da
+camada semântica já existente (mesma técnica de `tokens/_semantic.scss`).
+
+## Tokens
+
+| Token | Uso sugerido |
+|---|---|
+| `--fs-chart-series-1` … `--fs-chart-series-6` | Cor de cada série/categoria de dados. |
+| `--fs-chart-grid` | Linhas de grade do plano cartesiano. |
+| `--fs-chart-axis` | Rótulos e linhas dos eixos. |
+| `--fs-chart-tooltip-bg` / `--fs-chart-tooltip-text` | Fundo/texto do tooltip do gráfico. |
+
+As 6 séries reaproveitam as cores de tema (`primary`/`success`/`warning`/
+`danger`/`info`/`secondary`) — uma paleta categórica coerente com o resto
+da interface, sem introduzir cor nova. Se seu gráfico precisar de mais de
+6 séries ou de uma paleta com propósito diferente (sequencial/divergente),
+sobrescreva os tokens que precisar; eles são só `var()`, então qualquer
+CSS depois do import do FokusStyles vence.
+
+## Uso
+
+Leia os tokens em runtime com `getComputedStyle` e passe pra sua lib de
+gráficos na hora de montar a configuração:
+
+```js
+const styles = getComputedStyle(document.documentElement);
+const chartColors = {
+  series: [1, 2, 3, 4, 5, 6].map((n) => styles.getPropertyValue(`--fs-chart-series-${n}`).trim()),
+  grid: styles.getPropertyValue("--fs-chart-grid").trim(),
+  axis: styles.getPropertyValue("--fs-chart-axis").trim(),
+  tooltipBg: styles.getPropertyValue("--fs-chart-tooltip-bg").trim(),
+  tooltipText: styles.getPropertyValue("--fs-chart-tooltip-text").trim(),
+};
+```
+
+Exemplo com Chart.js:
+
+```js
+new Chart(ctx, {
+  type: "bar",
+  data: {
+    labels: ["Jan", "Fev", "Mar"],
+    datasets: [{ data: [12, 19, 7], backgroundColor: chartColors.series[0] }],
+  },
+  options: {
+    scales: {
+      x: { grid: { color: chartColors.grid }, ticks: { color: chartColors.axis } },
+      y: { grid: { color: chartColors.grid }, ticks: { color: chartColors.axis } },
+    },
+  },
+});
+```
+
+## Tema escuro e multi-brand
+
+Como os tokens de série são aliases de `--fs-color-*`, eles já respondem a
+`data-theme="dark"` e `data-fs-brand="x"` (ver [Theming](theming.md)) sem
+nenhum código adicional — só é preciso reler `getComputedStyle` (ou
+recriar o gráfico) depois de uma troca de tema/marca em runtime, porque a
+maioria das libs de gráfico não observa mudanças de CSS custom properties
+sozinha.
+
+## Próximo passo
+
+[Theming](theming.md) — as 3 camadas de tokens que os tokens de gráfico
+reaproveitam.

package/docs/guides/dark-mode.md

@@ -0,0 +1,90 @@
+# Dark mode
+
+O tema escuro é nativo desde a primeira versão do framework — não é um
+plugin nem exige JavaScript.
+
+## Ativação
+
+Um único atributo no `<html>` (ou em qualquer contêiner — o tema se aplica
+por escopo, não só global):
+
+```html
+<html data-theme="dark">
+```
+
+```html
+<!-- Escopo local: só este painel fica escuro -->
+<div data-theme="dark">
+  <div class="fs-card">...</div>
+</div>
+```
+
+Não há classe `.dark`/`.fs-dark` — é sempre o atributo `data-theme="dark"`.
+Remover o atributo (ou trocar pra qualquer outro valor) volta ao tema claro.
+
+## Como funciona
+
+`packages/fokus-core/scss/themes/_dark.scss` redefine os tokens semânticos
+de cor (`--fs-color-text`, `--fs-color-surface`, `--fs-color-{primary,
+success,...}`, `--fs-alert-*-bg/-text`, `--fs-feedback-*-bg`) sob o seletor
+`[data-theme="dark"]`. Como todo componente já consome esses tokens via
+`var()`, nenhum CSS extra por componente é necessário — trocar o atributo já
+propaga a cor nova para tudo.
+
+As cores do tema escuro não são um segundo conjunto arbitrário: primary/
+secondary/success/warning/danger/info são misturados (`color.mix()`, espaço
+OKLCH) a partir do mesmo primitivo do tema claro, clareando em direção ao
+branco — mantém a identidade de cor entre os dois temas. Os pesos de mistura
+foram calibrados para manter contraste WCAG AA (ver
+[`docs/reference/contrast-report.md`](../reference/contrast-report.md) e
+`npm run contrast`).
+
+## JavaScript para alternar (opcional)
+
+O framework não fornece um componente de "toggle de tema" pronto — é
+deliberadamente simples de implementar com o que você já tem
+(`.fs-switch`, ver [`../components/switch.md`](../components/switch.md)):
+
+```html
+<div class="fs-switch">
+  <input type="checkbox" class="fs-switch-input" id="theme-toggle">
+  <label for="theme-toggle" class="fs-switch-label">Tema escuro</label>
+</div>
+```
+
+```js
+const toggle = document.getElementById("theme-toggle");
+const stored = localStorage.getItem("theme");
+
+if (stored === "dark") {
+  document.documentElement.setAttribute("data-theme", "dark");
+  toggle.checked = true;
+}
+
+toggle.addEventListener("change", () => {
+  const theme = toggle.checked ? "dark" : "light";
+  document.documentElement.setAttribute("data-theme", theme);
+  localStorage.setItem("theme", theme);
+});
+```
+
+Para respeitar a preferência do sistema operacional por padrão (antes de
+qualquer escolha manual salva), combine com
+`window.matchMedia("(prefers-color-scheme: dark)").matches` na primeira
+carga.
+
+## Customizando o tema escuro
+
+Como qualquer outro token, redefina sob `[data-theme="dark"]` no seu
+próprio CSS — carregado **depois** do CSS do FokusStyles, para vencer a cascata:
+
+```css
+[data-theme="dark"] {
+  --fs-color-surface: #14151a;
+}
+```
+
+## Próximo passo
+
+[Acessibilidade](accessibility.md) — teclado, ARIA e contraste por
+componente.