fokus-styles 2.5.0 → 2.6.0

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) | Nativo quando houver link/botão | Manual (`role="alert"`/`"status"`) | Nenhuma automática | ✓ | 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 (Space) | Nativo + `aria-describedby` manual | Foco visível no controle | ✓ | 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 + `fieldset/legend` manual | Foco visível no controle | ✓ | 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 (Space) | Checkbox nativo; nome manual sem texto | Foco visível no trilho | ✓ | 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, `aria-busy`) | Foco preservado/transferido após dismiss | ✓ | 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) | Nativo em fechamento e ações | Automático (`role="status"`, `aria-live="polite"`) | Nenhuma automática; pausa em foco/hover | ✓ | Sim |
-| [Tooltip](../components/tooltip.md) | Nativo (`focus`/`blur`, ponteiro e Escape) | Automático (`role="tooltip"`, `aria-describedby`) | Nenhuma; foco permanece no gatilho | ✓ | 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,54 +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.
-
-Checkbox, Radio e Switch reutilizam esses tokens semânticos para bordas,
-superfícies, estados de ação e validação. O relatório visual dos laboratórios
-também deve ser executado após qualquer ajuste nos tokens locais dos controles.
-
-`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).