@brucesantos/design-space 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -6,6 +6,183 @@ Versionamento semântico. **Patch** para correção sem mudança de contrato,
6
6
  Mudança estrutural — pasta obrigatória nova, schema de cenário alterado — exige
7
7
  comando explícito e revisável, nunca merge silencioso.
8
8
 
9
+ ## 0.8.0 (2026-09-28)
10
+
11
+ **Major (incompatível).** Chrome novo, modelo de organização novo e a UI do
12
+ produto dentro de um `<iframe>`. Ver
13
+ `docs/decisions/0012-chrome-unico-telas-como-rotas-e-iframe.md`.
14
+
15
+ > **Primeira publicação depois da 0.6.0.** A 0.7.0 nunca foi publicada no npm:
16
+ > quem está em `^0.6.0` recebe as mudanças da 0.7.0 (acima, na seção dela) e as
17
+ > desta versão de uma vez. Leia os dois guias de migração, na ordem 0.7 → 0.8.
18
+
19
+ ### Removido
20
+
21
+ - **Módulos e jornadas:** `Module`, `Flow`, `FlowStep`, `ProductDefinition.modules`,
22
+ `ModuleNode`, `Registry.tree`, `Registry.orphans`, `Registry.treeFor`,
23
+ `Registry.orphansFor`, `Registry.module` e `Registry.flow`. A validação não
24
+ exige mais prefixo de módulo no id nem avisa quando falta; passos e
25
+ ramificações de jornada deixam de ser validados.
26
+ - **Home e palco inline:** `Home`, `HomeProps`, `Stage`, `StageProps`. A raiz
27
+ abre o primeiro item. `StageEmpty` continua exportado.
28
+ - **Rótulos:** os grupos `controls`, `inspector` e `home` e as chaves de fluxo e
29
+ de módulo em `sidebar` e `topbar` (`flowsTab`, `withoutModule`, `homeTitle`,
30
+ `toggleNav`, `panel`, `cleanReviewTitle`, `copyPrompt` de cenário…). Override
31
+ em `theme.labels` que declare esses grupos passa a ser erro de tipo.
32
+ - `buildHomeUrl`, `buildCleanReviewUrl`, `nextItemId` (eram exports internos do
33
+ shell, usados só em teste).
34
+
35
+ ### Adicionado
36
+
37
+ - **Telas e variações.** Uma tela é uma rota; as variações são os cenários cuja
38
+ `route` casa com o `path` (mesmo casamento e especificidade do roteador). Rota
39
+ sem cenário é tela com variação implícita "Padrão". `RouteDefinition.name` e
40
+ `RouteDefinition.description`. Nome da tela: `name` ?? título do primeiro
41
+ cenário ?? `path`.
42
+ - **Registry:** `screens`, `screen`, `screenForPath`, `screenOf`, `screensFor`
43
+ (com handoff), `searchScreens`, `searchComponents` (nome, descrição, grupo, id
44
+ e `source`, sem acento nem caixa), `componentsOfScreen`, `usagesOf`. Tipo
45
+ `ScreenNode`. `normalizeSearch` exportado.
46
+ - **`Scenario.components`**: ids de `ComponentPreview` usados na tela. Alimenta
47
+ "Componentes usados", o "Usado em" do componente e o "Copiar para o PR". Id
48
+ não registrado gera aviso.
49
+ - **`ComponentPreview.source`**: origem no sistema real, texto livre.
50
+ - **Chrome novo, preto e branco**, claro e escuro, sem cor de cliente e sem
51
+ logo. Seleção por tom (a cor do texto a 10%), grupos e abas em cápsula,
52
+ controles de 36px.
53
+ - Barra superior em três partes: o nome do produto e a versão do motor, com
54
+ link para o pacote; no centro, viewport (Celular 375, Tablet 768, Desktop
55
+ 1280, Ajustar), girar (só celular e tablet), zoom de 25% a 150% e revisão
56
+ limpa (`Shift` + `C`); à direita, copiar link, tema e o indicador de
57
+ diagnóstico. Em 100%, um viewport mais largo que a área encolhe até caber.
58
+ - Lateral esquerda: busca (`Cmd`/`Ctrl` + `K`) e as abas **Telas |
59
+ Componentes**, sempre visíveis; componentes agrupados por `group`, com
60
+ grupos recolhíveis.
61
+ - Lateral direita, sempre aberta com o chrome: filtro (`Cmd`/`Ctrl` + `F`)
62
+ e as abas **Variações | Informações**, com o botão **Copiar para o PR**.
63
+ - As duas laterais são redimensionáveis, e a largura é lembrada no navegador.
64
+ - **Quadro (`<iframe>`)**: a UI do produto roda na mesma origem e no mesmo
65
+ bundle, com `ds-frame=1`. A largura do viewport é a largura real da janela do
66
+ produto. Protocolo por `postMessage` validando origem e janela nos dois lados.
67
+ Exports `FRAME_PARAM` e `FRAME_ATTRIBUTE`; em `/testing`, `FRAME_SELECTOR`.
68
+ - **Estado na URL:** `zoom`, `rotate`, `tab` (aba do painel). `appearance` aceita
69
+ `dark` e `light`; sem ele, o tema segue a última escolha e, na falta dela, o
70
+ sistema. `ControlsState` ganha `zoom`, `rotated` e `panelTab`; tipo
71
+ `PanelTab`. `ZOOM_MIN`, `ZOOM_MAX`, `ZOOM_DEFAULT` e `clampZoom`.
72
+ - `useDesignSpaceState(registry, { frame })`; o retorno ganha `openScreen` e
73
+ `go`, e `openComponent` aceita `{ replace }`.
74
+ - **Validação de rotas:** `path` duplicado, `path` sem `/` inicial e `screen`
75
+ ausente são erro; `modules` ainda declarado vira aviso.
76
+
77
+ ### Alterado
78
+
79
+ - **`VIEWPORTS`**: `mobile` 375×812, `tablet` 768×1024, `desktop` 1280×800.
80
+ `custom` continua, só por URL (`viewport=custom&w=…`).
81
+ - **`ControlsState.chromeTheme`** fica `undefined` quando a URL não informa, em
82
+ vez de `dark`.
83
+ - **`scenariosForRoute`** devolve as variações da tela que renderiza o endereço,
84
+ pelo casamento de rota, e não mais cenários com o mesmo texto de caminho.
85
+ - **`validateScenario`**: id é minúsculo, kebab-case com pontos opcionais; não
86
+ precisa de prefixo.
87
+ - **`ProductDefinition.tagline`** continua no tipo, mas o chrome não o exibe.
88
+ - **CSS:** todos os seletores começam em `.ds-`; `.ds-root` agora define fundo,
89
+ fonte e cor e cobre a janela, porque o palco não é mais descendente dele. Os
90
+ tokens `--ds-*` foram todos renomeados para a paleta preto e branco.
91
+
92
+ ### Migração
93
+
94
+ 1. **Remova `modules`** da `ProductDefinition` (e os `flows` dentro dele). O
95
+ TypeScript aponta onde; se sobrar em JavaScript, o diagnóstico avisa.
96
+ 2. **Dê `name` às rotas** — é o nome da tela na lista. Opcionalmente, uma
97
+ `description`. Sem `name`, a tela usa o título do primeiro cenário da rota.
98
+ 3. **Ids de cenário continuam válidos.** O prefixo de módulo deixa de ter
99
+ significado, mas não precisa mudar: links antigos continuam abrindo.
100
+ 4. **Opcional:** liste em `components` de cada cenário os ids de componente que
101
+ a tela usa, e preencha `source` em cada `ComponentPreview`. É o que alimenta
102
+ "Componentes usados" e o "Copiar para o PR".
103
+ 5. **Troque container queries por media queries** onde elas existiam só porque
104
+ o palco não era uma janela. Dentro do quadro, `md:`/`lg:` respondem à largura
105
+ do viewport escolhido.
106
+ 6. **Testes de ponta a ponta:** a UI do produto está num iframe. Use
107
+ `page.frameLocator(FRAME_SELECTOR)` (de `@brucesantos/design-space/testing`)
108
+ para a UI e `page` para o chrome. Links do produto dentro do quadro navegam
109
+ sem recarregar e atualizam a URL do chrome.
110
+ 7. **Rótulos:** se `theme.labels` sobrescrevia `controls`, `inspector` ou `home`,
111
+ mova para `panel`, `info`, `diagnostics` e `shell`; o TypeScript aponta cada
112
+ chave. `EN_US_LABELS` já traz o dicionário novo completo.
113
+ 8. **CSS global do produto:** nada a fazer. O chrome define os próprios estilos
114
+ e ignora preflight e `body { … }` do produto. Se o produto dependia de algo
115
+ do chrome herdado no palco, isso acabou — o que é o objetivo.
116
+ 9. Links antigos com `module`, `flow`, `view`, `showPorted` ou parâmetros de
117
+ acessibilidade abrem sem erro: os parâmetros são ignorados.
118
+
119
+ ## 0.7.0 (2026-09-28) — não publicada
120
+
121
+ **Major (incompatível).** O motor deixa de impor acessibilidade e ciclo de vida
122
+ de cenário. Todo cenário registrado é simplesmente exibido. Ver
123
+ `docs/decisions/0011-revoga-a11y-e-ciclo-de-vida.md`.
124
+
125
+ ### Removido
126
+
127
+ - **Ciclo de vida do cenário:** `Scenario.status`, `Scenario.approvedAt`,
128
+ `ScenarioStatus`, `SCENARIO_STATUSES`, `ScenarioView`, `ControlsState.view` e
129
+ `showPorted`, a visão de referências portadas, a legenda e as contagens por
130
+ status na Home, na navegação e no Diagnóstico, os marcadores de status e os
131
+ parâmetros de URL `view` e `showPorted`. `Registry.byStatus` e
132
+ `Registry.coverage` saíram; `ScenarioQueryOptions` agora só tem `handoff`.
133
+ `useDesignSpaceState` não devolve mais `setScenarioView`. `Home` e `Sidebar`
134
+ perderam `view`, `onViewChange` e `showPorted`; `buildHomeUrl` perdeu o
135
+ parâmetro de visão.
136
+ - **Acessibilidade:** `Scenario.a11y`, `A11yContract`, `KeyboardCoverage`,
137
+ `ContrastTarget`, `ContrastPair`, `ProductTheme.contrastPairs`,
138
+ `ScenarioContext.a11y`, `ComponentPreviewProps.a11y`, todo `src/a11y/`
139
+ (`contrastRatio`, `checkContrastPair(s)`, `assertContrastPairs`,
140
+ `CONTRAST_THRESHOLDS`, `parseColor`, `flatten`, `relativeLuminance`,
141
+ `readCssVariable`, `computeRole`, `describeElement`, `shortSelector`,
142
+ `tabbableElements`, `useKeyboardMode` e tipos), `TabOrderOverlay`, o modo
143
+ teclado (atalho `Shift` + `K`), redução de movimento e ampliação de texto
144
+ (`TEXT_SCALES`, `keyboardMode`, `reducedMotion`, `textScale` e os parâmetros
145
+ `kb`, `motion`, `scale`), a aba Acessibilidade do Inspector.
146
+ `StageProps` ficou só com `viewport` e `children`.
147
+ - **Rótulos:** grupos `status`, `statusMeaning` e `keyboard`; exports
148
+ `STATUS_LABELS`, `STATUS_MEANING` e `KEYBOARD_LABELS`; as chaves de
149
+ referências portadas, aprovação, contraste e modo teclado em `sidebar`,
150
+ `controls`, `inspector` e `home`. Override em `theme.labels` que declare esses
151
+ grupos passa a ser erro de tipo.
152
+ - **`/testing`:** `scenariosUnderTest`, `keyboardScenarios` e a reexportação das
153
+ funções de contraste. Continuam `testOrigin`, `urlFor`, `pathFor`,
154
+ `scenarioUrl`, `assertValidProduct`, `validateProduct`, `hasErrors` e
155
+ `formatIssues`.
156
+
157
+ ### Alterado
158
+
159
+ - **`persona` é opcional em `Scenario`.** Cenário sem persona tem permissões
160
+ vazias, a menos que declare `permissions`. A validação só reclama de persona
161
+ inexistente quando ela é informada, e `scenarioUrl()` omite `persona` da URL
162
+ quando o cenário não declara uma.
163
+ - **Produto só de componentes é válido.** `routes` vazio só é erro quando há
164
+ cenários. Sem cenários e com `components`, a Home abre no catálogo de
165
+ componentes agrupado por `group`, e a navegação abre direto na lista de
166
+ componentes, sem aba de fluxos vazia.
167
+ - A Home sem cenário nem componente mostra um único estado vazio
168
+ (`home.noScenarios`); a navegação usa `sidebar.emptyScenarios`. Novo rótulo
169
+ `home.componentsLead`.
170
+
171
+ ### Migração
172
+
173
+ 1. Apague `a11y`, `status` e `approvedAt` de todos os cenários e
174
+ `theme.contrastPairs` da definição do produto.
175
+ 2. `persona` agora é opcional: mantenha onde ela decide permissões, remova onde
176
+ não acrescenta nada.
177
+ 3. Remova de `theme.labels` os grupos `status`, `statusMeaning` e `keyboard` e as
178
+ chaves listadas acima; o TypeScript aponta cada uma.
179
+ 4. Se os testes do produto usavam `scenariosUnderTest`, `keyboardScenarios` ou
180
+ as funções de contraste de `/testing`, troque por `product.scenarios` (ou um
181
+ filtro do próprio produto) e apague os testes de contraste e axe que
182
+ dependiam delas.
183
+ 5. Links antigos com `view=ported`, `showPorted=1`, `kb=1`, `motion=1` ou
184
+ `scale=…` continuam abrindo: os parâmetros são ignorados.
185
+
9
186
  ## 0.6.0 (2026-08-13)
