fokus-styles 2.4.0 → 2.6.0

package/docs/guides/migration-v1.md

@@ -1,63 +0,0 @@
-# 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

@@ -1,30 +0,0 @@
-# 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/rtl-and-system-preferences.md

@@ -1,28 +0,0 @@
-# RTL e preferências do sistema
-
-## Visão geral
-
-O Fokus Styles 2.4 mantém os componentes em fluxo lógico e oferece o preset
-`fokus-styles/rtl.css` para documentos com `dir="rtl"`. O preset complementa
-a folha principal e preserva `margin-inline`, `padding-inline`, `inset-inline`
-e `border-inline-*`.
-
-```html
-<html dir="rtl" data-fs-theme="auto">
-  <link rel="stylesheet" href="fokus-styles/dist/css/fokus.css">
-  <link rel="stylesheet" href="fokus-styles/dist/css/fokus-rtl.css">
-</html>
-```
-
-## Estados de sistema
-
-O framework respeita `prefers-reduced-motion`, `prefers-contrast: more`,
-`forced-colors: active` e `prefers-color-scheme`. Em alto contraste, bordas e
-foco passam a usar espessuras maiores; em forced colors, ações preservam
-`ButtonText` e o foco usa `Highlight`.
-
-## A11y
-
-O atributo `dir` deve ser aplicado ao documento ou ao contêiner que define o
-fluxo de leitura. Use `dir="auto"` quando a direção do texto inserido não for
-conhecida.

package/docs/guides/theming.md

@@ -1,140 +0,0 @@
-# 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/guides/utility-api.md

@@ -1,9 +0,0 @@
-# Utility API e configuração Sass
-
-O Fokus Styles oferece presets públicos em `fokus-styles/core`, `fokus-styles/components`,
-`fokus-styles/utilities` e `fokus-styles/themes`. O arquivo `fokus-styles/config` expõe o
-mapa `$fs-config` para entradas Sass customizadas.
-
-O mixin `fs-fluid-type()` usa `clamp()` para escalar valores entre dois limites sem exigir
-JavaScript. Classes utilitárias novas seguem o namespace `fs-u-*` e as classes existentes
-continuam válidas dentro da linha 2.x.

package/docs/prompts/prompt-plan.md

