@etus/seven-skill 0.1.0-beta.3 → 0.1.0-beta.4

package/docs/detector-rules.md

@@ -1,6 +1,6 @@
 # Catálogo de regras do detector Seven
 
-Referência canônica das 35 regras do detector determinístico `@etus/seven-skill`
+Referência canônica das 68 regras do detector determinístico `@etus/seven-skill`
 (`npx seven detect`). Cada regra tem um ID estável, uma categoria, a
 justificativa de design, um exemplo errado/certo e a referência ao documento
 do design system que a fundamenta.
@@ -14,9 +14,9 @@ verdade — atualize este doc.
 
 - **Categoria** — `quality` (drift de design real, problema de a11y) ou `slop`
   (tell de UI gerada por IA, no sabor Seven).
-- **Engines** — todas as 35 regras rodam nos três engines: `regex` (arquivos
-  de código), `static-html` (arquivos HTML, com a cascata CSS resolvida) e
-  `browser` (URLs vivas via Puppeteer, com `getComputedStyle` real).
+- **Engines** — regras de fonte usam `regex`; HTML pode usar a cascata
+  `static-html`; geometria, erros de script e valores efetivamente renderizados
+  usam `browser` (URLs vivas via Puppeteer). O registry declara o suporte por regra.
 - **Referência** — o documento em `source/reference/` que documenta a regra
   de design para os agentes de IA. É onde a regra "vive" como guideline.
 - **Exit codes** — `seven detect` sai com `0` limpo, `2` com findings, `1`
@@ -40,7 +40,7 @@ Algumas regras pulam código que legitimamente carrega o padrão:
 
 ## Grounding — token vs heurística
 
-Cada uma das 35 regras tem um veredito de grounding, inspecionável via
+Cada uma das 68 regras tem um veredito de grounding, inspecionável via
 `getRuleGrounding(id)` no registry:
 
 - **`token`** — os dados da regra vêm do snapshot de `@etus/tokens`
@@ -51,9 +51,10 @@ Cada uma das 35 regras tem um veredito de grounding, inspecionável via
   CSS/tooling, um padrão estrutural ou um standard de a11y que nenhum token
   define. `heuristic` é um veredito deliberado, não uma regra inacabada.
 
-**8 regras token-grounded:** `non-inter-font`, `hardcoded-color-not-token`,
+**12 regras token-grounded:** `non-inter-font`, `hardcoded-color-not-token`,
 `raw-tailwind-palette-color`, `pure-black-or-white`, `tiny-text`,
-`radius-mixed-scales`, `pill-on-button`, `bounce-easing`. As outras 27 são
+`radius-mixed-scales`, `pill-on-button`, `bounce-easing`, `design-system-font`,
+`design-system-color`, `design-system-radius` e `design-system-font-size`. As outras 55 são
 heurísticas — o veredito honesto da auditoria: nem toda regra de design tem
 um token que a informe (em-dash, vocabulário pt-PT, ratio de contraste WCAG,
 mecânica do Lightning CSS, geometria de a11y).
@@ -148,7 +149,7 @@ o estilo simplesmente não aplica e não há erro.
 
 ### 5. `missing-length-type-hint` · `quality`
 
-**O que detecta** — um `text-[var(--*)]` arbitrário que resolve para um length
+**O que detecta** — uma utilidade arbitrária de texto, baseada em variável CSS, que resolve para um length
 (font-size) sem o hint `length:`.
 
 **Justificativa** — mesma armadilha do Lightning CSS da regra 4, no eixo de
@@ -165,7 +166,7 @@ tamanho de fonte. `text-[var(--x)]` sem hint é dropado.
 
 ### 6. `leading-none-with-length-var` · `quality`
 