10
187
 
11
188
  ### Adicionado
package/README.md CHANGED
@@ -1,9 +1,14 @@
1
1
  # @brucesantos/design-space
2
2
 
3
- Motor neutro do Bananas Design Space. Fornece o ambiente — navegação por cenário,
4
- deep links, controles de persona/dados/viewport/rede, painel de contexto e
5
- ferramentas de acessibilidade — sem impor nenhum componente visual, token ou
6
- identidade ao produto.
3
+ Motor neutro do Bananas Design Space. Fornece o ambiente de revisão — telas e
4
+ componentes à esquerda, variações e informações à direita, deep links, controles
5
+ de persona/rede/viewport/zoom e o texto pronto para o PR — sem impor nenhum
6
+ componente visual, token ou identidade ao produto.
7
+
8
+ O chrome é o mesmo para todos os produtos: preto e branco, claro e escuro, sem
9
+ cor de cliente. A UI do produto roda num `<iframe>` da mesma origem e do mesmo
10
+ bundle, com a largura do viewport escolhido: CSS isolado nos dois sentidos, e
11
+ media queries respondendo como em produção.
7
12
 
8
13
  ```bash
9
14
  pnpm add @brucesantos/design-space
@@ -23,11 +28,33 @@ export function App() {
23
28
  }
24
29
  ```
