@snksergio/design-system 0.62.0 → 0.64.0

package/dist-lib/ai/exemplos/order-detail/order.types.ts

@@ -0,0 +1,118 @@
+/** Tipos da tela de detalhe de pedido (showcase OrderDetail). */
+
+export type OrderStatus = "paid" | "pending" | "refunded";
+export type FulfillmentStatus = "fulfilled" | "unfulfilled" | "partial";
+
+export interface OrderItem {
+  id: string;
+  name: string;
+  sku: string;
+  /** Preço unitário em centavos? Não — em reais (number) pra simplicidade do mock. */
+  price: number;
+  qty: number;
+  /** Cor do thumb placeholder (hex). */
+  thumb: string;
+}
+
+export interface OrderActivity {
+  id: string;
+  /** Cabeçalho do grupo de data (ex: "Domingo, 06 de março"). */
+  dateGroup: string;
+  title: string;
+  description?: string;
+  time: string;
+  /** true = evento concluído (verde); false = etapa do fluxo (brand). */
+  done?: boolean;
+}
+
+export interface OrderComment {
+  id: string;
+  author: string;
+  initials: string;
+  colorHex?: string;
+  when: string;
+  text: string;
+}
+
+export interface OrderAttachment {
+  id: string;
+  name: string;
+  kind: "pdf" | "image";
+  size: string;
+}
+
+export type OrderTagColor =
+  | "success"
+  | "primary"
+  | "warning"
+  | "neutral"
+  | "danger"
+  | "info";
+
+export interface OrderTag {
+  label: string;
+  color: OrderTagColor;
+}
+
+export interface OrderCustomer {
+  firstName: string;
+  middleName?: string;
+  lastName: string;
+  initials: string;
+  colorHex?: string;
+  email: string;
+  phone: string;
+  customerId: string;
+  accountType: string;
+  registeredAt: string;
+  active: boolean;
+  previousOrders: number;
+}
+
+export interface Order {
+  id: string;
+  status: OrderStatus;
+  fulfillment: FulfillmentStatus;
+  placedAt: string;
+  source: string;
+
+  items: OrderItem[];
+  subtotal: number;
+  shipping: number;
+  tax: number;
+  discountCode?: string;
+  discountLabel?: string;
+  discountValue?: number;
+  total: number;
+
+  customer: OrderCustomer;
+
+  shippingAddress: {
+    line1: string;
+    line2?: string;
+    city: string;
+    state: string;
+    zip: string;
+    country: string;
+    carrier: string;
+    tracking: string;
+    eta: string;
+  };
+
+  billing: {
+    address: string;
+    cityState: string;
+    country: string;
+    method: string;
+    transactionId: string;
+    paymentDate: string;
+  };
+
+  note: string;
+  internalNote: string;
+  tags: OrderTag[];
+
+  activity: OrderActivity[];
+  comments: OrderComment[];
+  attachments: OrderAttachment[];
+}

package/dist-lib/ai/global/componentes.md

@@ -131,6 +131,13 @@ sem passar pela entrevista guiada** (é justamente aí que o erro aparece):
      (`defaultViews`, ex.: "Ativos", "Pendentes"; `allowCreateView={false}` se forem fixas).
 2. **X não é coluna, pequeno e simples** (período/mês, um toggle) → `toolbar.actions`
    (máx ~2, label curta). Período que afeta a página toda → `PageHeader.actions` (dropdown).
+   **Precisa de um COMPONENTE na barra** (um `DatePicker mode="range"` de período)? →
+   `toolbar.customLeft` do `data-table`, que renderiza entre o refresh e a busca —
+   `toolbar.actions` não serve, seus kinds são `button/dropdown/input` e nenhum recebe
+   componente. ⚠️ **Exige o DS `0.64.0` ou mais novo**: em `0.63.0` e anteriores a
+   prop existe no tipo, o TS aceita e **nada renderiza** (era declarada e lida por nada).
+   Confira sua versão antes de prometer o controle — e note que o `data-list` **não tem**
+   esse slot, só `toolbarActions`.
 3. **Muitos filtros, ou muito grandes** → drawer "Filtros" **nativo** do `data-table` + chips
    pré-aplicados. Nunca empilhar selects soltos.
 

package/dist-lib/ai/indice.json

@@ -10,7 +10,8 @@
         "planilha",
         "colunas"
       ],