-**O que detecta** — `leading-none` combinado com `text-[length:var(--*)]` na
+**O que detecta** — `leading-none` combinado com uma utilidade de texto tipada como length na
 mesma lista de classes.
 
 **Justificativa** — no Tailwind v4 essa combinação zera a `line-height` (vira
@@ -235,11 +236,80 @@ puros leem como duros e não-refinados; o ramp tintado dá profundidade.
 
 ---
 
-## Regras invertidas / retunadas do impeccable (10-12)
+## Regras de integridade e runtime (10-21)
+
+Estas regras preservam o principal ganho operacional portado do Impeccable:
+validar o que realmente renderizou e comparar valores contra o release Seven
+instalado, sem criar uma paleta paralela no projeto consumidor.
+
+### 10. `broken-image` · `quality`
+
+Detecta `<img>` sem fonte, com placeholder ou que termina carregada com
+`naturalWidth === 0`. Imagens de produto precisam de asset real, dimensões,
+texto alternativo útil e fallback.
+
+### 11. `script-error` · `quality`
+
+Captura `pageerror` antes do carregamento da URL. Um erro de parse ou exceção
+de runtime pode inutilizar interações e esconder conteúdo; por isso bloqueia o check.
+
+### 12. `content-hidden-at-rest` · `quality`
+
+Faz um reveal sweep limitado e mede texto que continua em `opacity: 0`,
+`visibility: hidden` ou `content-visibility: hidden`. Dispara quando mais de
+30% e pelo menos 150 caracteres relevantes continuam invisíveis.
+
+### 13. `edge-flush-cards` · `quality`
+
+Mede cards arredondados em scrollers horizontais e aponta a perda do gutter
+no início do painel, que corta a borda e o raio do card.
+
+### 14. `text-occlusion` · `quality`
+
+Amostra a geometria de texto visível com `elementFromPoint` e detecta quando
+uma camada opaca não relacionada cobre materialmente as palavras.
+
+### 15. `heading-rhythm` · `quality`
+
+Compara a distância renderizada acima e abaixo de `h2` a `h6`. Um heading
+deve se ligar ao conteúdo que introduz, não ao bloco anterior.
+
+### 16. `text-overflow` · `quality`
+
+Compara `scrollWidth` e `clientWidth` do elemento que possui texto direto,
+ignorando regiões com scroll deliberado. Reporta spill de pelo menos 16px.
+
+### 17. `clipped-overflow-container` · `quality`
+
+Detecta um container `hidden`/`clip` que corta um filho absoluto funcional,
+como menu, tooltip ou popover. O check usa fonte e geometria renderizada.
+
+### 18. `design-system-font` · `quality`
+
+Compara a família renderizada com a lista de fontes do snapshot exato de
+`@etus/tokens`: Inter para produto e JetBrains Mono para código/dados.
+
+### 19. `design-system-color` · `quality`
+
+Resolve as variáveis de cor Seven no tema ativo e compara texto e superfícies
+renderizados. Literais equivalentes continuam sendo pegos no scan de fonte.
+
+### 20. `design-system-radius` · `quality`
+
+Compara raios de fonte e runtime com as escalas de componente, superfície e
+pill derivadas do release Seven instalado.
+
+### 21. `design-system-font-size` · `quality`
+
+Compara tamanhos tipográficos de fonte e runtime com o ramp exato de Seven.
+
+---
+
+## Regras invertidas / retunadas do impeccable (22-24)
 
 Regras do impeccable que existem no Seven mas com semântica adaptada.
 
-### 10. `side-stripe-border` · `slop`
+### 22. `side-stripe-border` · `slop`
 
 **O que detecta** — uma `border-left`/`border-right` mais grossa que 1px usada
 como stripe de acento colorido. (Funde as regras `side-tab` e
@@ -260,7 +330,7 @@ gerada por IA. Seven carrega hierarquia com borda completa de 1px
 dispara quando há classe de cor acentuada; um `border-l-2` neutro é um
 divisor estrutural, não um stripe.*
 
-### 11. `gradient-text-decorative` · `slop`
+### 23. `gradient-text-decorative` · `slop`
 
 **O que detecta** — texto com gradiente (`background-clip: text` +
 `linear-gradient`).
@@ -277,7 +347,7 @@ cor sólida do ramp OKLCH; ênfase vem de peso e escala, não de gradiente.
 
 **Referência** — `source/reference/color-and-contrast.md`.
 
-### 12. `shadows-not-borders` · `slop`
+### 24. `shadows-not-borders` · `slop`
 
 **O que detecta** — um box-shadow colorido e borrado em superfície escura (o
 "dark glow" da IA), ou um shadow fazendo o papel de chrome de card.
@@ -296,11 +366,11 @@ reservado para overlays (modais, dropdowns, popovers) e o plate do logo.
 
 ---
 
-## Regras universais de qualidade / a11y (13-29)
+## Regras universais de qualidade / a11y (25-41)
 
 Boas práticas de design e acessibilidade que valem para qualquer UI.
 
-### 13. `low-contrast` · `quality`
+### 25. `low-contrast` · `quality`
 
 **O que detecta** — texto que não atinge o contraste WCAG 2.1 AA (4.5:1 corpo,
 3:1 texto grande).
@@ -313,7 +383,7 @@ em corpo; use `var(--foreground)`.
 
 **Referência** — `source/reference/color-and-contrast.md`.
 
-### 14. `gray-on-color` · `quality`
+### 26. `gray-on-color` · `quality`
 
 **O que detecta** — texto cinza sobre fundo colorido.
 
@@ -329,7 +399,7 @@ próprio matiz do fundo, ou um foreground quase-branco, para contraste legível.
 
 **Referência** — `source/reference/color-and-contrast.md`.
 
-### 15. `nested-cards` · `slop`
+### 27. `nested-cards` · `slop`
 
 **O que detecta** — um card dentro de um card.
 
@@ -338,7 +408,7 @@ Seven achata a hierarquia: use divisor de seção, lista rotulada, ou `Tabs`.
 
 **Referência** — `source/reference/spatial-design.md`.
 
-### 16. `monotonous-spacing` · `quality`
+### 28. `monotonous-spacing` · `quality`
 
 **O que detecta** — o mesmo valor de espaçamento usado em todo lugar.
 
@@ -348,7 +418,7 @@ mais solto ainda entre seções.
 
 **Referência** — `source/reference/spatial-design.md`.
 
-### 17. `flat-type-hierarchy` · `quality`
+### 29. `flat-type-hierarchy` · `quality`
 
 **O que detecta** — tamanhos de fonte muito próximos entre si.
 
@@ -357,7 +427,7 @@ Text/Heading do Seven; combine escala com contraste de peso.
 
 **Referência** — `source/reference/typography.md`.
 
-### 18. `layout-transition` · `quality`
+### 30. `layout-transition` · `quality`
 
 **O que detecta** — animação de `width`, `height`, `padding` ou `margin`.
 
@@ -373,7 +443,7 @@ Seven anima só `transform` e `opacity`.
 
 **Referência** — `source/reference/motion-design.md`.
 
-### 19. `line-length` · `quality`
+### 31. `line-length` · `quality`
 
 **O que detecta** — linhas de texto mais largas que ~80 caracteres.
 
@@ -382,7 +452,7 @@ Use `max-width` de 65ch a 75ch em containers de texto.
 
 **Referência** — `source/reference/spatial-design.md`.
 
-### 20. `cramped-padding` · `quality`
+### 32. `cramped-padding` · `quality`
 
 **O que detecta** — texto colado na borda do container.
 
@@ -391,7 +461,7 @@ lê como apertado. Padding deve escalar com o tamanho da fonte.
 
 **Referência** — `source/reference/spatial-design.md`.
 
-### 21. `body-text-viewport-edge` · `quality`
+### 33. `body-text-viewport-edge` · `quality`
 
 **O que detecta** — parágrafo de corpo colado na borda da viewport, sem
 container de padding.
@@ -401,7 +471,7 @@ Envolva em container com padding horizontal, ou `max-width` com `mx-auto`.
 
 **Referência** — `source/reference/spatial-design.md`.
 
-### 22. `tight-leading` · `quality`
+### 34. `tight-leading` · `quality`
 
 **O que detecta** — `line-height` abaixo de 1.3x o tamanho da fonte.
 
@@ -410,7 +480,7 @@ O corpo do Seven usa leading 1.5.
 
 **Referência** — `source/reference/typography.md`.
 
-### 23. `skipped-heading` · `quality`
+### 35. `skipped-heading` · `quality`
 
 **O que detecta** — níveis de heading pulados (ex.: `h1` direto para `h3`).
 
@@ -419,7 +489,7 @@ navegar. Pular nível quebra o outline do documento.
 
 **Referência** — `source/reference/typography.md`.
 
-### 24. `justified-text` · `quality`
+### 36. `justified-text` · `quality`
 
 **O que detecta** — texto justificado sem hifenização.
 
@@ -428,7 +498,7 @@ entre palavras. Use `text-align: left` para corpo.
 
 **Referência** — `source/reference/typography.md`.
 
-### 25. `tiny-text` · `quality`
+### 37. `tiny-text` · `quality`
 
 **O que detecta** — texto de corpo abaixo de 12px.
 
@@ -438,7 +508,7 @@ no mínimo.
 
 **Referência** — `source/reference/typography.md`.
 
-### 26. `all-caps-body` · `quality`
+### 38. `all-caps-body` · `quality`
 
 **O que detecta** — passagens longas de texto em maiúsculas.
 
@@ -448,7 +518,7 @@ curtos de coluna de tabela monoespaçada; corpo é sentence case.
 
 **Referência** — `source/reference/typography.md`.
 
-### 27. `wide-tracking` · `quality`
+### 39. `wide-tracking` · `quality`
 
 **O que detecta** — `letter-spacing` acima de 0.05em em texto de corpo.
 
@@ -458,7 +528,7 @@ default; tracking largo é decisão Display-only.
 
 **Referência** — `source/reference/typography.md`.
 
-### 28. `bounce-easing` · `slop`
+### 40. `bounce-easing` · `slop`
 
 **O que detecta** — easing bounce, elastic ou spring.
 
@@ -475,7 +545,7 @@ suavemente. Seven é decelerado e para — sem overshoot em chrome. Use
 
 **Referência** — `source/reference/motion-design.md`.
 
-### 29. `everything-centered` · `slop`
+### 41. `everything-centered` · `slop`
 
 **O que detecta** — todos os elementos de texto centralizados.
 
@@ -487,12 +557,12 @@ deliberadas.
 
 ---
 
-## Regras de elemento Seven-específicas (30-35)
+## Regras de elemento Seven-específicas (42-47)
 
 Precisam de inspeção do DOM — é a razão de existir dos engines `static-html`
 e `browser`.
 
-### 30. `missing-tactile-press` · `quality`
+### 42. `missing-tactile-press` · `quality`
 
 **O que detecta** — uma afordância clicável (`<button>`, `role="button"`, item
 de lista interativo) sem transição de micro-press baseada em `transform`.
@@ -510,7 +580,7 @@ inset shadow. Um botão sem isso lê como morto.
 
 **Referência** — `source/reference/motion-design.md`.
 
-### 31. `pill-on-button` · `slop`
+### 43. `pill-on-button` · `slop`
 
 **O que detecta** — um `<button>` com `border-radius: 9999` ou `rounded-full`.
 
@@ -526,7 +596,7 @@ Pill (9999) é para badges, status indicators e avatar triggers — nunca botõe
 
 **Referência** — `source/reference/spatial-design.md`.
 
-### 32. `radius-mixed-scales` · `quality`
+### 44. `radius-mixed-scales` · `quality`
 
 **O que detecta** — um radius de escala-componente (4/8/12) misturado com um
 de escala-superfície (16/20/24/32) no mesmo elemento.
@@ -537,7 +607,7 @@ anti-pattern mais comum do Seven.
 
 **Referência** — `source/reference/spatial-design.md`.
 
-### 33. `non-lucide-icon` · `slop`
+### 45. `non-lucide-icon` · `slop`
 
 **O que detecta** — um `<svg>` inline que não é um ícone Lucide (Lucide usa
 viewBox 24x24, stroke de 2px, line caps/joins redondos, sem fill).
@@ -547,7 +617,7 @@ convenção de stroke quebra a consistência do sistema de ícones.
 
 **Referência** — `source/reference/typography.md`.
 
-### 34. `emoji-in-chrome` · `slop`
+### 46. `emoji-in-chrome` · `slop`
 
 **O que detecta** — um caractere emoji dentro de texto de botão, label ou
 heading.
@@ -564,7 +634,7 @@ renderiza inconsistente entre plataformas e quebra o tom.
 
 **Referência** — `source/reference/ux-writing.md`.
 
-### 35. `forbidden-em-dash` · `quality`
+### 47. `forbidden-em-dash` · `quality`
 
 **O que detecta** — um em-dash (`—`) ou en-dash (`–`) em copy voltado ao
 usuário.
@@ -583,6 +653,175 @@ travessão longo lê como prosa gerada por máquina.
 
 ---
 
+## Sinais atuais do upstream adaptados ao Seven (48-68)
+
+Estas regras completam os sinais úteis do Impeccable fixado no commit
+`087983070bd8f39150eb1118c90cba50e016b1fa`. Regras de gosto ficam como
+`slop`/advisory na policy do consumidor. Falhas concretas de legibilidade ou
+layout ficam como `quality`/warning. Nenhuma delas autoriza um valor visual fora
+dos componentes, variantes e tokens da release Seven instalada.
+
+### 48. `pulsing-dot` · `slop`
+
+**O que detecta** — um pequeno círculo com animação de pulse sem evidência de
+dado realmente vivo. Um status estático do Seven não precisa simular atividade.
+
+**Referência** — `source/reference/motion-design.md`.
+
+### 49. `blinking-cursor` · `slop`
+
+**O que detecta** — caret ou cursor piscando fora de input, textarea ou região
+editável. O cursor decorativo chama atenção sem comunicar estado do produto.
+
+**Referência** — `source/reference/motion-design.md`.
+
+### 50. `shape-assembled-illustration` · `slop`
+
+**O que detecta** — SVG pictórico grande montado com doze ou mais primitivas.
+Ícones Lucide, logos, charts e gráficos de dados ficam fora da regra.
+
+**Referência** — `source/reference/brand.md`.
+
+### 51. `radial-halo` · `slop`
+
+**O que detecta** — `radial-gradient` cromático que desaparece em transparente
+como halo decorativo. Charts, masks e visualizações de dados são isentos.
+
+**Referência** — `source/reference/color-and-contrast.md`.
+
+### 52. `marquee` · `slop`
+
+**O que detecta** — `<marquee>`, utility de ticker/marquee ou animação horizontal
+infinita. Scroll iniciado pelo usuário não é marquee.
+
+**Referência** — `source/reference/motion-design.md`.
+
+### 53. `icon-tile-stack` · `slop`
+
+**O que detecta** — três ou mais blocos repetindo tile de ícone arredondado
+imediatamente acima de um heading.
+
+**Referência** — `source/reference/spatial-design.md`.
+
+### 54. `numbered-section-labels` · `slop`
+
+**O que detecta** — três ou mais seções usando micro-label numérico ao lado do
+heading como scaffolding editorial. Lista ou sequência de produto real não entra.
+
+**Referência** — `source/reference/typography.md`.
+
+### 55. `marketing-buzzword` · `slop`
+
+**O que detecta** — frases genéricas como “potencialize”, “sem atrito”,
+“enterprise-grade” ou “cutting-edge” em copy visível. A correção deve dizer o
+job e o resultado concretos.
+
+**Referência** — `source/reference/ux-writing.md`.
+
+### 56. `aphoristic-cadence` · `slop`
+
+**O que detecta** — três ou mais construções de contraste curto repetidas, como
+“Não é X. É Y.”, produzindo cadência de copy gerada.
+
+**Referência** — `source/reference/ux-writing.md`.
+
+### 57. `oversized-h1` · `slop`
+
+**O que detecta** — headline longa, com pelo menos 32 caracteres ou seis
+palavras, usando escala de display de 64px ou mais. Um nome curto em display é
+permitido.
+
+**Referência** — `source/reference/typography.md`.
+
+### 58. `extreme-negative-tracking` · `slop`
+
+**O que detecta** — `letter-spacing` abaixo de `-0.075em` ou `-1.2px`, ponto em
+que apertar o display começa a degradar o desenho das letras.
+
+**Referência** — `source/reference/typography.md`.
+
+### 59. `first-viewport-column-overflow` · `quality`
+
+**O que detecta** — grid/flex de abertura com uma coluna encerrando próximo ao
+fold e a outra avançando muito além da primeira viewport. É uma regra de
+geometria renderizada e roda no engine browser.
+
+**Referência** — `source/reference/spatial-design.md`.
+
+### 60. `undersized-ui-text` · `quality`
+
+**O que detecta** — texto funcional de link, botão, label, tabela, menu ou aba
+abaixo de 11px. `sup`, `sub`, conteúdo oculto e smallprint legal são isentos.
+
+**Referência** — `source/reference/typography.md`.
+
+### 61. `repeated-container-text` · `quality`
+
+**O que detecta** — o mesmo texto significativo em três ou mais slots
+estruturalmente distintos de um card, painel, dialog ou região.
+
+**Referência** — `source/reference/ux-writing.md`.
+
+### 62. `gpt-thin-border-wide-shadow` · `slop`
+
+**O que detecta** — border de até 1px junto com shadow difusa de blur igual ou
+superior a 16px em superfície comum. Overlays legítimos ficam fora da regra.
+
+**Referência** — `source/reference/spatial-design.md`.
+
+### 63. `repeating-stripes-gradient` · `slop`
+
+**O que detecta** — `repeating-linear-gradient`, `repeating-radial-gradient` ou
+`repeating-conic-gradient` usados como textura decorativa fora de charts,
+progress e masks.
+
+**Referência** — `source/reference/color-and-contrast.md`.
+
+### 64. `codex-grid-background` · `slop`
+
+**O que detecta** — duas gradients lineares perpendiculares, com hairline e
+`background-size` fixo, formando grid decorativo. Canvas, mapa, blueprint e
+superfície de medição são isentos.
+
+**Referência** — `source/reference/spatial-design.md`.
+
+### 65. `theater-slop-phrase` · `slop`
+
+**O que detecta** — copy que chama segurança, inovação, compliance ou outro
+conceito de “theater” em vez de explicar objetivamente o comportamento.
+
+**Referência** — `source/reference/ux-writing.md`.
+
+### 66. `image-hover-transform` · `slop`
+
+**O que detecta** — `scale` ou `rotate` aplicado a imagem no hover sem uma
+necessidade de interação. Mudança de estado com significado continua possível.
+
+**Referência** — `source/reference/motion-design.md`.
+
+### 67. `sidebar-topbar-shell` · `quality`
+
+**O que detecta** — uma composição Sidebar + Topbar que não forma o shell
+canônico em L: Topbar fora de `SidebarInset`, Sidebar/Inset sem a relação de
+irmãos diretos, offset manual, borda/sombra no chrome, sobreposição T-shaped no
+desktop, ausência de `SidebarTrigger` visível na Topbar mobile ou conteúdo de
+`TopbarLeading` vazando por baixo do chrome trailing. O caso `collapsible="none"`
+é isento do trigger porque a navegação nunca fica oculta.
+
+**Referência** — `source/reference/app-shell.md`.
+
+### 68. `sidebar-rail-behavior` · `quality`
+
+**O que detecta** — drift no contrato da Rail dual: `SidebarRailButton` sem
+`label`, navegação com Link envolvendo button em vez de `asChild`, divergência
+entre `aria-expanded` e o Sheet mobile visível, ou painel mobile colapsado/
+estreito por ter herdado o estado desktop. A expansão 64→200px continua overlay
+sobre o painel de 216px; ela não altera o footprint de 280px.
+
+**Referência** — `source/reference/app-shell.md`.
+
+---
+
 ## Regras do impeccable que o Seven NÃO porta
 
 Quatro regras do impeccable foram deliberadamente descartadas — não fazem