fokus-styles 2.4.0 → 2.6.0

package/docs/guides/accessibility.md

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

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

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

package/docs/guides/icons.md

@@ -1,99 +0,0 @@
-# Í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/javascript-api.md

@@ -1,9 +0,0 @@
-# API JavaScript
-
-Os módulos vanilla são SSR-safe quando importados e expõem instâncias idempotentes por
-`getOrCreateInstance`. Modal, Theme, Navbar, Scrollspy e FormValidation também oferecem
-destruição explícita com `dispose()`.
-
-Os eventos comuns são `fs:show`, `fs:shown`, `fs:hide` e `fs:hidden`. Atributos declarativos
-usam `data-fs-toggle`, `data-fs-target`, `data-fs-dismiss`, `data-fs-placement` e
-`data-fs-theme`.

package/docs/guides/layout-advanced.md

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

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

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