@etus/seven-skill 0.1.0-beta.1

package/docs/figma-token-rule-exploration.md

@@ -0,0 +1,185 @@
+# Exploração de regras a partir de tokens e Figma
+
+Data: 2026-05-20
+
+## Objetivo
+
+Adaptar o detector do `pbakaus/impeccable` para o Seven sem copiar o gosto visual
+genérico do upstream. A regra para Seven é: o detector precisa proteger o que o
+Design System já declarou como verdade, principalmente Figma, `@etus/tokens` e
+os componentes canônicos.
+
+## Fontes verificadas
+
+- Upstream `pbakaus/impeccable` em `642f03d`, com detector CLI, skill, browser
+  bundle e catálogo de anti-patterns.
+- Registro Figma/código em `docs/seven-ds-components.md`: arquivo
+  `Core Components - Seven` (`ssJ2nEYUiAsMylSuP9KTzE`), 147 bullets Figma,
+  106 matches Figma/código e 89 itens code-only.
+- Fontes Figma em `.claude/skills/figma-sync/figma-sources.json`: arquivo de
+  tokens `Tokens - Seven` (`ZDTC9C9iBrBLwaZkteuYit`) e arquivo de componentes
+  `Core Components - Seven`.
+- Tokens locais em `packages/tokens/src/**/*.tokens.json`, especialmente
+  `semantic-colors`, `radius`, `spacing`, `typography`, `focus-ring` e tokens
+  por componente.
+- 87 caches locais de Figma em `ai_review/components/*/variables.json`.
+- Figma MCP ao vivo:
+  - Button `1007:301`: Inter, `radius/md = 8`, `border-width/border = 1`,
+    `height/h-8|h-9|h-10`, `brand/primary/*`, `brand/secondary/*`,
+    `core/border/ring`.
+  - Sidebar nav item `1087:204`: Inter, spacing `8/12`, radius `4`, foreground
+    e muted foreground semânticos.
+  - Tokens spacing `125:941`: escala documentada de spacing pequeno, médio e
+    grande.
+
+## O que já está bem encaminhado
+
+O port atual acertou na decisão mais importante: manteve a arquitetura do
+impeccable, mas trocou os julgamentos de gosto por contratos do Seven. Exemplos:
+
+- `overused-font` virou `non-inter-font`, porque Inter é requisito do Seven.
+- `gradient-text` virou `gradient-text-decorative`, mantendo o tell de IA, mas
+  com justificativa do sistema.
+- `side-tab` e `border-accent-on-rounded` foram fundidos em
+  `side-stripe-border`, agora condicionado a stripe lateral colorido.
+- Regras próprias do Seven já existem: type hints Tailwind v4, fuchsia fora de
+  chart, pt-BR, radius misturado, Lucide-only, tactile press e copy sem dash
+  longo.
+- O pacote agora está separado como `@etus/seven-skill`, evitando conflito com
+  o pacote umbrella do Design System.
+
+## Regra adicionada nesta exploração
+
+### `raw-tailwind-palette-color`
+
+Problema: o detector já pegava `#19e699`, `rgb(...)` e `oklch(...)`, mas deixava
+passar `bg-green-500`, `text-neutral-900`, `border-red-200`, `ring-blue-500`.
+Esses utilitários também bypassam a camada semântica de `@etus/tokens`.
+
+Evidência:
+
+- `PRODUCT.md` fixa a escada: Figma > `tokens.css` > `DESIGN.md` > docs.
+- Figma Button vivo usa `brand/primary/*`, `brand/secondary/*`,
+  `core/background/*`, `core/border/*`, não classes de paleta Tailwind.
+- Nos 87 `variables.json`, os tokens recorrentes são semânticos:
+  `core/background/muted-foreground` apareceu 62 vezes, `core/border/border`
+  48 vezes, `core/background/foreground` 42 vezes e `core/border/ring` 26 vezes.
+
+Implementação:
+
+- Regra textual em `cli/engine/rules/checks.mjs`.
+- Catálogo em `cli/engine/registry/seven-antipatterns.mjs`.
+- Fixture fail/pass em `tests/fixtures/antipatterns/`.
+- Documentação em `docs/detector-rules.md` e `source/reference/color-and-contrast.md`.
+- Exceção para `data-role="chart"` e SVG, preservando chart colors.
+
+## Regras que eu adicionaria depois
+
+### 1. `focus-ring-token-required`
+
+Detectar elementos interativos com `outline: none`, `focus:outline-none` ou
+remover foco sem restaurar `focus-visible` via `var(--ring)`.
+
+Por que vale: Figma Button declara efeitos `Focus Ring - Primary`,
+`Focus Ring - Secondary`, `Focus Ring - Ghost` e `Focus Ring - Destructive`.
+O token local também tem `focus-ring.tokens.json`. Essa regra protege
+acessibilidade e identidade ao mesmo tempo.
+
+Risco: precisa evitar falso positivo em componentes que delegam foco para
+Radix ou para wrappers. Eu faria primeiro como regex text-only com fixture e
+depois aprofundaria no engine DOM.
+
+### 2. `off-scale-radius`
+
+Detectar radius bruto fora da escala canônica: `2, 4, 8, 12, 16, 20, 24, 32,
+999/9999`. A regra atual `radius-mixed-scales` pega mistura no mesmo elemento,
+mas não pega `rounded-[7px]` ou `border-radius: 10px`.
+
+Por que vale: `radius.tokens.json`, Figma Button e vários caches convergem em
+`radius/md = 8`, `radius/sm = 4`, `radius/lg = 12`, `radius/pill = 999`.
+
+Risco: Figma ainda tem aliases legados como `border-radius/md = 6` e alguns
+componentes cacheados usam `rounded-sm = 2`. Antes de ativar como erro, eu
+criaria uma allowlist gerada dos tokens locais + caches Figma.
+
+### 3. `off-scale-spacing`
+
+Detectar `padding`, `margin` e `gap` com valores fora da escala de spacing.
+
+Por que vale: Figma spacing e os caches mostram escala recorrente (`2, 4, 6, 8,
+12, 16, 20, 24, 32, 40, 48, 56, 64`) e o pacote local expõe aliases de spacing.
+
+Risco: há uma diferença real entre `packages/tokens/src/spacing.tokens.json`
+(aliases 4/8/16/32/48/64 e local-only 80+) e Figma vivo/cacheado (também usa
+2/6/10/12/20/24/40/56). Eu não bloquearia isso sem antes consolidar a tabela.
+
+### 4. `component-height-drift`
+
+Detectar botões/inputs/controles usando alturas que não batem com tokens do
+componente. Exemplo: Button vivo usa `h-8`, `h-9`, `h-10` e radius `md`.
+
+Por que vale: pega drift de implementação que passa por cor/contraste, mas
+quebra a sensação do componente.
+
+Risco: precisa mapear componente para token. Eu só faria depois de extrair uma
+matriz `component -> allowed sizes` a partir de `packages/tokens/src/components`
+e Figma `variables.json`.
+
+### 5. `semantic-neutral-bypass`
+
+Versão mais estrita da regra adicionada agora: além de utilitários Tailwind de
+paleta crua, detectar usos de variáveis muito primitivas (`--neutral-*`,
+`--brand-primary-*`) quando existe token semântico (`--foreground`,
+`--primary`, `--border`, `--muted-foreground`).
+
+Por que vale: Seven quer que runtime consuma semântica, não escala primitiva.
+
+Risco: componentes do próprio DS às vezes precisam referenciar primitives para
+definir semântica. Essa regra deve ser consumer-only ou ter path/package
+exemptions fortes.
+
+## Regras que eu não portaria do impeccable
+
+- `single-font`: no upstream é problema, no Seven é requisito.
+- `overused-font`: idem, Inter é fonte canônica.
+- `italic-serif-display`: Seven não tem serif display.
+- `hero-eyebrow-chip` e `repeated-section-kickers`: são regras de landing page,
+  não de um design system operacional.
+- `ai-color-palette` genérica: melhor substituir por regras concretas do Seven
+  (`fuchsia-in-ui-chrome`, `raw-tailwind-palette-color`, tokens semânticos,
+  contraste).
+
+## Como eu geraria regras daqui para frente
+
+1. Extrair uma tabela versionada de evidências:
+   - tokens locais: nome, tipo, valor, origem.
+   - Figma caches: frequência de chave/valor em `ai_review/components`.
+   - Figma live: amostras de nós críticos, principalmente Button, Input, Tabs,
+     Sidebar e Drawer.
+2. Classificar cada candidato:
+   - `deterministic`: dá para detectar com AST/texto/DOM sem julgamento.
+   - `advisory`: precisa de contexto visual ou decisão humana.
+   - `do-not-port`: regra upstream que conflita com Seven.
+3. Para cada regra deterministic:
+   - registrar no catálogo;
+   - criar fixture fail/pass;
+   - documentar em `docs/detector-rules.md`;
+   - rodar dogfood em `packages/ui/src` com baseline explícito;
+   - só então considerar CI/gate.
+4. Manter uma regra por comportamento observável. Evitar regras que só
+   descrevem "parece estranho" sem token, Figma node ou guideline local.
+
+## Próximo corte recomendado
+
+O próximo PR deveria ser `focus-ring-token-required`. É mais seguro e mais
+valioso do que spacing/radius neste momento, porque:
+
+- tem fonte clara no Figma e nos tokens;
+- afeta acessibilidade;
+- tem baixo risco de bloquear layout legítimo;
+- complementa `missing-tactile-press`, que já olha affordance interativa.
+
+Depois disso, eu faria uma mini-ferramenta de extração de evidência para
+`off-scale-radius` e `off-scale-spacing`, mas deixaria as duas como advisory até
+resolver a divergência entre tokens locais e aliases que ainda aparecem nos
+caches do Figma.

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@etus/seven-skill",
+  "version": "0.1.0-beta.1",
+  "description": "Seven Design System skill, plugin, and CLI detector for AI coding agents — ETUS Digital",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/etusdigital/seven.git",
+    "directory": "packages/seven-skill"
+  },
+  "homepage": "https://github.com/etusdigital/seven#readme",
+  "bugs": {
+    "url": "https://github.com/etusdigital/seven/issues"
+  },
+  "keywords": [
+    "design-system",
+    "claude-code",
+    "skill",
+    "plugin",
+    "ai",
+    "etus",
+    "seven"
+  ],
+  "type": "module",
+  "bin": {
+    "seven": "./cli/bin/seven.mjs"
+  },
+  "exports": {
+    ".": "./cli/engine/detect-antipatterns.mjs",
+    "./detect": "./cli/engine/detect-antipatterns.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "cli",
+    ".claude",
+    ".claude-plugin",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "NOTICE.md"
+  ],
+  "dependencies": {
+    "css-select": "^5.2.2",
+    "css-tree": "^3.0.0",
+    "domutils": "^3.1.0",
+    "htmlparser2": "^9.1.0"
+  },
+  "optionalDependencies": {
+    "puppeteer": "^23.0.0"
+  },
+  "devDependencies": {
+    "@types/css-tree": "^2.3.10",
+    "@types/node": "^25.0.6",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.7",
+    "@etus/tokens": "^0.4.0-beta.2",
+    "@etus/tsconfig": "0.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsx build/build.ts && node build/build-token-data.mjs && node build/build-browser-detector.mjs",
+    "build:harnesses": "tsx build/build.ts",
+    "build:tokens": "node build/build-token-data.mjs",
+    "build:browser": "node build/build-browser-detector.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "detect": "node cli/bin/seven.mjs detect"
+  }
+}