-      "rota": "skill `crud-builder` (`/ds-create-crud`) — entrevista guiada"
+      "rota": "skill `crud-builder` (`/ds-create-crud`) — entrevista guiada",
+      "roteiro": "crud-builder"
     },
     {
       "sinais": [
@@ -20,7 +21,8 @@
         "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)"
+      "rota": "skill `crud-builder` (`/ds-create-crud`) — kanban é `viewMode` do DataTable; ref. `example-finance` (kanban por situação)",
+      "roteiro": "crud-builder"
     },
     {
       "sinais": [
@@ -28,7 +30,8 @@
         "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)"
+      "rota": "skill `crud-builder` (`/ds-create-crud`) — é `viewMode:\"list\"` + `listConfig` do DataTable (não DataList paralelo)",
+      "roteiro": "crud-builder"
     },
     {
       "sinais": [
@@ -40,7 +43,8 @@
         "treeview",
         "feed de cards"
       ],
-      "rota": "skill `list-builder` (`/ds-create-list`) — entrevista guiada"
+      "rota": "skill `list-builder` (`/ds-create-list`) — entrevista guiada",
+      "roteiro": "list-builder"
     },
     {
       "sinais": [
@@ -58,7 +62,8 @@
         "novo x",
         "multi-step"
       ],
-      "rota": "skill `page-edit` → `example-edit-page`"
+      "rota": "skill `page-edit` → `example-edit-page`",
+      "roteiro": "page-edit"
     },
     {
       "sinais": [
@@ -68,7 +73,8 @@
         "página de x com abas",
         "visão geral do pedido"
       ],
-      "rota": "skill `page-detail` → `example-order-detail`"
+      "rota": "skill `page-detail` → `example-order-detail`",
+      "roteiro": "page-detail"
     },
     {
       "sinais": [
@@ -80,7 +86,8 @@
         "esqueci a senha",
         "tela de login"
       ],
-      "rota": "skill `auth-builder` (`/ds-create-login`) → `example-login` (fullscreen, painel por tokens)"
+      "rota": "skill `auth-builder` (`/ds-create-login`) → `example-login` (fullscreen, painel por tokens)",
+      "roteiro": "auth-builder"
     },
     {
       "sinais": [
@@ -89,7 +96,8 @@
         "visão geral",
         "indicadores"
       ],
-      "rota": "skill `dashboard-builder` (`/ds-create-dashboard`) — entrevista → gate → geração ancorada no `example-dashboard`"
+      "rota": "skill `dashboard-builder` (`/ds-create-dashboard`) — entrevista → gate → geração ancorada no `example-dashboard`",
+      "roteiro": "dashboard-builder"
     },
     {
       "sinais": [
@@ -97,7 +105,8 @@
         "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)"
+      "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": [
@@ -105,7 +114,8 @@
         "chart",
         "barras/linha/área/pizza"
       ],
-      "rota": "skill `charts` → `Chart/USAGE.md` + `example-dashboard`"
+      "rota": "skill `charts` → `Chart/USAGE.md` + `example-dashboard`",
+      "roteiro": "charts"
     },
     {
       "sinais": [
@@ -123,13 +133,15 @@
         "conversas",
         "atendimento"
       ],
-      "rota": "skill `chat` → `example-chat`"
+      "rota": "skill `chat` → `example-chat`",
+      "roteiro": "chat"
     },
     {
       "sinais": [
         "drawer/painel de criar/editar/ver detalhe"
       ],
-      "rota": "skill `drawers` → drawers do `example-finance`"
+      "rota": "skill `drawers` → drawers do `example-finance`",
+      "roteiro": "drawers"
     },
     {
       "sinais": [
@@ -138,7 +150,8 @@
         "painéis soltos",
         "seções"
       ],
-      "rota": "skill `cards` → `Card`/`Panel` + showcase"
+      "rota": "skill `cards` → `Card`/`Panel` + showcase",
+      "roteiro": "cards"
     },
     {
       "sinais": [
@@ -154,7 +167,8 @@
         "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)"
+      "rota": "skill `app-builder` (`/ds-create-app`) → `example-app-shell` (AppShell + nav-data + mapa de rotas declarativo)",
+      "roteiro": "app-builder"
     },
     {
       "sinais": [
@@ -162,7 +176,8 @@
         "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"
+      "rota": "skill `module-replicator` (`/ds-replicate-module`) — avalia copiar × parametrizar; troca dados/rótulos, mantém estrutura",
+      "roteiro": "module-replicator"
     },
     {
       "sinais": [

package/dist-lib/ai/manifest.json

@@ -1,16 +1,42 @@
 {
   "pacote": "@snksergio/design-system",
-  "versao": "0.62.0",
-  "commit": "7cd6db7",
-  "gerado": "2026-09-15",
+  "versao": "0.64.0",
+  "commit": "cb0a1bf",
+  "gerado": "2026-09-16",
   "conteudo": {
     "roteiros": [
-      "dashboard"
+      "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,
-    "arquivosDeExemplo": 3,
-    "residuoClaudeCode": 8
+    "rotasComRoteiro": 15,
+    "arquivosDeExemplo": 108,
+    "arquivosDeBloco": 4,
+    "residuoClaudeCode": 42
   }
 }

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.