25
30
 
31
+ ## Telas e variações
32
+
33
+ **Uma tela é uma rota.** As **variações** de uma tela são os cenários cuja
34
+ `route` casa com o `path` dela — pelo mesmo casamento do roteador, então
35
+ `/requests/REQ-2043` é variação de `/requests/:id`, e `/requests/new` fica com a
36
+ rota literal. A ordem das telas é a de `routes`; a das variações, a de
37
+ `scenarios`. Rota sem cenário também é tela, aberta numa variação "Padrão".
38
+
39
+ ```ts
40
+ routes: [
41
+ { path: "/requests", screen: RequestList, name: "Fila de solicitações" },
42
+ {
43
+ path: "/requests/:id",
44
+ screen: RequestDetail,
45
+ name: "Detalhe da solicitação",
46
+ description: "Análise e decisão de uma solicitação.",
47
+ },
48
+ ],
49
+ ```
50
+
51
+ Sem `name`, a tela usa o título do primeiro cenário da rota e, na falta dele, o
52
+ `path`. Não existe módulo nem jornada (decisão 0012).
53
+
26
54
  ## O contrato de cenário
27
55
 
28
56
  Um cenário combina intenção, persona, permissões, pré-condições, dados, ações,
29
- regras e resultado esperado. É a unidade central: não é uma tela com dados
30
- diferentes.
57
+ regras e resultado esperado. O `title` é o nome da variação na lista.
31
58
 
