@snksergio/design-system 0.60.0 → 0.62.0

package/dist-lib/ai/lint/ds-lint-patterns.mjs

@@ -0,0 +1,115 @@
+/**
+ * ds-lint-patterns — FONTE ÚNICA dos anti-patterns de estilo do DS.
+ *
+ * Consumido por DOIS clientes (nunca duplique a tabela):
+ *   - .claude/hooks/ds-lint-styles.sh   → aviso local, nunca bloqueia
+ *   - scripts/lint-styles.mjs --ratchet → check de CI, bloqueia violação nova
+ *
+ * ⚠️ E por um TERCEIRO, fora deste repo: este arquivo é foundational
+ * (`foundational-pairs.mjs`) e é copiado inteiro para
+ * `cli/templates/default/_claude/hooks/`, que o ds:link projeta no projeto do
+ * consumidor. Lá, `.ai/` e os caminhos internos do DS NÃO EXISTEM — os que
+ * aparecem nos comentários abaixo só resolvem aqui. Por isso nenhuma `msg`
+ * cita caminho: mensagem de lint tem que se bastar onde for lida.
+ *
+ * ⚠️ Só entram aqui regras erradas INDEPENDENTE DE CONTEXTO (valor divergente
+ * do token, classe que não existe). Regras que exigem contexto cross-elemento
+ * ou julgamento de intenção — L-004 (afordância de foco pode estar no wrapper)
+ * e L-007 (escolha de preset tipográfico) — pertencem ao revisor semântico,
+ * NÃO a este arquivo. Ver `.ai/specs/pipeline-governance-ci.md` §1.1.
+ *
+ * Buracos de cobertura conhecidos (não fechados nesta rodada — cada um exige
+ * medição/decisão de política própria; ver it.todo no teste):
+ *   - `space-x-N` / `space-y-N` (utility legado, sem token DS direto) e
+ *     `w-N`/`h-N` isolados fora das famílias `h|min-h|size` acima.
+ *   - **Template literals**: o delimitador cobre aspas simples e duplas, mas
+ *     NÃO crase — `` `flex gap-4` `` passa limpo (forma diferente, não
+ *     coberta nesta rodada).
+ *   - **Números fora do que foi medido no baseline**: as alternações listam
+ *     só os valores encontrados na varredura de 2026-07-29, não a escala
+ *     Tailwind inteira — `w-10`, `p-9`, `gap-11`, `h-20` passam limpo hoje.
+ *     Ampliar a faixa numérica exige nova medição própria, fora desta correção.
+ */
+
+export const DS_LINT_PATTERNS = [
+  {
+    id: "L-001",
+    re: /ring-ring-[a-z-]+\/[0-9]+/,
+    msg: "ring-ring-*/N — o token de ring já tem alpha embutido. Remova o /N.",
+  },
+  // `0` fora da alternação de propósito: não existe token DS pra zero
+  // (p-0/gap-0 são resets legítimos, comuns com `!` sobre base do shadcn).
+  {
+    id: "L-002",
+    re: /['"][^'"]*\bgap(-[xy])?-(1|2|3|4|5|6|7|8|9|10|12|14|16|20|24)\b[^'"]*['"]/,
+    msg: "gap-N literal → use gap-gp-{2xs,xs,sm,md,lg,xl,2xl}.",
+  },
+  {
+    id: "L-002",
+    re: /['"][^'"]*\b(px|py|pt|pb|pl|pr|p)-(1|2|3|4|5|6|7|8|10|12|16)\b[^'"]*['"]/,
+    msg: "pad/space literal → use p-sp-* (space) ou px-pad-* (pad).",
+  },
+  // ⚠️ Esta msg NÃO aponta pra arquivo, e é de propósito. Ela terminava com
+  // "ver .ai/context/tokens/sizing-shape-elevation.md" — caminho que existe aqui
+  // e que o CONSUMIDOR nunca recebe: este módulo é foundational (ver
+  // foundational-pairs.mjs) e roda também no `.claude/` projetado pelo ds:link,
+  // onde `.ai/` não existe. Mensagem que manda ler o inalcançável faz a pessoa
+  // parar de investigar achando que a resposta está em outro lugar (L-060).
+  // A regra aqui é: msg de lint se basta ou não cita caminho.
+  {
+    id: "L-002",
+    re: /['"][^'"]*\b(h|min-h|size)-(7|8|9|10|11|12|13|14|16)\b[^'"]*['"]/,
+    msg: "height/size fixo → use min-h-form-* (h-9=form-md, h-10=form-lg, h-11=form-xl). Se for quadrado, size-comp-*. Se for maior (~h-12 a h-16, 48-64px), não é form — use token de layout (ex.: h-layout-navbar).",
+  },
+  // `none` e `full` fora da alternação: são numericamente IDÊNTICOS ao token DS
+  // (--radius-radius-full: 9999px, --radius-radius-none: 0px) → não podem ser
+  // defeito. Já sm..3xl DIVERGEM (nativo lg=0.5rem vs DS 0.625rem) → defeito
+  // real. Side variants (rounded-t-lg) carregam o mesmo valor divergente.
+  {
+    id: "L-002",
+    re: /['"][^'"]*\brounded(-(t|b|l|r|tl|tr|bl|br|s|e|ss|se|es|ee))?-(sm|md|lg|xl|2xl|3xl)\b[^'"]*['"]/,
+    msg: "rounded-N nativo tem VALOR DIFERENTE do token DS (nativo lg=0.5rem vs DS 0.625rem) → use rounded-radius-*.",
+  },
+  {
+    id: "L-002",
+    re: /['"][^'"]*\bshadow-(2xs|xs|sm|md|lg|xl|2xl)\b[^'"]*['"]/,
+    msg: "shadow-N nativo → use shadow-sh-*.",
+  },
+  {
+    id: "L-003",
+    re: /['"][^'"]*\bring-3\b[^'"]*['"]/,
+    msg: "ring-3 não existe no Tailwind (vira no-op silencioso) → use ring-4.",
+  },
+  {
+    id: "L-005",
+    re: /['"][^'"]*\bbg-input\/[0-9]+[^'"]*['"]/,
+    msg: "bg-input/N é var do shadcn → use o token DS bg-bg-surface (ou bg-bg-muted).",
+  },
+  {
+    id: "IMPORT",
+    re: /from\s+['"]tailwind-variants['"]/,
+    msg: 'import errado: use `import { tv } from "@/utils/tv"` — o wrapper do DS carrega o twMergeConfig da L-016.',
+  },
+];
+
+/** Linha de comentário não é código — citar uma classe proibida ao explicar a
+ *  regra não pode reprovar o CI. Cobre `//`, `/*`, ` *` e o comentário JSX
+ *  `{/* ... *\/}`, que entrou no escopo junto com o `.tsx`. */
+const isComment = (text) => /^\s*(\/\/|\/\*|\*|\{\s*\/\*)/.test(text);
+
+/**
+ * Roda todos os patterns contra uma lista de linhas.
+ * @param {Array<{n: number, text: string}>} lines
+ * @returns {Array<{id: string, msg: string, n: number, text: string}>}
+ */
+export function scanLines(lines) {
+  const out = [];
+  for (const { n, text } of lines) {
+    if (isComment(text)) continue;
+    for (const p of DS_LINT_PATTERNS) {
+      // `re` sem flag /g → .test() não mantém lastIndex, seguro reusar.
+      if (p.re.test(text)) out.push({ id: p.id, msg: p.msg, n, text });
+    }
+  }
+  return out;
+}

package/dist-lib/ai/manifest.json

@@ -0,0 +1,16 @@
+{
+  "pacote": "@snksergio/design-system",
+  "versao": "0.62.0",
+  "commit": "7cd6db7",
+  "gerado": "2026-09-15",
+  "conteudo": {
+    "roteiros": [
+      "dashboard"
+    ],
+    "componentes": 47,
+    "componentesComRegra": 19,
+    "rotas": 19,
+    "arquivosDeExemplo": 3,
+    "residuoClaudeCode": 8
+  }
+}

package/dist-lib/ai/regras/design.md

@@ -0,0 +1,88 @@
+
+# Regras de design iGreen (auto-carregadas)
+
+Ao gerar ou editar QUALQUER UI neste projeto, aplique sem ser pedido. Detalhe e
+contexto em `DESIGN.md` (raiz). API de cada componente em
+`src/components/ui/<Nome>/USAGE.md`.
+
+> **Modo submódulo.** Se existe `.claude/ds-config.json` com `"mode": "submodule"`, três
+> coisas mudam nesta regra: (1) `DESIGN.md` e os `USAGE.md` ficam em `<dsPath>/` e
+> `<dsPath>/src/components/ui/<Nome>/`, não na sua raiz; (2) **não** existe `igreen:add`,
+> manifesto nem hook de proteção — os componentes estão no disco e você importa pelo
+> `importBase`; (3) a regra de **não editar o tema/fundação** continua valendo, só que por
+> disciplina, não por bloqueio: o que você editar no submódulo some no próximo `git pull`.
+
+## Composição de tela
+- Wrapper de página: `flex flex-col h-full min-h-0 gap-gp-2xl`.
+- **16px (`gap-gp-2xl`) entre o `PageHeader` e o próximo bloco** — nunca grudado.
+- Conteúdo que precisa preencher (tabela): `className="flex-1 min-h-0"` + pai com altura.
+- Forms: `<FormField>` (nunca `<label>` cru) + `gap-form-gap` (20px) entre campos.
+- Card: densidade pela prop `size` do `<Card>` — `sm` 16 · **`md` 20 (default)** · `lg` 24 (tokens `p-pad-card-sm/md/lg`; `base` é alias depreciado de `md`); entre cards `gap-gp-md`/`gap-gp-lg`.
+
+## Tokens (classe DS antes de Tailwind literal)
+```
+gap-4 → gap-gp-md      p-4 → p-sp-md/p-pad-2xl    rounded-lg → rounded-radius-lg
+shadow-md → shadow-sh-md    h-9/h-10 → min-h-form-md/lg    size-5 → size-icon-md
+```
+- **Prefira o token de COMPONENTE ao genérico**: altura `min-h-form-*` (não `h-9/10`), gap de form `gap-form-gap`, ícone `size-icon-*` (não `size-5`), padding de card `p-pad-card-*`, gutter `px-pad-page-*`, chrome `h-layout-*`, largura `max-w-*`. Genérico (`gap-gp-*`/`p-sp-*`/`px-pad-*`) só como fallback. Cheat-sheet completo em `DESIGN.md` ("Tokens de componente").
+- Foco: `focus-visible:outline-none focus-visible:ring-4 focus-visible:ring-ring-{color}` (ring já tem alpha — nunca `/30`, nunca `ring-3`).
+- Cor só por token semântico (`bg-bg-brand`, `text-fg-default`...). Zero hex em className. Destrutivo na API = `color="critical"`.
+
+- ⚠️ **`max-w-container-*` NÃO existe** — `container` é o único namespace que não dobra o
+  prefixo. `max-w-md` já é os **768px do DS** (não os 448px do Tailwind); use `max-w-lg`,
+  `max-w-drawer-md`, `max-w-modal-sm`. A forma com `container` não emite CSS e some em silêncio.
+- ⚠️ **`bg-bg-scrollbar-thumb` / `-hover` são de uso interno** dos `@utility scrollbar-*`
+  (alpha neutro, pra barra ter contraste próprio). Não use como fundo de elemento.
+
+## Tipografia
+- Default interativo: `text-body-sm` (13/500). **7 papéis**: display/heading/title/body/caption/**stat**/code.
+- **Número de KPI/métrica = `text-stat-{sm,md,lg,xl}`** (20/24/30/34px) + `tabular-nums`. Nunca `text-[Npx]` na unha, nunca `display-*`/`heading-*` pra valor de indicador.
+- **Código / identificador / valor técnico = `text-code-{sm,md}`** (13/14px, Geist Mono) — chave de env, ID, hash, slug, path. Nunca `font-mono text-body-*` + `tracking-*` na unha: `code` é 1 dos 7 papéis e existe pra isto.
+- Override de peso via `font-bold/semibold/medium/normal`. Nunca `text-xs font-semibold` avulso → use preset.
+
+## ⛔ O tema já traz o runtime — não redeclare
+O `tailwind-theme.css` importado no seu CSS de entrada **não é só CSS vars**. Ele traz
+`@font-face` do Geist, `--font-sans`/`--font-mono`, `@custom-variant dark`, regras de
+`html`/`body`/`button` e as utilities `outline-float` e `scrollbar-thin`/`scrollbar-default`.
+
+**Não redeclare nenhuma delas** no seu CSS: classe comum vence `@utility`, e a **segunda**
+declaração de `@custom-variant` vence a primeira — você acaba com um comportamento no seu
+projeto e outro no resto do sistema, sem erro nenhum. Os `.woff2` do Geist, sim, são seus
+(o `@font-face` aponta pra `/fonts/`, raiz do site).
+
+## 🖼️ Trabalhando a partir de print / Figma / tela existente
+A referência decide **conteúdo**; o DS decide **pele e comportamento**.
+- **Dela**: copy, labels, nomenclatura, ordem dos campos. Copie e não "melhore" sem pedir — o jargão é do domínio do usuário.
+- **Do DS, sempre**: fonte/família, tamanho, peso, tracking, cor, espaçamento, radius, sombra, foco e **comportamento de componente**. Preset existe → use o preset; compor na unha porque "ficou igual ao print" é drift.
+- **Cor**: a referência escolhe o CONJUNTO (print escuro → `dark`; outra marca → `data-theme`), **nunca** o valor. Não derive hex do pixel.
+- **Chrome (rail/menu/header) na referência = shell no escopo.** Print de app + pedido de "uma tela" é `shell + tela`. Não vai entregar o shell? Avise em linha destacada **antes** de gerar.
+
+## Antes de criar
+- Existe exemplo/skill pra isso? (tabela→`/ds-create-crud`; ver `DESIGN.md` mapa de intenção). Puxe e adapte em vez de escrever do zero.
+- Leu o `USAGE.md` do componente? Não invente prop/variante.
+- `npx tsc --noEmit` limpo antes de entregar.
+
+## ⛔ Arquivos protegidos — NÃO editar (integridade do DS)
+- **NUNCA edite** o tema/tokens (`src/styles/theme/**`) nem a fundação (`src/lib/utils.ts` = cn, `src/utils/tv.ts` = tv, `src/lib/lucide-types.ts`). São a base visual gerada pelo DS — editar quebra o sistema todo e some no próximo update.
+
+  > **O que de fato te impede, por canal:**
+  >
+  > | canal | trava |
+  > |---|---|
+  > | copy-in / scaffold | ✅ hook `protect-ds.mjs` **bloqueia** (`Edit`/`Write`/`MultiEdit`) e **avisa** em `Bash` que escreve nesses paths |
+  > | **submódulo** | ✅ **desde o CLI 0.24.0** — o `ds-link` projeta o hook, e ele reconhece o layout de submódulo (bloqueia `<dsPath>/src/styles/theme/**` e `<dsPath>/tokens/**`, sem confundir com o **seu** `src/`). ⚠️ **1 passo manual:** hook só roda se estiver no seu `.claude/settings.json`, e o `ds-link` não escreve nesse arquivo (é seu) — ele **imprime o bloco pronto** e repete o aviso até você colar |
+  > | npm install | ❌ nenhuma — o código vive em `node_modules` |
+  >
+  > ⚠️ **Até o CLI 0.25.1 esta tabela dizia "❌ nenhuma" no submódulo**, justificando com *"o
+  > `ds-link` não projeta `hooks/`"*. Era verdade até a 0.23.x e **deixou de ser na 0.24.0** —
+  > eu mudei o mecanismo e atualizei a `ds-channels.md`, mas não procurei as outras superfícies
+  > que descreviam a mesma coisa. Se você leu a versão anterior e concluiu que no submódulo não
+  > há rede de segurança: há, e vale colar o bloco.
+- **Não edite o `.styles.ts`/internals de um componente do DS** pra "ajustar visual" de uma tela. Isso vira edição local (drift) e diverge do padrão. **Customize na COMPOSIÇÃO**: escolha variantes/props do componente + classes DS na SUA tela.
+- Quer outra cor/tom? Use o **token/variante semântico** que já existe (`color="..."`, `bg-bg-*`). Não invente hex nem reescreva o token.
+- Pra evoluir o tema de fato → re-sincronize com o DS (`npm run igreen:add -- theme`), não edite à mão.
+
+## Puxar componentes/exemplos (manifesto)
+- **SEMPRE** `npm run igreen:add -- <item> [<item> ...]` — o wrapper instala E registra no `.igreen-ds/manifest.json` (baseline pro `igreen:drift`/`igreen:update`).
+- **NUNCA** `npx shadcn add @igreen/...` cru: o componente instala mas fica **fora do manifesto** (o `igreen:drift` acusa "não gerenciado"). Se acontecer, recupere rodando `npm run igreen:add -- <os mesmos itens>` (idempotente; re-baseline sem sobrescrever edição).
+- Commite o `.igreen-ds/manifest.json`.

package/dist-lib/ai/regras/temas.md

@@ -0,0 +1,192 @@
+
+# Temas de marca (iGreen DS)
+
+O DS tem 5 marcas. Cada marca não-default é um **overlay de cor** escopado em
+`[data-theme="<id>"]` que sobrescreve **só o que difere** do tema-base — 87 vars em `blue` e
+`green`, 125 em `vibrant`, 166 em `pay`, contra ~350 do base.
+
+| id | marca | arquivo |
+|---|---|---|
+| `default` | iGreen (verde padrão) | — **é** o tema-base, não tem overlay |
+| `blue` | Azul | `brand-blue.css` |
+| `green` | Verde (grass) | `brand-green.css` |
+| `pay` | iGreen Pay | `brand-pay.css` |
+| `vibrant` | iGreen Vibrant (verde fluorescente) | `brand-vibrant.css` |
+
+## ⛔ Antes de mexer: 2 fatos que causam 90% dos erros
+
+1. **Importar o CSS não ativa nada.** O overlay é escopado — sem
+   `data-theme="<id>"` no `<html>`, nenhuma regra casa e nada muda. Não existe erro:
+   falha em silêncio.
+2. **Ordem de import importa.** O overlay tem que vir **depois** do `tailwind-theme.css`.
+   Antes, o tema-base ganha por ordem de fonte.
+
+Marca e claro/escuro são **eixos independentes**: `data-theme` no `<html>` + classe
+`.dark`. Combinam livremente.
+
+```html
+<html data-theme="vibrant" class="dark">   <!-- vibrant, escuro -->
+<html data-theme="vibrant">                <!-- vibrant, claro  -->
+<html>                                     <!-- default (sem atributo) -->
+```
+
+## Trocar o tema — identifique o modo PRIMEIRO
+
+Existe `.claude/ds-config.json` com `"mode": "submodule"`?
+
+### Modo SUBMÓDULO
+
+O **CSS** já está no disco. Importe (ajuste o caminho pro `dsPath` do `ds-config.json`):
+
+```css
+@import "tailwindcss";
+@import "../design-system/src/styles/theme/tailwind-theme.css";
+@import "../design-system/src/styles/theme/brand-vibrant.css";
+```
+
+Não rode `igreen:add` — em modo submódulo ele não se aplica. Tema novo chega com
+`git pull` no submódulo. **Não** precisa de `@source`: o submódulo fica dentro da raiz do
+projeto e o Tailwind v4 já escaneia daí.
+
+⚠️ **Duas coisas NÃO vêm com o submódulo**, e a segunda falha em silêncio:
+
+1. **As dependências.** O submódulo entrega código-fonte, não pacote — `npm i` das libs que os
+   componentes importam. O mínimo pra `Button` + `Modal`:
+   `tailwind-variants tailwind-merge clsx lucide-react @radix-ui/react-dialog @radix-ui/react-slot`.
+   O build quebra alto (`failed to resolve …`), então é fácil de achar.
+2. **Os arquivos da fonte Geist.** O `@font-face` viaja no tema, mas aponta pra `/fonts/*.woff2`
+   — raiz do **site**, não do submódulo. Copie:
+   `mkdir -p public/fonts && cp design-system/public/fonts/*.woff2 public/fonts/`.
+   Sem isso **não há erro**: o `font-family` segue dizendo `Geist`, o navegador recebe o
+   `index.html` no lugar do arquivo, e os 27 presets caem em system-ui. Confira com
+   `document.fonts.check("16px Geist")` — tem que ser `true`.
+
+### Modo COPY-IN (scaffold do CLI)
+
+Cada tema é item do registry. Traga com o mesmo comando dos componentes:
+
+```bash
+npm run igreen:add -- theme-vibrant     # copia src/styles/theme/brand-vibrant.css
+```
+
+Depois importe:
+
+```css
+@import "./styles/theme/tailwind-theme.css";
+@import "./styles/theme/brand-vibrant.css";
+```
+
+⚠️ O scaffold **apaga** os overlays não escolhidos no prompt "Tema de cor?". Se o arquivo
+não está em `src/styles/theme/`, é porque outro tema foi escolhido na criação — traga com
+o `igreen:add` acima.
+
+### Consumindo o DS por `npm install`
+
+⚠️ **A diretiva `@source` é OBRIGATÓRIA e é o erro nº 1 deste canal.** O Tailwind v4 **não
+escaneia `node_modules`** — sem ela **nenhuma** classe do DS é gerada e os componentes
+renderizam **sem estilo nenhum**, sem erro no console e sem build quebrado. Fácil concluir
+que "o pacote está quebrado".
+
+```css
+@import "tailwindcss";
+
+/* Sem esta linha, zero classes do DS. Tem que cobrir `dist-lib/**`, não só o
+   index.mjs — as classes dos componentes flutuantes vivem nos *chunks*. */
+@source "../node_modules/@snksergio/design-system/dist-lib/**/*.mjs";
+
+@import "@snksergio/design-system/theme.css";                 /* obrigatório */
+@import "@snksergio/design-system/theme/brand-vibrant.css";    /* a marca */
+```
+
+Ajuste o caminho do `@source` à profundidade do seu CSS de entrada (de `src/index.css`, a
+raiz do projeto é `../`).
+
+**Copie as fontes Geist** — o `@font-face` viaja no tema, mas aponta pra `/fonts/*.woff2`,
+raiz do **site**:
+
+```bash
+mkdir -p public/fonts
+cp node_modules/@snksergio/design-system/dist-lib/fonts/*.woff2 public/fonts/
+```
+
+⚠️ Sem isso **não há erro**: o `font-family` segue dizendo `Geist`, o navegador recebe o
+`index.html` no lugar do arquivo e os 27 presets caem em system-ui. Confira com
+`document.fonts.check("16px Geist")` — tem que ser `true`.
+
+Requer `@snksergio/design-system` **≥ 0.31.1** (antes disso o pacote levava só o tema-base);
+as fontes só são publicadas a partir da **0.35.0**.
+
+## Trocar em runtime (seletor de marca)
+
+### Consumindo por `npm install` → use o hook `useBrand` (≥ 0.33.0)
+
+Ele já resolve persistência, sincronia entre abas e a regra de que `default` significa
+**remover** o atributo (o tema-base não tem overlay).
+
+```tsx
+import { useBrand } from "@snksergio/design-system";
+
+// Passe SÓ as marcas cujo overlay você importou no CSS.
+const MINHAS_MARCAS = [
+  { id: "default", label: "iGreen",         swatch: "oklch(0.5248 0.1415 150.9)" },
+  { id: "vibrant", label: "iGreen Vibrant", swatch: "#0fff00" },
+];
+
+function SeletorDeMarca() {
+  const { brand, brands, current, setBrand } = useBrand({ brands: MINHAS_MARCAS });
+  return (
+    <select value={brand} onChange={(e) => setBrand(e.target.value)} aria-label="Marca">
+      {brands.map((b) => (
+        <option key={b.id} value={b.id}>{b.label}</option>
+      ))}
+    </select>
+  );
+}
+```
+
+⚠️ **O catálogo é o ponto todo.** Sem o argumento, `useBrand` usa as 5 marcas do DS — e o
+seletor listaria temas cujo CSS não está no seu bundle. `data-theme` com id sem overlay é
+**no-op silencioso**: a opção aparece, o usuário clica, nada acontece, e não há erro.
+Declare só o que você importou. `current` devolve a entrada ativa (label + swatch) pronta,
+sem `find()`.
+
+Valor persistido fora do catálogo cai na primeira entrada — então um `localStorage` com
+`"pay"` de outro app não deixa este num tema órfão.
+
+### Copy-in / submódulo, ou sem o pacote npm
+
+Escreve/remove o atributo na mão. `default` remove:
+
+```ts
+function aplicarMarca(id: string) {
+  const root = document.documentElement;
+  if (id === "default") root.removeAttribute("data-theme");
+  else root.setAttribute("data-theme", id);
+}
+```
+
+Mesma armadilha: só funciona pras marcas cujo CSS **está no bundle**. Se o app oferece N
+marcas ao usuário, importe os N overlays — e valide o id contra a lista que você importou,
+não contra as 5 do DS.
+
+## Criar um tema novo
+
+Marca muda **somente cor**. Spacing, sizing, radius, elevation e tipografia vêm sempre da
+`default` — não há como uma marca alterá-los, por design. Se o pedido envolve mudar
+espaçamento ou fonte "só nesta marca", **não é tema** — é outra coisa, pergunte.
+
+Criar marca é trabalho no **repo do DS**, não aqui: 3 arquivos em `tokens/brands/<id>/`
+(palette + color-light + color-dark, mesmo contrato de nomes da default) e
+`npm run tokens:brand:<id>`. Neste projeto você **consome** o resultado. Se o usuário
+quer uma marca que não existe, o caminho é abrir a demanda no DS — não improvisar CSS
+sobrescrevendo tokens aqui (isso quebra o `protect-ds` e sai do sistema).
+
+## Nunca faça
+
+- Sobrescrever CSS var de tema na unha (`--color-bg-brand: ...`) pra "simular" uma marca.
+  Use overlay; var solta divergem do dark, dos status e do resto do sistema.
+- Duplicar o overlay dentro do projeto pra editar cor. Ele é gerado; edição some no
+  próximo update.
+- Aplicar `data-theme` num wrapper interno em vez do `<html>`. Os dois blocos do overlay
+  (`[data-theme="x"]:not(.dark)` e `.dark[data-theme="x"]`) assumem marca e modo no MESMO
+  elemento — em elementos diferentes o light vaza pro dark.

package/dist-lib/ai/regras-por-componente.json

@@ -0,0 +1,103 @@
+{
+  "AppShell": [
+    "tem áreas separadas (Comercial, Financeiro…)? → `sidebar=\"menu\"` + `contexts`. Não tem? → `\"single\"` + `categories`, sem `sidebarModules` nem `sidebarShowSearch`",
+    "NÃO passe `sidebarLogo`: o default é a marca iGreen. Só com marca própria pedida explicitamente",
+    "`sidebarTitle` = nome do projeto (vai à direita da logo) — pergunte, não invente"
+  ],
+  "avatar-ig": [
+    "vários avatares juntos → `<AvatarGroup>`, nunca `-ml-*` + `ring` na mão: ele resolve sobreposição por tamanho, cor do anel e excedente",
+    "`<AvatarGroup surface=\"...\">` = a superfície ATRÁS do grupo (`table` numa linha de tabela). Errar isso põe um halo claro em volta de cada avatar",
+    "`max` + `total`: o `+N` conta pelo `total` (o do servidor), senão uma lista paginada mostra `+0` tendo 40 pessoas",
+    "`colorHex` escolhe a cor do texto por contraste WCAG (L-027) — nunca `text-white` na unha",
+    "foto de pessoa → `<Avatar src=\"…\">` com as iniciais em `children` (são o fallback da URL que falha), nunca `<img>` solto nem o compound do shadcn dentro do grupo"
+  ],
+  "Breadcrumb": [
+    "o caminho e o seletor vêm do MESMO item: `import { Breadcrumb, BreadcrumbItem, BreadcrumbSwitcher } from \"@/components/ui/Breadcrumb\"`",
+    "página de DETALHE (ficha de cliente, UC, contrato, chamado) → o item do registro no breadcrumb é `<BreadcrumbSwitcher>`, não texto: quem está numa ficha quer pular pra outra, não voltar à lista",
+    "é controlado e **não navega**: `onValueChange` devolve o `value` e quem decide rota/fetch é você",
+    "no `Header`, o item vira seletor com os TRÊS juntos — `switcher` + `value` + `onValueChange`; faltando um, fica texto",
+    "escolher valor de FORMULÁRIO não é isto: é `combobox` (o trigger dele tem cara de campo de propósito)"
+  ],
+  "CardOption": [
+    "switch = efeito IMEDIATO, sem Salvar, e só em `layout=\"list\"`; tela com botão Salvar → `type=\"checkbox\"`",
+    "opções que se COMPARAM (plano, tier, preço, descrição longa) → cards espaçados; itens do mesmo tipo com rótulo curto (settings, permissões, pagamento, endereço) → `layout=\"list\"`",
+    "mais de ~5 opções → não é CardOption: `Select`/`Combobox`. E on/off de UMA coisa nunca são 2 radios",
+    "`type=\"radio\"` EXIGE `<CardOptionGroup type=\"radio\">` em volta; checkbox e switch funcionam soltos",
+    "em lista o selecionado NÃO pinta por default (a borda ali é a divisória) — queira pintado? `highlightSelected` no grupo",
+    "omita `orientation`, `highlightSelected` e `size`: derivam do type · `md` é o calibrado"
+  ],
+  "DataTable": [
+    "filtro é NATIVO e reativo: `enableColumnFilter` na coluna — nunca select/form solto acima da grade. Pra ele aparecer desde o load (e não ficar escondido atrás do ícone), `showEmptyFilterChips={[\"status\", …]}`",
+    "não fixe `width`: com `autoFit` (default) ele é PISO e entra no rateio, não trava. Travar de verdade = `width` + `maxWidth` iguais",
+    "vazio são DOIS casos distintos: sem dado nenhum → `renderEmpty` (CTA de criar); filtro/busca zerou → `renderNoResults` (o \"limpar filtros\" já vem cabeado)"
+  ],
+  "FloatingPanel": [
+    "painel de DETALHE → siga o bloco `dsgreen-paneldetail-1`, que é o **padrão**. As variações são opt-in: use `-2` (tarefa com abas) ou `-3` (com tabela, `size=\"xl\"`) **só se o usuário citar o ID**",
+    "em todos: identidade ou contexto no `titleSlot`, ações de ícone `soft` + `aria-label` no `headerActions`, ação primária no `footer` — nunca botão de ação solto no corpo",
+    "`bodyPadded={false}` quando usar `FloatingPanelSection` (a section gerencia padding e divisória full-width)",
+    "é REDIMENSIONÁVEL em runtime — nenhuma largura escrita na mão acompanha o arrasto",
+    "aba dentro dele → `<Tabs fullWidth>` na variante default; `line` aqui vira trilho curto"
+  ],
+  "Gantt": [
+    "monte a tela a partir do `example-gantt` (`igreen:add example-gantt`) — é o comportamento COMPLETO, não um toy",
+    "o pai precisa ter ALTURA (o componente é `h-full`): sem isso você vê só a toolbar",
+    "busca do servidor → passe `loading`, senão `rows={[]}` afirma \"Nenhuma tarefa neste período\"",
+    "`colorKey` diz CATEGORIA (qual frente), não status: status vai em `row.trailing` como `Chip`"
+  ],
+  "Kpi": [
+    "`tone` e `KpiDelta tone` são DECISÃO, não derivação: subir nem sempre é bom (tempo de espera ↑ é ruim). `signed` só quando o sinal é literalmente bom/ruim",
+    "o valor sai do preset `stat-*` pela prop `size` (default `md`=24px) — nunca `text-[Npx]` na unha; fora do `Kpi`, `text-stat-* tabular-nums`",
+    "`divided` no `KpiGroup` vira UM card com divisórias e os filhos viram `plain` — não empilhe card dentro de card pra conseguir isso"
+  ],
+  "Modal": [
+    "aba dentro dele → `<Tabs fullWidth>` até o size `lg`; no `xl` (1100px) use hug",
+    "ação destrutiva → `AlertModal`, não confirmação montada na mão"
+  ],
+  "Panel": [
+    "painel de DETALHE → siga o bloco `dsgreen-paneldetail-1` (o **padrão**). `-2` (tarefa com abas) e `-3` (com tabela) só se o usuário citar o ID",
+    "header aqui é só STRING (`title`/`description`): precisa de avatar, Chip de status ou ação de ícone? → `FloatingPanel`",
+    "form dentro dele → `<FormField>` + `gap-form-gap`, nunca `<label>` cru",
+    "aba dentro dele → `<Tabs fullWidth>` na variante default (560px é estreito pro `line`)"
+  ],
+  "ScreenLoader": [
+    "omita `size`: `md` é o calibrado pro slot do AppShell; `lg` não é \"pra dar destaque\"",
+    "omita `skeletonLayout`: `page` serve pra qualquer tela — só mude se ela TEM KPIs no topo",
+    "o pai precisa ter altura, senão a variante spinner colapsa no topo",
+    "loading inline (botão, célula) → `Spinner` direto; overlay é composição do consumidor"
+  ],
+  "SingleMenuSidebar": [
+    "NÃO passe `logo`: o default é a marca iGreen. Só com marca própria pedida explicitamente",
+    "`title` = nome do projeto (vai à direita da logo) — pergunte, não invente",
+    "é a escolha quando NÃO há divisão em áreas: `showSearch={false}`, sem `module`/`modules`"
+  ],
+  "TabsNavigation": [
+    "aba de NAVEGADOR (sessão que abre/fecha: conversa, chamado, registro) → `<TabsNavigation>`; filtro de conteúdo dentro da tela → `tabs` do shadcn",
+    "`<TabsNavigation>` é SEMPRE controlado (`value` + `onValueChange`) e NÃO hospeda conteúdo — o painel pode morar fora, e aí a aba leva `panelId`",
+    "`surface` = a superfície do conteúdo ABAIXO da tira (`surface` num card, `canvas` na página). Errar quebra a união da aba ativa, que é o componente",
+    "`actions` na aba SUBSTITUI o `⋯`+`×` — é por ele que entram ✓/✗ de aceitar/recusar; sem `actions` e sem `onClose` a aba não tem ação"
+  ],
+  "tabs": [
+    "`variant` default (segmented) dentro de superfície (card, bloco, Panel, Modal, drawer); `line` só pra seção de página",
+    "`fullWidth` em superfície compacta; ⛔ nunca `w-full` no List nem `flex-1` no trigger na mão"
+  ],
+  "drawer": [
+    "é bottom-sheet (vaul): mobile ou gesto de arrastar. Detalhe lateral em desktop → `Panel` (bloqueia) ou `FloatingPanel` (coexiste com a lista)",
+    "painel de DETALHE → siga o bloco `dsgreen-paneldetail-1` (o **padrão**). `-2` (tarefa com abas) e `-3` (com tabela) só se o usuário citar o ID"
+  ],
+  "select": [
+    "⛔ nunca `<SelectItem value=\"\">` — é a sentinela do Radix e apaga valor em silêncio",
+    "em form, prefira `FormFieldSelect` (já trata a sentinela e o eco do valor)"
+  ],
+  "card": [
+    "`size` (`sm`/`md`/`lg`) declare SÓ no `<Card>` — Header/Content/Footer herdam por contexto; repetir nas partes é o que deixa uma seção com densidade diferente",
+    "`CardHeader variant=\"banded\"` com ação à direita pede `className=\"flex …\"`, NUNCA `flex-row`: o header é `grid` e `flex-row` não troca o display — o botão cai embaixo do título"
+  ],
+  "alert-dialog": [
+    "confirmação comum → use o composto `ui/AlertModal` (já monta tom + ícone + botões); o primitivo cru só pra caso fora do padrão",
+    "⚠️ ESC FECHA (só o clique fora é bloqueado). Decisão inescapável exige `onEscapeKeyDown={(e) => e.preventDefault()}`"
+  ],
+  "sonner": [
+    "`<Toaster/>` **1× no root**, senão o toast não aparece e não há erro",
+    "card ergonômico (title/description/action) → use o composto `ui/Toast`"
+  ]
+}

package/dist-lib/ai/roteiros/dashboard/blueprint.md

@@ -0,0 +1,47 @@
+> **Nota de portabilidade.** Este roteiro foi extraído do pipeline do iGreen DS
+> para Claude Code. Menções a slash command (`/ds-create-…`), a `.claude/` e a
+> ferramentas daquele ambiente descrevem **como ele é acionado lá** — aqui o
+> equivalente é carregar este roteiro pelo `indice.json`. O conteúdo de decisão
+> (entrevista, blueprint, regras de composição) vale igual.
+
+> **Modo submódulo (`ds-link`).** Existe `.claude/ds-config.json` com `"mode": "submodule"`?
+> Então **NÃO rode `igreen:add`** — esse script não existe no seu projeto. Os componentes e
+> exemplos já estão no disco em `<dsPath>/src`: importe pelo `importBase` do config
+> (compostos) e pelo `primitivesBase` (primitivos shadcn), e **leia** o exemplo direto de
+> `<dsPath>/src/examples/`.
+
+# Dashboard Builder (consumidor) — Blueprint + GATE
+
+Consolide a entrevista num preview de uma tela só e **pare** — ⛔ zero edição antes do "aprovar".
+
+## Preview a apresentar
+
+```
+PAINEL: <nome>  ·  rota <definir com o usuário>  ·  fonte: mock | API(<shape>)
+Wrapper: AppShell + PageHeader | puro     (chrome do print entregue? sim/não)
+
+⚠️ Inferido (não perguntei) — vete se discordar:
+  • <decisão> → <o que muda se vetar>       [ou: nenhuma]
+
+MAPA DE ROWS (top → bottom):
+  Row 1 — [hero/insight?]                         (opcional)
+  Row 2 — KPI-group "Painel do Líder" · N cols    (§1)  KPIs: <label · tom · delta(signed?)> …
+  Row 3 — <gráfico principal> (2/3) + <donut/resumo> (1/3)   (§2)
+  Row 4 — <ranking / fusão KPI+evolução?>         (§3)
+  Row 5 — <card dividido / mapa?>                 (§4)
+  Row 6 — <tabela | lista embutida?>              (§5/§6 → delega crud/list-builder)
+
+Primitivos (igreen:add): kpi · chart · panel · <data-table|data-list?> · example-dashboard (base)
+```
+
+## Pré-validações
+- [ ] É mesmo dashboard (2+ tipos de seção)? Senão → rotear pro builder certo.
+- [ ] Cada gráfico com tipo + séries; cabe no padrão (skill `charts`).
+- [ ] KPI delta: `signed` só onde sinal = bom/ruim; senão tom explícito.
+- [ ] Ícone: KPI-group = círculo; mini-stat/legenda = quadrado.
+- [ ] Tabela/lista embutida delega a crud/list-builder; distribuição correta.
+- [ ] Layout estreito não coloca cards lado-a-lado apertados; zero hardcode.
+
+## Gate
+Apresentar mapa de rows + pré-validações numa tela só. Aguardar `aprovar` → `generate.md`;
+`ajustar X` → re-montar; `cancelar` → abortar (zero edits). **Não tocar em arquivo antes do aprovar.**

package/dist-lib/ai/roteiros/dashboard/entrevista.md

@@ -0,0 +1,62 @@
+> **Nota de portabilidade.** Este roteiro foi extraído do pipeline do iGreen DS
+> para Claude Code. Menções a slash command (`/ds-create-…`), a `.claude/` e a
+> ferramentas daquele ambiente descrevem **como ele é acionado lá** — aqui o
+> equivalente é carregar este roteiro pelo `indice.json`. O conteúdo de decisão
+> (entrevista, blueprint, regras de composição) vale igual.
+
+> **Modo submódulo (`ds-link`).** Existe `.claude/ds-config.json` com `"mode": "submodule"`?
+> Então **NÃO rode `igreen:add`** — esse script não existe no seu projeto. Os componentes e
+> exemplos já estão no disco em `<dsPath>/src`: importe pelo `importBase` do config
+> (compostos) e pelo `primitivesBase` (primitivos shadcn), e **leia** o exemplo direto de
+> `<dsPath>/src/examples/`.
+
+# Dashboard Builder (consumidor) — Entrevista (fases 0–6)
+
+Uma pergunta (ou grupo curto) por vez. Acumule as escolhas — **ZERO edição em disco**
+até o gate. Use `AskUserQuestion` pra escolhas fechadas; proponha um default sensato.
+As receitas de cada seção estão no `generate.md` (§1–§6) + no `example-dashboard`.
+
+## Fase 0 — Intent + fonte
+- Do que é o painel? (visão geral de quê, pra quem — ex.: painel do líder, resumo de
+  categoria, financeiro consolidado).
+- Dados: mock ou API? Se API, anote o shape → a geração cria mock tipado espelhando.
+- Período/segmentação no topo? (quase sempre → PeriodSelector no `actions` do PageHeader).
+
+- **Envelope (wrapper)** — verifique antes de perguntar: existe `AppShell`? A referência
+  mostra rail/menu/header? Chrome sem shell → ofereça `/ds-create-app` junto; recusado →
+  registre no blueprint o que do print fica de fora.
+
+## Fase 1 — KPIs rápidos ("Painel do Líder", §1)
+- Quais métricas rápidas? (label + valor + tom do ícone).
+- Delta? O sinal é literalmente bom/ruim → `signed`. Senão, tom explícito (tempo ↓ = success).
+- Quantas colunas (4–6)? → `<KpiGroup columns={N} divided>`.
+
+## Fase 2 — Gráficos (chart-cards, §2)
+- Quais gráficos? Tipo (barras/linha/área/pizza-donut), séries, o que comparam (ver skill `charts`).
+- Cada um num SectionCard (head título+subtítulo discreto). Big-number liderando? Legenda/metric-rows?
+- Donut com total no centro? 2 séries → verde+âmbar; pizza → rampa da marca.
+
+## Fase 3 — Ranking / fusão KPI+evolução (§3)
+- Ranking (reconhecimento, top do mês) ou linha de lista rica que funde identidade +
+  mini-KPIs em colunas + métrica headline com delta (ex.: cidades/licenciados por status)?
+- Se sim: mini-KPIs (label+ícone+tom), métrica headline à direita (delta Chip), identificador (rank/nome/sub).
+
+## Fase 4 — Card dividido em 2 / mapa (§4)
+- Seção que junta dados + visual lado a lado (ex.: barras por UF | mapa)? → card dividido (divisor no 2º painel).
+- Precisa de mapa? (SVG por região/UF + legenda). Anote regiões/UFs.
+
+## Fase 5 — Tabela / lista embutida (delega)
+- Termina com tabela (grade) ou lista (cards) de detalhe?
+- Tabela → geração delega a distribuição de colunas ao `crud-builder` (identidade → status →
+  categóricos → muted → moeda/data à direita; filtros nativos pré-aplicados).
+- Lista/kanban → delega ao `list-builder` (linha1 título+secundário, linha2 meta, status chip,
+  valor à direita; sem botão de ação).
+- Nenhuma → pula.
+
+## Fase 6 — Layout das rows
+- Ordem/agrupamento. Padrão: (1) hero/insight opcional · (2) KPI-group "Painel do Líder" faixa larga ·
+  (3) gráfico principal (2/3) + donut/resumo (1/3) · (4) qualidade/ranking/fusão · (5) listas/tabela.
+- Estreito → 1 card/row + coluna única. Rows 2–3 col via `grid grid-cols-1 lg:grid-cols-{2,3} gap-gp-2xl items-stretch`.
+
+## Fim
+Resumir em 1 frase + `BLUEPRINT_PRONTO: <Painel> (dashboard) — aguardando gate` → carregar `blueprint.md`.