fokus-styles 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,891 @@
+# Changelog
+
+## Unreleased
+
+- refina o Carousel com tokens locais, controles compactos, indicadores em
+  pill, legendas opt-in, arraste aprimorado e autoplay pausável/retomável;
+- consolida tokens públicos de foco, transição, densidade, alturas e padding dos controles;
+- adiciona suporte CSS global a `prefers-reduced-motion`;
+- reorganiza o índice da documentação e adiciona `npm run docs:check` ao fluxo local e ao CI;
+- atualiza a baseline de tamanho e os snapshots visuais afetados pelo refinamento dos componentes.
+- define fundos semânticos explícitos para superfícies, controles, navegação,
+  accordions, calendários, dropdowns e ordenação de tabelas.
+- consolida os mockups em seis laboratórios documentados, com âncoras estáveis,
+  preview funcional, código sincronizado, temas e cobertura de regressão visual;
+  preserva as fontes executáveis em `mockup/examples/` para testes de interação
+  e acessibilidade.
+
+- atualiza as baselines visuais Linux dos mockups após o refinamento dos componentes;\n- consolidates visual tokens for spacing, control heights, overlay layers and
+  contrast-aware content colors;
+- refines focus-visible states, responsive form controls and overlay widths;
+- improves dropdown, tooltip, popover and datepicker positioning on resize and
+  scroll, while restoring DOM/style state on disposal;
+- strengthens modal/offcanvas/accordion/tabs semantics and adds manual tab
+  activation;
+- adds typed DataTable sorting and busy-state feedback;
+- hardens date parsing, transition fallback and scroll-lock restoration.
+
+Todas as mudanças notáveis deste projeto serão documentadas neste arquivo.
+
+O formato segue [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/),
+e este projeto adere a [Semantic Versioning](https://semver.org/lang/pt-BR/).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-07-08
+
+> As versões `0.3.1`–`0.6.0` foram tags de checkpoint cortadas em sequência
+> rápida durante o mesmo arco contínuo de desenvolvimento rumo à v1.0.0
+> (sem changelog próprio por versão) — todo o trabalho acumulado desde a
+> `0.3.0` está consolidado nesta entrada única, que corresponde ao corte
+> da primeira versão estável do framework.
+
+### Added
+
+- **Templates prontos e página comparativa**: 4 templates
+  completos e prontos pra copiar em `mockup/templates/` (`dashboard.html`,
+  `auth.html`, `landing.html`, `admin.html`), montados só com componentes/
+  utilitários já publicados (`dist/css`/`dist/js`), com tema escuro
+  funcional (mesmo mecanismo de `docs/guides/dark-mode.md`) — referenciados
+  em `docs/README.md#templates-prontos`. Nova página
+  [`docs/comparison.md`](docs/comparison.md) ("Clarus vs Bootstrap vs
+  Tailwind CSS"): tabelas de filosofia, tamanho de bundle, dependências e
+  tema escuro nativo, com dados públicos e reproduzíveis (arquivos
+  oficiais publicados de cada framework, medidos localmente com o mesmo
+  método do gate de CI — `gzip` nível 9) em vez de números estimados;
+  benchmarks de performance ao vivo marcados explicitamente como
+  "pendente de metodologia" em vez de omitidos silenciosamente.
+
+### Fixed
+
+- `.fs-empty-state[hidden]` não escondia o elemento: `.fs-empty-state`
+  define `display: flex` em `@layer components`, e author styles sempre
+  vencem a regra `[hidden] { display: none }` do user-agent stylesheet,
+  mesmo dentro de `@layer` — sem uma regra author explícita pro atributo
+  `hidden`, ele não tinha efeito nenhum. Descoberto ao construir o
+  template `dashboard.html` (sub-fase 5.13): `DataTable`
+  (`packages/clarus-js/js/datatable.js`) alterna esse atributo em
+  `this.emptyEl`/`this.errorEl`, então o estado vazio/erro ficava sempre
+  visível por baixo da tabela com dados — inclusive no mockup oficial
+  (`mockup/datatable.html`, baseline visual atualizada). Corrigido com
+  `.fs-empty-state[hidden] { display: none; }` em
+  `packages/clarus-components/scss/components/_empty-state.scss`, mesmo
+  padrão já usado em `.fs-notification-badge[hidden]`/
+  `.fs-notification-empty[hidden]`.
+
+### Changed
+
+- Dogfooding do `clarus-icons`: emoji usados como placeholder de ícone em
+  mockups/docs (Empty State, Tile, Notification Center, DataTable)
+  trocados por SVGs reais do pacote — nenhum lugar oficial do projeto usa
+  emoji como ícone hoje. [Rating](docs/components/rating.md) também
+  trocou o glifo `★` pelo ícone `star` (contorno vazio por padrão,
+  preenchido via `fill: currentcolor` quando selecionado/hover — imita o
+  visual sólido do glifo antigo sem perder o estado "vazio"); cada
+  `<label>` ganhou `aria-label` (`"5 estrelas"` etc.), obrigatório agora
+  que o ícone é `aria-hidden`. Pagination ganhou ícones
+  (`chevron-left`/`chevron-right` no lugar de `«`/`»`, `ellipsis` pra
+  intervalo de páginas omitido — variação nova, documentada), e o pager
+  gerado por `DataTable` (`packages/clarus-js/js/datatable.js`) trocou
+  `‹`/`›` pelos mesmos chevrons (SVG embutido como string — `clarus-js`
+  não pode depender do pacote opcional `clarus-icons` em runtime).
+  `.fs-btn`/`.fs-badge`/`.fs-alert`/`.fs-breadcrumb-item a` ganharam `gap`
+  próprio pra espaçar ícone+texto corretamente (antes só funcionava por
+  acidente, via colapso de espaço em branco do HTML); ajustado
+  `.fs-dropdown-toggle::after` (removido `margin-left` redundante, já que
+  agora conta como item flex do `.fs-btn` e herda o `gap`). Pagination
+  ganhou `aria-label`/`aria-hidden` explícitos nos itens só-ícone.
+
+### Added
+
+- **DX e supply-chain**: `.d.ts`
+  hand-escritos para toda a API JS pública (`packages/clarus-js/js/*.d.ts`,
+  um por módulo + `clarus.d.ts` agregador + `global.d.ts` pro uso via
+  `<script>`), validados por `npm run types:check` (`tsc --noEmit`) contra
+  um exemplo de uso real (`tests/types/clarus.test-d.ts`) — gate novo no
+  CI. Corrigido bug real descoberto ao validar o subpath export
+  (`clarus-css/js/modal.js`, o formato documentado em `usage.md`): o
+  padrão `"./js/*"` do `exports` do `package.json` duplicava a extensão
+  `.js` (`modal.js.js`), quebrando qualquer import direto de um módulo —
+  nunca fora exercitado por um import real antes desta sub-fase.
+  `npm publish --provenance` no novo `.github/workflows/release.yml`
+  (dispara em tags `v*.*.*`, publica `clarus-css`+`clarus-icons`).
+  `.github/FUNDING.yml` e `.github/dependabot.yml` (npm + github-actions,
+  semanal). Utilitários de impressão (`.u-print-hide`/`.u-print-only`/
+  `.u-print-block`/`-inline`/`-inline-block`,
+  `packages/clarus-utilities/scss/utilities/_print.scss`), documentados em
+  `docs/guides/print.md`. Página kitchen sink
+  (`mockup/kitchen-sink.html`) com um exemplo compacto de cada componente,
+  dois temas — smoke test visual rápido, referenciada em `docs/README.md`.
+
+- **Presets de tema, `clarus-cli`, tokens de gráficos, forms extras e wrapper React**:
+  - Dois novos presets de marca em
+    `packages/clarus-core/scss/themes/_brands.scss`: `corporate`
+    (azul-marinho sóbrio) e `vibrant` (laranja energético) — mesma técnica
+    OKLCH do preset `violet` existente. O primitivo do "vibrant" é claro o
+    bastante pra o texto branco padrão de `.fs-btn-primary`/
+    `.fs-badge-primary` cair abaixo de 4.5:1 (pego pelo gate `test:a11y`);
+    corrigido com um override em `@layer overrides` (a camada de maior
+    prioridade — cascade layers ignoram especificidade, então um seletor
+    mais específico dentro de `@layer tokens` perderia mesmo assim). Ao
+    investigar o fix, descoberto que `.fs-badge-primary` fixava `color`
+    diretamente (ao contrário de `.fs-btn-primary`, que já seguia a
+    convenção de só sobrescrever uma custom property) — alinhado
+    (`--fs-badge-color`/`--fs-badge-bg`, mesmo padrão de `.fs-btn`).
+  - Pacote `clarus-cli` (`packages/clarus-cli/`): comandos `build`
+    (compila um entry `.scss` de um projeto consumidor com o mesmo
+    pipeline sass→autoprefixer→cssnano do build interno), `theme` (gera um
+    preset `data-fs-brand` em CSS puro via `color-mix()`, sem dependência de
+    Sass, decidindo automaticamente `--fs-btn-color`/`--fs-badge-color`
+    pelo contraste com a cor informada) e `analyze` (tamanho bruto/gzip de
+    qualquer arquivo, versão genérica de `scripts/size.mjs`).
+  - Tokens de gráficos agnósticos de biblioteca (`--fs-chart-series-1..6`,
+    `--fs-chart-grid`, `--fs-chart-axis`, `--fs-chart-tooltip-bg/text`,
+    `packages/clarus-core/scss/tokens/_charts.scss`) — aliases da camada
+    semântica existente, sem wrapper de nenhuma lib específica. Documentado
+    em `docs/guides/charts.md`, mockup `mockup/charts.html`.
+  - Range/Slider (`.fs-form-range`,
+    `packages/clarus-components/scss/forms/_range.scss`): trilha/thumb
+    estilizados via pseudo-elementos vendor-prefixados; teclado e ARIA já
+    vêm do `<input type="range">` nativo. JS opcional
+    (`packages/clarus-js/js/range.js`, `data-fs="range"`) só pinta a
+    trilha preenchida (`--fs-range-percent`, necessário porque só o
+    Firefox suporta `::-moz-range-progress`) e espelha o valor num
+    `<output>` associado. Documentado em `docs/components/range.md`,
+    mockup `mockup/range.html`.
+  - Upload avançado (`packages/clarus-js/js/file-upload-advanced.js`,
+    `data-fs="file-upload-advanced"`): evolução do File Upload simples —
+    múltiplos arquivos, preview (thumbnail de imagem via
+    `URL.createObjectURL`, nome, tamanho), progresso individual
+    (`setProgress`/`setError`, reusa `.fs-progress`) e remoção por item.
+    Agnóstico de backend (não faz upload de verdade, só expõe a API pro
+    consumidor plugar o próprio XHR/fetch). Documentado em
+    `docs/components/file-upload-advanced.md`, mockup
+    `mockup/file-upload-advanced.html`.
+  - Pacote `clarus-react` (`packages/clarus-react/`): wrapper React fino
+    (`ModalTrigger`/`ModalPanel`, `DropdownTrigger`/`DropdownMenu`,
+    `TabList`) — cada componente só instancia a classe vanilla
+    correspondente (`clarus-css/js/*`) sobre o elemento renderizado pelo
+    React e desfaz no unmount, sem reimplementar comportamento. Cobertura
+    parcial e deliberada (só React, só 3 componentes cobrindo os dois
+    formatos de contrato do `clarus-js`) — serve de molde pros demais.
+  - Placeholder estrutural de showcase de produção (`docs/showcase.md`) —
+    sem casos fictícios nem métricas inventadas, aguardando projetos reais.
+  - `.github/workflows/ci.yml` ganhou o gate `npm run types:check`.
+
+- **Pacote `clarus-icons`**: 1994 ícones SVG do conjunto [Lucide](https://lucide.dev) (ISC),
+  gerados em build-time a partir do devDependency `lucide-static`
+  (`scripts/build-icons.mjs`, `npm run build:icons`) — o pacote publicado
+  não tem nenhuma dependência de runtime. Dois formatos de consumo: SVG
+  puro (`clarus-icons/svg/<nome>.svg`) e módulos ES tree-shakeable
+  (`clarus-icons/icons/<nome>.js`, mais um barrel `clarus-icons` com nomes
+  em camelCase). Nova classe utilitária `.fs-icon` (com `-xs`/`-sm`/`-lg`/`-xl`)
+  em `packages/clarus-utilities/scss/utilities/_icon.scss`, sempre
+  disponível no `clarus-css` independente do pacote de ícones estar
+  instalado. Documentado em `docs/guides/icons.md`, mockup
+  `mockup/icons.html`, 5 testes unitários cobrindo a geração (limpeza do
+  SVG, `stroke="currentColor"`, colisões de nome no barrel). Licenças
+  (`LICENSE` MIT do Clarus + `LICENSE-LUCIDE.txt` ISC/Feather) distribuídas
+  junto do pacote.
+
+- **Matriz de compatibilidade e guia de migração externa**:
+  `docs/reference/browser-support.md` ganhou uma **matriz de
+  compatibilidade explícita por feature** (`@layer`, `color-mix()`/OKLCH,
+  `@container`, `:focus-visible`, `prefers-reduced-motion`) — navegador
+  mínimo com suporte nativo × comportamento de fallback documentado por
+  recurso, em vez de só o alvo geral do `.browserslistrc`. Novo guia
+  `docs/guides/migration-external.md`: tabela de equivalência de
+  classes/componentes pra quem migra de outro framework CSS pro Clarus
+  (utilitários, componentes, o que não migra 1:1, checklist). Corrigida
+  também uma lacuna no índice (`docs/README.md`): DataTable, Command
+  Palette e Tree View (sub-fases 5.5/5.6) não estavam listados.
+
+- **Command Palette e Tree View**:
+  `packages/clarus-js/js/command-palette.js`, diálogo de busca/comandos
+  disparado por botão ou por atalho global (`data-fs-shortcut="mod+k"`),
+  combinando o overlay/focus trap do Modal com o filtro/navegação por
+  teclado do Combobox — reusa `.fs-dropdown-item` pros itens da lista.
+  `packages/clarus-js/js/tree-view.js`, lista hierárquica seguindo o
+  padrão [WAI-ARIA Tree View](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/):
+  marcação `<ul>`/`<li>` nativa aninhada, botão de expandir/colapsar
+  auto-injetado, roving `tabindex`, navegação completa por teclado
+  (`ArrowRight`/`ArrowLeft` cruzam níveis, `Home`/`End`,
+  `Enter`/`Espaço`). 27 testes unitários somados entre os dois, mockups
+  (`mockup/command-palette.html`, `mockup/tree-view.html`), a11y e visual
+  regression verdes. Documentados em `docs/components/command-palette.md`
+  e `docs/components/tree-view.md`. Budget de tamanho do JS: 17.25 KB
+  gzip de um teto de 24 KB.
+
+- **DataTable v1**:
+  `packages/clarus-js/js/datatable.js`, camada JS opcional sobre uma
+  [Table](docs/components/table.md) comum — ordenação por coluna
+  (`data-fs-sort`, ciclo asc → desc → nenhuma, `aria-sort` seguindo o
+  padrão [WAI-ARIA Table Sort](https://www.w3.org/WAI/ARIA/apg/patterns/table/examples/sortable-table/)),
+  filtro por texto (`[data-fs-datatable-filter]`, substring
+  case-insensitive em qualquer célula) e paginação client-side
+  (`data-fs-page-size`, reusa `.fs-pagination`/`.fs-page-link`). Estados de
+  vazio/carregando/erro reusam `.fs-empty-state`/`.fs-skeleton`
+  (`setLoading()`/`setError()`). Roving `tabindex` nas células do corpo com
+  navegação completa por setas/`Home`/`End`/`Ctrl+Home`/`Ctrl+End`. 18
+  testes unitários, mockup (`mockup/datatable.html`), a11y e visual
+  regression verdes. Documentado em `docs/components/datatable.md` (com
+  `docs/components/table.md` atualizado pra referenciá-lo).
+
+### Changed
+
+- Budget de tamanho do JS (`scripts/size.mjs`, gate `npm run size:check`)
+  recalibrado de 14 KB pra **24 KB gzip** (`js/clarus.min.js`). O teto de
+  14 KB foi fixado antes da decisão de incluir Combobox, Datepicker,
+  DataTable, Command Palette e Tree View no bundle — com Combobox+Datepicker
+  já em 13.82 KB, não sobrevivia ao resto do escopo aprovado.
+
+### Added
+
+- **Datepicker/Timepicker**: duas
+  abordagens. **CSS-only**:
+  `<input type="date">`/`<input type="time">` herdam `.fs-form-control`
+  normalmente; corrige o indicador nativo (ícone calendário/relógio) no
+  tema escuro, invisível por padrão sobre `--fs-color-surface` escuro.
+  **Datepicker customizado (JS)**, `packages/clarus-js/js/datepicker.js`:
+  calendário completo seguindo o padrão
+  [WAI-ARIA Date Picker Dialog](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/)
+  adaptado a popup não-modal — `role="combobox"`/`aria-haspopup="grid"` no
+  input, `role="grid"`/`"row"`/`"gridcell"` na grade, roving `tabindex`
+  (dias são focáveis de verdade, ao contrário do Combobox). Teclado
+  completo: `ArrowRight`/`ArrowLeft`/`ArrowUp`/`ArrowDown` (cruzam
+  semana/mês), `Home`/`End`, `PageUp`/`PageDown` (mês),
+  `Shift+PageUp`/`Shift+PageDown` (ano), `Enter`/`Space` seleciona,
+  `Escape` fecha sem alterar o valor. Reusa `js/core/positioning.js`.
+  17 testes unitários (incluídos dois bugs reais pegos e corrigidos
+  durante o desenvolvimento: `aria-expanded` não é permitido no role
+  implícito `textbox`, exigindo `role="combobox"`; e as setas do teclado
+  não tinham efeito nenhum com foco no input, porque o handler de teclado
+  do grid só reagia com foco já num dia — corrigido com um handler
+  dedicado no input que abre/move o foco pro grid em `ArrowDown`/`ArrowUp`).
+  Mockup em `mockup/datepicker.html`, documentado em
+  [`docs/components/datepicker.md`](docs/components/datepicker.md).
+
+- **Combobox/Autocomplete**: `<input>` de
+  texto com listbox de sugestões que filtra por substring conforme o
+  usuário digita, seguindo o padrão
+  [WAI-ARIA Combobox (List Autocomplete)](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)
+  — `role="combobox"`/`aria-autocomplete`/`aria-controls`/`aria-expanded`
+  no input, `role="listbox"`/`role="option"`/`aria-selected` na lista,
+  destaque de navegação via `aria-activedescendant` (foco nunca sai do
+  input). Teclado completo (`ArrowUp`/`ArrowDown` com wrap,
+  `Home`/`End`, `Enter` seleciona, `Escape` fecha sem alterar o valor).
+  Reusa `js/core/positioning.js` e as classes `.fs-dropdown-menu`/
+  `.fs-dropdown-item` do Dropdown/Select para a listbox flutuante — só
+  `packages/clarus-components/scss/components/_combobox.scss` (wrapper +
+  `max-height` com scroll) é novo em CSS. Item opcional `data-fs-empty`
+  para mensagem de "sem resultados", com visibilidade alternada
+  automaticamente. Testes unitários (13 casos), mockup em
+  `mockup/combobox.html`, documentado em
+  [`docs/components/combobox.md`](docs/components/combobox.md).
+
+- **Theming multi-brand**: suporte a
+  `data-fs-brand="x"` sobre a camada de tokens semânticos existente,
+  sobrescrevendo só a cor de ação primária (`--fs-color-primary` e os
+  tokens derivados de alert/feedback) — `secondary`/`success`/`warning`/
+  `danger`/`info` continuam universais entre marcas. Combina corretamente
+  com `data-theme="dark"` (mesma técnica de mistura OKLCH de
+  `themes/_dark.scss`). Um brand de exemplo (`violet`) em
+  `packages/clarus-core/scss/themes/_brands.scss` prova a troca em runtime
+  sem recompilar, com par de contraste auditado em `npm run contrast` e
+  demo em `mockup/theming.html`. Documentado em
+  [`docs/guides/theming.md`](docs/guides/theming.md#multi-brand), incluindo
+  a limitação conhecida de `color-contrast()` (texto de preenchimento
+  sólido calculado em build a partir do primary padrão, não por marca).
+
+- **Layout avançado**: três novas
+  primitivas de layout CSS-only, `.fs-stack` (empilhamento vertical com
+  `gap`), `.fs-cluster` (grupo horizontal com quebra automática) e
+  `.fs-sidebar` (aside de largura fixa + conteúdo flexível, com variante
+  `.fs-sidebar-reverse`) — todas com modificador de gap
+  (`.fs-{stack,cluster,sidebar}-gap-{0..5}`), em
+  `packages/clarus-core/scss/layout/`. Utilitários `.u-sticky-top`/
+  `.u-sticky-bottom` (posição fixa ao rolar, com offset configurável).
+  Utilitários de container query (`.u-cq` + `.u-cq-{sm,md,lg}-d-*`),
+  reagindo à largura do container mais próximo em vez da viewport, com
+  tokens de referência `--fs-cq-sm/md/lg` (320/480/640px). Documentado em
+  [`docs/guides/layout-advanced.md`](docs/guides/layout-advanced.md), com
+  exemplo em `mockup/layout.html`.
+
+- **Qualidade, A11y e performance como gate de CI**:
+  - Gate `npm run test:a11y` (axe-core via Playwright, regras WCAG 2.1
+    A/AA) sobre todo mockup em `mockup/*.html`, rodando no CI a cada PR.
+    Descobriu e corrigiu violações reais de contraste em texto sobre
+    fundo (link/nav ativo, botão `outline-*`, feedback de formulário,
+    step/timeline de erro) que usavam a cor de token "crua" — agora usam
+    `--fs-alert-{nome}-text` (já calibrado ≥4.5:1 nos dois temas) — e uma
+    violação de nome acessível ausente em `role="progressbar"`
+    (`aria-label` adicionado nos exemplos, guia atualizado em
+    [`docs/components/progress.md`](docs/components/progress.md)).
+  - [Matriz de acessibilidade](docs/reference/accessibility-matrix.md)
+    publicada em `docs/reference/`: teclado, ARIA e gestão de foco por
+    componente, com link pra seção "A11y" de cada página.
+  - Budgets de tamanho como blocker no CI: `npm run size:check` falha o
+    build se `layout` (core), `components`, `clarus` (full) ou o JS
+    ultrapassarem os tetos definidos (12/18/32/14 KB gzip). Relatório
+    de tamanho gzip desta release (`npm run size`):
+
+    | Distribuição | Bruto | Gzip | Budget |
+    | --- | --- | --- | --- |
+    | `css/layout.min.css` | 13.39 KB | 3.10 KB | 12 KB |
+    | `css/forms.min.css` | 18.24 KB | 4.26 KB | — |
+    | `css/components.min.css` | 48.41 KB | 9.19 KB | 18 KB |
+    | `css/helpers.min.css` | 41.59 KB | 7.24 KB | — |
+    | `css/fonts.min.css` | 1.47 KB | 0.40 KB | — |
+    | `css/clarus.min.css` | 97.08 KB | 15.58 KB | 32 KB |
+    | `js/clarus.min.js` | 51.17 KB | 11.19 KB | 14 KB |
+
+  - `npm run contrast:check` (mesma auditoria de `npm run contrast`, mas
+    falha o build abaixo de AA) também vira gate do CI.
+
+### Changed
+
+- **Documentação profissional**: `guide.md` (76KB, um
+  arquivo só, desatualizado em relação ao rename da API) é substituído
+  por `docs/`, estruturada por categoria: `getting-started/` (instalação,
+  uso), `guides/` (theming, dark mode, acessibilidade, migração),
+  `components/` (38 arquivos, um por componente/controle, template padrão:
+  visão geral → anatomia → variações → estados → A11y → API JS → tokens →
+  exemplo — todo conteúdo verificado contra o SCSS/JS atual, não copiado do
+  guia antigo), `reference/` (design tokens, arquitetura SCSS, suporte a
+  navegadores, relatório de contraste, definições) e `contributing/`.
+  Documentos internos de planejamento (planos provisórios, gap-analysis,
+  guia de comandos) mantidos fora da documentação pública; removidos do
+  repositório após o corte da v1.0.0, papel encerrado.
+  `definitions.md`/`scss-architecture.md` movidos para `docs/reference/`.
+  `package.json > files` publica a nova `docs/` pública (exceto `internal/`).
+  Referências cruzadas (README raiz, CONTRIBUTING, templates de PR)
+  atualizadas para os novos caminhos.
+
+- **BREAKING** — Refundação técnica rumo à v1.0.0:
+  - Rename mecânico de toda a API pública com prefixo `fs-`, para não colidir
+    com classes de outras bibliotecas/CSS de terceiros na mesma página: toda
+    classe de componente ganha o prefixo `fs-` (`.btn` → `.fs-btn`,
+    `.dropdown-menu` → `.fs-dropdown-menu` etc.), utilitários passam a usar
+    `u-` (`.d-flex` → `.u-d-flex`, `.mt-3` → `.u-mt-3`), e os estados
+    controlados por JavaScript usam `.is-*` (`.show` → `.is-open`, `.active`
+    → `.is-active`, `.disabled` → `.is-disabled`; `.is-valid`/`.is-invalid`
+    já seguiam a convenção). Tokens CSS (`--clarus-*` → `--fs-*`), o atributo
+    de auto-init (`data-fsarus` → `data-fs`) e os atributos de alvo/dispensa
+    (`data-target`/`data-dismiss` → `data-fs-target`/`data-fs-dismiss`)
+    seguem o mesmo prefixo, assim como os eventos DOM customizados
+    (`clarus:*` → `fs:*`). O global JavaScript (`window.Clarus`) e o nome do
+    pacote npm (`clarus-css`) **não mudam**. Afeta todo HTML que consome o
+    framework — quem atualizar precisa migrar as classes/atributos/eventos
+    citados acima.
+  - Reestruturação do repositório em monorepo (npm workspaces):
+    `scss/`/`js/` viram `packages/{clarus-core,clarus-components,
+    clarus-utilities,clarus-js,clarus-fonts}/`. Não afeta o consumo do
+    pacote publicado (`dist/`, `clarus-css/scss`, `clarus-css/js/*`
+    continuam nos mesmos caminhos), só a organização interna do
+    repositório-fonte.
+  - Todo o CSS emitido agora está organizado em cascade layers, na ordem
+    `reset, tokens, base, layout, components, utilities, overrides`
+    (declarada uma vez em `packages/clarus-core/scss/tokens/_root.scss`,
+    propagada a cada bundle de `dist/css/`). Efeito prático: uma classe
+    utilitária (`.u-*`) sempre vence uma classe de componente, mesmo com
+    especificidade igual, independente da ordem de import — ver
+    `docs/reference/scss-architecture.md`. A camada `overrides` fica reservada, sem
+    regras do framework, para customização do consumidor sem `!important`.
+  - Cores primitivas migradas para OKLCH (`packages/clarus-core/scss/settings/_colors.scss`),
+    calibradas para reproduzir os mesmos matizes hex de antes (round-trip
+    hex→oklch→hex), com fallback automático em sRGB via
+    `@supports (color: oklch(0% 0 0))` para navegadores sem suporte —
+    identidade visual inalterada, sem browsers não suportados. Piso de
+    navegador atualizado para moderno com fallback progressivo (Safari/iOS
+    16.4+; ver `docs/reference/browser-support.md`).
+  - Nova camada semântica de tokens (`packages/clarus-core/scss/tokens/_semantic.scss`:
+    `--fs-color-bg-surface`, `--fs-color-text-primary`,
+    `--fs-color-border-default` etc., todos alias `var()` dos tokens
+    primitivos) e primeiro componente migrado para tokens próprios
+    (`.fs-btn` ganha `--fs-btn-bg`/`--fs-btn-color`/`--fs-btn-border-color`,
+    sobrescrevíveis por instância sem `!important`) — ver
+    `docs/reference/scss-architecture.md` para o padrão a seguir em outros componentes.
+  - Nova escala tipográfica compacta (`--fs-font-size-*`): corpo ~13px, piso
+    ~11px reservado a texto de apoio; headings (`h1`–`h6`) ganham tamanho e
+    peso próprios pela primeira vez (antes usavam o padrão do navegador).
+    Utilitários `.u-fs-*`/`.u-fw-*` expandidos (`xl`, `h1`–`h6`,
+    `semibold`/`bold`).
+  - Governança: `CODE_OF_CONDUCT.md`, templates de issue/PR
+    (`.github/ISSUE_TEMPLATE/`, `.github/PULL_REQUEST_TEMPLATE.md`), política
+    de depreciação (2 minors) em `CONTRIBUTING.md`, guia de migração
+    (`docs/guides/migration-v1.md`) com codemod (`scripts/migrate-v1.mjs`),
+    script de baseline de tamanho gzip (`npm run size`) e relatório de
+    contraste WCAG (`npm run contrast`).
+
+### Added
+
+- **Componentes e refinamentos Cirrus**, já na convenção `fs-`/`@layer`/tokens:
+  - Checkbox/radio/switch 100% CSS (`packages/clarus-components/scss/forms/_check-radio-switch.scss`):
+    `.fs-check`/`.fs-radio`/`.fs-switch`, técnica de input oculto + label
+    irmã (mesma do Segmented Control/Rating). Estados checked/disabled/
+    indeterminate/`:focus-visible`, validação `is-valid`/`is-invalid`,
+    tamanhos sm/md/lg. Switch com knob retangular arredondado (não circular).
+  - Tile (`_tile.scss`): `.fs-tile` > `.fs-tile-icon` / `.fs-tile-body`
+    (`-title`/`-subtitle`) / `.fs-tile-actions` (à direita por padrão,
+    `.fs-tile-actions-bottom` pra embaixo). Variante `.fs-tile-clickable`
+    reusa `.fs-stretched-link` do Card. Tamanhos sm/lg.
+  - Pagination (`_pagination.scss`): `.fs-pagination-bordered` (itens
+    colados, borda fundida), tamanhos sm/lg, `.fs-page-link-text` para
+    prev/next descritivo (texto em vez de só «/»).
+  - Tabs (`_tabs.scss`): estilos `.fs-tabs-pill` e `.fs-tabs-depth` (além do
+    padrão em linha), alinhamento `.fs-tabs-center`/`-right`/`-fill`,
+    tamanhos sm/lg — tudo modificador de `.fs-tabs`, reaproveita `.fs-nav-link`
+    e a navegação por teclado existente (`js/tabs.js`) sem mudar o HTML.
+  - Tags (`_tag.scss`): escala própria `.fs-tag-xs`…`-xl`, agrupamento
+    (`.fs-tag-group`), feedback tátil (`:active`) no botão de dispensa.
+  - Mockups novos: `mockup/check-radio-switch.html`, `mockup/tile.html`;
+    exemplos adicionados a `mockup/pagination-breadcrumbs.html`,
+    `mockup/accordion-tabs-toast.html`, `mockup/tag.html`.
+
+- **Notification Center e Nested Menu**:
+  - Notification Center (`scss/components/_notification-center.scss`,
+    `js/notification-center.js`): orquestra múltiplas instâncias de
+    `Clarus.Toast` e mantém um histórico. `push({title, body, variant})` empilha
+    um toast e registra a notificação; painel de histórico (posicionado como o
+    Dropdown, fecha com Escape/clique fora) com dispensa por item, "limpar tudo"
+    e contador de não-lidas no gatilho — abrir marca tudo como lido.
+    Persistência opcional em `localStorage` (`data-storage="local"` +
+    `data-storage-key`); padrão em memória. `Clarus.NotificationCenter` com
+    `push()`/`remove()`/`clear()`/`getAll()`/`open()`/`close()`/`toggle()`/
+    `dispose()` e eventos `clarus:notification:pushed`/`-opened`/`-closed`/
+    `-cleared`. Mockup `mockup/notification-center.html`. Testes em
+    `tests/unit/notification-center.test.js`.
+  - Menu aninhado / Nested Menu (`scss/components/_nested-menu.scss`,
+    `js/nested-menu.js`): Dropdown com submenus recursivos, reaproveitando
+    `.dropdown-menu`/`.dropdown-item`. Abertura por hover é 100% CSS;
+    posicionamento em cascata (`left: 100%`, com flip para a esquerda perto da
+    borda) e navegação por teclado por nível (↓/↑ no nível, → abre, ←/Esc
+    fecham, Enter/Espaço alternam). `Clarus.NestedMenu` com API padrão
+    (`getInstance()`/`show()`/`hide()`/`toggle()`/`dispose()`) e eventos
+    `clarus:nested-menu:shown`/`-hidden`. Mockup `mockup/nested-menu.html`.
+    Testes em `tests/unit/nested-menu.test.js`.
+- **File Input Drag-and-Drop e Hover Card**:
+  - File Input Drag-and-Drop (`js/file-drop.js`): evolui
+    `.file-upload`/`.file-input`/`.file-label` com
+    `dragenter`/`dragover`/`dragleave`/`drop`, sincronizando o arquivo
+    solto com o `<input type="file">` nativo (dispara `change` nativo).
+    Estado visual `.is-dragover` e variante `.file-label-dropzone`. Mockup
+    `mockup/file-drop.html`. Testes unitários em
+    `tests/unit/file-drop.test.js`.
+  - Hover Card (`.popover-hover-card` em `scss/components/_popover.scss`):
+    composição do Popover já existente com `data-trigger="hover"`, sem
+    JavaScript novo — só um ajuste visual (largura + layout de avatar ao
+    lado do texto). Mockup `mockup/hover-card.html`.
+- **Badge dismissível / Tag** (`scss/components/_tag.scss`, `js/tag.js`).
+  `.tag` estende `.badge` e `.btn-close`, só ajustando o
+  tamanho do botão de fechar (14×14px) para caber num badge. Precisa de
+  JavaScript, de forma mínima:
+  `Clarus.Tag` só ouve o clique em `[data-dismiss="tag"]` e dispara o
+  evento cancelável `clarus:tag:dismissed` antes de remover o elemento do
+  DOM (`preventDefault()` bloqueia a remoção). Mockup `mockup/tag.html`.
+  Testes unitários em `tests/unit/tag.test.js`.
+- **Quick wins 100% CSS**:
+  - Divider (`scss/components/_divider.scss`): `<hr class="divider">` para
+    o traço simples; `<div class="divider">` com `.divider-label` para
+    texto centralizado, via `::before`/`::after`. Mockup
+    `mockup/divider.html`.
+  - Empty State (`scss/components/_empty-state.scss`): `.empty-state` com
+    `.empty-state-icon` (slot vazio), `.empty-state-title`,
+    `.empty-state-text` e ação opcional reaproveitando os botões
+    existentes. Mockup `mockup/empty-state.html`.
+  - Rating / Stars (`scss/components/_rating.scss`): `.rating`/
+    `.rating-star`, mesma técnica de input oculto + label irmão do
+    Segmented Control (`<input type="radio">` por estrela, `row-reverse` +
+    combinador de irmãos gerais). Tamanhos `.rating-sm`/`-lg`. Mockup
+    `mockup/rating.html`.
+- **Input Group e Alert Dialog**:
+  - Input Group (`scss/forms/_forms.scss`): `.input-group`/`.input-group-text`,
+    100% CSS. Funde `.form-control`/`.form-select`/`.btn` com addons de
+    prefixo/sufixo, bordas adjacentes sem duplicação e altura do addon
+    acompanhando o controle via `align-items: stretch`. Tamanhos
+    `.input-group-sm`/`-lg`. Mockup `mockup/input-group.html`.
+  - Alert Dialog / Confirm (`scss/components/_alert-dialog.scss`,
+    `js/confirm.js`): variante do Modal para confirmação, montada
+    dinamicamente (sem HTML pré-declarado) por `Clarus.confirm(options)`,
+    reaproveitando `js/modal.js` (foco/teclado/overlay). Retorna uma
+    `Promise<boolean>` (`true` ao confirmar, `false` ao cancelar/Escape/
+    clique fora), com o foco voltando ao elemento que chamou. Opções
+    `title`/`message`/`confirmText`/`cancelText`/`variant`. Mockup
+    `mockup/alert-dialog.html`.
+  - Testes unitários (Vitest) para `confirm()` (`tests/unit/confirm.test.js`).
+- **Segmented Control, Skeletons, Timeline, Collapse standalone e Breadcrumb avançado**:
+  - Componente Segmented Control (`scss/components/_segmented-control.scss`):
+    `.segmented-control`/`.segmented-item`/`.segmented-label`, 100% CSS.
+    Modo exclusivo (`<input type="radio">`) ou inclusivo (`<input
+    type="checkbox">`), input oculto pela mesma técnica de `.file-input`
+    (`scss/forms/_forms.scss`), reaproveitando `color-contrast()` no item
+    selecionado. Tamanhos `.segmented-control-sm`/`-lg`. Mockup
+    `mockup/segmented-control.html`.
+  - Componente Skeletons (`scss/components/_skeleton.scss`): `.skeleton` base
+    e variantes `.skeleton-text`/`-circle`/`-rect`, 100% CSS. Animação
+    "pulse" por padrão; `.skeleton-wave` varre um brilho via
+    pseudo-elemento. Ambas desativadas em `prefers-reduced-motion: reduce`.
+    Mockup `mockup/skeletons.html`.
+  - Componente Timeline (`scss/components/_timeline.scss`): `.timeline`/
+    `.timeline-item`/`.timeline-marker`, 100% CSS, vertical por padrão
+    (`.timeline-horizontal` inverte o eixo). Estados padrão (pendente)/
+    `.timeline-active`/`.timeline-completed`/`.timeline-failed`
+    reaproveitando os tokens de cor de estado; conector de progresso na
+    mesma lógica do Stepper. Mockup `mockup/timeline.html`.
+  - Collapse standalone (`scss/components/_collapse.scss`, `js/collapse.js`):
+    extrai `collapse()`/`expand()` de `js/core/transition.js` (já usado pelo
+    Accordion) para uma seção expansível independente. `Clarus.Collapse`
+    segue a API da seção 20 (`data-fsarus="collapse"`, `data-target`,
+    `getInstance()`, `.show()`/`.hide()`/`.toggle()`/`.dispose()`, eventos
+    `clarus:collapse:shown`/`-hidden`). Mockup `mockup/collapse.html`.
+  - Breadcrumb avançado (`scss/components/_breadcrumbs.scss`,
+    `js/breadcrumb.js`): truncamento por CSS com tooltip (`js/tooltip.js`)
+    só quando o texto transborda (medido após `document.fonts.ready`); abaixo
+    do breakpoint `sm` (640px), colapsa os níveis intermediários num item
+    "…" que compõe um `Dropdown` (`js/dropdown.js`), mantendo sempre o
+    primeiro e o último nível visíveis. `data-max-items` configurável.
+    Mockup `mockup/pagination-breadcrumbs.html` (exemplo avançado).
+- Testes unitários (Vitest) para Collapse e Breadcrumb
+  (`tests/unit/collapse.test.js`, `tests/unit/breadcrumb.test.js`).
+
+### Changed
+
+- Cores `primary` e `danger` escurecidas no preenchimento sólido para o texto
+  branco ter contraste adequado (WCAG ≥ 4.5:1): `--clarus-color-primary` passa
+  de blue-500 (#2972fa) para blue-600 (#1a61e6) e `--clarus-color-danger` de
+  red-500 (#fb4143) para red-700 (#cc3335) em `scss/settings/_colors.scss`.
+  Antes o `color-contrast()` caía para texto preto nesses fundos (pouca
+  legibilidade, sobretudo no vermelho). O peso de clareamento do `primary` no
+  dark mode (`scss/themes/_dark.scss`) sobe de 86% para 95%, porque o texto do
+  preenchimento passou de preto para branco (clarear reduz o contraste com o
+  branco). Afeta botões, badges, alerts e bordas que usam essas cores.
+- Fontes self-hosted (Plus Jakarta Sans e Source Code Pro) movidas para um
+  arquivo à parte, opcional: novo bundle `dist/css/fonts.css` (a partir de
+  `scss/base/_fonts.scss` + `scss/entries/fonts-entry.scss`), exportado como
+  `clarus-css/fonts.css`; `scss/base/_typography.scss` mantém só as pilhas de
+  `font-family`. Quem quiser as fontes importa `fonts.css` antes do CSS
+  principal; sem ele, a tipografia cai no `sans-serif`/`monospace` do sistema.
+  Também elimina a duplicação dos `@font-face`, antes repetidos em `clarus.css`,
+  `components.css`, `forms.css`, `layout.css` e `helpers.css`.
+- Alert Dialog / Confirm (`js/confirm.js`, `scss/components/_alert-dialog.scss`):
+  removido o ícone informativo do corpo do diálogo — fica só título e mensagem.
+- Paleta de cores evoluída para escalas completas 100-900 por matiz
+  (yellow/green/blue/gray/red/purple) com papéis semânticos por cor de
+  estado (`color`/`-hover`/`-active`/`-disabled`/`bg`/`bg-2`/`text`/`text-2`/
+  `border`) em `scss/settings/_colors.scss`, incluindo uma nova cor
+  `secondary`; `scss/tokens/_root.scss` e `scss/themes/_dark.scss`
+  (variantes de dark mode por peso de tint) acompanham a nova estrutura.
+- Fonte monoespaçada Source Code Pro passa a ser self-hosted
+  (`assets/fonts/source-code-pro/`, licença OFL), removendo o último
+  `@import` externo de Google Fonts em `scss/base/_typography.scss` —
+  completa a meta de dependência externa zero em tempo de execução (seção 6
+  de `docs/definitions.md`) também para a fonte mono, no mesmo padrão já
+  usado pela Plus Jakarta Sans.
+
+- Componente Stepper/Wizard (`scss/components/_stepper.scss`, `js/stepper.js`):
+  `.stepper`/`.stepper-header`/`.step` com `.step-indicator` (número, ou "check"
+  em SVG quando concluído) e `.step-label`; estados `.step-active`/
+  `.step-completed`/`.step-error`; conector de progresso na cor primária após um
+  passo concluído; variante `.stepper-vertical` (com `.step-content` +
+  `.step-description`); painéis opcionais `.step-panel` e ações `.stepper-actions`
+  com `[data-stepper="prev"]`/`[data-stepper="next"]`. `Clarus.Stepper` com
+  `.next()`/`.prev()`/`.goTo()`/`.setError()`/`.complete()`/`.dispose()`; evento
+  **cancelável** `clarus:stepper:beforechange` (hook de validação por passo),
+  `clarus:stepper:changed` e `clarus:stepper:completed`. Linear por padrão
+  (`data-linear`), `aria-current="step"` e navegação por teclado. Mockup
+  `mockup/stepper.html`.
+- Breakpoint adicional `xxxl` (1920px, `scss/settings/_breakpoints.scss`),
+  para monitores externos Full HD sem escala — gera automaticamente
+  `.col-xxxl-*`, `.container-xxxl` e todos os utilitários responsivos
+  `-xxxl` (spacing, gap, flex, display) via os mesmos loops que já geram os
+  demais breakpoints.
+- Componente Offcanvas (`scss/components/_offcanvas.scss`, `js/offcanvas.js`):
+  painel deslizante com posições `.offcanvas-start`/`-end`/`-top`/`-bottom`,
+  mesmo mecanismo de overlay do Modal (bloqueio de scroll, focus trap,
+  Escape/clique fora), aplicado de forma independente (sem compor
+  `js/modal.js`). Backdrop criado dinamicamente pelo JS;
+  `data-backdrop="static"` desativa Escape/clique fora, `data-backdrop="false"`
+  remove o backdrop visual mantendo Escape/clique fora ativos. `Clarus.Offcanvas`
+  com `getInstance()`/`.show()`/`.hide()`/`.toggle()`/`.dispose()`, eventos
+  `clarus:offcanvas:shown`/`-hidden`, `data-dismiss="offcanvas"`. Mockup
+  `mockup/offcanvas-popover.html`.
+- Componente Popover (`scss/components/_popover.scss`, `js/popover.js`):
+  painel flutuante com conteúdo rico (`.popover-header`/`-body`/`-footer`),
+  posicionado via `computePosition()`/`applyPosition()` (como Dropdown/Tooltip),
+  `role="dialog"` + `aria-modal="false"` (não é modal — sem focus trap, sem
+  bloqueio de scroll). `data-trigger` controla o disparo: `"click"` (padrão),
+  `"hover"` (com tolerância para mover o mouse ao conteúdo), `"focus"` (via
+  `focusout`/`relatedTarget`) ou `"manual"` (sem listeners automáticos).
+  `Clarus.Popover` com `getInstance()`/`.show()`/`.hide()`/`.toggle()`/
+  `.dispose()`, eventos `clarus:popover:shown`/`-hidden`, `data-dismiss="popover"`.
+  Mockup `mockup/offcanvas-popover.html`.
+
+### Changed
+
+- Escala de breakpoints (`scss/settings/_breakpoints.scss`) recalibrada para
+  as larguras lógicas de tela mais comuns do mercado atual:
+  `sm` 576px→640px (tablets pequenos/phablets), `lg` 992px→1024px (tablet
+  paisagem/iPad), `xl` 1200px→1280px (laptop comum), `xxl` 1400px→1536px
+  (laptop/desktop com escala, ex.: Mac/Windows a 125%). `md` (768px)
+  permanece igual. `$container-max-widths` ajustado na mesma proporção
+  (600/720/960/1200/1440px). Os nomes de classe não mudam
+  (`.col-md-6`, `.d-lg-none`, etc. continuam os mesmos) — só os valores em
+  px por trás de cada breakpoint, o que pode alterar sutilmente o layout
+  visual de projetos existentes nos pontos de corte afetados.
+
+### Fixed
+
+- Erro do bundlephobia ao analisar o pacote ("Found an asset without the
+  `.bundle` suffix ... `.woff2`"): o `main` (`dist/css/clarus.css`) referenciava
+  as `url(...woff2)` dos `@font-face`, que o webpack do bundlephobia não resolve
+  sem loader. Com os `@font-face` isolados em `fonts.css` (ver Changed), os
+  bundles principais não têm mais referências a woff2.
+- Badge (`scss/components/_badges.scss`): texto centralizado verticalmente — o
+  padding assimétrico `2px 8px 0`, que empurrava o texto para baixo, virou
+  `0 8px`, deixando a centralização por conta do flex.
+- Tag (`scss/components/_tag.scss`): o "x" do botão de fechar herda a cor de
+  texto do badge (contraste automático por variante) em vez de um cinza fixo,
+  corrigindo a baixa visibilidade sobre badges coloridos.
+- Timeline horizontal (`scss/components/_timeline.scss`): o conector alinha com
+  o centro do marcador — o `margin-top: 3px` do marcador (necessário só no modo
+  vertical) é zerado no horizontal, onde deixava a linha acima do centro do
+  círculo.
+
+## [0.3.0] - 2026-07-04
+
+### Added
+
+- Componente Spinner e Progress (`scss/components/_spinner.scss`, 100% CSS):
+  spinner giratório `.spinner` (animação `clarus-spin`) com tamanhos
+  (`.spinner-sm`/`.spinner-lg`) e variantes de cor de estado
+  (`.spinner-#{nome}`); barra de progresso `.progress`/`.progress-bar` com
+  largura por `--clarus-progress-value` (0–100), tamanhos
+  (`.progress-sm`/`.progress-lg`), variantes de cor
+  (`.progress-bar-#{nome}`, via `color-contrast()`) e faixas opcionais
+  (`.progress-bar-striped`/`.progress-bar-animated`). Toda animação respeita
+  `prefers-reduced-motion`. Mockup `mockup/spinner-progress.html`. Primeiro
+  item da Etapa 1 do roadmap de paridade.
+- Componente Carousel (`scss/components/_carousel.scss`, `js/carousel.js`):
+  carrossel de slides com layout "slide" (trilha flex deslocada por
+  `translateX`) e variante `.carousel-fade` (opacidade); setas
+  (`.carousel-control-prev`/`-next`) e indicadores (`.carousel-indicators`)
+  opcionais, com modificador opcional `.carousel-hover-controls` (setas só no
+  hover/foco). `Clarus.Carousel` com `.next()`/`.prev()`/`.goTo()`/`.pause()`/
+  `.dispose()`, evento `clarus:carousel:slid`, navegação por teclado
+  (setas/Home/End), swipe por pointer events e autoplay opcional
+  (`data-autoplay`/`data-interval`, válido para slide e fade) que pausa no
+  hover/foco. ARIA completo (`role="group"`, `aria-roledescription`,
+  `aria-current` nos indicadores) e respeito a `prefers-reduced-motion`. O
+  recorte fica no `.carousel` (elemento parado) e não na trilha, para não
+  cortar os slides seguintes ao deslocar. Mockup `mockup/carousel.html`.
+  Segundo item (Etapa 2) do roadmap de paridade.
+- Testes de regressão visual com Playwright integrados ao CI, com baselines por
+  plataforma (`-win32`/`-linux`, estas geradas em container Docker para bater
+  com o ambiente do CI).
+
+## [0.2.0] - 2026-07-04
+
+### Added
+
+- Suíte de testes automatizados: testes funcionais de JavaScript com Vitest +
+  jsdom (`tests/unit/`, cobrindo estado, ARIA e eventos de cada componente
+  interativo e dos módulos de `js/core/`) e testes visuais com Playwright
+  (`tests/visual/`, screenshots de baseline por mockup e testes de interação).
+  Ambos rodam automaticamente no GitHub Actions a cada push/PR, além do lint e
+  do build.
+
+## [0.1.2] - 2026-07-04
+
+### Added
+
+- Componente Botões (`scss/components/_buttons.scss`): variantes sólidas e
+  outline por cor de estado (`.btn-primary/success/warning/danger/info`,
+  `.btn-outline-*`), tamanhos (`.btn-sm`/`.btn-lg`) e estados de
+  hover/active/focus/disabled.
+- Função `color-contrast()` (`scss/tools/_mixins.scss`), que escolhe texto
+  branco ou preto por cor de fundo com base no contraste WCAG (mínimo 4.5:1).
+- Componente Badges (`scss/components/_badges.scss`): variantes sólidas por
+  cor de estado (`.badge-primary/success/warning/danger/info`) e tamanhos
+  (`.badge-sm`/`.badge-lg`).
+- Componente Alertas (`scss/components/_alerts.scss`): variantes tintadas
+  por cor de estado (`.alert-primary/success/warning/danger/info`), com
+  tokens `--clarus-alert-*-bg`/`-text` (`scss/tokens/_root.scss`,
+  sobrescritos no dark mode em `scss/themes/_dark.scss`).
+- Funções `tint-color()`/`shade-color()` (`scss/tools/_mixins.scss`), para
+  gerar variações claras/escuras de uma cor base.
+- Componente Cards (`scss/components/_cards.scss`): `.card-header`,
+  `.card-body`, `.card-footer`, `.card-title`, `.card-subtitle`,
+  `.card-text` e tamanhos (`.card-sm`/`.card-lg`).
+- Utilitários de sombra (`.shadow-sm`/`.shadow`/`.shadow-lg`) em
+  `scss/utilities/_shadow.scss`, com tokens `--clarus-shadow-*`
+  (`scss/tokens/_root.scss`) e override para dark mode.
+- Componente `.btn-close` (`scss/components/_buttons.scss`), reaproveitável
+  em cards, e futuramente em modal/toast.
+- `.card-header` agora suporta título + botão de fechar alinhados nas
+  pontas (layout flex com `justify-content: space-between`).
+- `.card-clickable` + `.stretched-link`: torna o card inteiro clicável e
+  focável via um único link, sem aninhar elementos interativos.
+- `.card-horizontal`: inverte o eixo do card para linha, com raio e borda
+  do header/footer ajustados para a lateral.
+- Componente Tabelas (`scss/components/_tables.scss`): `.table-striped`,
+  `.table-hover`, `.table-bordered`, `.table-borderless`, `.table-sm`,
+  `.table-responsive` e variantes de cor de estado
+  (`.table-primary/success/warning/danger/info`), reaproveitando os
+  tokens `--clarus-alert-*-bg`/`-text` da Fase 2.
+- Componente Navbar (`scss/components/_navbar.scss`): `.navbar-brand`,
+  `.navbar-nav`, `.nav-link` (com estados `.active`/`.disabled`), versão
+  estática (sem dropdown/collapse).
+- Componente Paginação (`scss/components/_pagination.scss`): `.page-link`,
+  estados `.active`/`.disabled`, reaproveitando `color-contrast()` da
+  Fase 1.
+- Componente Breadcrumbs (`scss/components/_breadcrumbs.scss`):
+  `.breadcrumb-item`, separador via `::before`, estado `.active`.
+- Infraestrutura JS compartilhada (`js/core/`), pré-requisito dos
+  componentes interativos das próximas fases, sem dependências externas:
+  `positioning.js` (`computePosition()`/`applyPosition()`, com flip
+  automático e clamp na viewport); `overlay.js` (`lockScroll()`/
+  `unlockScroll()` com compensação de scrollbar e contagem de referências,
+  `onClickOutside()`); `focus.js` (`createFocusTrap()` com ciclo
+  Tab/Shift+Tab, `onEscapeKey()`); `transition.js` (`collapse()`/
+  `expand()` animando `height`, respeitando `prefers-reduced-motion`).
+  Reexportado como `Clarus.core` pelo bundle único e importável de forma
+  granular (`clarus-css/js/core/*`).
+- Componente Dropdown (`scss/components/_dropdown.scss`, `js/dropdown.js`):
+  `.dropdown-toggle`/`.dropdown-menu`/`.dropdown-item`/`.dropdown-divider`/
+  `.dropdown-header`; posicionamento via `Clarus.core` com flip automático e
+  alinhamento configurável (`data-align="start"`/`"center"`/`"end"`, padrão
+  `"start"`), navegação por ArrowUp/ArrowDown, fecha com clique fora/em um
+  item/Escape (foco retorna ao toggle). Primeiro componente a seguir a API
+  JS da seção 20: auto-init via `data-fsarus="dropdown"`, `Clarus.Dropdown`
+  com `getInstance()`/`.show()`/`.hide()`/`.toggle()`/`.dispose()`, eventos
+  `clarus:dropdown:shown`/`-hidden`.
+- `computePosition()` (`js/core/positioning.js`) ganhou a opção `align`
+  para o eixo cruzado (usada pelo Dropdown acima), além do `placement`
+  já existente.
+- Componente Tooltip (`scss/components/_tooltips.scss`, `js/tooltip.js`):
+  `.tooltip`/`.tooltip-inner`/`.tooltip-arrow` com 4 posicionamentos
+  (top/bottom/left/right) e novos tokens `--clarus-tooltip-bg`/`-text`
+  (invertidos no dark mode); show/hide por hover/foco/blur e Escape,
+  `aria-describedby` ligando referência e tooltip; mesma API JS do
+  Dropdown (`Clarus.Tooltip`, `data-fsarus="tooltip"`, eventos
+  `clarus:tooltip:shown`/`-hidden`).
+- `js/core/register.js` (`autoInit()`/`createInstanceRegistry()`):
+  generaliza o padrão de auto-inicialização via `data-fsarus` e registro de
+  instância (`getInstance()`) para os próximos componentes interativos.
+- Componente Modal (`scss/components/_modal.scss`, `js/modal.js`):
+  `.modal`/`.modal-dialog`/`.modal-content`/`.modal-header`/`.modal-title`/
+  `.modal-body`/`.modal-footer`, tamanhos `.modal-sm`/`.modal-lg`. Reaproveita
+  a infraestrutura da Fase 7: `lockScroll()` enquanto aberto,
+  `createFocusTrap()`, fecha com Escape/clique fora (foco volta ao
+  gatilho) ou `data-dismiss="modal"`; `data-backdrop="static"` desativa
+  fechar por Escape/clique fora. Segue a mesma API JS de Dropdown/Tooltip
+  (`Clarus.Modal`, `data-fsarus="modal"`, eventos
+  `clarus:modal:shown`/`-hidden`).
+- Select customizado (`js/select.js`, `Clarus.Select`): gera a marcação
+  (`.form-select` + `.dropdown-menu`/`.dropdown-item` por `<option>`) a
+  partir de um `<select>` nativo (`data-fsarus="select"`, oculto mas
+  sincronizado para submissão de formulário) e compõe uma instância de
+  `Dropdown` por cima, reaproveitando posicionamento/navegação/fechamento
+  da Fase 8 em vez de duplicar essa lógica; dispara `change` nativo e
+  `clarus:select:changed` ao selecionar. Novo `.form-select`/
+  `.form-select-sm`/`-lg` em `scss/forms/_forms.scss`.
+- Componente Accordion (`scss/components/_accordion.scss`, `js/accordion.js`):
+  `.accordion`/`.accordion-item`/`.accordion-header`/`.accordion-button`/
+  `.accordion-collapse`/`.accordion-body`. Reaproveita `collapse()`/
+  `expand()` de `Clarus.core` (Fase 7) para animar a altura de cada painel;
+  só um painel aberto por vez por padrão (`data-multiple="true"` permite
+  vários); segue a API JS da seção 20 (`Clarus.Accordion`,
+  `data-fsarus="accordion"`, eventos `clarus:accordion:shown`/`-hidden`).
+- Componente Tabs (`scss/components/_tabs.scss`, `js/tabs.js`):
+  `.tabs`/`.tab-content`/`.tab-pane`, reaproveitando `.nav-link` (Navbar,
+  Fase 4) com indicador de sublinhado escopado a `.tabs`. Navegação por
+  ArrowLeft/ArrowRight/Home/End (`role="tablist"`/`"tab"`/`"tabpanel"`,
+  `aria-selected`, `tabindex` roving), disparando `clarus:tab:changed`
+  (`Clarus.Tabs`, `data-fsarus="tabs"`).
+- Componente Toast (`scss/components/_toasts.scss`, `js/toast.js`):
+  `.toast-container`/`.toast`/`.toast-header`/`.toast-body`, variantes de
+  cor de estado (`.toast-#{nome}`, reaproveitando os tokens
+  `--clarus-alert-*-bg`/`-text` da Fase 2). Reaproveita `expand()`/
+  `collapse()` de `Clarus.core` para mostrar/esconder, com timer de
+  auto-dismiss configurável (`data-delay`, `data-autohide="false"` para
+  desativar) e dismiss via `data-dismiss="toast"`; segue a API JS da seção
+  20 (`Clarus.Toast`, `data-fsarus="toast"`, eventos
+  `clarus:toast:shown`/`-hidden`).
+- Formulários avançados (`scss/forms/_forms.scss`): estados de validação
+  `.form-control.is-valid`/`.is-invalid` (borda e anel de foco em
+  `--clarus-color-success`/`-danger`) com `.valid-feedback`/
+  `.invalid-feedback` (exibidos via seletor de irmão adjacente, sem
+  JavaScript); upload de arquivo estilizado `.file-upload`/`.file-input`/
+  `.file-label` (input nativo ocultado via `clip-path`, mantendo foco e
+  navegação por teclado), com tamanhos (`.file-label-sm`/`-lg`) e estado
+  desabilitado.
+- Paleta de cores oficial "Indigo autoral" (`docs/definitions.md`, seção
+  18.1) em `scss/settings/_colors.scss`: `primary #4F46E5`, `success
+  #1BC559`, `warning #F0B40E`, `danger #DC263E`, `info #8BA2C4`; escala
+  neutra completada para 9 degraus cheios (`$color-gray-100` a
+  `$color-gray-900`).
+- Variantes de `primary`/`success`/`warning`/`danger`/`info` para o dark
+  mode (`scss/themes/_dark.scss`, token `--clarus-color-#{nome}`, via
+  `color.mix()` com peso por cor em `$dark-color-weights`).
+- Tipografia principal Plus Jakarta Sans self-hosted (`docs/definitions.md`,
+  seção 18.2): arquivos `.woff2` (licença OFL) em
+  `assets/fonts/plus-jakarta-sans/`, com `@font-face` em
+  `scss/base/_typography.scss` no lugar do `@import` do Google Fonts,
+  cumprindo a meta de dependência externa zero em tempo de execução para a
+  fonte principal (Source Code Pro, no monoespaçado, mantida via Google
+  Fonts).
+
+### Fixed
+
+- Duplicidade entre `$color-primary` e `$color-info` (mesmo valor de azul)
+  em `scss/settings/_colors.scss`, corrigida pela nova paleta "Indigo
+  autoral".
+- `.dropdown-menu` sem `position: absolute` no CSS base (só era aplicado
+  via JS no `show()`): a medição de largura acontecia com o menu ainda como
+  bloco normal (ocupando a largura inteira do `body`), quebrando o cálculo
+  de alinhamento `start`/`end`. Corrigido em
+  `scss/components/_dropdown.scss`.
+- Texto solto (`<h2>`/`<p>` sem cor própria) invisível no painel escuro de
+  vários mockups (`badges-alerts.html`, `buttons.html`, `forms-advanced.html`,
+  `dropdown-tooltip.html`): `[data-theme="dark"].theme-panel` só definia
+  `background-color`, nunca `color` — o texto herdava o valor já resolvido
+  de `color` do `body` (calculado no tema claro), que não é reavaliado só
+  por redefinir a custom property num elemento descendente.
+- Tooltip/Dropdown não invertiam para o tema escuro quando o elemento de
+  referência estava dentro de um wrapper com `data-theme="dark"` (em vez de
+  no `<html>`): como `js/tooltip.js`/`js/dropdown.js` reanexam o elemento
+  flutuante a `document.body`, ele saía do escopo do wrapper e sempre usava
+  os tokens do tema claro. Agora ambos copiam o `data-theme` do ancestral
+  mais próximo do elemento de referência/toggle para o elemento flutuante a
+  cada `show()`.
+- `.btn-close` (`scss/components/_buttons.scss`): o "×" (glifo `\00d7`)
+  centralizado por flexbox não ficava opticamente centrado no botão, por
+  depender da métrica vertical do glifo na fonte. Substituído por duas
+  barras via `::before`/`::after`, giradas ±45° e centralizadas por
+  `transform: translate(-50%, -50%)` a partir do centro absoluto do
+  botão — centralização exata, independente de fonte.
+
+## [0.1.1] - 2026-07-01
+
+### Added
+
+- Definições iniciais do projeto (`docs/definitions.md`) e arquitetura SCSS
+  (`docs/scss-architecture.md`).
+- Estrutura modular `scss/` (settings, tools, tokens, base, layout, forms,
+  components, utilities, themes).
+- Sistema de layout: containers, grid de 12 colunas baseado em Flexbox
+  (`.row`/`.col-*`) e utilitários responsivos por breakpoint.
+- Pipeline de build: Sass + PostCSS (Autoprefixer) + esbuild, gerando `dist/css`
+  (`layout`, `forms`, `components`, `helpers`, `clarus`) e `dist/js/clarus.js`,
+  cada um em versão expandida e minificada com source maps.
+- Lint de SCSS via stylelint.
+- CI no GitHub Actions (lint + build).
+- Utilitários de tipografia (`text-*`, `fw-*`, `fs-*`, `font-*`) em
+  `scss/utilities/_typography.scss`.
+- Estado `:read-only` em `.form-control`.
+
+[Unreleased]: https://github.com/jorgewreis/clarus-css/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/jorgewreis/clarus-css/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/jorgewreis/clarus-css/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/jorgewreis/clarus-css/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/jorgewreis/clarus-css/releases/tag/v0.1.1