32
59
  ```ts
33
60
  import type { Scenario } from "@brucesantos/design-space";
@@ -35,66 +62,54 @@ import type { Scenario } from "@brucesantos/design-space";
35
62
  export const approveBlocked: Scenario = {
36
63
  id: "requests.approve-blocked",
37
64
  title: "Aprovação bloqueada por falta de documento",
65
+ intent: "Verificar se a regra fica legível na tela.",
38
66
  route: "/requests/REQ-2043",
39
67
  persona: "approver",
40
68
  permissions: ["requests.read", "requests.approve"],
41
69
  fixture: "request-without-document",
42
70
  rules: ["approval-needs-document"],
43
- a11y: {
44
- keyboard: "full",
45
- contrast: "AA",
46
- announces: ["request.status", "approval.result"],
47
- },
48
- status: "approved",
49
- approvedAt: {
50
- url: "https://review.example.test/commit/0123456/requests/REQ-2043",
51
- commit: "0123456789abcdef",
52
- date: "2026-08-13",
53
- },
71
+ expected: ["O motivo do bloqueio aparece junto da ação indisponível."],
72
+ components: ["actions.primary-button", "feedback.notice"],
54
73
  };
55
74
  ```
56
75
 
57
76
  O vocabulário do exemplo é genérico de propósito: o domínio é do produto, nunca do
58
77
  motor.
59
78
 