@@ -1,45 +0,0 @@
-# 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.
-```

package/docs/reference/accessibility-matrix.md

@@ -1,77 +0,0 @@
-# Matriz de acessibilidade por componente
-
-Resumo rápido do que cada componente cobre em teclado, ARIA e gestão de foco.
-O detalhe completo (com exemplos) está na seção "A11y" da página de cada
-componente em [Componentes](../README.md#componentes); os padrões
-compartilhados entre vários componentes (foco visível, focus trap,
-`prefers-reduced-motion` etc.) estão no [guia de acessibilidade](../guides/accessibility.md).
-
-Todo laboratório em `mockup/*.html` roda no gate `npm run test:a11y` em tema
-claro e escuro. As fontes executáveis em `mockup/examples/*.html` também são
-verificadas por axe-core via
-Playwright, regras WCAG 2.1 A/AA) no CI — um componente só é considerado
-"coberto" abaixo se aparecer em algum mockup testado. Contraste de cor é verificado em dois níveis complementares:
-pares de token conhecidos (`npm run contrast`, ver
-[contrast-report.md](contrast-report.md)) e, de forma mais abrangente, texto
-renderizado de fato nos mockups (via o gate axe).
-
-| Componente | Teclado | ARIA | Gestão de foco | Contraste AA | Coberto por axe (CI) |
-|---|---|---|---|---|---|
-| [Accordion](../components/accordion.md) | Nativo (`<button>`) | Automático | — | ✓ | Sim |
-| [Alert Dialog](../components/alert-dialog.md) | Herdado do Modal | Herdado do Modal | Focus trap + devolve ao gatilho | ✓ | Sim |
-| [Alert](../components/alert.md) | N/A | Manual (`role="alert"`/`"status"`) | — | ✓ | Sim |
-| [Badge](../components/badge.md) | N/A (decorativo) | N/A | — | ✓ | Sim |
-| [Breadcrumb](../components/breadcrumb.md) | Nativo (links) | Manual (`<nav aria-label>`) | — | ✓ | Sim |
-| [Button](../components/button.md) | Nativo | Manual (`aria-label` em só-ícone) | Foco visível padrão | ✓ | Sim |
-| [Card](../components/card.md) | Nativo (stretched-link) | — | Foco no link real | ✓ | Sim |
-| [Carousel](../components/carousel.md) | Automático (setas/Home/End e arraste) | Automático (`aria-hidden`, `aria-current`, toggle) | Recebe foco no contêiner; autoplay pausável | ✓ | Sim |
-| [Checkbox](../components/checkbox.md) | Nativo | Nativo | — | ✓ | Sim |
-| [Collapse](../components/collapse.md) | Nativo (gatilho) | Automático | — | ✓ | Sim |
-| [Divider](../components/divider.md) | N/A | Implícito (`<hr>`) | — | ✓ | Sim |
-| [Dropdown](../components/dropdown.md) | Automático (setas/Escape) | Automático | Primeiro item ao abrir; devolve ao gatilho | ✓ | Sim |
-| [Empty State](../components/empty-state.md) | N/A | Manual (`aria-live` opcional) | — | ✓ | Sim |
-| [File Upload](../components/file-upload.md) | Nativo | Nativo | — | ✓ | Sim |
-| [Input / Select estático](../components/input.md) | Nativo | Manual (`for`/`id`, `aria-describedby`) | — | ✓ | Sim |
-| [Input Group](../components/input-group.md) | Nativo | Manual (`aria-describedby` no addon) | — | ✓ | Sim |
-| [Modal](../components/modal.md) | Nativo dentro do trap | Automático (`role="dialog"`) | Focus trap; devolve ao gatilho | ✓ | Sim |
-| [Navbar](../components/navbar.md) | Nativo | Manual (`<nav aria-label>`) | — | ✓ | Sim |
-| [Nested Menu](../components/nested-menu.md) | Automático (setas, Escape por nível) | Automático | Move foco entre níveis | ✓ | Sim |
-| [Notification Center](../components/notification-center.md) | Automático (Escape) | Automático | Devolve ao gatilho | ✓ | Sim |
-| [Offcanvas](../components/offcanvas.md) | Nativo dentro do trap | Automático (`role="dialog"`) | Focus trap; devolve ao gatilho | ✓ | Sim |
-| [Pagination](../components/pagination.md) | Nativo (links) | Manual (`<nav aria-label>`, `aria-current`) | — | ✓ | Sim |
-| [Popover](../components/popover.md) | Automático (Escape) | Automático | Devolve ao gatilho | ✓ | Sim |
-| [Spinner / Progress](../components/progress.md) | N/A | Manual (`role`+`aria-label`/`aria-valuenow`) | — | ✓ | Sim |
-| [Radio](../components/radio.md) | Nativo (setas no grupo) | Nativo | — | ✓ | Sim |
-| [Rating](../components/rating.md) | Nativo (setas no grupo) | Manual (`aria-label` por estrela) | — | ✓ | Sim |
-| [Segmented Control](../components/segmented-control.md) | Nativo (setas no grupo) | Nativo | — | ✓ | Sim |
-| [Select (custom)](../components/select.md) | Herdado do Dropdown | Automático (`role="listbox"`) | Herdado do Dropdown | ✓ | Sim |
-| [Skeleton](../components/skeleton.md) | N/A | Manual (`aria-busy` opcional) | — | ✓ | Sim |
-| [Stepper](../components/stepper.md) | Automático (passos clicáveis) | Automático (`aria-current="step"`) | — | ✓ | Sim |
-| [Switch](../components/switch.md) | Nativo | Nativo (+ `aria-label` sem texto visível) | — | ✓ | Sim |
-| [Table](../components/table.md) | Nativo | Manual (`scope`, `<caption>`) | — | ✓ | Sim |
-| [Tabs](../components/tabs.md) | Automático (roving tabindex) | Automático (`role="tab"`/`"tabpanel"`) | — | ✓ | Sim |
-| [Tag](../components/tag.md) | Nativo (botão de fechar) | Manual (`aria-label` descritivo) | — | ✓ | Sim |
-| [Tile](../components/tile.md) | Nativo (link real) | — | Foco no link, não no `::after` | ✓ | Sim |
-| [Timeline](../components/timeline.md) | N/A (sem interação própria) | — | — | ✓ | Sim |
-| [Toast](../components/toast.md) | N/A | Automático (`role="status"`, `aria-live`) | — | ✓ | Sim |
-| [Tooltip](../components/tooltip.md) | Nativo (`focus`/`blur`) | Automático (`aria-describedby`) | — | ✓ | Sim |
-
-## Legenda
-
-- **Nativo**: comportamento do elemento HTML nativo (`button`, `input`,
-  links), sem JS do framework.
-- **Automático**: o JS do FokusStyles aplica/atualiza o atributo ou o
-  comportamento de teclado ao inicializar — nada a fazer no HTML.
-- **Manual**: precisa ser adicionado por quem usa o componente (o framework
-  não infere texto/contexto).
-- **N/A**: componente não interativo por padrão.
-
-## Processo
-
-- Toda contribuição de componente novo segue o checklist de acessibilidade
-  do [guia de contribuição](../contributing/contributing.md) antes do merge.
-- O gate `npm run test:a11y` roda no CI a cada PR (ver
-  [.github/workflows/ci.yml](../../.github/workflows/ci.yml)); uma
-  regressão de contraste, nome acessível ou papel ARIA quebra o build.
-- Esta tabela é mantida manualmente — ao adicionar/alterar teclado, ARIA ou
-  foco de um componente, atualize a linha correspondente na mesma PR.

package/docs/reference/browser-support.md

@@ -1,75 +0,0 @@
-# Suporte a navegadores
-
-O Fokus Styles mira um alvo **moderno com fallback progressivo**: as duas
-últimas versões dos navegadores principais, com piso mínimo garantido em
-**Safari/iOS Safari 16.4**. Não há suporte a Internet Explorer.
-
-## Alvo (`.browserslistrc`)
-
-```text
-last 2 Chrome versions
-last 2 Edge versions
-last 2 Firefox versions
-Firefox ESR
-last 2 Safari versions
-Safari >= 16.4
-last 2 iOS versions
-iOS >= 16.4
-not dead
-not IE 11
-```
-
-Esse alvo alimenta o Autoprefixer no build (`scripts/build.mjs`), então
-prefixos são adicionados automaticamente apenas onde o alvo ainda exige.
-
-## Por que Safari 16.4 é o piso
-
-É a versão mínima com suporte estável a todos os recursos usados pela base
-do framework — `@layer` (Safari 16.4) e `color-mix()`/OKLCH (Safari 16.4)
-são os dois recursos que fixam esse piso; sem eles, o piso seria mais baixo.
-
-## Matriz de compatibilidade por feature
-
-Diferente do alvo geral acima (que é sobre *quais navegadores testamos*),
-esta tabela é sobre *o que acontece em navegadores fora do alvo* —
-navegador mínimo com suporte nativo e o comportamento de fallback
-documentado (não "quebra silenciosamente") para cada recurso moderno
-usado no CSS/JS do framework.
-
-| Feature | Uso no FokusStyles | Suporte nativo mínimo | Comportamento sem suporte |
-|---|---|---|---|
-| `@layer` (cascade layers) | Organiza `reset/tokens/base/layout/components/utilities/overrides` (`packages/fokus-core/scss/tokens/_root.scss:8`; ver [scss-architecture.md](scss-architecture.md)) | Safari 16.4, Chrome 99, Firefox 97, Edge 99 | Todas as regras caem para a cascata padrão (ordem de origem + especificidade). Como o SCSS já é organizado na mesma ordem lógica das camadas, a degradação visual é mínima — sem garantia formal de paridade pixel-a-pixel, mas sem quebra funcional. |
-| `color-mix()` / `oklch()` | Tokens de cor gerados em OKLCH, dentro de um bloco `@supports (color: oklch(0% 0 0))` (`packages/fokus-core/scss/tokens/_root.scss:73`); usado também nos temas `data-theme="dark"` e `data-fs-brand="*"` | Safari 16.4, Chrome 111, Firefox 113, Edge 111 | `@supports` faz a detecção — navegadores sem suporte simplesmente ignoram o bloco OKLCH inteiro e usam os valores hex sRGB declarados antes dele (mesmas cores, aproximação visual, não pixel-perfect). Não é uma feature isolada: é o mecanismo de fallback de **todos** os tokens de cor do framework. |
-| `@container` (container queries) | Utilitários opt-in `.fs-u-cq`/`.fs-u-cq-{sm,md,lg}-d-*` (`packages/fokus-utilities/scss/utilities/_container-queries.scss`); ver [layout-advanced.md](../guides/layout-advanced.md) | Safari 16.0, Chrome 105, Firefox 110, Edge 105 | Sem suporte, o `@container` inteiro é ignorado pelo navegador — os elementos permanecem no `display` padrão do HTML (ex.: `<div>` como `block`), sem a responsividade condicionada à largura do container. Como é opt-in (só afeta quem usa `.fs-u-cq-*`), não há regressão em quem não usa esses utilitários. |
-| Propriedades customizadas (`--fs-*`) | Tokens em todas as camadas (cor, espaçamento, raio, sombra, tipografia) | Suportado desde 2017 em todos os navegadores principais (abaixo do piso Safari 16.4) | Não relevante ao alvo atual — nenhum navegador do alvo (`.browserslistrc`) carece desse suporte. |
-| `:focus-visible` | Anel de foco acessível (mixin `focus-ring`, `packages/fokus-core/scss/tools/_mixins.scss`), usado em botões, inputs, itens de menu/tree, etc. | Safari 15.4, Chrome 86, Firefox 85, Edge 86 (abaixo do piso Safari 16.4) | Não relevante ao alvo atual pelo mesmo motivo — mas caso um navegador não suporte, o seletor inteiro é ignorado (sem erro), só o anel de foco customizado some; o `outline` nativo do navegador permanece como fallback funcional (não visual). |
-| `prefers-reduced-motion` | Desliga animações de skeleton/carousel/transições (`packages/fokus-js/js/core/transition.js`, `_skeleton.scss`) | Suportado desde 2019 em todos os navegadores principais (abaixo do piso Safari 16.4) | Não relevante ao alvo atual. Em navegadores sem suporte à media query, a regra é ignorada e as animações continuam ativas por padrão (comportamento seguro: anima por padrão, só desliga quando o recurso E a preferência do usuário existem). |
-
-### Recursos considerados, mas não usados hoje
-
-Para não deixar dúvida sobre lacunas silenciosas: `:has()` e
-`@custom-media` (as duas features citadas com mais frequência ao lado de
-`@container`/`color-mix()` em discussões sobre CSS moderno) **não são
-usadas em nenhuma linha do framework atualmente** — não há necessidade
-técnica identificada até a v1.0.0. Se/quando entrarem, esta tabela ganha
-uma linha nova no mesmo formato antes do merge.
-
-## Fallback progressivo (resumo)
-
-- **Cores**: OKLCH com fallback em hex sRGB via `@supports` (ver tabela
-  acima) — nunca "quebra", só perde precisão de mistura de cor.
-- **`@layer`**: degrada para cascata padrão, sem garantia formal de
-  paridade visual mas sem quebra funcional.
-- **`@container`**: opt-in; sem suporte, os elementos ficam no `display`
-  HTML padrão.
-- Sem polyfills: o projeto não inclui polyfills de CSS; navegadores fora
-  do alvo (`.browserslistrc`) devem ser tratados como não suportados, não
-  como "degradados".
-
-## Testes
-
-A regressão visual (`npm run test:visual`, Playwright + Chromium) cobre o
-navegador mais permissivo do alvo. Não há cobertura automatizada de
-Safari/Firefox no momento — mudanças que dependem de recursos recentes
-(a tabela acima) devem ser verificadas manualmente nesses engines antes
-do release.

package/docs/reference/contrast-report.md

@@ -1,50 +0,0 @@
-# Relatório de contraste
-
-`npm run contrast` audita a razão de contraste WCAG dos pares
-texto/fundo emitidos pelos tokens (`packages/fokus-core/scss/tokens/_root.scss`,
-`packages/fokus-core/scss/themes/_dark.scss`), nos temas claro e escuro:
-texto base sobre superfície, botões sólidos e alerts, nas seis cores de tema
-(`primary`/`secondary`/`success`/`warning`/`danger`/`info`).
-
-## Como rodar
-
-```bash
-npm run contrast
-```
-
-Cada linha reporta a razão calculada e se atinge AA (WCAG 2.1 SC 1.4.3/1.4.11)
-e AAA:
-
-- **4.5:1** — mínimo AA para texto normal (corpo de alert, texto base).
-- **3:1** — mínimo AA para texto grande/negrito e componentes de UI (usado
-  para o texto de botões sólidos, que é sempre bold/UI, não corpo de leitura).
-- **7:1** — AAA, opcional.
-
-`npm run contrast -- --strict` sai com código de erro se algum par ficar
-abaixo do mínimo AA — é o comando rodado pelo gate `contrast:check` do CI
-(`.github/workflows/ci.yml`).
-
-## Por que o tema escuro precisa de pesos próprios
-
-O texto de um botão sólido (`.fs-btn-primary` etc.) é decidido uma vez, em
-tempo de build, por `color-contrast()` (branco ou preto, o que der mais
-contraste contra a cor sólida no **tema claro**) e gravado como valor
-estático em `--fs-btn-color`. Ele não é recalculado por tema. O fundo, por
-outro lado, muda no escuro (`--fs-color-{nome}` é misturado em direção ao
-branco). Isso significa que uma cor de texto escolhida para o fundo claro
-pode ficar com contraste ruim contra o fundo (mais claro) do tema escuro — é
-exatamente esse cenário que o relatório cobre nas linhas `dark: btn-* text
-(light)/bg(dark)`.
-
-Da mesma forma, os pesos de mistura de `--fs-alert-*-bg`/`-text` no escuro
-(`$dark-alert-bg-weight`/`$dark-alert-text-weight` em `themes/_dark.scss`)
-foram ajustados a partir do relatório — os pesos "óbvios" (mistura simétrica)
-davam ~4.0–4.3:1 em quatro das seis cores, abaixo do mínimo AA de 4.5:1. Se
-você alterar esses pesos, ou os pesos de `$dark-color-weights`, rode
-`npm run contrast` de novo antes de commitar.
-
-## Última execução
-
-29 pares checados, 0 abaixo do mínimo AA (ver `npm run contrast` para os
-valores atuais — este arquivo documenta o processo, não os números, que
-mudam a cada ajuste de token).