@snksergio/design-system 0.61.0 → 0.63.0

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/app-builder/roteiro.md

@@ -0,0 +1,155 @@
+> **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.
+
+
+# app-builder — Esqueleto de aplicação (AppShell + navegação + rotas)
+
+O "chassi" onde as telas moram. Não é uma tela de conteúdo — é o shell + nav +
+roteamento. Conteúdo de cada tela vem depois dos builders (crud/list/dashboard).
+Não gere de memória: puxe e adapte o exemplo.
+
+## Passo 0 — duas perguntas ao usuário, nesta ordem
+
+### 1. Como o projeto se chama?
+
+Vai **à direita da logo** na sidebar (`sidebarTitle`), na raiz do breadcrumb e no título da
+aba. É a única coisa deste passo que o DS não adivinha — e `sidebarTitle` é obrigatória de
+propósito, pra o TS cobrar a pergunta.
+
+### 2. O app tem módulos?
+
+⚠️ **Vocabulário — leia ANTES de formular a pergunta.** A mesma coisa tem três nomes na boca
+do usuário: **módulo**, **workspace** e, às vezes, **categoria**. E "categoria" é armadilha:
+na API da sidebar única, `categories` são os **grupos do menu**, não os módulos — a palavra
+nomeia os dois lados da escolha. Então **não** use "categoria" na pergunta, e **não** use
+nome de componente (`MenuSidebar`/`SingleMenuSidebar`): descreva **o que aparece na tela**.
+
+**Espelhe a palavra do usuário** — se ele disse "módulo" ou "workspace", use a dele. **Exceto
+"categoria"**: essa é ambígua e você **não pode** adivinhar. Se ele disse "categorias",
+desambigue antes de qualquer coisa:
+
+> *"Quando você fala 'categorias', são **áreas grandes**, cada uma com o menu dela — tipo
+> Comercial, Financeiro, Suporte? Ou são os **grupos dentro de um menu só** — tipo Cadastros,
+> Relatórios, Configurações?"*
+
+**Se ele JÁ listou as áreas** ("tenho Comercial, Financeiro e Suporte"), **não pergunte do
+zero** — recomende e confirme numa linha: *"Como você tem 3 áreas separadas, vou de menu com
+a coluna de módulos à esquerda (é o link X). Confirma?"*.
+
+Fora isso, ofereça **duas** opções, e só essas duas — **com recomendação**, não neutro:
+
+> *"Seu sistema é dividido em áreas grandes e separadas — tipo Comercial, Financeiro,
+> Suporte — cada uma com o menu dela? Ou é um sistema só, com um menu único?*
+>
+> *1. **Tem áreas separadas** — cada área vira um ícone numa coluna estreita à esquerda, e o
+> menu dela (com submenus) abre ao lado:
+> https://igreen-desingsystem-admin.vercel.app/#/menu-sidebar*
+>
+> *2. **É um sistema só** — sem a coluna de ícones: só o nome do projeto no topo e, abaixo, os
+> grupos do menu com seus submenus:
+> https://igreen-desingsystem-admin.vercel.app/#/single-menu-sidebar*
+>
+> *Pelo que você me contou, eu iria de **<a que você inferiu>** — mas abra os dois links e me
+> diga."*
+
+⚠️ **Recomende sempre uma das duas**, com o motivo em meia linha ("porque você tem 3 áreas
+distintas" / "porque é um sistema só"). Pergunta neutra devolve a decisão pra quem não conhece
+os componentes — e foi assim que um consumidor escolheu errado sem querer (2026-08-22).
+
+| resposta | `sidebar` | dados | o que NÃO passar |
+|---|---|---|---|
+| **tem áreas/módulos** | `"menu"` (default) | `contexts` | — |
+| **é um sistema só** | `"single"` | `categories` | `sidebarModules` e `sidebarShowSearch` — é a variação **"Sem módulo / sem busca"** |
+
+**Regra de tendência:** existe divisão → `"menu"`. Não existe → `"single"` enxuta. A sidebar
+única **também** aceita módulos (`sidebarModules`), e é justamente o que não oferecer: quando
+existe divisão, o rail da `"menu"` mostra as áreas todas de uma vez, enquanto na única elas
+ficam atrás de um botão acima da busca. Quer conhecer as outras variações? Mande a página do
+componente — ampliar o leque na entrevista é o que produz escolha errada.
+
+```tsx
+<AppShell
+  sidebar="single"
+  categories={CATEGORIES}
+  sidebarTitle="Meu Sistema"     {/* ← o nome do projeto, à direita da logo */}
+  activeItemId={ativo}
+  onSidebarItemClick={setAtivo}
+  breadcrumb={[{ label: "Meu Sistema" }]}
+>…</AppShell>
+```
+
+### Logo e nome — aplique, não pergunte
+
+- **A logo é a da iGreen, sempre.** **Não passe `sidebarLogo`** — o default já é a marca
+  (lib 0.46.0+; antes a prop era obrigatória, e trocar pra sidebar única fazia a logo da
+  iGreen desaparecer, porque a API pedia outra). Só troque se o usuário pedir marca própria
+  **explicitamente**, e aí ele fornece o arquivo. **Nunca pergunte "qual logo?"**.
+- **O nome do projeto vai à direita dela** — é a resposta da pergunta 1.
+- Numa lib anterior a essa a prop é obrigatória: passe
+  `sidebarLogo={<SidebarBrandMark />}` (de `@/components/ui/MenuSidebar/sidebar-brand`) em
+  vez de inventar uma.
+
+**O AppShell monta as DUAS** (lib ≥ 0.41.0). O tipo é união discriminada: o TS cobra o
+conjunto certo pra cada escolha. O toggle do Header funciona nos dois sem cabeamento — e na
+variante `single` ele **sai** do Header no desktop, porque a sidebar tem o próprio botão (no
+mobile volta, senão não haveria como abrir).
+
+⚠️ **Não ligue `sidebarShowSearch`** se o Header já tem `commandGroups` — seriam duas buscas
+na mesma tela. O shell entrega a busca da sidebar **desligada** por default.
+
+> ⚠️ **Até o CLI 0.25.0 esta seção dizia o contrário** — que o AppShell só montava com
+> `menu-sidebar`, porque o `single-menu-sidebar` "não tem colapso nem drawer mobile". **Era
+> falso**: ele tem colapso controlado (`expanded`) e tem mobile. Se você montou layout na mão
+> por causa dessa instrução, agora dá pra usar o AppShell.
+
+**Item de menu com destino → declare `href`** (as duas sidebars emitem `<a>`: ctrl+clique e
+nova aba funcionam). Com router próprio, passe
+`renderLink={({ href, ...rest }) => <Link to={href} {...rest} />}`.
+
+**AppShell dentro de container com altura** (layout com footer seu, aba, preview) →
+`fillHeight`. Sem isso ele mede 100vh, transborda e o conteúdo fica cortado na base.
+
+## Fluxo
+
+1. `npm run igreen:add -- example-app-shell` (traz o esqueleto + AppShell, MenuSidebar, Header, PageHeader).
+2. **Leia** `src/examples/app-shell/` — 3 arquivos:
+   - `nav-data.ts` — contextos (módulos do rail) + itens/subitens + helpers.
+   - `routes.tsx` — **mapa de rotas declarativo** (href → tela) + resolveRoute.
+   - `app-shell-example.tsx` — o cabeamento do AppShell (não costuma mexer).
+   + `src/components/ui/AppShell/USAGE.md`.
+3. Adapte: **`nav-data.ts`** (os módulos/telas do app do usuário) e **`routes.tsx`**
+   (uma linha por tela; troque `<StubPage/>` pela tela real conforme for criando).
+4. Ligue ao seu app (renderize `<AppShellExample/>` na raiz, ou copie o cabeamento).
+   `npx tsc --noEmit` limpo.
+
+> **Modo submódulo (ds-link).** Se existe `.claude/ds-config.json` com `"mode": "submodule"`,
+> componentes/exemplos JÁ estão em `<dsPath>/src` — **não** rode `igreen:add`. Use `importBase`
+> do config e leia o exemplo em `<dsPath>/src/examples/app-shell/`.
+
+## Gotchas do tipo
+
+- **Rota é um MAPA declarativo, não `if/else`**: registrar tela = 1 linha em
+  `ROUTES` (`"#/path": () => <Screen/>`). Nunca reintroduza a cadeia de `if`.
+- **AppShell é controlled pra navegação real**: ligue `activeContextId`/`onContextChange`
+  + `activeItemHref`/`onItemClick` ao seu router; `href` = path. Os `default*` são só
+  pro modo uncontrolled/preview.
+- **breadcrumb + ⌘K + notificações derivam da nav** (não hardcode): veja como o
+  exemplo mapeia `NAV_ENTRIES` → commandGroups e a entry ativa → breadcrumb.
+- **Tema**: o exemplo usa state local que alterna `.dark` no `<html>`. Se o app já
+  tem provider de tema, ligue nele (`theme` + `onThemeChange`).
+- **Conteúdo NÃO vai aqui**: cada tela é um builder (crud/list/dashboard). O shell
+  só navega e resolve a rota.
+- Fullscreen sem outro shell por volta. Body do AppShell já tem padding próprio —
+  **responsivo**: 18px (<768) · 24px (768–1535) · 32px (≥1536). Não adicione padding
+  por fora nem por dentro do slot.
+- **O menu NASCE COLAPSADO abaixo de 1536px.** Notebook (1366/1440) abre com o rail,
+  ganhando ~264px de largura útil. Se o app precisa do menu sempre aberto, passe
+  **`defaultMenuCollapsed={false}` explícito** — o default responsivo só vale quando a
+  prop é omitida. É aplicado **só no mount**: não reage a resize, de propósito (senão
+  brigaria com quem abriu o menu na mão). Abaixo de 768px o menu vira drawer e ignora
+  isso.
+
+Aplique `DESIGN.md` + `.claude/rules/ds-design.md`. Handoff: `APP_PRONTO: <app>` + rotas.

package/dist-lib/ai/roteiros/auth-builder/roteiro.md

@@ -0,0 +1,42 @@
+> **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.
+
+
+# auth-builder — Tela de login / autenticação
+
+Tela de login split (form + painel de marca) usando o padrão do DS. Não gere de
+memória — puxe e adapte o exemplo.
+
+## Fluxo
+
+1. `npm run igreen:add -- example-login` (traz a tela + `Button`, `FormField`).
+2. **Leia** `src/examples/login/login-screen.tsx` + `src/components/ui/FormField/USAGE.md`.
+3. Adapte ao caso: marca/copy do painel direito, campos do form (email/senha,
+   ou telefone/código, SSO…), e o handler `entrar` (plugue a auth real).
+4. Registre a rota onde o usuário indicar (login é fullscreen, sem AppShell).
+   `npx tsc --noEmit` limpo.
+
+> **Modo submódulo (ds-link).** Se existe `.claude/ds-config.json` com `"mode": "submodule"`,
+> o DS é consumido como **submódulo** (não copy-in): componentes/exemplos JÁ estão no disco
+> em `<dsPath>/src` e **não** há registry. Use `importBase` do config (ex.: `@ds/components/ui/FormField`)
+> e leia o exemplo direto em `<dsPath>/src/examples/login/login-screen.tsx` — **NÃO** rode `igreen:add`.
+
+## Gotchas do tipo
+
+- **Login é fullscreen SEM chrome de app** — não embrulhe em `AppShell`/`MenuSidebar`.
+  Root = `flex min-h-screen ... items-center justify-center bg-bg-canvas`.
+- **Sempre `<FormField>`** (FormFieldInput/Checkbox) — nunca `<label>` cru (L-023).
+  Spacing do form = `gap-form-gap` (L-024). Inputs `min-h-form-xl` (44px, WCAG mobile).
+- **Painel de marca = 100% tokens, sem imagem externa** (evita "imagem quebrada"):
+  `bg-bg-brand` + camadas decorativas via `var(--color-fg-on-brand)` + texto
+  `text-fg-on-brand`. Some no mobile (`hidden lg:flex`). Se PRECISAR de foto, use
+  caminho base-aware (`import.meta.env.BASE_URL`), nunca `/arquivo.png` absoluto.
+- **Botão Entrar** = `<Button color="primary" variant="filled" size="lg" className="w-full">`.
+  Toggle de senha = `<button type="button">` no `endAddon` do FormFieldInput.
+- Ring/focus por token (`focus-visible:ring-4 focus-visible:ring-ring-brand`), nunca
+  `outline-none` sozinho.
+
+Aplique `DESIGN.md` + `.claude/rules/ds-design.md`. Handoff: `LOGIN_PRONTO: <marca>` + rota.

package/dist-lib/ai/roteiros/cards/roteiro.md

@@ -0,0 +1,34 @@
+> **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.
+
+
+# cards — Composição de cards/painéis
+
+**(Guia de composição, não puxa example.)** Cards são blocos; a tela ao redor
+segue `DESIGN.md`. Para uma TELA inteira baseada em cards (dashboard), use a skill `dashboard-builder` (`/ds-create-dashboard`).
+
+## Fluxo
+1. `npm run igreen:add -- card` (shadcn Card: `Card`/`CardHeader`/`CardTitle`/`CardContent`/`CardFooter`) — bloco simples.
+2. `npm run igreen:add -- panel` (iGreen `Panel` + `CardHead`) — card com cabeçalho título+subtítulo+ação, usado em dashboards.
+3. **Leia** os respectivos `USAGE.md`. Para ver variações montadas, consulte o **showcase hospedado**: https://igreen-desingsystem-admin.vercel.app
+4. Componha os cards na tela do usuário; `npx tsc --noEmit` limpo.
+
+> **Modo submódulo (ds-link).** Se existe `.claude/ds-config.json` com `"mode": "submodule"`,
+> o DS é consumido como **submódulo** (não copy-in): os componentes/exemplos JÁ estão no disco
+> em `<dsPath>/src` e **não** há registry. Use `importBase` do config (ex.: `@ds/components/ui/Panel`)
+> e leia os `USAGE.md`/exemplos direto em `<dsPath>/src` — **NÃO** rode `igreen:add`.
+
+## Gotchas do tipo
+- Card: use o componente **`<Card>`** (não replique a superfície na unha — a lista de classes que estava aqui divergia do componente real em 3 itens). Densidade pela prop **`size`**: `sm` 16px · **`md` 20px (default)** · `lg` 24px, e ela vale pro `CardHeader`/`CardContent`/`CardFooter` juntos (declare só no `<Card>`).
+- Header em faixa: **`<CardHeader variant="banded">`** — fundo `bg-bg-subtle` + divisória embaixo, encostado nas bordas. Aceita qualquer estrutura dentro e acompanha o `size`. Use quando a seção precisa de cabeçalho destacado (ficha, detalhe, formulário por etapas).
+- Título de card: **não passe `font-*`** — `text-title-md` já é semibold (600) por preset.
+- Grid de cards: `grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-gp-md`.
+- KPI card: label `caption-md`/`uppercase` em `fg-muted` + valor grande **`text-stat-lg`/`text-stat-md` + `tabular-nums`** (nunca `display-*`/`heading-*`) + opcional `Chip` de tendência. (Ver `example-dashboard`.)
+- Card de seção (label/valor): título da seção `title`, linhas rótulo (`fg-muted`) + valor.
+- Dark mode: sombra vira borda hairline (automático via token).
+- **Don't:** não invente padding/gap avulso — no `<Card>` a densidade é a prop `size`, e fora dele use `p-pad-card-*` e `gap-gp-*`; não use hex (cor por token); não empilhe cards "grudados" (`gap-gp-md` entre eles).
+
+Aplique `DESIGN.md`. Handoff: `CARDS_PRONTO`.

package/dist-lib/ai/roteiros/charts/roteiro.md

@@ -0,0 +1,32 @@
+> **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.
+
+
+# charts — Gráficos (Chart / Recharts 3)
+
+## Fluxo
+1. `npm run igreen:add -- chart` (e `example-dashboard` se quiser gráfico em contexto de painel).
+2. **Leia** `src/components/ui/Chart/USAGE.md` (API: `ChartContainer` + `ChartConfig`) + os gráficos em `src/examples/dashboard/dashboard-screen.tsx`.
+3. Monte o gráfico dentro de `<ChartContainer config={...}>`; cor só por token.
+4. Registre a rota/local onde o usuário indicar. `npx tsc --noEmit` limpo.
+
+> **Modo submódulo (ds-link).** Se existe `.claude/ds-config.json` com `"mode": "submodule"`,
+> o DS é consumido como **submódulo** (não copy-in): os componentes/exemplos JÁ estão no disco
+> em `<dsPath>/src` e **não** há registry. Use `importBase` do config (ex.: `@ds/components/ui/Chart`)
+> e leia `<dsPath>/src/components/ui/Chart/USAGE.md` + `<dsPath>/src/examples/dashboard/dashboard-screen.tsx`
+> direto — **NÃO** rode `igreen:add`.
+
+## Gotchas do tipo
+- Gráfico SEMPRE em `<ChartContainer config={...}>`; cor só por token (`chart-1..5` / chaves do config). 2 séries = verde (`chart-1`) + âmbar (`chart-4`); pizza = rampa monocromática da marca.
+- Grid: `<CartesianGrid vertical={false} strokeDasharray="4 4" />` (token `chart-grid`, **sem** passar `stroke` — o `ChartContainer` reescreve via token).
+- Card do gráfico: `Panel`/`Card` + título (`title`/`heading`).
+- **Caveats do Recharts 3 (quebram mudo):**
+  1. `text-display-sm`/`display-xs` **não existem** → valor de KPI usa **`text-stat-{sm,md,lg,xl}`** (20/24/30/34px, bold, com `tabular-nums`). Nunca `display-*`/`heading-*` pra número de indicador.
+  2. Pizza: sem `activeIndex`/`activeShape` → use `shape={(props,index)=><Sector/>}`.
+  3. Radial empilhado/gauge parcial → `<PolarAngleAxis type="number" domain={[0,total]} />`.
+  4. Eixo Y omite tick de borda (ex.: `0`) → `interval={0}`; `domain` máximo = maior tick (senão linha-guia duplicada no topo).
+
+Aplique `DESIGN.md`. Para uma TELA inteira de painel, use a skill `dashboard-builder` (`/ds-create-dashboard`). Handoff: `CHART_PRONTO: <tipo>`.

package/dist-lib/ai/roteiros/chat/roteiro.md

@@ -0,0 +1,31 @@
+> **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.
+
+
+# chat — Inbox / conversas
+
+Tela de chat: coluna de conversas + thread de mensagens + composer.
+
+## Fluxo
+1. `npm run igreen:add -- example-chat` (traz a tela + componentes).
+2. **Leia** `src/examples/chat/chat-screen.tsx` + os sub-componentes (ConversationColumn, etc) + USAGE dos componentes DS usados.
+3. Adapte canais, conversas e mensagens aos dados do usuário.
+4. Registre a rota. `npx tsc --noEmit` limpo.
+
+> **Modo submódulo (ds-link).** Se existe `.claude/ds-config.json` com `"mode": "submodule"`,
+> o DS é consumido como **submódulo** (não copy-in): os componentes/exemplos JÁ estão no disco
+> em `<dsPath>/src` e **não** há registry. Use `importBase` do config (ex.: `@ds/components/ui/avatar-ig`)
+> e leia o exemplo direto em `<dsPath>/src/examples/chat/chat-screen.tsx` —
+> **NÃO** rode `igreen:add`.
+
+## Gotchas do tipo
+- Chat ocupa 100% da altura disponível: wrapper `flex flex-col h-full min-h-0` (sem o gap-2xl de página comum — a tela é edge-to-edge).
+- Layout em colunas: lista de conversas (largura fixa) + thread (flex-1) + opcional painel de detalhe.
+- Avatares de pessoa via **`avatar-ig`** (`@/components/ui/avatar-ig`) — cor por `colorHex` quando custom, com contraste WCAG automático. O item `avatar` do registry é o Radix puro e **não** tem `colorHex`.
+- Status de canal/online via dot/`Chip`.
+- Scroll independente por coluna; composer fixo no rodapé da thread.
+
+Aplique `DESIGN.md` + regras. Handoff: `CHAT_PRONTO` + rota.

package/dist-lib/ai/roteiros/crud-builder/blueprint.md

@@ -0,0 +1,63 @@
+> **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/`.
+
+# CRUD Builder — Blueprint [GATE]
+
+Consolide a entrevista num preview ÚNICO e **pare** pra aprovação. Nenhuma edição
+em disco antes do "aprovar".
+
+## Apresente ao usuário
+
+```
+Entidade:        <Nome>   (tipo <NomeRow>)
+Modo:            client | server (endpoint: ...)
+Onde:            <PAGES_DIR>/<Arquivo>.tsx  · registro: <REGISTRO>
+Wrapper:         AppShell + PageHeader | puro   (chrome do print entregue? sim/não)
+Colunas:         <campo:tipo[:sortable][:editável]>, ... (primária: <campo>)
+Busca/Filtros:   busca=<sim/não> · filtros=<col:tipo, ...>
+Ações linha:     <editar, excluir(confirm AlertModal), ...>   · seleção/bulk: <...>
+Export:          <não | escopo tudo/filtrado/selecionado · csv>
+Views:           presets=<nome → filtro>, ...   · do usuário=<sim/não · savedViewsService+persistId>
+Paginação/virt:  <pageSize / virtualize>   · totalizadores: <colunas>
+Drawers:         criar/editar=<sim/não> · campos=<campo:obrigatório?:máscara?> · detalhe=<sim/não>
+Estados:         loading=<skeleton> · vazio=<msg + CTA> · sem-resultado=<msg + limpar>
+Kanban:          <não | campo de agrupamento>
+Componentes a puxar: data-table[, example-finance p/ drawers][, alert-modal p/ excluir][, ...]
+```
+
+## ⚠️ Decisões inferidas — vete se discordar
+
+Depois do bloco acima, liste **só** o que o usuário não disse e você decidiu sozinho —
+uma linha cada, com o que muda se ele vetar. Sem inferência → `nenhuma`; não apague a
+seção: é a ausência dela que faz a decisão passar aprovada em pacote.
+
+```
+⚠️ Inferido (não perguntei):
+  • wrapper = puro       → a tela nasce SEM rail/menu/header
+  • tema = light         → a referência mostrava dark
+  • <coluna> = <tipo>    → confiança baixa (inferido só pelo nome do campo)
+```
+
+## Pré-validações (rode ANTES de pedir aprovação)
+- Todo filtro tem operador compatível com o filterType (multiSelect⇒isAnyOf, text⇒contains, date⇒between, number⇒gte/lte/between, boolean⇒equals).
+- `virtualize` ⇒ paginação off + container com altura. `groupBy`/kanban ⇒ paginação off.
+- Kanban: cada lane mapeia uma option do campo de agrupamento.
+- Coluna `actions` se há ações por linha; cada action tem `id` único.
+- **Ação `destructive` (excluir) ⇒ tem `AlertModal` de confirmação no plano.**
+- **Os 3 estados (loading/vazio/sem-resultado) estão definidos** (mesmo que com default).
+- Nome/rota da página sem colisão.
+
+Liste qualquer ajuste necessário. Só depois pergunte: **"Aprovar e gerar?"**
+
+- `aprovar` → carregue `generate.md`.
+- pedir mudança → ajuste o blueprint e reapresente.
+- `cancelar` → encerre (zero edições).

package/dist-lib/ai/roteiros/crud-builder/entrevista.md

@@ -0,0 +1,139 @@
+> **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/`.
+
+# CRUD Builder — Entrevista
+
+Pergunte em fases, **uma pergunta de cada vez quando possível**, acumulando as
+escolhas. NÃO edite arquivo nenhum aqui. Ao fim, vá pro `blueprint.md`.
+
+## ⛔ Perguntas obrigatórias (NUNCA pular, mesmo que dê pra inferir)
+
+A IA tende a inferir tudo e ir direto pro blueprint — **não faça isso**. Estas duas
+são sempre explícitas:
+
+1. **Colunas** — mesmo que dê pra inferir do nome da entidade, **LISTE** as colunas
+   inferidas (campo · rótulo · tipo) e **confirme** (adicionar/remover/reordenar) +
+   pergunte se **alguma tem particularidade** (ordenável, editável inline, alinhamento,
+   fixar/pin, largura, filtro, totalizador). Nunca gere com colunas só inferidas.
+2. **Views salvas** — **sempre OFEREÇA e explique** (não trate como "off" silencioso):
+
+   > "Quer **views salvas**? São abas com filtros + ordenação + colunas/densidade
+   > pré-configurados (ex.: _Ativos_, _Alto valor_, _Atrasados_). O usuário troca de
+   > recorte num clique — sem precisar de uma tela nova pra cada um."
+
+   Pergunte quais (nome + filtro + sort). Default = nenhuma, **mas só depois de perguntar**.
+
+## Fase 0 — Entidade & origem dos dados
+
+- Qual entidade? (ex.: Clientes, Pedidos, Faturas) → vira o nome da tela/tipo.
+- Dados **client-side** (array em memória/mock) ou **server-side** (fetch paginado da API)?
+  - Server: qual o endpoint/forma de buscar? (vira `fetchData` em `useCallback`).
+- Onde a página vai morar e como registra a rota? (`PAGES_DIR`/`REGISTRO`).
+
+## Fase 1 — Página e shell
+
+| Pergunta | Default |
+| --- | --- |
+| Título da página | plural da entidade |
+| Descrição (1-2 frases) | gerada do domínio, confirmar |
+| **Wrapper** | ver abaixo |
+| Onde mora + como registra a rota | `PAGES_DIR` / `REGISTRO` do seu projeto |
+
+**Antes de perguntar o wrapper, VERIFIQUE** — as duas respostas costumam decidir sozinhas:
+
+1. existe `AppShell` no projeto? (grep em `src/`)
+2. a referência que o usuário deu — print, Figma, tela existente — mostra rail/menu/header?
+
+- **`AppShell` + `PageHeader`** → chrome na referência **e** shell disponível. Sem perguntar.
+- **componente puro** (no seu `PAGES_DIR`) → sem referência visual, ou app sem shell e sem
+  chrome na referência.
+- **chrome na referência e SEM shell no projeto** → **pare e ofereça `/ds-create-app` junto**.
+  Se o usuário recusar, o blueprint diz em **linha destacada** o que do print não vai ser
+  entregue.
+
+> Print de app inteiro + pedido de "uma tela" é **`shell + tela`**, não `tela`. Foi este
+> recorte que fez uma tela nascer sem o menu que o print mostrava. A regra de o que é da
+> referência e o que é do DS está em `_claude/rules/ds-design.md`.
+
+---
+
+## Fase 2 — Colunas
+
+Pra cada coluna: campo, rótulo, **tipo** (text, number, currency, percentage, date,
+datetime, email, phone, url, status/badge, boolean, user, tags, actions), e se é
+sortable / editável (inline). Pergunte quais colunas o usuário quer e em que ordem.
+Marque a coluna "primária" (a que abre detalhe / leva avatar).
+
+**`copyable` é inferido, não perguntado** — marque nas colunas cujo valor a pessoa
+**cola em outro lugar** (documento, e-mail, telefone, conta/chave PIX, protocolo/NF/
+rastreio, token, ID externo) e **só** nelas; nome, status, data, valor e quantidade
+ficam de fora. Não abra pergunta própria pra isso: **declare** as colunas marcadas
+quando apresentar a lista de colunas, junto do tipo e do filtro, pra o usuário tirar
+em lote ("CNPJ sem copyable"). Critério completo e limites: `generate.md` item 4.
+
+## Fase 3 — Busca, filtros & ações
+
+> ⛔ **Anti-pattern — NUNCA gerar form/selects soltos ACIMA da tabela.** Intenção de
+> "adicionar filtro" (select de status em cima, campo de período, "filtrar por X") →
+> **sugira o padrão certo** (a tabela já filtra reativo, com chips clicáveis/editáveis):
+>
+> - **Filtro por COLUNA** (status/categoria/tipo/data…) → `enableColumnFilter` +
+>   `filterType`. Quer abrir já filtrado? **pré-aplique** (`defaultViews`/`presetView`
+>   ou `filterModel`) → abre com o **chip aplicado**, editável, reativo. Pode pré-setar
+>   **vários** (id/período/status/…), sem campos.
+> - **toolbar.actions é SÓ pra caso pequeno e simples que NÃO reage com coluna** (ex.:
+>   data/período, escopo) — **label curta**, **máx ~2**. Se mexe com coluna, é grande, ou
+>   são muitos → **NÃO use o toolbar.**
+> - **Muitos filtros, ou ligados a coluna** → SEMPRE os nativos **pré-aplicados** (chips no
+>   load) + drawer "Filtros". Nunca empilhar selects.
+>
+> Regra de ouro: **filtro é recurso da tabela (reativo), não UI montada na unha.**
+
+- Busca global? (`enableSearch`)
+- Filtros por coluna? **Default = TODAS as colunas de dados filtram** (`enableColumnFilter: true` + `filterType` por tipo) — pergunte só "alguma NÃO deve filtrar?". O funil/drawer só lista colunas com `enableColumnFilter`; marcar só 2 = bug. (Ver §Regras de coluna em `generate.md`.)
+- Ações por linha (editar, excluir, ...)? (coluna `actions`, `getActions`) — vai por **último**; o DataTable ancora à direita/estreita sozinho (sem `pinned`/`width`). NÃO setar `width` nas demais (autoFit distribui).
+  **Toda ação destrutiva (Excluir) → confirmação OBRIGATÓRIA via `AlertModal`** (nunca
+  deletar direto). Pergunte o texto do confirm.
+- Seleção + ações em massa (exportar, etc.)? (`selectionConfig` + bulk actions).
+- Export: escopo (tudo / filtrado / selecionado) + formato (csv)? (`toolbar.enableExport`).
+- Ação custom no toolbar (ex.: seletor de período/mês, botão extra)? `toolbar.actions: ToolbarAction[]` (`button`/`dropdown`/`input`) — inline no desktop, colapsa no ⋯ no mobile. Oferecer só se o usuário pedir.
+
+## Fase 4 — Views, paginação & densidade
+
+- Views (ver bloco obrigatório). Dois sabores, pergunte os dois:
+  - **Presets fixos** que VOCÊ define (`defaultViews`/`presetView`, ex.: "Ativos", "Alto valor").
+  - **Views do usuário**: ele cria/salva/persiste as próprias (`savedViewsService` + `persistId`).
+- Paginação (tamanho inicial, opções) ou virtualização (10k+ linhas)?
+- Totalizadores no rodapé? (`showTotalizers` + `aggregate`).
+
+## Fase 5 — Criar/editar/detalhe (drawers)
+
+- Precisa criar/editar registro? → drawer estilo `NovoClienteDrawer` (Panel + FormField).
+  - **Quais campos no form?** (default: espelha as colunas editáveis). Pra cada campo:
+    **obrigatório?** **máscara** (CNPJ / telefone / CEP / moeda)? **validação** (formato,
+    min/max)? Todo label via `<FormField>` (nunca `<label>` cru) + `gap-form-gap`.
+- Precisa ver detalhe ao clicar na linha? → `FinanceDetailPanel` (FloatingPanel).
+- (Puxar `example-finance` na geração pra reusar esses padrões.)
+
+## Fase 6 — Kanban (opcional)
+
+- Quer alternar tabela↔kanban? Se sim: qual campo agrupa as colunas (ex.: status)?
+  Cada lane = uma option desse campo. (`viewMode` controlado + `kanbanConfig`.)
+
+## Fase 7 — Estados (SEMPRE perguntar — sai faltando se não)
+
+- **Loading** (`loading` + `renderLoading`): skeleton enquanto carrega — obrigatório em server mode.
+- **Vazio** (`renderEmpty`): sem nenhum registro → "Nenhuma `<entidade>` ainda" + CTA _Adicionar_.
+- **Sem resultado** (`renderNoResults`): filtro/busca sem match → "Nenhum resultado" + _Limpar filtros_.
+- (Aceite defaults sensatos se o usuário não quiser customizar — mas **sempre wire os três**.)
+
+Ao terminar: resuma as escolhas e siga pro `blueprint.md` (gate).