60
- `a11y` é obrigatório. Acessibilidade é campo do contrato, não auditoria de fim de
61
- projeto: um cenário de ação bloqueada em que o bloqueio não é anunciado para leitor
62
- de tela está incompleto, não está pronto para aprovação.
63
-
64
- ### Ciclo de vida
65
-
66
- O estado diz o que o cenário representa; importar uma tela existente não a torna
67
- proposta nem compromisso de implementação.
68
-
69
- | Valor | Rótulo padrão | Significado |
70
- | --- | --- | --- |
71
- | `ported` | Portado — não validado | Veio do sistema existente, mas não foi validado e não representa compromisso de implementação. |
72
- | `proposed` | Proposta | Exploração ainda não aprovada. |
73
- | `in-review` | Em revisão | Aberto para validação de design, negócio ou cliente. |
74
- | `approved` | Aprovado | Referência autorizada, registrada por URL de commit. |
75
- | `in-implementation` | Em implementação | Ligado a um trabalho ativo de engenharia. |
76
- | `implemented` | Implementado | Disponível no produto real e validado. |
77
- | `superseded` | Superado | Mantido para histórico ou substituído por outra decisão. |
78
-
79
- `approved` só representa uma aprovação completamente registrada quando
80
- `approvedAt` contém a URL imutável do commit, o SHA e a data. Sem esse registro, o
81
- Inspector mostra **Aprovado — registro pendente** e o validador emite o warning
82
- “Aprovação incompleta”; a referência não é apresentada como plenamente
83
- autorizada.
84
-
85
- `scenariosUnderTest()` inclui por padrão apenas `approved`, `in-implementation` e
86
- `implemented`. Cenários `ported` ficam fora até serem promovidos, mas podem ser
87
- selecionados explicitamente pelo segundo argumento.
88
-
89
- Na interface, `ported` vive numa coleção separada. **Trabalho ativo** mostra apenas
90
- cenários não portados; **Referências portadas** mostra apenas portados. A entrada
91
- textual “Ver N referências portadas” troca de coleção e grava `view=ported` na URL.
92
- Busca, home, módulos e contagens seguem a visão atual, sem renderizar módulos
93
- vazios. Um deep link direto para um portado infere a visão de referências mesmo
94
- sem o parâmetro. Links 0.4.0 com `showPorted=1` continuam sendo lidos e são
95
- normalizados para a nova visão. O diagnóstico sempre avalia o catálogo completo.
96
- A home também apresenta uma legenda estável com a cor, o rótulo e o significado
97
- de cada status; os chips de contagem continuam mostrando apenas a visão atual.
79
+ - `id` é qualquer id estável, minúsculo, em kebab-case com pontos opcionais.
80
+ Precisa ser único; não precisa de prefixo.
81
+ - `persona` é opcional. Cenário sem persona tem permissões vazias, a menos que
82
+ declare `permissions`.
83
+ - `components` lista os ids de `ComponentPreview` usados na tela. Alimenta
84
+ "Componentes usados", o "Usado em" de cada componente e o "Copiar para o PR".
85
+
86
+ ## O chrome
87
+
88
+ | Região | Conteúdo |
89
+ | --- | --- |
90
+ | Barra superior | Nome do produto; viewport (Celular 375, Tablet 768, Desktop 1280, Ajustar), girar, zoom 25–150%, copiar link, revisão limpa, tema, painel e — quando a validação tem algo a dizer — o indicador de diagnóstico. |
91
+ | Esquerda | **Telas** e **Componentes**, com contagem e busca sem acento nem caixa (nome, descrição, grupo, id e `source`). Componentes agrupados por `group`. Aba vazia some. Redimensionável. |
92
+ | Centro | O quadro do produto no tamanho do viewport, com zoom só de visualização. |
93
+ | Direita | **Variações** (cenários da tela ou fixtures do componente, mais persona e rede) e **Informações** (rota, intenção, pré-condições, ações, comportamento esperado, regras, componentes usados e **Copiar para o PR**). Redimensionável. |
94
+
95
+ Sem Home: a raiz abre a primeira tela na primeira variação ou, sem telas, o
96
+ primeiro componente. O tema segue o sistema, e a troca é lembrada.
97
+
98
+ ### Copiar para o PR
99
+
100
+ Gera markdown com o nome da tela, um link absoluto por variação (com o link do
101
+ deployment e o commit quando o produto informa), a tabela componente → origem e
102
+ o comportamento esperado de cada variação.
103
+
104
+ ### O quadro
105
+
106
+ O chrome renderiza `<iframe data-ds-frame>` apontando para o mesmo endereço com
107
+ `ds-frame=1`. Nesse modo, `<DesignSpace>` renderiza **só** o wrapper do produto e
108
+ a tela ou o preview. Trocar variação, persona ou rede vai por `postMessage`, sem
109
+ recarregar; trocar de tela ou de componente troca o endereço do quadro sem criar
110
+ entrada no histórico. Navegação feita pela UI do produto (`context.navigate`,
111
+ `openScenario` ou um link comum) volta para a URL do chrome. Os dois lados só
112
+ aceitam mensagem da mesma origem e da janela esperada.
98
113
 
99
114
  ## A URL é o estado
100
115
 
@@ -105,21 +120,19 @@ rede declarados no cenário.
105
120
  | Parâmetro | Efeito |
106
121
  | --- | --- |
107
122
  | `scenario` | Cenário ativo. Define os padrões dos demais. |
108
- | `view=ported` | Abre a coleção de referências portadas. Omitido significa trabalho ativo. |
109
123
  | `component` | Referência ativa no catálogo visual do produto. |
110
124
  | `persona` | Troca o papel e as permissões. |
111
125
  | `fixture` | Troca a fixture global do cenário ou a fixture local do componente ativo. |
112
- | `showPorted=1` | Compatibilidade de leitura com links 0.4.0; equivale a `view=ported`. |
113
126
  | `network` | `success`, `loading`, `empty`, `error`, `slow`. |
114
- | `viewport` | `fit`, `mobile`, `tablet`, `desktop`, `custom`. |
127
+ | `viewport` | `fit`, `mobile`, `tablet`, `desktop`; `custom` para links antigos. |
115
128
  | `w` | Largura, quando `viewport=custom`. |
129
+ | `rotate=1` | Troca largura e altura do viewport. |
130
+ | `zoom` | Zoom da visualização, 25–150. Omitido em 100. |
116
131
  | `theme`, `locale`, `source` | Variações declaradas pelo produto. |
117
- | `appearance` | Aparência do chrome: omitido para dark, `light` para modo claro. |
132
+ | `appearance` | Tema do chrome, `light` ou `dark`. Omitido: última escolha ou o sistema. |
118
133
  | `chrome=0` | Revisão limpa: oculta o chrome do ambiente. |
