fokus-styles 2.5.0 → 2.6.0

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.

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 abaixo:
-
-## Contexto do pedido 8011827-28.2026
-
-- Objetivo: [REFINAMENTO VISUAL DO COMPONENTE TOOLTIP;
-Sugira correções, alterações e implementações de códigos, funcionalidades de mudanças de visual para algo com maior qualidade, responsividade, acessibilidade, criatividade 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.
-```