@snksergio/design-system 0.61.0 → 0.63.0

package/dist-lib/ai/indice.json

@@ -0,0 +1,192 @@
+{
+  "rotas": [
+    {
+      "sinais": [
+        "tabela",
+        "grade",
+        "grid de dados",
+        "crud",
+        "datatable",
+        "planilha",
+        "colunas"
+      ],
+      "rota": "skill `crud-builder` (`/ds-create-crud`) — entrevista guiada",
+      "roteiro": "crud-builder"
+    },
+    {
+      "sinais": [
+        "kanban",
+        "board",
+        "funil",
+        "pipeline de vendas",
+        "quadro por status/etapa"
+      ],
+      "rota": "skill `crud-builder` (`/ds-create-crud`) — kanban é `viewMode` do DataTable; ref. `example-finance` (kanban por situação)",
+      "roteiro": "crud-builder"
+    },
+    {
+      "sinais": [
+        "tabela e lista no mesmo lugar",
+        "alternar tabela/lista",
+        "toggle de visão tabela↔lista"
+      ],
+      "rota": "skill `crud-builder` (`/ds-create-crud`) — é `viewMode:\"list\"` + `listConfig` do DataTable (não DataList paralelo)",
+      "roteiro": "crud-builder"
+    },
+    {
+      "sinais": [
+        "lista de cards",
+        "árvore",
+        "hierarquia",
+        "rede/organograma",
+        "níveis",
+        "treeview",
+        "feed de cards"
+      ],
+      "rota": "skill `list-builder` (`/ds-create-list`) — entrevista guiada",
+      "roteiro": "list-builder"
+    },
+    {
+      "sinais": [
+        "lista",
+        "listagem de x"
+      ],
+      "rota": "PERGUNTE \"grade de colunas ou cards?\" → `crud-builder` ou `list-builder` (ou front-door `/ds-create-screen`)"
+    },
+    {
+      "sinais": [
+        "formulário",
+        "cadastro",
+        "tela de edição",
+        "editar x",
+        "novo x",
+        "multi-step"
+      ],
+      "rota": "skill `page-edit` → `example-edit-page`",
+      "roteiro": "page-edit"
+    },
+    {
+      "sinais": [
+        "detalhe",
+        "detalhamento",
+        "ficha",
+        "página de x com abas",
+        "visão geral do pedido"
+      ],
+      "rota": "skill `page-detail` → `example-order-detail`",
+      "roteiro": "page-detail"
+    },
+    {
+      "sinais": [
+        "login",
+        "entrar",
+        "acesso",
+        "autenticação",
+        "sign in",
+        "esqueci a senha",
+        "tela de login"
+      ],
+      "rota": "skill `auth-builder` (`/ds-create-login`) → `example-login` (fullscreen, painel por tokens)",
+      "roteiro": "auth-builder"
+    },
+    {
+      "sinais": [
+        "dashboard",
+        "painel",
+        "visão geral",
+        "indicadores"
+      ],
+      "rota": "skill `dashboard-builder` (`/ds-create-dashboard`) — entrevista → gate → geração ancorada no `example-dashboard`",
+      "roteiro": "dashboard-builder"
+    },
+    {
+      "sinais": [
+        "tabela + detalhe ao lado",
+        "clicar abre o detalhe",
+        "filtro no topo que muda tudo"
+      ],
+      "rota": "skill `screen-composer` — master-detail / cross-filter; monta as peças pelos builders + cabeia o estado compartilhado (a receita está na própria skill)",
+      "roteiro": "screen-composer"
+    },
+    {
+      "sinais": [
+        "gráfico",
+        "chart",
+        "barras/linha/área/pizza"
+      ],
+      "rota": "skill `charts` → `Chart/USAGE.md` + `example-dashboard`",
+      "roteiro": "charts"
+    },
+    {
+      "sinais": [
+        "financeiro",
+        "extrato",
+        "saldo",
+        "transações"
+      ],
+      "rota": "`example-finance` (puxar + adaptar)"
+    },
+    {
+      "sinais": [
+        "chat",
+        "inbox",
+        "conversas",
+        "atendimento"
+      ],
+      "rota": "skill `chat` → `example-chat`",
+      "roteiro": "chat"
+    },
+    {
+      "sinais": [
+        "drawer/painel de criar/editar/ver detalhe"
+      ],
+      "rota": "skill `drawers` → drawers do `example-finance`",
+      "roteiro": "drawers"
+    },
+    {
+      "sinais": [
+        "cards",
+        "blocos",
+        "painéis soltos",
+        "seções"
+      ],
+      "rota": "skill `cards` → `Card`/`Panel` + showcase",
+      "roteiro": "cards"
+    },
+    {
+      "sinais": [
+        "igual ao exemplo de <x>",
+        "estrutura do <x>"
+      ],
+      "rota": "puxar `example-<X>` e adaptar"
+    },
+    {
+      "sinais": [
+        "esqueleto do app",
+        "estrutura/base do app",
+        "shell + navegação + rotas",
+        "montar o app do zero"
+      ],
+      "rota": "skill `app-builder` (`/ds-create-app`) → `example-app-shell` (AppShell + nav-data + mapa de rotas declarativo)",
+      "roteiro": "app-builder"
+    },
+    {
+      "sinais": [
+        "replica o módulo x igual ao y",
+        "mesma estrutura pra outro segmento/vertical",
+        "clonar telas"
+      ],
+      "rota": "skill `module-replicator` (`/ds-replicate-module`) — avalia copiar × parametrizar; troca dados/rótulos, mantém estrutura",
+      "roteiro": "module-replicator"
+    },
+    {
+      "sinais": [
+        "que componente uso pra x",
+        "tem componente de y?",
+        "quais opções pra abas / filtro / data",
+        "o que o ds tem pra formulário"
+      ],
+      "rota": "rule `.claude/rules/ds-components.md` — vocabulário dos componentes por tarefa, com o critério de escolha. Não é pedido de tela: responda pela rule, não abra builder"
+    }
+  ]
+}

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,42 @@
+{
+  "pacote": "@snksergio/design-system",
+  "versao": "0.63.0",
+  "commit": "d9db4cd",
+  "gerado": "2026-09-15",
+  "conteudo": {
+    "roteiros": [
+      "app-builder",
+      "auth-builder",
+      "cards",
+      "charts",
+      "chat",
+      "crud-builder",
+      "dashboard-builder",
+      "drawers",
+      "list-builder",
+      "module-replicator",
+      "page-detail",
+      "page-edit",
+      "screen-composer"
+    ],
+    "exemplos": [
+      "app-shell",
+      "chat",
+      "clientes",
+      "dashboard",
+      "edit-page",
+      "finance",
+      "gantt",
+      "login",
+      "mapa-rede",
+      "order-detail"
+    ],
+    "componentes": 47,
+    "componentesComRegra": 19,
+    "rotas": 19,
+    "rotasComRoteiro": 15,
+    "arquivosDeExemplo": 108,
+    "arquivosDeBloco": 4,
+    "residuoClaudeCode": 42
+  }
+}

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.