119
- | `kb=1` | Modo teclado, com ordem de tabulação evidenciada. |
120
- | `motion=1` | Movimento reduzido no palco. |
121
- | `scale` | Ampliação de texto: `1`, `1.25`, `1.5`, `2`. |
122
- | `panel=0` | Oculta o painel de contexto. |
134
+ | `panel=0` | Oculta o painel direito. |
135
+ | `tab=info` | Abre o painel direito em Informações. |
123
136
  | `handoff=1` | Ativa um recorte explícito de revisão/handoff. |
124
137
  | `allowScenario` | Cenário permitido; pode ser repetido e autoriza também a rota do cenário. |
125
138
  | `allowRoute` | Padrão de rota permitido, como `/requests/:id`; pode ser repetido. |
@@ -128,9 +141,10 @@ rede declarados no cenário.
128
141
  ## Handoff focado por URL
129
142
 
130
143
  O handoff é uma allowlist transportada junto dos demais controles. Ela filtra
131
- Home, navegação, busca, flows, referências portadas e componentes. A raiz abre a
132
- Home já filtrada; uma tentativa de abrir cenário, rota ou componente fora da
133
- lista mostra um bloqueio claro sem montar a tela solicitada.
144
+ telas, variações, busca e componentes. A raiz abre o primeiro item permitido;
145
+ uma tentativa de abrir cenário, rota ou componente fora da lista mostra um
146
+ bloqueio claro no quadro, sem montar a tela solicitada. Links internos da UI do
147
+ produto carregam o recorte.
134
148
 
135
149
  ```ts
136
150
  import {
@@ -166,23 +180,18 @@ continuam no navegador. Preview público que precisa ocultar de fato o restante
166
180
  produto exige build separado para o recorte ou autenticação/autorização no
167
181
  produto que publica o preview.
168
182
 
169
- ### Escopo no Inspector
170
-
171
- Na aba Cenário, **Dados desta tarefa** reúne situação, reprodução, regras,
172
- critérios e aprovação; **Contexto herdado do produto e da persona** reúne objetivo
173
- e permissões efetivas. Em Acessibilidade, o contrato da tarefa, a inspeção da tela
174
- atual e os pares globais do produto têm agrupamentos próprios. Diagnóstico
175
- continua deliberadamente geral e identifica que avalia o catálogo inteiro,
176
- inclusive fora do handoff.
183
+ O indicador de diagnóstico continua deliberadamente geral: avalia o catálogo
184
+ inteiro, inclusive fora do handoff.
177
185
 
178
186
  ## API
179
187
 
180
188
  ### Shell
181
189
 
182
- - `DesignSpace` — o ambiente completo.
183
- - `Home` — mapa de situações, usado na raiz.
184
- - `Stage`, `StageEmpty`, `TabOrderOverlay` — partes do palco, expostas para casos
185
- fora do padrão.
190
+ - `DesignSpace` — o ambiente completo: chrome no documento de cima, UI do
191
+ produto no quadro.
192
+ - `StageEmpty` — estado vazio neutro, para `notFound` e casos fora do padrão.
193
+ - `FRAME_PARAM`, `FRAME_ATTRIBUTE` — o parâmetro do modo quadro e o atributo do
194
+ `<iframe>`.
186
195
 
187
196
  ### Rótulos do chrome
188
197
 
@@ -192,9 +201,9 @@ não for declarado fica no padrão.
192
201
  ```ts
193
202
  theme: {
194
203
  labels: {
195
- status: { approved: "Approved", "in-review": "In review" },
204
+ network: { success: "Success", error: "Error" },
196
205
  topbar: { copyLink: "Copy link" },
197
- home: { lead: (total) => `${total} scenarios, each one a link.` },
206
+ info: { copyForPr: "Copy for PR" },
198
207
  },
199
208
  }
