fokus-styles 2.0.0

package/docs/reference/design-tokens.md

@@ -0,0 +1,194 @@
+# Design tokens
+
+Referência completa dos tokens do Fokus Styles. Escolha primeiro o token pelo
+papel que ele desempenha; consulte [Theming](../guides/theming.md) para
+customizá-lo em runtime ou via Sass.
+
+## Cor — primitivo → semântico → componente
+
+### Semânticos (uso geral)
+
+| Token | Papel |
+|---|---|
+| `--fs-color-text` | Texto principal |
+| `--fs-color-muted` | Texto secundário/discreto |
+| `--fs-color-border` | Bordas padrão |
+| `--fs-color-surface` | Fundo de superfície (card, modal, input) |
+| `--fs-color-subtle` | Fundo levemente destacado (hover, header de card) |
+| `--fs-color-white` / `--fs-color-black` | Acromáticos, sem variação por tema |
+
+### Aliases por papel (`packages/fokus-core/scss/tokens/_semantic.scss`)
+
+Mesmos valores dos acima, com nome por função — use estes quando o nome
+comunica melhor a intenção no seu código:
+
+| Token | Alias de |
+|---|---|
+| `--fs-color-bg-surface` | `--fs-color-surface` |
+| `--fs-color-bg-subtle` | `--fs-color-subtle` |
+| `--fs-color-surface-raised` | `--fs-color-surface` |
+| `--fs-color-text-primary` | `--fs-color-text` |
+| `--fs-color-text-muted` | `--fs-color-muted` |
+| `--fs-color-border-default` | `--fs-color-border` |
+| `--fs-color-action-primary` | `--fs-color-primary` |
+| `--fs-color-action-danger` | `--fs-color-danger` |
+
+### Gráficos (`packages/fokus-core/scss/tokens/_charts.scss`)
+
+Agnósticos de biblioteca — ver [guia de gráficos](../guides/charts.md).
+
+| Token | Alias de |
+|---|---|
+| `--fs-chart-series-1` | `--fs-color-primary` |
+| `--fs-chart-series-2` | `--fs-color-success` |
+| `--fs-chart-series-3` | `--fs-color-warning` |
+| `--fs-chart-series-4` | `--fs-color-danger` |
+| `--fs-chart-series-5` | `--fs-color-info` |
+| `--fs-chart-series-6` | `--fs-color-secondary` |
+| `--fs-chart-grid` | `--fs-color-border` |
+| `--fs-chart-axis` | `--fs-color-muted` |
+| `--fs-chart-tooltip-bg` | `--fs-tooltip-bg` |
+| `--fs-chart-tooltip-text` | `--fs-tooltip-text` |
+
+### Cores de tema
+
+Seis papéis, cada um com 3 tokens derivados automaticamente do primitivo
+(tint/shade em OKLCH):
+
+`primary`, `secondary`, `success`, `warning`, `danger`, `info`
+
+| Padrão de token | Exemplo (`primary`) | Uso |
+|---|---|---|
+| `--fs-color-{nome}` | `--fs-color-primary` | Cor sólida (fundo de botão, borda ativa) |
+| `--fs-alert-{nome}-bg` | `--fs-alert-primary-bg` | Fundo tintado (alerta) |
+| `--fs-alert-{nome}-text` | `--fs-alert-primary-text` | Texto sobre o fundo tintado |
+| `--fs-feedback-{nome}-bg` | `--fs-feedback-primary-bg` | Fundo tintado mais sutil (badge suave, notificação) |
+
+### Componente
+
+Componentes expõem tokens próprios quando precisam de uma API de customização
+local. Eles têm fallback para um token semântico e podem ser alterados sem
+`!important`:
+
+```css
+.meu-botao-especial {
+  --fs-btn-bg: var(--fs-color-action-primary);
+}
+```
+
+Consulte a página do componente para a lista completa. Por exemplo,
+`.fs-btn` documenta `--fs-btn-bg`, `--fs-btn-color` e
+`--fs-btn-border-color`. Prefira nomes de intenção, como
+`--fs-color-action-primary`, em vez de nomes baseados no valor da cor.
+
+O Carousel expõe tokens locais para que controles, indicadores, transições e
+legendas possam ser ajustados por instância: `--fs-carousel-radius`,
+`--fs-carousel-transition-duration`, `--fs-carousel-transition-easing`,
+`--fs-carousel-control-*`, `--fs-carousel-indicator-*` e
+`--fs-carousel-caption-scrim`. Consulte a [página do Carousel](../components/carousel.md)
+para os nomes completos e seus fallbacks.
+
+## Tipografia
+
+| Token | Valor | Uso |
+|---|---|---|
+| `--fs-font-sans` | Plus Jakarta Sans, sans-serif | Corpo, UI |
+| `--fs-font-mono` | Source Code Pro, monospace | Código |
+| `--fs-font-size-md` | 0.8125rem (13px) | Corpo — único tamanho de texto exposto como token; `xs`/`sm`/`lg`/`xl` são variáveis Sass (`$font-size-*`), não CSS Custom Properties, por serem só usadas em geração de classe |
+| `--fs-font-size-h1`…`h6` | 1.75rem → 0.875rem | Headings |
+| `--fs-font-weight-semibold` | 600 | Peso dos headings |
+| `--fs-line-height-base` | 1.5 | Corpo |
+| `--fs-line-height-heading` | 1.25 | Headings |
+
+## Formato
+
+| Token | Valor |
+|---|---|
+| `--fs-radius-sm` | 4px |
+| `--fs-radius-md` | 6px |
+| `--fs-radius-lg` | 8px |
+
+Circular só é usado em dois lugares deliberadamente (radio, spinner) — o
+resto do framework é quadrado/arredondado por decisão de design, não por
+limitação técnica.
+
+## Espaçamento, elevação e controles
+
+Os valores mais usados também ficam disponíveis em runtime para que
+componentes e extensões mantenham a mesma escala visual:
+
+| Token | Papel |
+|---|---|
+| `--fs-space-0` … `--fs-space-5` | Escala de espaçamento baseada em `$spacers` |
+| `--fs-z-dropdown` … `--fs-z-tooltip` | Camadas padronizadas para overlays |
+| `--fs-control-height` / `--fs-control-height-sm` / `--fs-control-height-lg` | Alturas dos controles de formulário |
+| `--fs-control-padding-x` / `--fs-control-padding-x-sm` / `--fs-control-padding-x-lg` | Padding horizontal dos controles |
+| `--fs-border-width` | Espessura padrão de bordas |
+| `--fs-disabled-opacity` | Opacidade visual de controles desabilitados |
+| `--fs-color-on-primary` … `--fs-color-on-info` | Cor de conteúdo sobre cada cor de tema |
+
+## Interação e movimento
+
+| Token | Papel |
+|---|---|
+| `--fs-color-focus` | Cor semântica do foco de teclado |
+| `--fs-focus-width` / `--fs-focus-offset` | Geometria do anel de foco |
+| `--fs-focus-ring-alpha` | Intensidade do halo de foco |
+| `--fs-transition-fast` / `--fs-transition-normal` | Durações de transição |
+| `--fs-ease-standard` | Curva de movimento padrão |
+
+O framework respeita `prefers-reduced-motion: reduce`, reduzindo transições e
+animações CSS ao mínimo sem remover estados ou interações.
+
+Use `--fs-color-on-{nome}` em texto e ícones sobre fundos de tema. Isso
+permite que uma marca altere o contraste sem duplicar regras de componente.
+
+## Sombra
+
+| Token |
+|---|
+| `--fs-shadow-sm` |
+| `--fs-shadow-md` |
+| `--fs-shadow-lg` |
+
+## Grid
+
+| Token | Valor |
+|---|
+| `--fs-gutter-x` | 1.5rem |
+| `--fs-gutter-y` | 0px |
+
+Controlados em runtime pelas classes `.fs-u-g-*`/`.fs-u-gx-*`/`.fs-u-gy-*` — ver
+[`docs/reference/scss-architecture.md`](scss-architecture.md#layout).
+
+## Layout avançado (Stack/Cluster/Sidebar/sticky/container queries)
+
+| Token | Valor padrão |
+|---|---|
+| `--fs-stack-gap` | `1rem` (`.fs-stack-gap-{0..5}` sobrescreve) |
+| `--fs-cluster-gap` | `0.5rem` (`.fs-cluster-gap-{0..5}` sobrescreve) |
+| `--fs-sidebar-gap` | `1rem` (`.fs-sidebar-gap-{0..5}` sobrescreve) |
+| `--fs-sidebar-width` | `16rem` (`.fs-sidebar-width-{sm..xxxl}` sobrescreve) |
+| `--fs-sticky-top` / `--fs-sticky-bottom` | `0` |
+| `--fs-cq-sm` / `--fs-cq-md` / `--fs-cq-lg` | `320px` / `480px` / `640px` — só informativos, ver [Layout avançado](../guides/layout-advanced.md#container-queries-container) |
+
+Ver [Layout avançado](../guides/layout-advanced.md) para a documentação
+completa de uso.
+
+## Só-Sass (sem CSS Custom Property)
+
+Não têm equivalente em token CSS porque alimentam geração de classe em
+tempo de build (nome de classe fixo, não pode reagir a uma variável em
+runtime):
+
+| Variável Sass | Uso |
+|---|---|
+| `$spacers` | Escala de espaçamento (`.fs-u-m*`/`.fs-u-p*`/`.fs-u-g*`) |
+| `$breakpoints` | Grid e utilitários responsivos (`.fs-u-*-{breakpoint}`) |
+| `$container-max-widths` / `$column-max-widths` | Containers e colunas com largura máxima |
+| `$font-size-xs`/`-sm`/`-lg`/`-xl` | Escala de tamanho de texto (utilitários `.fs-u-fs-*` e tamanhos `-sm`/`-lg` de componente) |
+| `$font-weight-regular`/`-medium`/`-bold` | Peso de texto (`.fs-u-fw-*`) |
+| `$theme-colors` / `$theme-bg-colors` | Mapas usados pelos `@each` que geram as variantes de cor de cada componente |
+
+Customizáveis só via `@use ... with (...)` na compilação — ver
+[Theming](../guides/theming.md#customizando-via-sass).

package/docs/reference/scss-architecture.md

@@ -0,0 +1,227 @@
+# Arquitetura SCSS do Fokus Styles
+
+## Objetivo
+
+A arquitetura SCSS do Fokus Styles organiza o framework em módulos pequenos, previsíveis e alinhados a uma abordagem híbrida: componentes prontos, utilitários reutilizáveis e tokens customizáveis por CSS Custom Properties.
+
+O repositório é um monorepo (npm workspaces). O código-fonte SCSS vive em
+`packages/*/scss/`; `scss/` (raiz do repo) contém apenas os pontos de entrada
+de build (`scss/fokus.scss` e `scss/entries/`), que combinam os pacotes.
+
+`scss/fokus.scss` é o ponto de entrada oficial do bundle completo:
+
+```text
+scss/fokus.scss
+```
+
+## Estrutura
+
+```text
+packages/
+├── fokus-core/scss/
+│   ├── settings/
+│   ├── tools/
+│   ├── tokens/
+│   ├── base/
+│   ├── layout/
+│   └── themes/
+├── fokus-components/scss/
+│   ├── components/
+│   └── forms/
+├── fokus-utilities/scss/
+│   └── utilities/
+├── fokus-fonts/scss/
+└── fokus-js/js/
+scss/
+├── fokus.scss      # bundle completo (dist/css/fokus.css)
+└── entries/         # pontos de entrada auxiliares por distribuição
+```
+
+Cada pacote expõe seu próprio `scss/` como raiz de resolução (`scssLoadPaths`
+em `scripts/build.mjs`), então `@use "settings"`/`@use "tokens"`/etc. resolve
+sem caminhos relativos `../../` entre pacotes.
+
+## Cascade layers (`@layer`)
+
+Todo CSS emitido pelo framework é organizado em cascade layers, na ordem
+declarada uma única vez em `packages/fokus-core/scss/tokens/_root.scss`:
+
+```scss
+@layer reset, tokens, base, layout, components, utilities, overrides;
+```
+
+- **reset** — normalização mínima (`base/_reset.scss`).
+- **tokens** — CSS Custom Properties em `:root` e overrides de tema
+  (`tokens/_root.scss`, `themes/_dark.scss`).
+- **base** — estilos globais de elementos (`base/_typography.scss`).
+- **layout** — grid/containers (`layout/`).
+- **components** — todo componente pronto, incluindo `forms/`.
+- **utilities** — classes utilitárias (`.fs-u-*`).
+- **overrides** — reservada, sem regras do próprio framework; existe para que
+  consumidores possam sobrescrever qualquer camada anterior sem precisar de
+  `!important` ou seletores mais específicos.
+
+Cada parcial que gera CSS envolve seu próprio conteúdo na camada
+correspondente (ex.: `_buttons.scss` inteiro dentro de `@layer components { }`).
+Parciais que só declaram variáveis/mixins Sass (`settings/`, `tools/`) **não**
+são envolvidos em `@layer` — eles não emitem CSS.
+
+Como a ordem de precedência vem da ordem das camadas (não da ordem de
+`@use` no arquivo), um componente sempre perde para uma utility (`.fs-u-*`)
+mesmo que o componente seja `@use`'d depois — é o comportamento desejado.
+
+## Camadas de conteúdo
+
+### settings
+
+Define valores Sass usados em tempo de compilação: breakpoints, larguras de
+containers, escala de espaçamento, cores primitivas, tipografia, raios de
+borda. Esses arquivos não geram CSS diretamente e não entram em `@layer`.
+
+### tools
+
+Define mixins e funções Sass reutilizáveis (`media-breakpoint-up`,
+`focus-ring`, `truncate`, `color-contrast`, etc.). Também não geram CSS.
+
+### tokens
+
+Gera CSS Custom Properties públicas em `:root` (camada `tokens`), permitindo
+customização em CSS sem recompilar o framework. Nomes seguem o prefixo
+`--fs-*`, em 3 camadas:
+
+1. **Primitivo** (`settings/_colors.scss`, `settings/_spacing.scss`, etc.) —
+   valores Sass em tempo de compilação (`$color-blue-500`, `$radius-md`), não
+   emitidos diretamente como CSS.
+2. **Semântico** (`tokens/_root.scss` para as cores/raio/sombra "cruas" —
+   `--fs-color-primary`, `--fs-radius-md` — e `tokens/_semantic.scss` para
+   aliases nomeados por papel — `--fs-color-bg-surface`,
+   `--fs-color-text-primary`, `--fs-color-border-default`). Todo token
+   semântico é um `var()` de um token primitivo; nunca redeclara um valor.
+3. **Componente** (`--fs-btn-bg`, `--fs-btn-color`, `--fs-btn-border-color`
+   em `_buttons.scss`) — cada componente declara suas próprias custom
+   properties, com fallback para um token semântico/primitivo, e usa só essas
+   nas propriedades CSS reais. Isso permite sobrescrever a aparência de uma
+   instância específica (`.minha-classe { --fs-btn-bg: ...; }`) sem
+   `!important`. `_buttons.scss` é a referência do padrão — componentes mais
+   antigos ainda consomem tokens semânticos/primitivos diretamente e devem
+   migrar para o próprio padrão à medida que forem alterados.
+
+Primitivos de cor são gerados em OKLCH (`color.to-space(#hex, oklch)` a
+partir do hex histórico — ver comentário em `settings/_colors.scss`), com
+fallback sRGB automático: cada token de cor é declarado duas vezes em
+`tokens/_root.scss`/`themes/_dark.scss` — incondicionalmente com
+`rgb-fallback()` (gamut-mapeado), depois de novo dentro de
+`@supports (color: oklch(0% 0 0))` com o valor OKLCH nativo. Navegadores sem
+suporte a `oklch()` ignoram o bloco `@supports` inteiro e ficam só com o
+fallback. `tint-color()`/`shade-color()`/`color.mix()` usados para derivar
+tons (`--fs-alert-*-bg`, tema escuro) misturam com `$method: oklch` — rode
+`npm run contrast` (ver `docs/reference/contrast-report.md`) depois de mudar
+qualquer peso de mistura.
+
+### base
+
+Estilos globais mínimos de elementos (`body`, tipografia base). Camada
+`base` — deve permanecer pequena para evitar efeitos colaterais.
+
+### layout
+
+Base estrutural do framework: containers, rows, colunas, grid baseado em
+Flexbox. Camada `layout`.
+
+O gutter do grid (`.fs-row`/`.fs-col-*`) é implementado via padding + margin
+negativo controlados pelas CSS Custom Properties `--fs-gutter-x`/`--fs-gutter-y`
+(não via `gap` do flexbox), porque `gap` não é descontado da largura em
+porcentagem das colunas numeradas (`.fs-col-6`, `.fs-col-md-4`), o que causaria
+estouro de linha. As classes `.fs-u-g-*`/`.fs-u-gx-*`/`.fs-u-gy-*` (em `utilities/_spacing.scss`)
+controlam essas variáveis e só têm efeito dentro de uma `.fs-row`. Para `gap`
+literal em qualquer container flex/grid fora do sistema de colunas, use
+`.fs-u-gap-*`/`.fs-u-gap-x-*`/`.fs-u-gap-y-*`.
+
+### forms
+
+Agrupa estilos de formulários (linhas/colunas, labels, textos auxiliares,
+inputs, tamanhos de campo, estados de foco/desabilitado/leitura). Empacotado
+com `fokus-components`, camada `components`.
+
+### components
+
+Agrupa componentes prontos — um parcial `_nome.scss` por componente em
+`packages/fokus-components/scss/components/`, registrado em `_index.scss`.
+Camada `components`. Lista completa: ver o diretório do pacote (a lista muda
+com frequência conforme novos componentes entram).
+
+### utilities
+
+Classes utilitárias reutilizáveis (`.fs-u-*`): display, flex, spacing,
+shadow, typography, visibility. Camada `utilities` — sempre a última camada
+com regras do próprio framework, garantindo que uma utility sempre vença um
+componente. Utilitários devem ser previsíveis, pequenos e combináveis.
+
+### themes
+
+Variações globais de tema. O primeiro tema obrigatório é o dark mode via:
+
+```html
+<html data-theme="dark">
+```
+
+Camada `tokens` (só redefine `--fs-*`; não define novas regras de layout).
+
+## Convenções
+
+- Usar arquivos parciais com prefixo `_`.
+- Usar `@use` e `@forward`, evitando `@import` para módulos internos.
+- `@use`/`@forward` sempre no topo do arquivo, antes de qualquer `@layer`.
+- Manter `scss/fokus.scss` como único ponto de entrada público para o bundle completo.
+- Classes de componente: `.fs-*`; utilitários: `.fs-u-*`; estados controlados por
+  JS: `.is-*`; tokens CSS: `--fs-*`; atributos de auto-init: `data-fs`/
+  `data-fs-target`/`data-fs-dismiss`; eventos DOM customizados: `fs:*`.
+- Evitar estilos globais agressivos.
+- Preferir CSS Custom Properties para valores que usuários podem sobrescrever.
+- Centralizar valores de interação em tokens (`--fs-focus-*`, `--fs-transition-*`
+  e `--fs-ease-*`) em vez de repetir durações ou anéis de foco.
+- Todo componente interativo deve declarar foco visível, estado desabilitado e
+  comportamento compatível com `prefers-reduced-motion`.
+- Controles e superfícies devem declarar um `background-color` explícito por
+  meio de token semântico; `transparent` fica reservado a trilhas, backdrops
+  ou variantes cuja transparência faça parte da API visual.
+- Preferir variáveis Sass para valores usados em geração de classes.
+
+## Pipeline de Build
+
+O build (`npm run build`, `scripts/build.mjs`) compila SCSS para CSS via Dart
+Sass, aplica PostCSS com Autoprefixer (alvo em `.browserslistrc` — ver
+`docs/reference/browser-support.md`) e gera versões minificadas com source
+maps em `dist/css/`.
+
+Para preservar a distribuição em arquivos separados (`layout.css`, `forms.css`,
+`components.css`, `helpers.css`), existem pontos de entrada auxiliares em
+`scss/entries/`, cada um combinando `tokens` + `base` + `themes` com o módulo
+correspondente, garantindo que qualquer um dos arquivos possa ser usado de
+forma isolada (com variáveis, reset e dark mode funcionando). Esses arquivos
+são exclusivos do processo de build e não substituem `scss/fokus.scss` como
+entrada pública para quem deseja o bundle completo.
+
+`scss/fokus.scss` também é compilado diretamente para `dist/css/fokus.css`
+(+ `.min.css`), como opção de import único para quem não precisa da distribuição
+granular. É esse bundle que o campo `style` do `package.json` aponta por padrão.
+
+Os nomes em `scss/entries/` usam o sufixo `-entry` (ex: `layout-entry.scss`)
+para evitar colisão com os módulos de mesmo nome (`@use "layout"` dentro de
+`scss/layout.scss` causaria um loop de importação).
+
+Cada entry independente declara a ordem de `@layer` no início do seu CSS
+compilado (herdada de `tokens/_root.scss`, sempre o primeiro `@use`), então
+qualquer arquivo de `dist/css/` funciona isolado, com a cascata correta,
+mesmo carregado sozinho numa página.
+
+## Regra de Evolução
+
+Novos componentes devem seguir este fluxo:
+
+1. Criar `packages/fokus-components/scss/components/_nome-do-componente.scss`,
+   com o conteúdo CSS envolvido em `@layer components { }` (`@use` fica fora,
+   antes da camada).
+2. Adicionar o arquivo em `packages/fokus-components/scss/components/_index.scss`.
+3. Documentar a API de classes em Markdown.
+4. Adicionar exemplo em `mockup/` quando fizer sentido.

package/docs/reference/size-baseline.json

@@ -0,0 +1,34 @@
+{
+  "measuredAt": "2026-09-07T21:04:20.442Z",
+  "unit": "bytes",
+  "files": {
+    "css/layout.min.css": {
+      "bytes": 21560,
+      "gzipBytes": 4809
+    },
+    "css/forms.min.css": {
+      "bytes": 30769,
+      "gzipBytes": 6476
+    },
+    "css/components.min.css": {
+      "bytes": 83375,
+      "gzipBytes": 14496
+    },
+    "css/helpers.min.css": {
+      "bytes": 53574,
+      "gzipBytes": 9104
+    },
+    "css/fonts.min.css": {
+      "bytes": 1505,
+      "gzipBytes": 409
+    },
+    "css/fokus.min.css": {
+      "bytes": 144930,
+      "gzipBytes": 22544
+    },
+    "js/fokus.min.js": {
+      "bytes": 98921,
+      "gzipBytes": 21196
+    }
+  }
+}

package/docs/reference/stability.md

@@ -0,0 +1,89 @@
+# Estabilidade e roadmap
+
+Este documento define como o Fokus Styles evolui. A existência de um componente
+no repositório não significa que ele tenha o mesmo nível de maturidade do
+núcleo.
+
+## Direção estratégica
+
+O Fokus Styles está em fase de consolidação. A prioridade é tornar o núcleo CSS
+pequeno, previsível, acessível e fácil de adotar. Novos componentes só devem
+entrar no núcleo quando houver uso real, API documentada, testes funcionais,
+regressão visual e validação de acessibilidade.
+
+O objetivo não é competir pela maior quantidade de componentes, mas oferecer
+uma base confiável para páginas institucionais, sistemas administrativos e
+aplicações web construídas com HTML, CSS e JavaScript nativo.
+
+## Níveis de estabilidade
+
+### Núcleo essencial
+
+É o caminho recomendado para novos projetos e recebe prioridade de manutenção:
+
+- tokens, reset, temas e dark mode;
+- containers, grid e utilitários básicos;
+- tipografia, espaçamento e estados visuais;
+- botões, cards, alertas, badges e tabelas;
+- inputs, select, checkbox, radio e switch;
+- navbar, dropdown, tabs, accordion, modal, toast, paginação e breadcrumbs.
+
+Mudanças nesses recursos exigem revisão de compatibilidade, documentação de
+migração quando necessário e cobertura de testes correspondente.
+
+### Extensões de interface
+
+São componentes prontos e úteis, mas não bloqueiam o uso do núcleo:
+
+- Stack, Cluster, Sidebar e recursos avançados de layout;
+- Collapse, Offcanvas, Tooltip, Popover e Alert Dialog;
+- Stepper, Input Group, Empty State, Skeleton, Spinner e Progress;
+- Tag, Rating, Segmented Control, Timeline e upload básico.
+
+### Componentes avançados
+
+Atendem casos específicos e permanecem sob observação de uso e manutenção:
+
+- Combobox e Datepicker;
+- DataTable;
+- Tree View e Command Palette;
+- Carousel;
+- Upload avançado e integrações de gráficos.
+
+Esses recursos não devem ser usados como argumento para aumentar o escopo do
+núcleo sem evidência de necessidade recorrente.
+
+### Ecossistema opcional
+
+`fokus-styles/icons`, `fokus-styles/cli` e `fokus-styles/react` são subpaths
+opcionais do mesmo pacote. Eles devem
+seguir documentação, versionamento e testes próprios, sem tornar o pacote
+principal dependente de React, Sass, CLI ou bibliotecas de ícones.
+
+## Roadmap de consolidação
+
+1. Corrigir e uniformizar a documentação pública e os exemplos.
+2. Garantir que cada componente essencial tenha API, estados, acessibilidade,
+   tokens e exemplo mínimo documentados.
+3. Validar o núcleo em Chromium, Firefox e WebKit, além de testes manuais de
+   teclado e leitores de tela.
+4. Criar documentação visual com busca, exemplos executáveis e templates de
+   sistemas reais.
+5. Medir adoção e bugs antes de promover componentes avançados ao núcleo.
+
+## Critério para promover um componente
+
+Um componente avançado só deve ser promovido quando cumprir todos estes
+critérios:
+
+- necessidade recorrente em projetos reais;
+- API pública estável e consistente com `data-fs`, `fs:*` e `window.FokusStyles`;
+- documentação de anatomia, estados, tokens e teclado;
+- testes unitários, visuais e de acessibilidade;
+- comportamento verificado nos navegadores definidos pelo projeto;
+- impacto de bundle conhecido e registrado.
+
+## Regra para novas funcionalidades
+
+Antes de criar um novo componente, prefira compor recursos existentes. A
+adição deve resolver um problema recorrente, não apenas completar um catálogo.

package/docs/showcase.md

@@ -0,0 +1,25 @@
+# Showcase de produção
+
+> 🚧 **Em construção.** Esta página é um placeholder estrutural — ainda não
+> há casos de uso reais de terceiros usando o Fokus Styles em produção pra
+> citar aqui. Preencher com dados fictícios ou métricas inventadas seria
+> pior do que deixar isso em aberto.
+
+## O que vai entrar aqui
+
+Quando houver projetos reais usando o FokusStyles, cada entrada segue este
+formato:
+
+- **Nome do projeto/empresa** (com link, se público).
+- **Contexto**: que tipo de produto, desde quando usa o FokusStyles.
+- **Por que escolheram o FokusStyles**: motivação (bundle size, zero
+  dependências, dark mode nativo, etc.).
+- **Métricas**, quando o time autorizar compartilhar (tamanho de bundle
+  antes/depois de uma migração, tempo de desenvolvimento, etc.) — nunca
+  números estimados ou genéricos.
+
+## Quer aparecer aqui?
+
+Se você usa o Fokus Styles em produção e topa ser citado, abra uma
+[issue](https://github.com/jorgewreis/fokus-styles/issues) com o rótulo
+`showcase` — conte um pouco do seu caso de uso.

package/mockup/README.md

@@ -0,0 +1,41 @@
+# Laboratórios de componentes
+
+Os mockups são documentação viva: cada seção combina uma definição em
+português, contrato de acessibilidade, configurações suportadas, preview
+funcional e o HTML extraído do exemplo que está sendo executado. O markup não
+é mantido em duplicidade: o painel de código é sincronizado com o iframe de
+demonstração.
+
+| Laboratório | Componentes e fundamentos |
+|---|---|
+| [Fundamentos](foundations.html) | Layout, temas, ícones, divider e APIs JS compartilhadas. |
+| [Ações e feedback](feedback-actions.html) | Button, badge, alert, tag, empty state, skeleton, spinner e progress. |
+| [Formulários](forms.html) | Input, select, input group, escolhas, range, segmented, rating, data/hora, combobox e upload. |
+| [Navegação](navigation-disclosure.html) | Navbar, breadcrumb, pagination, accordion, tabs, collapse, stepper, nested menu e tree view. |
+| [Overlays](overlays-commands.html) | Dropdown, tooltip, hover card, popover, offcanvas, modal, alert dialog, command palette, toast e notification center. |
+| [Conteúdo e dados](content-data.html) | Card, tile, carousel, timeline, charts, table e DataTable. |
+
+## Leitura recomendada
+
+1. Abra o laboratório da família de componentes.
+2. Navegue pela âncora do componente e leia o contrato antes de copiar o
+   código.
+3. Interaja com o preview e use **Copiar código** para obter o markup que o
+   compõe.
+4. Consulte a página equivalente em [`docs/components/`](../docs/components/)
+   para a referência completa da API pública.
+
+## Integração e templates
+
+- [`kitchen-sink.html`](kitchen-sink.html) continua como smoke test compacto:
+  ele confere a convivência dos componentes, não substitui estes laboratórios.
+- [`templates/`](templates/README.md) contém páginas completas de produto e
+  aponta para os laboratórios sempre que um componente precisar de consulta
+  detalhada.
+
+## Fontes executáveis
+
+Os arquivos em `examples/` preservam a demonstração funcional de origem dos
+laboratórios. Eles não fazem parte da navegação editorial nem da descoberta
+automática de screenshots; existem para que cada seção tenha uma fonte de
+markup única e verificável.

package/mockup/assets/example-theme.css

@@ -0,0 +1,6 @@
+html[data-theme="dark"],
+html[data-theme="dark"] body {
+  min-height: 100%;
+  color: var(--fs-color-text);
+  background-color: var(--fs-color-surface);
+}

package/mockup/assets/example-theme.js

@@ -0,0 +1,9 @@
+// Os exemplos são carregados em iframes pelos laboratórios. O tema vem da
+// página-pai via query string, para que uma única ação altere toda a página.
+const exampleTheme = new URLSearchParams(window.location.search).get("theme");
+
+if (exampleTheme === "dark") {
+  document.documentElement.setAttribute("data-theme", "dark");
+} else {
+  document.documentElement.removeAttribute("data-theme");
+}