fokus-styles 2.0.0

package/docs/guides/icons.md

@@ -0,0 +1,99 @@
+# Ícones
+
+O Fokus Styles inclui ícones como subpath opcional — ícone é conteúdo, não
+estilo, e o bundle principal não importa nenhum deles. Use
+`fokus-styles/icons`, com 1994 ícones SVG do conjunto
+[Lucide](https://lucide.dev) (licença ISC), mais uma classe utilitária
+`.fs-icon` no `fokus-styles` (sempre disponível, custo desprezível) pro
+dimensionamento.
+
+## Instalação
+
+```bash
+npm install fokus-styles
+```
+
+Zero dependências em runtime — o subpath contém apenas arquivos `.svg` e módulos
+`.js` gerados; `lucide-static` é usado apenas para gerar o pacote, nunca é
+instalado por quem consome o `fokus-styles`.
+
+## Uso — SVG puro (zero JS)
+
+Cada ícone pode ser resolvido como `fokus-styles/svg/<nome>.svg`, já
+com `class="fs-icon"` aplicada. Copie o conteúdo direto no seu HTML:
+
+```html
+<button type="button" class="fs-btn fs-btn-primary">
+  <svg class="fs-icon" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20 6 9 17l-5-5"/></svg>
+  Salvar
+</button>
+```
+
+Essa é a forma recomendada: nenhuma dependência de build, o SVG já nasce
+otimizado (sem comentários, sem atributos redundantes).
+
+## Uso — módulo JS (tree-shakeable)
+
+Se seu projeto já usa um bundler (Vite, esbuild, Rollup, webpack), importe
+só os ícones que usa — cada um é um módulo próprio, então o restante dos
+1994 nunca entra no seu bundle final:
+
+```js
+import check from "fokus-styles/icons/check.js";
+
+document.querySelector("#status-icon").innerHTML = check;
+```
+
+Ou pelo barrel, com nomes em camelCase (`arrow-right` → `arrowRight`):
+
+```js
+import { arrowRight, check } from "fokus-styles/icons";
+```
+
+O pacote é publicado com `"sideEffects": false`, então bundlers modernos
+eliminam os ícones não usados mesmo importando do barrel — mas prefira o
+caminho direto (`fokus-styles/icons/check.js`) se seu bundler não fizer
+tree-shaking de barrels corretamente.
+
+## Dimensionamento e cor — `.fs-icon`
+
+```html
+<svg class="fs-icon fs-icon-lg" ...>...</svg>
+```
+
+| Classe | Tamanho |
+|---|---|
+| `.fs-icon` (padrão) | `1em` × `1em` — acompanha o `font-size` do elemento ao redor |
+| `.fs-icon-xs` | 12px |
+| `.fs-icon-sm` | 16px |
+| `.fs-icon-lg` | 32px |
+| `.fs-icon-xl` | 48px |
+
+Cor: os ícones usam `stroke="currentColor"` — herdam a cor do texto
+automaticamente. Para uma cor diferente do texto ao redor, aplique `color`
+no elemento (ou num ancestral) como faria com qualquer texto.
+
+## Ícones em componentes com JS
+
+Componentes como [Combobox](../components/combobox.md) ou
+[Command Palette](../components/command-palette.md) não têm nenhuma
+integração especial com `fokus-styles/icons` — você cola o SVG (ou injeta via
+módulo JS) dentro da marcação normal do componente, exatamente como faria
+com qualquer outro conteúdo:
+
+```html
+<li class="fs-dropdown-item" data-value="download">
+  <svg class="fs-icon" ...>...</svg>
+  Baixar arquivo
+</li>
+```
+
+## Licença
+
+O código de geração do pacote é MIT (mesma licença do FokusStyles). Os ícones
+em si são do projeto Lucide, licença ISC — parte deles derivada do
+projeto Feather (MIT). Ambos os avisos de copyright são distribuídos junto
+do pacote (`LICENSE`/`LICENSE-LUCIDE.txt` em `node_modules/fokus-styles/packages/fokus-icons/`
+depois de instalado).
+
+Mockup: [`mockup/foundations.html#icons`](../../mockup/foundations.html#icons).

package/docs/guides/layout-advanced.md

@@ -0,0 +1,118 @@
+# Layout avançado
+
+Três primitivas de layout CSS-only (Stack, Cluster, Sidebar), utilitários de
+posição sticky e utilitários de container query (`@container`) — para
+composições que os utilitários de grid/flex existentes (`.fs-row`/`.fs-col-*`,
+`.fs-u-d-flex`) não cobrem bem sozinhos. Exemplo funcional completo em
+[`mockup/foundations.html#layout`](../../mockup/foundations.html#layout).
+
+## Stack
+
+Empilha os filhos diretos verticalmente com espaçamento consistente via
+`gap` (não `margin` — evita o problema de "o último filho não deve ter
+margin-bottom"):
+
+```html
+<div class="fs-stack">
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</div>
+```
+
+O espaçamento padrão vem do token `--fs-stack-gap` (`$spacers[3]`, `1rem`).
+Ajuste com uma classe `.fs-stack-gap-{0..5}` (mesma escala de
+`$spacers` usada nos utilitários `.fs-u-m*`/`.fs-u-p*`) ou redefinindo o token
+direto no elemento:
+
+```html
+<div class="fs-stack fs-stack-gap-1">…</div>
+```
+
+## Cluster
+
+Agrupa itens horizontalmente com quebra de linha automática e espaçamento
+consistente nos dois eixos — para grupos de tags, botões ou badges que
+precisam "fluir" sem estourar o container:
+
+```html
+<div class="fs-cluster">
+  <span class="fs-tag">Frontend</span>
+  <span class="fs-tag">CSS</span>
+  <span class="fs-tag">Acessibilidade</span>
+</div>
+```
+
+Gap ajustável do mesmo jeito que o Stack: `.fs-cluster-gap-{0..5}` ou
+`--fs-cluster-gap`.
+
+## Sidebar
+
+Um lado com largura fixa (a "aside") e o outro preenchendo o espaço
+restante — quebra para empilhado quando o container fica estreito demais,
+sem media query (a técnica é puramente flexbox: `.fs-sidebar-content` tem
+`flex-basis: 0` e `min-width: 50%`, forçando a quebra quando não cabe ao
+lado da aside na largura disponível):
+
+```html
+<div class="fs-sidebar">
+  <aside class="fs-sidebar-aside">Menu lateral</aside>
+  <div class="fs-sidebar-content">Conteúdo principal</div>
+</div>
+```
+
+- Largura da aside: `--fs-sidebar-width` (padrão `16rem`), ou uma classe
+  `.fs-sidebar-width-{sm,md,lg,xl,xxl,xxxl}` (reusa a escala de
+  `$column-max-widths`, de 120px a 720px).
+- `.fs-sidebar-reverse` inverte a ordem visual (aside à direita).
+- Gap: `.fs-sidebar-gap-{0..5}` ou `--fs-sidebar-gap`.
+
+## Sticky
+
+`.fs-u-sticky-top`/`.fs-u-sticky-bottom` (`position: sticky`) com offset
+configurável via `--fs-sticky-top`/`--fs-sticky-bottom` (padrão `0`) e
+`z-index: 1020` (mesma faixa numérica dos demais componentes de overlay —
+acima de conteúdo normal e do Dropdown, abaixo de Modal/Offcanvas):
+
+```html
+<div style="overflow-y: auto; max-height: 300px;">
+  <div class="fs-u-sticky-top">Cabeçalho fixo</div>
+  <p>Conteúdo rolável…</p>
+</div>
+```
+
+Um contêiner com scroll próprio (como no exemplo acima) precisa ser
+focável por teclado (`tabindex="0"`) se o conteúdo for maior que a área
+visível — sem isso, quem navega só por teclado não consegue rolar o
+conteúdo (regra `scrollable-region-focusable` do gate `axe` no CI).
+
+## Container queries (`@container`)
+
+Reagem à largura do **container** mais próximo, não da viewport — útil
+para um componente que se comporta de forma diferente dependendo de onde é
+colocado (uma sidebar estreita vs. uma área de conteúdo larga), independente
+do tamanho da tela. Ative com `.fs-u-cq` no elemento pai:
+
+```html
+<div class="fs-u-cq">
+  <div class="fs-u-cq-md-d-flex fs-u-gap-2">
+    <div>A</div>
+    <div>B</div>
+  </div>
+</div>
+```
+
+- `.fs-u-cq` define `container-type: inline-size` — só aplique num elemento
+  cuja largura você quer usar como referência (não precisa ser o `:root`).
+- Utilitários disponíveis: `.fs-u-cq-{sm,md,lg}-d-{none,block,inline-block,flex}`,
+  seguindo os limiares `--fs-cq-sm` (320px), `--fs-cq-md` (480px),
+  `--fs-cq-lg` (640px) — uma escala própria, mais compacta que a de
+  viewport (`$breakpoints`), porque containers costumam ser bem menores
+  que a tela inteira.
+- Os tokens `--fs-cq-*` em `:root` são só **informativos** (documentam os
+  valores usados) — a condição de um `@container` exige um valor literal
+  em tempo de build, não aceita `var()`; mudar o token em runtime não
+  recalibra as regras já compiladas.
+- Complementam, não substituem, os utilitários de viewport existentes
+  (`.fs-u-d-flex` etc.) — para a maioria dos casos, media query por viewport
+  continua sendo a ferramenta certa.

package/docs/guides/migration-clarus-to-fokus.md

@@ -0,0 +1,48 @@
+# Migração do Clarus para o Fokus Styles
+
+O Fokus Styles 2.0 renomeia integralmente a API pública do Clarus. Não há
+aliases: atualize todos os imports, seletores, atributos e acessos ao global
+JavaScript antes de remover o pacote anterior.
+
+| Clarus 1.x | Fokus Styles 2.0 |
+| --- | --- |
+| `clarus-css` | `fokus-styles` |
+| `clarus-icons` | `fokus-styles/icons` |
+| `clarus-react` | `fokus-styles/react` |
+| `clarus-cli` | `fokus-styles` com o comando `fokus` |
+| `.fs-*` | `.fs-*` |
+| `.u-*` | `.fs-u-*` |
+| `--fs-*` | `--fs-*` |
+| `data-fs*` | `data-fs*` |
+| `data-fs-brand` | `data-fs-brand` |
+| `window.Clarus` | `window.FokusStyles` |
+| `fs:*` | `fs:*` |
+
+## Instalação
+
+```bash
+npm uninstall clarus-css clarus-icons clarus-cli clarus-react
+npm install fokus-styles
+```
+
+## Exemplo
+
+```html
+<button class="fs-btn fs-btn-primary" data-fs="modal" data-fs-target="#perfil">
+  Abrir perfil
+</button>
+
+<script src="node_modules/fokus-styles/dist/js/fokus.min.js"></script>
+<script>
+  document.addEventListener("fs:modal:shown", () => console.log("aberto"));
+</script>
+```
+
+Para React, importe `ModalTrigger`, `ModalPanel`, `DropdownTrigger`,
+`DropdownMenu` e `TabList` de `fokus-styles/react`. Para ícones, importe do
+barrel `fokus-styles/icons` ou de um módulo individual como
+`fokus-styles/icons/check.js`.
+
+O codemod `scripts/migrate-fokus.mjs` ajuda a converter a versão anterior do
+framework. Execute-o primeiro com `--dry-run`, revise o diff e só então grave
+as alterações.

package/docs/guides/migration-external.md

@@ -0,0 +1,123 @@
+# Guia de migração — vindo de outro framework CSS
+
+Este guia é para quem já usa **outro framework CSS de utilitários/componentes**
+(ex.: um framework baseado em classes utilitárias tipo `flex`/`gap-4`, ou um
+framework de componentes com prefixo `.btn`/`.card`/`.alert`) e quer migrar
+pro Fokus Styles. Ele mapeia os padrões de nomenclatura mais comuns do
+ecossistema pros equivalentes do FokusStyles — não é uma migração automatizada
+(classes e comportamento não são 1:1 em todo canto), mas cobre os casos mais
+frequentes.
+
+> Procurando pela migração de uma versão **antiga do FokusStyles** (rename da
+> API pública pra prefixo `fs-`) para a v1.0.0? Isso é
+> [`migration-v1.md`](migration-v1.md), um guia diferente.
+
+## Como o FokusStyles nomeia as coisas
+
+Duas convenções fixas, sem exceção, ajudam a prever qualquer classe sem
+decorar a lista inteira:
+
+- **Componentes**: prefixo `fs-` (`.fs-btn`, `.fs-card`, `.fs-modal`).
+- **Utilitários** (uma propriedade CSS por classe): prefixo `fs-u-` (`.fs-u-d-flex`,
+  `.fs-u-mt-3`, `.fs-u-text-center`).
+
+Responsividade é sempre um infixo de breakpoint antes do valor:
+`.fs-u-d{-sm|-md|-lg|-xl|-xxl}-flex`, `.fs-u-mt-lg-4` — nunca um prefixo diferente
+por breakpoint.
+
+## Utilitários de layout (flexbox/grid/spacing)
+
+Framework baseados em classes utilitárias atômicas costumam usar nomes
+curtos sem prefixo (`flex`, `gap-4`, `p-2`) ou com prefixo de uma letra
+(`d-flex`, `mt-3`, já familiar a quem vem de um framework de componentes com
+utilitários auxiliares). O FokusStyles usa **nomes completos com prefixo `fs-u-`**,
+priorizando previsibilidade sobre brevidade:
+
+| Padrão comum no ecossistema | Fokus Styles | Observação |
+|---|---|---|
+| `flex` / `d-flex` | `.fs-u-d-flex` | Idem `.fs-u-d-block`, `.fs-u-d-none`, `.fs-u-d-inline-block`. |
+| `items-center` / `align-items-center` | `.fs-u-align-items-center` | Também `-start`/`-end`. |
+| `justify-between` / `justify-content-between` | `.fs-u-justify-content-between` | Também `-start`/`-center`/`-end`/`-around`. |
+| `gap-4` / `gap-3` (escala 0–5) | `.fs-u-gap-4` | Escala de espaçamento própria — ver [tokens](../reference/design-tokens.md) pro mapa `$spacers`; não é 1:1 numérico com a escala de outros frameworks. |
+| `m-4`, `mt-2`, `mx-auto` | `.fs-u-m-4`, `.fs-u-mt-2`, `.fs-u-mx-auto` | Mesmo padrão de abreviação (`m`/`mt`/`mr`/`mb`/`ml`/`mx`/`my`) já usado por frameworks de componentes com utilitários auxiliares — só troca o prefixo pra `fs-u-`. |
+| `p-4`, `px-3`, `py-2` | `.fs-u-p-4`, `.fs-u-px-3`, `.fs-u-py-2` | Idem acima, para padding. |
+| `text-center` | `.fs-u-text-center` | Também `-start`/`-end`. |
+| `font-bold` / `fw-bold` | `.fs-u-fw-bold` | Também `-regular`/`-medium`/`-semibold`. |
+| `text-lg` / `fs-5` | `.fs-u-fs-lg` | Escala nomeada (`xs`/`sm`/`md`/`lg`/`xl`/`h1`…`h6`), não numérica. |
+| `hidden` / `d-none` | `.fs-u-d-none` | Oculta via `display: none` (remove do layout e da árvore de acessibilidade). |
+| `invisible` | `.fs-u-invisible` | `visibility: hidden` — reserva o espaço no layout, ao contrário de `.fs-u-d-none`. |
+| `container` | `.fs-container` | Componente de layout, não utilitário — ver seção seguinte. |
+| `row` / `grid grid-cols-12` | `.fs-row` | Grid flexbox de 12 colunas, não CSS Grid. |
+| `col`, `col-6`, `col-md-4` | `.fs-col`, `.fs-col-6`, `.fs-col-md-4` | Mesma lógica de frações de 12 colunas com infixo de breakpoint. |
+
+Para stack/cluster/sidebar/sticky/container-queries (utilitários de layout
+mais recentes, sem equivalente direto e estabelecido em frameworks mais
+antigos), veja o guia dedicado
+[`layout-advanced.md`](layout-advanced.md) — não há "de onde migrar" porque
+são aditivos, não substituem nada que você já tinha.
+
+## Componentes
+
+Frameworks de componentes tradicionalmente usam classes curtas sem prefixo
+(`.btn`, `.card`, `.alert`); frameworks só-utilitários normalmente não têm
+esse conceito (você compõe o visual de um botão a partir de utilitários) —
+o FokusStyles segue o primeiro modelo, com o prefixo `fs-` obrigatório em todos:
+
+| Padrão comum (framework de componentes) | Fokus Styles |
+|---|---|
+| `.btn`, `.btn.btn-primary` | `.fs-btn`, `.fs-btn.fs-btn-primary` |
+| `.btn-outline-primary` | `.fs-btn-outline-primary` |
+| `.btn-sm`, `.btn-lg` | `.fs-btn-sm`, `.fs-btn-lg` |
+| `.card`, `.card-header`, `.card-body`, `.card-footer` | `.fs-card`, `.fs-card-header`, `.fs-card-body`, `.fs-card-footer` |
+| `.alert.alert-danger` | `.fs-alert.fs-alert-danger` |
+| `.badge.bg-primary` / `.badge.badge-primary` | `.fs-badge.fs-badge-primary` |
+| `.table.table-striped` | `.fs-table.fs-table-striped` |
+| `.modal`, `.modal-dialog`, `.modal-body` | `.fs-modal`, `.fs-modal-dialog`, `.fs-modal-body` — ver [modal.md](../components/modal.md) pra diferenças de API JS |
+| `.dropdown-menu`, `.dropdown-item` | `.fs-dropdown-menu`, `.fs-dropdown-item` |
+| `.form-control` | `.fs-form-control` |
+
+Se você está migrando de um framework só-utilitários (sem classes de
+componente prontas), o ponto de partida é o oposto: em vez de recompor cada
+botão/card a partir de utilitários, procure o componente FokusStyles equivalente
+em [`docs/components/`](../components/) — geralmente é menos código, não
+mais.
+
+## O que **não** migra 1:1
+
+- **API JavaScript**: nomes de método/evento são específicos do FokusStyles
+  (`data-fs="modal"`, `FokusStyles.Modal.getInstance()`, eventos
+  `fs:modal:shown`) — não há compatibilidade de API com nenhum outro
+  framework. Veja a página de cada componente em
+  [`docs/components/`](../components/) pra API completa.
+- **Escala de espaçamento/tipografia**: os valores numéricos
+  (`fs-u-gap-4`, `fs-u-fs-lg`) seguem a escala própria do FokusStyles
+  (`$spacers`/`$font-size-*`), não a de nenhum outro framework — não
+  assuma que `gap-4` de outro lugar é visualmente idêntico a `.fs-u-gap-4`
+  aqui, mesmo com o nome parecido.
+- **Grid**: `.fs-row`/`.fs-col-*` é flexbox de 12 colunas, não CSS Grid —
+  se você vem de um framework CSS Grid nativo (`grid-cols-12`), o modelo
+  mental de "colunas fluem e quebram linha" é diferente de "células fixas
+  numa grade".
+- **Tema/dark mode**: o FokusStyles usa `data-theme="dark"` num ancestral
+  (não uma classe `.dark` no `<html>`) — ver [`dark-mode.md`](dark-mode.md).
+- **Build/configuração**: não há arquivo de configuração JS central
+  (customização é via variáveis Sass — `$primitives`, `$spacers` etc.) —
+  ver [`scss-architecture.md`](../reference/scss-architecture.md).
+
+## Checklist de migração
+
+1. Troque classes de utilitário: adicione o prefixo `fs-u-` e expanda
+   abreviações de uma letra pro nome completo mais próximo da tabela acima
+   (`flex` → `fs-u-d-flex`, não existe atalho de uma letra no FokusStyles).
+2. Troque classes de componente: adicione o prefixo `fs-` em todas
+   (`.btn` → `.fs-btn`, incluindo variantes: `.btn-primary` → `.fs-btn-primary`).
+3. Rode `npm run lint:scss` (se você também copiou SCSS customizado — o
+   FokusStyles usa Stylelint com `stylelint-config-standard-scss`) e
+   `npm run test:visual` (se tiver mockups próprios) pra pegar
+   divergências visuais cedo.
+4. Refaça a integração JS pelos `data-fs="*"`/`data-fs-target`/eventos
+   `fs:*` — não existe camada de compatibilidade com a API de outro
+   framework.
+5. Revise a matriz de [suporte a navegadores](../reference/browser-support.md)
+   se seu projeto anterior mirava um alvo diferente (ex.: IE11) — o FokusStyles
+   não suporta IE11 e usa `@layer`/OKLCH nativamente.

package/docs/guides/migration-v1.md

@@ -0,0 +1,63 @@
+# Guia de migração para v1.0.0
+
+A v1.0.0 renomeia mecanicamente toda a API pública do Fokus Styles para evitar
+colisão com classes de terceiros na mesma página. É a única mudança
+breaking desta versão — nenhum componente foi removido ou teve
+comportamento alterado.
+
+Não mudam: o global `window.FokusStyles` e o nome do pacote npm `fokus-styles`.
+
+## O que muda
+
+| Categoria | Antes | Depois | Exemplo |
+|---|---|---|---|
+| Classe de componente/layout | sem prefixo | `fs-` | `.btn` → `.fs-btn`, `.dropdown-menu` → `.fs-dropdown-menu`, `.container`/`.row`/`.col-*` → `.fs-container`/`.fs-row`/`.fs-col-*` |
+| Classe utilitária | sem prefixo | `fs-u-` | `.d-flex` → `.fs-u-d-flex`, `.mt-3` → `.fs-u-mt-3` |
+| Estado controlado por JS | variava | `is-*` | `.show` → `.is-open`, `.active` → `.is-active`, `.disabled` → `.is-disabled` |
+| Tokens CSS | `--fokus-*` | `--fs-*` | `--fokus-color-primary` → `--fs-color-primary` |
+| Atributo de auto-init | `data-fokus` | `data-fs` | `data-fokus="modal"` → `data-fs="modal"` |
+| Atributos de alvo/dispensa | `data-target`/`data-dismiss` | `data-fs-target`/`data-fs-dismiss` | `data-target="#foo"` → `data-fs-target="#foo"` |
+| Eventos DOM customizados | `fokus:*` | `fs:*` | `fokus:modal:shown` → `fs:modal:shown` |
+
+`.is-valid`/`.is-invalid` (validação de formulário) e `.is-dragover`
+(file-drop) já seguiam a convenção `is-*` antes da v1 — não mudam.
+
+## Rodando o codemod
+
+O pacote inclui um codemod que aplica essas substituições em arquivos
+HTML/JS (`class="..."`, `data-fokus`/`data-target`/`data-dismiss`, tokens
+`--fokus-*` em `<style>`/JS, e strings de evento `fokus:*`):
+
+```bash
+node node_modules/fokus-styles/scripts/migrate-v1.mjs caminho/para/seu/projeto --dry-run
+node node_modules/fokus-styles/scripts/migrate-v1.mjs caminho/para/seu/projeto
+```
+
+- `--dry-run` só lista os arquivos que seriam alterados, sem escrever nada.
+- Sem `--dry-run`, sobrescreve os arquivos in-place — rode com o working
+  tree do seu projeto limpo (git) para poder revisar o diff depois.
+- A substituição de classes é por correspondência **exata de token**: o
+  codemod só troca tokens que batem com um nome antigo conhecido do FokusStyles
+  (`scripts/migrate-v1-map.json`, ~1360 pares gerados diretamente da
+  renomeação). Uma classe sua com o mesmo nome de uma classe antiga do
+  FokusStyles (ex.: você também tinha uma `.card` própria) seria trocada por
+  engano — **revise o diff antes de commitar**.
+- O codemod não cobre CSS que você escreveu contra o seletor antigo (ex.:
+  `.btn { ... }` no seu próprio stylesheet, sobrescrevendo o FokusStyles) — isso
+  precisa de ajuste manual, com a tabela acima como referência.
+
+## Checklist de migração manual
+
+1. Rode o codemod (acima) na sua base HTML/JS.
+2. Busque no seu CSS por seletores que dependam das classes antigas do
+   FokusStyles (não só sobre elas, mas herdando de `--fokus-*`) e atualize para
+   os novos nomes/tokens.
+3. Se você escuta os eventos customizados do FokusStyles
+   (`addEventListener("fokus:...")`), confirme que o codemod pegou todas as
+   strings — ele só reescreve literais entre aspas.
+4. Rode sua suíte de testes/visual regression e confira manualmente os
+   componentes interativos (modal, dropdown, tabs, offcanvas) — o
+   comportamento não muda, só os seletores.
+5. Se você customizava o framework via `--fokus-*` num stylesheet próprio
+   (não gerado pelo codemod, por não estar em HTML/JS), atualize esses
+   arquivos `.css` manualmente para `--fs-*`.

package/docs/guides/print.md

@@ -0,0 +1,30 @@
+# Utilitários de impressão
+
+Classes para ajustar o layout quando a página é impressa (`@media print`),
+sem exigir uma folha de estilos de impressão separada.
+
+## Classes
+
+- `.fs-u-print-hide` — oculta o elemento só na impressão (`display: none`).
+  Útil para navbars, botões de ação, sidebars de navegação.
+- `.fs-u-print-only` — oculta o elemento fora da impressão; ele só aparece no
+  resultado impresso (ex.: um bloco com URL/data de geração do documento).
+- `.fs-u-print-block` / `.fs-u-print-inline` / `.fs-u-print-inline-block` — força um
+  valor de `display` só na impressão, útil para reverter um `.fs-u-d-none` (ou
+  outro `display` aplicado na tela) especificamente no documento impresso.
+
+```html
+<header class="fs-u-print-hide">
+  <nav>…</nav>
+</header>
+
+<div class="fs-u-print-only">Gerado em fokus-styles.dev — 2026-07-07</div>
+```
+
+## Notas
+
+- São utilitários de `display`, não uma folha de estilos de impressão
+  completa — não alteram cor, quebra de página ou tamanho de fonte.
+- Combinam com os demais utilitários de `display` (`.fs-u-d-*`): a classe de
+  impressão só atua dentro de `@media print`, então não conflita com o
+  valor aplicado na tela.

package/docs/guides/theming.md

@@ -0,0 +1,140 @@
+# Theming
+
+Toda a identidade visual do Fokus Styles é exposta via CSS Custom Properties
+(prefixo `--fs-*`) — customize redefinindo a variável no seu próprio CSS,
+sem fork e sem recompilar.
+
+## As 3 camadas de tokens
+
+1. **Primitivo** — valores Sass em tempo de compilação
+   (`packages/fokus-core/scss/settings/`): `$color-blue-500`, `$radius-md`,
+   `$spacers`. Não são emitidos como CSS diretamente; só existem para gerar
+   as camadas seguintes.
+2. **Semântico** — CSS Custom Properties nomeadas por papel, não por valor
+   (`packages/fokus-core/scss/tokens/`): `--fs-color-primary`,
+   `--fs-color-bg-surface`, `--fs-color-text-primary`,
+   `--fs-color-border-default`. É aqui que você customiza na prática.
+3. **Componente** — alguns componentes expõem tokens próprios, com fallback
+   pra um token semântico (ex.: `.fs-btn` tem `--fs-btn-bg`/`--fs-btn-color`/
+   `--fs-btn-border-color`) — permite sobrescrever **uma instância**
+   específica sem afetar o resto:
+
+   ```css
+   .meu-botao-especial {
+     --fs-btn-bg: #6d28d9;
+   }
+   ```
+
+Ver [`docs/reference/design-tokens.md`](../reference/design-tokens.md) para
+a lista completa de tokens e [`docs/reference/scss-architecture.md`](../reference/scss-architecture.md)
+para como as camadas se organizam em `@layer`.
+
+## Customizando globalmente
+
+Redefina o token semântico em `:root` (afeta todos os componentes que o
+usam):
+
+```css
+:root {
+  --fs-color-primary: #6d28d9;
+  --fs-radius-md: 10px;
+  --fs-font-sans: "Inter", sans-serif;
+}
+```
+
+Isso funciona em runtime, direto no CSS final — não precisa recompilar o
+Sass nem ter acesso ao código-fonte do framework.
+
+## Cores: OKLCH com fallback automático
+
+Os primitivos de cor são gerados em [OKLCH](https://oklch.com/), calibrados
+para reproduzir o mesmo matiz do hex histórico do projeto (round-trip
+hex→oklch→hex). Cada token de cor é declarado duas vezes:
+
+```css
+:root {
+  --fs-color-primary: #1a61e6; /* fallback sRGB, todo navegador */
+}
+
+@supports (color: oklch(0% 0 0)) {
+  :root {
+    --fs-color-primary: oklch(53.6% 0.213 261.6deg); /* nativo, navegadores modernos */
+  }
+}
+```
+
+Navegadores sem suporte a `oklch()` ignoram o bloco `@supports` inteiro e
+ficam só com o fallback — sem quebra, sem polyfill. Se você **também**
+customiza uma cor em OKLCH, recomenda-se o mesmo padrão de dois valores
+(fallback + `@supports`) pelo mesmo motivo. Ver
+[`docs/reference/browser-support.md`](../reference/browser-support.md).
+
+## Customizando via Sass
+
+Para quem compila o próprio bundle (em vez de sobrescrever CSS em runtime),
+os valores primitivos aceitam override na hora do `@use`:
+
+```scss
+@use "fokus-styles/scss/fokus" with (
+  $radius-md: 10px,
+  $font-family-sans: "Inter", sans-serif
+);
+```
+
+Qualquer variável marcada `!default` nos arquivos de
+`packages/fokus-core/scss/settings/` pode ser sobrescrita dessa forma.
+
+## Escala de espaçamento e breakpoints
+
+`$spacers` (0–5, usado pelos utilitários `.fs-u-m*`/`.fs-u-p*`/`.fs-u-g*`) e
+`$breakpoints` (`xs`–`xxxl`, usado pelo grid e por todo utilitário
+responsivo `.fs-u-*-{breakpoint}`) também são customizáveis via Sass — não têm
+equivalente em CSS Custom Property, porque alimentam a geração de classes
+(nomes de classe fixos em `.css`, não podem reagir a uma variável em
+runtime). Ver [`docs/reference/design-tokens.md`](../reference/design-tokens.md).
+
+## Multi-brand
+
+Além de `data-theme` (claro/escuro), o FokusStyles suporta `data-fs-brand="x"` para
+trocar a **cor de ação primária** em runtime, sem recompilar CSS — útil pra
+produtos white-label ou múltiplas marcas sobre o mesmo design system:
+
+```html
+<html data-fs-brand="violet">
+```
+
+```html
+<html data-fs-brand="violet" data-theme="dark">
+```
+
+Três presets vêm prontos em `packages/fokus-core/scss/themes/_brands.scss`,
+provando que a troca funciona combinada com claro e escuro:
+
+- `violet` — o mesmo tom do exemplo de customização acima.
+- `corporate` — azul-marinho sóbrio, para aplicações internas/B2B.
+- `vibrant` — laranja energético, para produtos de consumo/marketing.
+
+Só a cor de ação primária muda por marca — `secondary`/`success`/`warning`/
+`danger`/`info` continuam universais entre marcas, porque são semânticos
+(sucesso é sempre verde, erro sempre vermelho, independente de qual marca
+está ativa).
+
+Pra adicionar sua própria marca, siga o mesmo padrão do arquivo de exemplo:
+um bloco `[data-fs-brand="sua-marca"]` (mais o par `@supports` OKLCH e a
+combinação com `[data-theme="dark"]`) redefinindo `--fs-color-primary`,
+`--fs-alert-primary-bg`, `--fs-alert-primary-text` e
+`--fs-feedback-primary-bg`.
+
+**Limitação conhecida:** `.fs-btn-primary`/`.fs-badge-primary` (preenchimento
+sólido) calculam a cor do texto em tempo de build via `color-contrast()` a
+partir do primary **padrão** (azul) — não recalculam por marca. Escolha um
+primitivo de marca escuro o bastante pro texto branco continuar legível
+(como no exemplo `violet`), ou sobrescreva `--fs-btn-color`/`--fs-badge-color`
+manualmente se o primitivo da sua marca for muito claro. Rode
+`npm run contrast` depois de adicionar uma marca — o relatório já audita os
+pares `brand violet`/`brand corporate`/`brand vibrant` como referência
+(`scripts/contrast-report.scss`).
+
+## Próximo passo
+
+[Dark mode](dark-mode.md) — como o tema escuro usa a mesma camada de tokens.

package/docs/prompts/prompt-plan.md

@@ -0,0 +1,45 @@
+# Prompt para planejar refinamentos de um componente
+
+Copie o texto abaixo e substitua os campos entre colchetes antes de usar.
+
+```text
+Atue como responsável pelo planejamento técnico e de design do Fokus Styles.
+
+Quero criar um plano, sem implementar ainda, para o componente **[NOME DO COMPONENTE]**.
+
+## Contexto do pedido
+
+- Objetivo: [REFINAMENTO VISUAL DO COMPONENTE CAROUSEL;
+Sugira correções, alterações e implementações de códigos, funcionalidades de mudanças de visual para algo com maior qualidade e usabilidade]
+
+Antes de propor o plano, investigue o repositório e use a documentação como fonte de verdade. Não presuma que o componente está isolado: determine suas dependências, impactos visuais, comportamentais, públicos e de manutenção.
+
+Leia, no mínimo, nesta ordem conforme forem aplicáveis:
+
+1. `docs/README.md`, para entender o mapa e o contrato editorial da documentação;
+2. a página de documentação do componente em `docs/components/` e as páginas dos componentes relacionados;
+3. `docs/reference/definitions.md` e `docs/reference/stability.md`, para respeitar decisões e escopo já firmados;
+4. `docs/reference/scss-architecture.md` e `docs/reference/design-tokens.md`, para preservar a arquitetura, as cascade layers, convenções e a hierarquia de tokens;
+5. `docs/guides/accessibility.md`, a matriz de acessibilidade e o relatório de contraste quando o trabalho afetar interface, interação ou cores;
+6. `CONTRIBUTING.md`, os mockups, exemplos, testes e o código-fonte efetivamente envolvidos.
+
+Localize o SCSS, JavaScript, documentação, laboratórios em `mockup/`, testes unitários, testes visuais e testes de acessibilidade do componente. Consulte também tokens e componentes relacionados quando houver acoplamento, padrões compartilhados ou risco de regressão.
+
+Priorize refinamento visual consistente com o sistema: use tokens semânticos e, quando cabível, tokens próprios do componente com fallback; não introduza valores soltos nem `!important`; preserve `@layer`, prefixos `.fs-*`, `.fs-u-*`, `.is-*`, `--fs-*` e as convenções de API. Avalie responsividade, estados padrão/hover/focus-visible/active/disabled/erro, temas claro e escuro, contraste, teclado, ARIA, foco e `prefers-reduced-motion`. Considere SemVer e compatibilidade pública ao sugerir mudanças de classes, atributos, tokens, eventos ou API JavaScript.
+
+Se faltarem informações que alterem materialmente o plano, você pode me fazer de **5 a 10 perguntas** antes de finalizá-lo. Para cada pergunta, apresente exatamente **5 alternativas**, incluindo uma alternativa recomendada identificada como **"Recomendada"** e acompanhada de uma explicação mais detalhada do motivo. Não faça perguntas apenas por formalidade: use-as para resolver incertezas reais de objetivo, escopo, prioridade, direção visual, compatibilidade ou critérios de aceite.
+
+Depois da investigação — e das minhas respostas, se houver perguntas — entregue um plano implementável, em português, sem modificar arquivos, com:
+
+1. **Diagnóstico breve:** estado atual, causa/limitação e oportunidade identificada, citando arquivos e trechos relevantes.
+2. **Decisões e escopo:** o que será feito, o que não será feito e as premissas adotadas.
+3. **Plano passo a passo:** cada passo deve indicar arquivos prováveis, alteração concreta, justificativa, impacto em API/compatibilidade e dependências entre etapas.
+4. **Direção visual e UX:** alterações propostas para hierarquia, espaçamento, tipografia, cor, elevação, responsividade e todos os estados aplicáveis; diferencie correções objetivas de sugestões opcionais.
+5. **Acessibilidade e qualidade:** verificações de foco, teclado, ARIA, contraste, movimento reduzido e possíveis riscos.
+6. **Testes e validação:** comandos e cenários específicos (unitário, build, lint, visual, a11y, contraste, documentação), proporcionais ao impacto.
+7. **Documentação pós-implementação:** liste exatamente quais documentos devem ser corrigidos ou ampliados depois de implementar o plano — incluindo a página do componente, exemplos/mockups, tokens, guias, matriz de acessibilidade, changelog ou migração somente quando necessário — e descreva o conteúdo a atualizar. A implementação não estará concluída enquanto documentação, exemplos e testes afetados não refletirem o comportamento final.
+8. **Riscos, alternativas e sugestões futuras:** riscos de regressão, trade-offs, alternativas descartadas e possíveis evoluções que devem ficar fora deste plano.
+9. **Critérios de aceite:** resultados objetivos e verificáveis para considerar o trabalho concluído.
+
+Se o pedido contiver uma implementação nova, primeiro avalie se ela pode ser composta com recursos existentes e se é coerente com a direção de consolidação do projeto. Sinalize explicitamente qualquer necessidade de discussão prévia por contradizer uma decisão documentada ou por representar uma mudança breaking.
+```