200
209
  ```
@@ -205,7 +214,7 @@ theme: {
205
214
  - `useLabels()` — os rótulos resolvidos, dentro do chrome.
206
215
  - `Labels`, `LabelsOverride` — os tipos.
207
216
 
208
- Rótulo de **produto** continua vindo do produto: nome de módulo, título de cenário,
217
+ Rótulo de **produto** continua vindo do produto: nome de tela, título de cenário,
209
218
  nome de persona, rótulo de fixture.
210
219
 
211
220
  Para usar o chrome integralmente em en-US:
@@ -224,28 +233,34 @@ const product = {
224
233
 
225
234
  ### Aparência do chrome
226
235
 
227
- O seletor na topbar alterna entre dark e light sem alterar tokens ou tema da UI
228
- do produto. A escolha é serializada como `?appearance=light`, então links copiados
229
- e a revisão limpa preservam a aparência escolhida.
236
+ Preto e branco, igual em todo produto. O botão de tema alterna claro e escuro sem
237
+ tocar na UI do produto; a escolha vai para `?appearance=` e fica lembrada no
238
+ navegador. Sem escolha, vale o `prefers-color-scheme` do sistema. Não existe
239
+ tema, cor ou logo por produto.
230
240
 
231
241
  ### Registry e validação
232
242
 
233
- - `createRegistry(product)` — índice consultável: busca por vocabulário de
234
- negócio, árvore de módulos, cobertura por status.
235
- - `activeScenarios()`, `treeFor()`, `orphansFor()`, `search()` e `coverage()` —
236
- consultam trabalho ativo por padrão e aceitam `{ view: "ported" }` para a
237
- biblioteca de referências. `{ includePorted: true }` permanece disponível para
238
- diagnóstico e consultas do catálogo completo. `tree` e `issues` continuam
239
- completos. Todas aceitam também `{ handoff }`; `componentsFor(handoff)` aplica
240
- o mesmo recorte ao catálogo visual.
243
+ - `createRegistry(product)` — índice consultável.
244
+ - `screens`, `screen(id)`, `screenForPath(path)`, `screenOf(scenario)` — telas
245
+ (`ScreenNode`) e suas variações.
246
+ - `screensFor({ handoff })`, `activeScenarios()`, `search()`,
247
+ `searchScreens()`, `searchComponents()`, `componentsFor(handoff)` — aplicam o
248
+ recorte; a busca não diferencia acento nem caixa (`normalizeSearch`).
249
+ - `componentsOfScreen(screen)`, `usagesOf(componentId)` — componentes de uma
250
+ tela e telas de um componente, a partir de `Scenario.components`.
241
251
  - `validateProduct(product)` / `validateScenario(scenario)` — validação em runtime
242
- do contrato. Pega fixture, persona, regra ou rota inexistente, que o TypeScript
243
- não alcança.
252
+ do contrato. Pega fixture, persona, regra ou rota inexistente, rota duplicada,
253
+ id duplicado e componente citado sem registro — o que o TypeScript não
254
+ alcança. `routes` vazio só é erro quando há cenários, então um produto que é
255
+ só catálogo de componentes é válido.
244
256
 
245
257
  ### Catálogo de componentes
246
258
 
247
- O catálogo é opcional. O motor fornece navegação, busca e deep link; cada preview
248
- continua sendo UI do produto:
259
+ O motor fornece navegação, busca e deep link; cada preview continua sendo UI do
260
+ produto. Um produto pode ser só catálogo: com `scenarios`, `fixtures` e `routes`
261
+ vazios, a aba Telas some e a raiz abre o primeiro componente. As **variações** de
262
+ um componente são as `fixtures` dele; `source` diz de onde ele vem no sistema
263
+ real.
249
264
 
250
265
  ```tsx
251
266
  type ButtonData = {
@@ -259,7 +274,6 @@ function PrimaryButtonPreview({
259
274
  viewport,
260
275
  themeMode,
261
276
  locale,
262
- a11y,
263
277
  }: ComponentPreviewProps<ButtonData>) {
264
278
  return (
265
279
  <button disabled={data?.disabled} data-viewport={viewport.id}>
@@ -276,6 +290,7 @@ const product: ProductDefinition = {
276
290
  name: "Botão primário",
277
291
  group: "Ações",
278
292
  description: "Ação principal da página",
293
+ source: "components/button.ex → button/1",
279
294
  preview: PrimaryButtonPreview,
280
295
  defaultFixture: "default",
281
296
  fixtures: [
@@ -304,10 +319,9 @@ const product: ProductDefinition = {
304
319
  Abrir o exemplo produz
305
320
  `?component=actions.primary-button&fixture=default`; trocar os dados para o
306
321
  estado desabilitado produz
307
- `?component=actions.primary-button&fixture=disabled`. O seletor só aparece quando
308
- o componente declara fixtures. Se a URL pedir uma fixture inexistente, o preview
309
- usa `defaultFixture` (ou a primeira fixture) e o painel nomeia o fallback; a URL
310
- inválida não é descartada silenciosamente.
322
+ `?component=actions.primary-button&fixture=disabled`. Se a URL pedir uma fixture
323
+ inexistente, o preview usa `defaultFixture` (ou a primeira fixture) e o painel
324
+ nomeia o fallback; a URL inválida não é descartada silenciosamente.
311
325
 
312
326
  `ComponentPreview`, `ComponentPreviewFixture` e `ComponentPreviewProps` são os
313
327
  tipos públicos. Um preview 0.3.0 sem props continua compatível:
@@ -342,7 +356,7 @@ omite branch e commit.
342
356
  consome.
343
357
  - `scenarioUrl(scenario, options)` — URL absoluta reproduzível.
344
358
  - `componentUrl(component, options)` — URL absoluta do componente com sua fixture.
345
- - `commitUrl(scenario, { template })` — URL imutável para registrar aprovação. O
359
+ - `commitUrl(scenario, { template })` — URL imutável do cenário num commit. O
346
360
  template é do produto, com `{commit}` ou `{shortCommit}`.
347
361
 
348
362
  ### Dados
@@ -351,15 +365,6 @@ omite branch e commit.
351
365
  - `createHttpAdapter(options)` — adapter REST/GraphQL com fallback para fixture.
352
366
  - `useScenarioData(...)` — resolução do cenário ativo pelo adapter selecionado.
353
367
 
354
- ### Acessibilidade
355
-
356
- - `contrastRatio(fg, bg)`, `checkContrastPairs(pairs)`, `assertContrastPairs(pairs)`
357
- — razão de contraste do WCAG 2.x, com composição de alfa sobre o fundo.
358
- `assertContrastPairs` falha o build a partir de um teste do produto.
359
- - `describeElement(el)` — papel, nome acessível, origem do nome e estados.
360
- - `tabbableElements(root)` — ordem de tabulação real.
361
- - `useKeyboardMode(enabled, ref)` — foco observado e ordem de tabulação medida.
362
-
363
368
  ### Testes
364
369
 
365
370
  `@brucesantos/design-space/testing` — entrypoint separado, fora do bundle do
@@ -370,31 +375,41 @@ preview.
370
375
  - `testOrigin(fallback)` — lê `PREVIEW_URL` quando existe um ambiente publicado
371
376
  para testar; sem ela, o Playwright roda contra o dev server local.
372
377
  - `assertValidProduct(product)` — falha o teste quando o contrato tem erro.
373
- - `scenariosUnderTest(product)`, `keyboardScenarios(product)` — recortes para
374
- parametrizar jornadas.
378
+ - `FRAME_SELECTOR` — o seletor do quadro. A UI do produto está num iframe:
379
+
380
+ ```ts
381
+ await page.goto(pathFor(scenario));
382
+ const app = page.frameLocator(FRAME_SELECTOR);
383
+ await expect(app.getByRole("heading", { name: "Fila" })).toBeVisible();
384
+ await expect(page).toHaveURL(/scenario=/); // o chrome fica em `page`
385
+ ```
375
386
 
376
387
  ## Atalhos
377
388
 
378
389
  | Atalho | Efeito |
379
390
  | --- | --- |
380
- | `Command/Ctrl` + `K` ou `F` | Foco na busca da lateral |
381
- | `↑` / `↓` | Percorrer resultados filtrados |
382
- | `Shift` + `K` | Modo teclado |
383
- | `Shift` + `P` | Painel de contexto |
391
+ | `Command/Ctrl` + `K` | Foco na busca da lateral |
392
+ | `Shift` + `C` | Revisão limpa: esconde e mostra o chrome |
393
+ | `Command/Ctrl` + `F` | Foco no filtro do painel direito |
394
+
395
+ Os três funcionam também com o foco dentro do quadro; `Shift` + `C`, fora de
396
+ campos de texto.
384
397
 
385
398
  ## Créditos
386
399
 
387
- Os ícones dos presets de viewport são derivados do
388
- [Lucide](https://lucide.dev/), disponibilizado sob licença MIT. Obrigado às
389
- pessoas mantenedoras e contribuidoras do projeto. Os SVGs necessários são
390
- incorporados ao motor, portanto não existe dependência de runtime do Lucide.
400
+ Os ícones do chrome seguem o traço do [Lucide](https://lucide.dev/),
401
+ disponibilizado sob licença MIT. Obrigado às pessoas mantenedoras e
402
+ contribuidoras do projeto. Os SVGs são incorporados ao motor, portanto não existe
403
+ dependência de runtime do Lucide.
391
404
 
392
405
  ## Fronteira
393
406
 
394
407
  O motor **não** contém e não deve conter: componente visual, token, tipografia,
395
408
  cor, ícone, persona de domínio, fixture, regra de negócio ou conteúdo de cliente.
396
409
  Isso é exclusivo de cada produto — e é o que permite que dois produtos sobre o
397
- mesmo motor continuem parecendo produtos distintos.
410
+ mesmo motor continuem parecendo produtos distintos. O chrome em preto e branco é
411
+ ferramenta, não identidade: a identidade do cliente fica inteira dentro do
412
+ quadro.
398
413
 
399
414
  Três coisas que também não pertencem ao motor, cada uma travada por teste:
400
415
  provedor de hospedagem, texto visível fixo em componente do chrome e nome de
@@ -2,8 +2,6 @@ import { ControlsState } from '../types/index.js';
2
2
  /** Nomes curtos: a URL é colada em Slack, em ticket e em thread de revisão. */
3
3
  export declare const PARAM: {
4
4
  readonly scenario: "scenario";
5
- readonly view: "view";
6
- readonly showPorted: "showPorted";
7
5
  readonly component: "component";
8
6
  readonly persona: "persona";
9
7
  readonly fixture: "fixture";
@@ -15,10 +13,10 @@ export declare const PARAM: {
15
13
  readonly dataSource: "source";
16
14
  readonly chromeTheme: "appearance";
17
15
  readonly chrome: "chrome";
18
- readonly keyboardMode: "kb";
19
- readonly reducedMotion: "motion";
20
- readonly textScale: "scale";
21
16
  readonly inspector: "panel";
17
+ readonly panelTab: "tab";
18
+ readonly zoom: "zoom";
19
+ readonly rotated: "rotate";
22
20
  };
23
21
  /**
24
22
  * Serializa um valor de controle para a query string.