@snksergio/design-system 0.60.0 → 0.62.0

package/dist-lib/ai/exemplos/dashboard/index.ts

@@ -0,0 +1 @@
+export { DashboardScreen, default } from "./dashboard-screen";

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

@@ -0,0 +1,217 @@
+
+# Que componente usar (iGreen DS)
+
+Os nomes abaixo são os **ids do registry**. Para trazer um: `npm run igreen:add -- <id>`
+— exceto em **modo submódulo** (existe `.claude/ds-config.json` com `"mode": "submodule"`),
+onde tudo já está no disco em `<dsPath>/src` e você só importa pelo `importBase`.
+
+**Onde está a API** (não invente props — nenhuma das duas fontes é sua memória):
+
+- **Compostos do iGreen** (`components/ui/<Nome>/`) vêm com **`USAGE.md` ao lado** — props,
+  variants, gotchas. Leia antes de compor.
+- **Primitivos** não têm USAGE por arquivo (a API é a padrão shadcn/Radix, e eles já chegam
+  re-estilizados nos tokens do DS) — mas **têm índice de pegadinhas**:
+  **`.claude/skills/ds-kit/shadcn-gotchas.md`**. Leia antes de montar `select`, `sonner`,
+  `tabs`, `tooltip` e os flutuantes: são gotchas que não dão erro, só resultado errado.
+  ⚠️ No copy-in eles caem em **`components/ui/` como arquivo solto** (`ui/badge.tsx`,
+  `ui/input.tsx`, `ui/avatar.tsx`), não numa pasta `components/shadcn/` — os itens de
+  COMPONENTE do registry apontam para `components/ui/` (os demais vão pra `src/lib`,
+  `src/utils`, `src/styles/theme` e `examples/`). Importe `@/components/ui/badge`.
+  ⚠️ Em **modo submódulo** o layout é OUTRO: você lê o repo do DS, onde os primitivos ficam
+  em `<importBase-irmão>/components/shadcn/<nome>` (kebab) e só os compostos em
+  `components/ui/<Nome>`. O `ds-config.json` traz os dois caminhos (`importBase` e
+  `primitivesBase`).
+
+Catálogo visual: **https://igreen-desingsystem-admin.vercel.app**.
+
+> Não existe "componente shadcn" vs "componente iGreen" pra você: todos chegam por
+> `@igreen/<nome>` e todos já seguem os tokens do DS. Escolha pela tarefa, não pela origem.
+
+> **Escopo desta regra: QUAL componente.** Como estilizar (tokens, spacing, foco, cor,
+> tipografia) está em `ds-design.md` — deliberadamente não repetido aqui, pra as duas
+> regras não divergirem.
+
+## Formulário
+
+`form-field` é wrapper **obrigatório** de todo campo — nunca `<label>` cru (ele cuida de
+label, helper, erro e do `htmlFor`).
+
+| Precisa de | Use |
+|---|---|
+| texto curto / longo | `input` · `textarea` |
+| escolher de uma lista | `select` — muitas opções + busca → `combobox` |
+| liga/desliga | `switch` (aplica na hora) · `checkbox` (confirma no submit) |
+| **escolha em CARD** (área grande, label + descrição) — plano, frete, permissão, lista de settings | **`card-option`** — o controle é prop: type = checkbox \| radio \| switch. **switch = efeito IMEDIATO, sem Salvar, e só com layout=list (Apple HIG: switch mora em linha de lista); 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, meio de pagamento, endereço) → layout=list. On/off de UMA coisa nunca são 2 radios: é switch (imediato) ou 1 checkbox (com submit). Mais de ~5 opções → não é card-option: `select` ou `combobox`. type=radio exige CardOptionGroup em volta. Em lista o selecionado NÃO pinta por default (ali a borda do item é a divisória) — queira o pintado, ligue highlightSelected no grupo. Omita orientation, highlightSelected e size (derivam do type; md é o padrão) |
+| escolha em bloco visual, só checkbox | `card-checkbox` — atalho de `card-option` com `type="checkbox"`; componente novo usa `card-option` |
+| uma entre várias | `radio-group` (campo compacto) — em card, `card-option` com `type="radio"` |
+| data | `date-picker` — `mode`: `single` (default) · `range` · `multiple` |
+| só mês/ano | `month-year-picker` |
+| agenda de EVENTOS (não é campo de data) | `scheduler` — ver o grupo de dados |
+| CRONOGRAMA com dependência entre tarefas | `gantt` — ver o grupo de dados |
+| arquivo | `file-upload-field` |
+| código / OTP | `input-otp` — mesmos `size` (`xxs`/`xs`/`sm`/`md`) e `state` do `input`, então num form misto use o MESMO size dos dois. `variant`: `connected` (default) · `outlined` · `filled` · `underline` |
+| cor | `color-picker` |
+| faixa numérica | `slider` |
+| prefixo, sufixo, ícone ou botão **dentro** do campo | `input-group` — não componha na mão |
+
+## Abas e alternância de visão
+
+- `tabs` — seções de conteúdo. Duas props no `<Tabs>` (propagadas por contexto, nunca no
+  List/Trigger): **`variant`** `"segmented"` (default) dentro de superfície — card, bloco,
+  Panel, FloatingPanel, Modal, drawer · `"line"` para seções de página. **`fullWidth`** em
+  superfície compacta; hug em toolbar/página. ⛔ nunca `w-full`/`flex-1` na mão.
+- `tabs-navigation` — **abas de NAVEGADOR**, não de conteúdo: cada aba é uma **sessão aberta**
+  (conversa, chamado, registro) que o usuário abre, troca e fecha, com avatar/ícone, status e
+  ações próprias. Critério: se o usuário **abre e fecha** as abas → `tabs-navigation`; se as seções
+  são fixas dentro da tela → `tabs`. É controlado (`value`/`onValueChange`) e **não hospeda o
+  conteúdo** — o painel pode morar em outra coluna ou rota (aí a aba leva `panelId`). ⛔ nunca
+  monte a tira na mão com margem negativa: a união da aba ativa com o conteúdo é o componente.
+- `button-group` — ações relacionadas lado a lado; uma dispara, **não guarda estado**.
+- `toggle-group` — modo ou filtro que **persiste** · `toggle` para um só, on/off.
+- ⚠️ Alternar tabela ↔ cards dos **mesmos dados** não é nenhum dos três: é `viewMode`
+  do `data-table` (com `listConfig`). Não monte duas telas paralelas.
+
+## Feedback e estado
+
+| Situação | Use |
+|---|---|
+| notificação rica (title, description, ação) | `toast` — **prefira este** |
+| toaster cru | `sonner` — monte `<Toaster/>` 1× no root; o `toast` roda sobre ele |
+| aviso fixo dentro da página | `alert` |
+| confirmar ação destrutiva | `alert-modal` — **obrigatório** antes de excluir, nunca delete direto |
+| sem dados / primeira vez | `empty-state` |
+| **página/área inteira carregando** (slot de conteúdo, card, section) | `screen-loader` — spinner centrado + título/subtítulo (default) ou `variant="skeleton"` genérico (skeletonLayout: page default · dashboard · kpis). Preenche o PAI (que precisa ter altura); omita size (md é o padrão). NÃO é overlay nem loading inline |
+| carregando pedaço com layout conhecido / ação pontual | `skeleton` (silhueta custom composta na mão) · `spinner` (pontual, inline em botão) |
+| progresso conhecido | `progress` |
+
+## Sobreposição (o que cobre a tela)
+
+| Quando | Use |
+|---|---|
+| clique, ancorado, conteúdo curto | `popover` |
+| lista de ações a partir de um gatilho | `dropdown-menu` |
+| clique com o botão direito | `context-menu` |
+| hover: dica de 1 linha / prévia rica | `tooltip` · `hover-card` |
+| **bloqueia** a página, centralizado | `modal` (body já rola sozinho — não trate scroll no children) |
+| **bloqueia**, lateral, mais espaço que o modal | `panel` (560px default) · `sheet` · `drawer` (mobile, gesto) |
+| **não** bloqueia — coexiste com a lista atrás, resizável | `floating-panel` |
+| **painel de DETALHE** (o que abre ao clicar na linha da tabela ou no card) | **use o bloco `dsgreen-paneldetail-1` — ele é o PADRÃO.** A estrutura já está resolvida ali: identidade no header, métricas em cards compactos, campos em seções colapsáveis por assunto, ação primária no footer, e sem aba (o colapso já é o mecanismo de esconder). Precisa de avatar/chip/ação no header → é `floating-panel`, porque no `panel` o header é só string.<br><br>**Variações são opt-in — só monte se o usuário citar o ID:** `dsgreen-paneldetail-2` (detalhe de TAREFA: título grande no corpo, propriedades em lista plana, abas pra anexo/comentário/log) · `dsgreen-paneldetail-3` (com TABELA dentro: ficha em 2 colunas + métricas + tabela compacta, e aí o painel vai a `xl` 720px). Não escolha entre as três por conta própria: sem o ID citado, o padrão é o `-1` |
+| diálogo cru, sem o chrome do DS | `dialog` · `alert-dialog` |
+
+Todo flutuante já segue a mesma receita visual (superfície frosted, radius 12,
+`shadow-sh-lg`). Não re-estilize.
+
+## Dados em grade e lista
+
+| Precisa de | Use |
+|---|---|
+| grade com colunas: filtros, visões, seleção, kanban, virtualização | `data-table` — o completo |
+| tabela simples, sem inteligência | `table` |
+| rodapé de paginação/page-size/contagem | `footer-table` — já embutido no `data-table` |
+| lista de **cards** com filtros, visões, hierarquia/árvore | `data-list` |
+| lista de cards simples | `list` |
+| quadro por status/etapa | `kanban` — ou `viewMode: "kanban"` do `data-table` |
+| **eventos ao longo do TEMPO** (agenda, compromissos, reservas) | **`scheduler`** — 4 views numa prop só: `month` · `week` · `day` · `list`. Toolbar embutida (período, busca, filtros, seletor de view). **Não confundir com `calendar`/`date-picker`, que escolhem uma DATA num campo** — aqui o assunto são eventos. Dumb sobre mutação: arrastar emite `onEventMove`/`onEventResize` e QUEM APLICA é você (mesma gramática do `onCardMove` do kanban). Filtro é declarativo (`filterFields`) e abre num painel-COLUNA à direita, não em overlay. **O pai precisa ter altura** — o componente é `h-full`, e é a altura dele que decide quantos eventos cabem na célula do mês. Detalhe do evento é SEU: o componente só emite `onEventClick` e devolve `event.meta` intacto; monte o painel com o bloco `dsgreen-paneldetail-2`. `draggable`/`resizable` nascem `false` de propósito: ligados sem handler, o usuário arrasta e vê o evento voltar |
+| **cronograma de PROJETO** (o que depende do quê, prazo, caminho crítico) | **`gantt`** — hierarquia com collapse à esquerda, eixo de tempo à direita, e **setas de dependência** entre as barras. É a seta que distingue: sem ela isto seria uma timeline, e timeline é o `scheduler`. Quatro tipos de vínculo (finish-to-start, start-to-start, finish-to-finish, start-to-finish) com espera/antecipação em dias. Linha agrupadora deriva o intervalo dos filhos; marco vira losango. **Dumb sobre mutação como o kanban**: arrastar emite evento e QUEM APLICA é você — o componente detecta conflito de prazo e sinaliza, mas nunca reagenda. **O pai precisa ter altura** (é `h-full`), e um cronograma legível pede ~900px de largura. A cor da barra diz CATEGORIA (qual frente), não status — status vai no slot livre da linha como `chip`. Detalhe da tarefa é SEU: o componente emite o clique e devolve o payload intacto. ⭐ **Antes de montar a tela, rode `igreen:add example-gantt`** — é a extração 1:1 do showcase do DS (20 linhas em 4 níveis, 16 vínculos, 2 conflitos, os 4 gestos APLICANDO, as 3 visões, filtro nos 6 kind, painel de detalhe e drawer). O `USAGE.md` descreve a API; o exemplo mostra o COMPORTAMENTO junto, que é onde a composição erra. Troque `_gantt-data.tsx` primeiro |
+| paginar algo que não é tabela | `pagination` |
+
+### ⛔ Filtro em tabela/lista → SEMPRE nativo, nunca form/select acima
+
+"Filtrar por X" numa grade/lista **não** é montar select ou form acima da tabela — isso
+empilha UI na unha, come espaço e foge do padrão. Filtro é **recurso reativo** do
+`data-table`/`data-list`. Aplique esta hierarquia **sempre — inclusive em pedido em lote e
+sem passar pela entrevista guiada** (é justamente aí que o erro aparece):
+
+1. **X é uma coluna** (status, categoria, tipo, graduação… — o caso normal, ~90%):
+   - Na coluna: `enableColumnFilter: true` + `filterType` + `filterOptions`.
+   - **Deixe o filtro visível na tabela**: `showEmptyFilterChips={["status", …]}` — o chip
+     nasce **vazio e clicável** já no load, o usuário vê a afordância sem abrir menu nenhum.
+   - Abrir **já filtrado** → `defaultViews`/`presetView` com filtros pré-aplicados (`filterModel`) → chip aplicado.
+   - Status é o **eixo de navegação** (poucos valores, muito usado) → **uma visão por valor**
+     (`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).
+3. **Muitos filtros, ou muito grandes** → drawer "Filtros" **nativo** do `data-table` + chips
+   pré-aplicados. Nunca empilhar selects soltos.
+
+> As exceções (2 e 3) são raras. Sempre que a informação já está numa coluna: **chip nativo
+> primeiro**. Exemplo vivo do padrão: `example-clientes` (status/categoria pré-aplicados +
+> chip vazio de "Atribuído"). Entrevista guiada completa em `/ds-create-crud`.
+
+## Layout e chrome do app
+
+- `app-shell` — a casca (rail de módulos + header + área de conteúdo). **Embutido em container com altura** (layout com footer, aba, preview) → passe `fillHeight`; sem isso ele mede 100vh, transborda e o conteúdo fica cortado na base.
+- `header` — barra superior de 60px (breadcrumb, busca, tema, usuário) dentro do shell.
+- **Menu lateral — a escolha depende de o app ter módulos, então PERGUNTE:**
+  - **tem áreas separadas** (Comercial, Financeiro…), cada uma com menu próprio → `menu-sidebar` (rail + contextos). É o que o `app-shell` usa.
+  - **sistema único**, um menu só → `single-menu-sidebar` (nível único). No `app-shell` passe `sidebar="single"` + `categories` + `sidebarLogo` + `sidebarTitle`. ⚠️ **Não** ligue `sidebarShowSearch` se o header já tem busca — o shell já entrega a da sidebar desligada. (Até o CLI 0.25.0 esta linha dizia que o `single-menu-sidebar` não encaixava no `app-shell`: era **falso**, ele tem colapso e mobile.)
+  - Nas duas: item com destino declara `href` (vira `<a>`, então ctrl+clique e nova aba funcionam). Router próprio → `renderLink`.
+
+  > 🧭 **O app tem router (react-router, Next, TanStack)? Passe `renderLink`.**
+  > `<AppShell renderLink={(p) => <Link {...p} to={p.href} />} … />`
+  >
+  > O menu renderiza `<a href={item.href}>`. Sem `renderLink`, um `item.href` de **path**
+  > (`/clientes`) fazia o browser **recarregar a página inteira** a cada clique — bug
+  > reportado por consumidor e corrigido na v0.38.0. Alternativa: passar `onItemClick`
+  > (aí o menu cancela a navegação nativa sozinho, preservando ctrl+clique, link externo
+  > e `item.href` de hash). Detalhe: `MenuSidebar/USAGE.md` §Integração com router.
+- `page-header` — título + ações + breadcrumb **dentro** do body.
+- `card` — container de conteúdo · `separator` · `scroll-area` (scroll estilizado) ·
+  `aspect-ratio`.
+- Esconder/mostrar conteúdo: `accordion` (várias seções abrindo) · `collapsible` (uma) ·
+  `carousel` (deslizar horizontal).
+
+## Métrica e gráfico
+
+- `kpi` — `Kpi` / `KpiGroup` / `KpiDelta` para cards de métrica e faixas de indicadores.
+- `chart` — wrapper do Recharts (barras, linha, área, pizza, radar, radial).
+- `choropleth-map` — mapa por região colorido por valor (traz `d3-geo` como dependência).
+
+## Blocos — composições de referência (não são componentes)
+
+Um **bloco** é um arranjo pronto, feito só com os componentes acima, que existe porque o arranjo é
+o que a IA não inventa: você sabe as peças e os tokens, mas não a disposição que um designer
+escolheu. Ele **não tem props nem versão própria** — você lê a estrutura e reconstrói com os dados
+do usuário.
+
+Cada bloco tem um código no formato `dsgreen-<categoria>-<n>`. **Quando o usuário citar um código,
+não classifique intenção** — resolva o código (é o Passo 0 da skill ds-kit).
+
+**A lista dos blocos NÃO está aqui**, de propósito: ela vive em
+`.claude/skills/ds-kit/blocks-index.md`, que é **gerado** a partir dos arquivos e carregado **só
+quando um código é citado**. Esta regra é `alwaysApply` — listar cada bloco aqui faria o custo de
+contexto crescer a cada bloco novo, e o catálogo é feito pra crescer. Bloco só entra em jogo quando
+o humano cita um ID, então não há caso em que você precise descobrir blocos sem ser provocada.
+
+O catálogo **visual** fica na seção **Blocks** do showcase do DS — é de lá que o usuário tira o
+código.
+
+## Identidade, status e navegação
+
+- `avatar` — compound Radix, pra fallback que NÃO é iniciais (ícone, skeleton) · `avatar-ig` — o avatar do DS: iniciais com presets de cor **e foto** (`src`, com as iniciais de `children` como fallback da URL que falha). Foto de pessoa → `avatar-ig`. **Vários avatares juntos → `AvatarGroup` (do mesmo item `avatar-ig`), nunca `-ml-*`+`ring` na mão:** ele resolve sobreposição por tamanho, cor do anel (`surface` = o que está ATRÁS) e excedente (`max`+`total`, sendo `total` a contagem do servidor)
+  (escolhe preto/branco por contraste WCAG quando recebe hex).
+- `badge` — rótulo estático · `chip` — pílula de status/tag/filtro, pode ser interativa.
+- `icon` — ícones do DS, incluindo o set de marca `igreen-*`.
+- `breadcrumb` — caminho de navegação. Em página de **detalhe**, o item do registro aberto
+  pode virar seletor: `<BreadcrumbSwitcher>` (vem no mesmo item) transforma o nome do que está
+  aberto em gatilho de uma lista com busca — quem está numa ficha quer pular pra outra, não
+  voltar à lista. É controlado e **não navega** (`onValueChange` devolve o valor; rota é sua),
+  e no `header` o item do breadcrumb vira seletor com `switcher`+`value`+`onValueChange`
+  juntos. ⛔ escolher valor de formulário não é isto: é `combobox`.
+- `menubar` (barra de menus estilo desktop) · `navigation-menu` (mega-menu).
+- `label` — só fora de formulário; **dentro** de form quem cuida é o `form-field`.
+
+## Comando e texto
+
+- `command` — paleta de comandos / busca com teclado (⌘K).
+- `markdown-text` — renderizar markdown (chat, descrições vindas de API).
+- `calendar` — calendário inline; para **campo** de data use `date-picker`, para exibir EVENTOS use `scheduler`, e para CRONOGRAMA com dependência entre tarefas use `gantt`.
+- `button` — ação. Variações (cor, tamanho, ícone, loading) na própria API; ver o USAGE.
+
+---
+
+**Não achou o que precisa?** Antes de compor na unha, confira o catálogo visual. E para
+**telas inteiras** não escolha componente a componente: use `/ds-create-crud` (tabela),
+`/ds-create-list` (cards) ou `/ds-create-dashboard` (painel) — eles entrevistam e montam a
+tela no padrão, e existem `example-*` prontos pra adaptar. Adaptar sempre ganha de escrever
+do zero.

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

@@ -0,0 +1,182 @@
+# DESIGN.md — guia de construção de telas (iGreen DS)
+
+> Guia **enxuto** pra montar telas no padrão dos showcases do iGreen DS. Você
+> (consumidor) **já tem os componentes** em `src/components/ui/` — então este
+> arquivo NÃO re-documenta API de componente (isso é o `USAGE.md` ao lado de cada
+> um). Aqui ficam as decisões de **composição, espaçamento, cor e
+> responsividade** que não cabem num USAGE isolado.
+>
+> **Para a IA:** ao montar qualquer tela → siga este arquivo + o `USAGE.md` do
+> componente + o **exemplo** mais próximo. O orquestrador `.claude/skills/ds-kit`
+> escolhe a rota. Nunca invente API, cor ou espaçamento.
+
+---
+
+## Regra de ouro
+
+1. **Não comece do zero.** Puxe o exemplo mais próximo (`npm run igreen:add -- example-<x>`) e adapte — são extrações 1:1 dos showcases de produção.
+2. **Leia o `USAGE.md`** do componente antes de usar (variantes, props, gotchas).
+3. **Classe DS antes de Tailwind literal** (ver Do/Don't).
+4. **Não edite tokens** — consuma via classe semântica (`bg-bg-brand`, `text-fg-default`, `gap-gp-md`).
+
+---
+
+## 1. Atmosfera
+
+CRM/operações vestindo uniforme de energia sustentável: telas **densas** (tabelas, forms, kanban), canvas branco, **verde de marca** `#00803C` como acento que sinaliza "ação" (usado com parcimônia — o sistema é majoritariamente cinza). Fonte **Geist**; corpo interativo **13px/500** (`body-sm`) — lê mais "encorpado" que texto de leitura, é o que dá a densidade confiante. Radius padrão 10px. **Sem gradiente, sem glass, sem animação decorativa, sem `scale()` no clique.** Workspace, não landing page.
+
+---
+
+## 2. Anatomia de uma tela (o que mais importa)
+
+Toda página segue este esqueleto (veja `FinanceScreen`/`ClientesScreen`):
+
+```tsx
+// Conteúdo da página vive dentro do seu AppShell/layout, que dá a altura.
+<div className="flex flex-col h-full min-h-0 gap-gp-2xl">
+  <PageHeader title="..." description="..." badge={...} actions={...} />
+  {/* 16px (gap-gp-2xl) entre o PageHeader e o próximo bloco — NUNCA grudado */}
+  <DataTable ... className="flex-1 min-h-0" />   {/* ou Card / Tabs / grid de KPIs */}
+</div>
+```
+
+**Ritmo de espaçamento (decorar):**
+
+| Onde | Classe | Valor |
+|---|---|---|
+| PageHeader → conteúdo | `gap-gp-2xl` | 16px |
+| Entre fields de um form | `gap-form-gap` | 20px |
+| Entre cards / KPIs | `gap-gp-md` / `gap-gp-lg` | 8–10px |
+| Padding interno de card | Prop `size` do `<Card>`: `sm` 16 · **`md` 20 (default)** · `lg` 24 — tokens `p-pad-card-sm/md/base`. Card montado na unha usa os mesmos tokens. | — |
+| Seção major | `gap-gp-6xl` | 32px |
+| Ícone → texto | `gap-gp-xs` / `gap-gp-sm` | 4–6px |
+
+> Densa, **não apertada**: 16px (`gap-gp-2xl`) é o respiro padrão entre blocos; 8px entre label e input. Espaçamento sempre via token, nunca px avulso. Divisória (`border-border-subtle`) entre seções heterogêneas (toolbar/tabela/footer); whitespace puro entre homogêneas (lista de cards).
+
+### Tokens de componente (use o ESPECÍFICO, não valor genérico)
+
+O DS tem tokens orientados a composição — prefira-os a `h-10`/`gap-4`/`size-5`. Caia no genérico (`gp`/`sp`/`pad`) só pro que não tem token de componente.
+
+| Família | Classes | Quando usar |
+|---|---|---|
+| **Altura de form** | `min-h-form-xs`(28) `sm`(32) `md`(36) `lg`(40 ⭐) `xl`(44) | Botões, inputs, selects, chips. `lg`=desktop default · `xl`=touch WCAG mobile. Nunca `h-9`/`h-10`. |
+| **Gap de form** | `gap-form-gap`(20) | Entre fields de um formulário (vertical ou grid). Nunca `gap-gp-*` em form. |
+| **Ícone** | `size-icon-2xs`(8) `xs`(12) `sm`(16) `md`(20 ⭐) `lg`(24) `xl`(32) `2xl`(40) | Tamanho de ícone. Nunca `size-5`/`w-4 h-4`. |
+| **Padding de card** | `p-pad-card-sm`(16) `p-pad-card-md`(20 ⭐) `p-pad-card-lg`(24) | Padding interno de Card/Panel/Modal/Drawer. No `<Card>` vem pela prop `size` (sm/md/lg) — não escreva a classe na mão ali. ⚠️ `p-pad-card-base` existe e é **alias de `md`** (20px) só por compatibilidade — era 24 até 2026-08-19. Não usar em código novo. |
+| **Gutter de página** | `px-pad-page-sm`(16, mobile) `base`(24) `lg`(40, wide) | Margem lateral do conteúdo (o AppShell normalmente já aplica). |
+| **Altura de chrome** | `h-layout-navbar`(64) `h-layout-toolbar`(48) `h-layout-tab-bar`(56) `h-layout-header-{sm,md,lg}` | Topbar, toolbar de tabela, tab-bar mobile, hero de página. |
+| **Largura/container** | `max-w-{lg,xl,2xl}`(1024/1280/1440) · `max-w-drawer-{sm,md,lg}` · `max-w-dropdown-*` · `max-w-modal-*` · `max-w-tooltip-*` | Cap de conteúdo / largura de drawer/dropdown. ⚠️ **`container` é o ÚNICO namespace que NÃO dobra o prefixo** — `max-w-container-*` **não existe** e não emite CSS. O transform emite `--container-md`, que **sobrescreve** a escala nativa do Tailwind: `max-w-md` já é os **768px do DS**, não os 448px do Tailwind. |
+| **Genéricos** | `gap-gp-*` (gaps) · `p-sp-*` (margin/offset) · `px-pad-*` (padding) | Só quando não há token de componente acima. |
+
+Regra: **se existe token de componente pra aquilo (form/icon/padCard/padPage/layout/container), use ele**; o genérico é fallback.
+
+---
+
+## 3. Cores e tokens
+
+Tokens já vivem em `src/styles/theme/tailwind-theme.css`. Use pelos nomes semânticos — **nunca hex**. Dark mode é automático (tokens trocam sob `.dark`; sem lógica condicional de tema).
+
+**Contrato de 4 papéis** (marca e cada status seguem o mesmo): `{cor}` · `{cor}-subtle` · `{cor}-hover` · `{cor}-subtle-hover`. Não invente tinta intermediária.
+
+| Intenção | Classe |
+|---|---|
+| Ação principal / CTA | `bg-bg-brand text-fg-on-brand` (hover `bg-bg-brand-hover`) |
+| Texto de marca / ghost | `text-fg-brand` · ativo/seleção `bg-bg-brand-subtle` |
+| Texto | padrão `text-fg-default` · secundário `text-fg-muted` · sutil `text-fg-subtle` |
+| Superfície | card `bg-bg-surface` · página `bg-bg-canvas` (separação por borda+sombra, não por bg) |
+| Borda | `border-border-default` · sutil `border-border-subtle` · input `border-border-input` |
+| Destrutivo | `bg-bg-danger`/`text-fg-danger` — **na API de componentes a cor chama `critical`** |
+| Sucesso / aviso / info | `*-success` / `*-warning` / `*-info` |
+| Foco | `focus-visible:outline-none focus-visible:ring-4 focus-visible:ring-ring-{color}` (ring já tem alpha) |
+
+- **Sem azul no sistema.** `info` é **roxo** de propósito (mensagens informativas) — não use azul pra nada.
+- `warning` é claro → texto sobre ele é preto (`fg-on-warning`).
+
+---
+
+## 4. Tipografia
+
+- **`text-body-sm` (13/500) é o default interativo** — botões, inputs, células, dropdowns.
+- 7 papéis: `display-*` / `heading-*` / `title-*` / `body-*` / `caption-*` / `stat-*` / `code-*`. `stat-{sm,md,lg,xl}` (20/24/30/34px) é o valor de KPI/métrica — estático, bold, com `tabular-nums`; nunca `text-[Npx]` na unha. Title default = 600; body de leitura = 400; interativo = 500.
+- Tracking sempre negativo/zero. Override de peso via Tailwind (`text-title-md font-bold`). **Nunca** invente preset nem use `text-xs font-semibold` avulso → use o preset (`text-body-xs`, `text-caption-md`).
+
+---
+
+## 5. Profundidade
+
+- Sombras em **2 camadas** (ambiente + chave); `shadow-sh-{sm,md,lg,xl,2xl}`. Modal = `2xl`. Drawer lateral = `sh-aside` (direcional).
+- **Dark mode troca sombra por borda hairline** — não force sombra no escuro.
+- Foco é `ring` (box-shadow), não muda layout. Ring já vem com alpha — nunca `/30`, nunca `ring-3`.
+
+---
+
+## 6. Mapa intenção → o que puxar / qual skill
+
+A IA roteia isso automaticamente via `.claude/skills/ds-kit`. Resumo:
+
+| O usuário quer… | Rota | Âncora |
+|---|---|---|
+| tabela / lista / crud / grid de dados | **skill `crud-builder`** (`/ds-create-crud`, entrevista guiada) | `example-clientes` |
+| tela de edição / cadastro / formulário | skill `page-edit` | `example-edit-page` + `FormField` |
+| detalhe / detalhamento / ficha (abas) | skill `page-detail` | `example-order-detail` |
+| dashboard / painel / KPIs | skill `dashboard-builder` (`/ds-create-dashboard`) | `example-dashboard` |
+| gráfico (barras/linha/área/pizza) | skill `charts` | `Chart/USAGE.md` + `example-dashboard` |
+| financeiro / extrato / saldo | (exemplo direto) | `example-finance` |
+| chat / inbox / conversas | skill `chat` | `example-chat` |
+| drawer de criar/editar/detalhe | skill `drawers` | drawers do `example-finance` |
+| cards / blocos / painéis soltos | skill `cards` | `Card`/`Panel` + showcase hospedado |
+| lista de cards / árvore / hierarquia / rede | **skill `list-builder`** (`/ds-create-list`) | `example-mapa-rede` + `DataList` |
+| app inteiro (shell + navegação + rotas) | **skill `app-builder`** (`/ds-create-app`) | `example-app-shell` |
+| login / autenticação | **skill `auth-builder`** (`/ds-create-login`) | `example-login` |
+| 2+ peças que conversam (master-detail, cross-filter) | **skill `screen-composer`** (`/ds-create-screen`) | receita na própria skill |
+| replicar módulo existente pra outro domínio | **skill `module-replicator`** (`/ds-replicate-module`) | o módulo de origem |
+| mapa do Brasil por estado/município (coroplético) | componente | `ChoroplethMap` |
+| cabeçalho de página | componente | `PageHeader` |
+| shell / menu lateral / topbar (só a casca) | componentes | `app-shell` / `menu-sidebar` / `header` |
+
+Puxe com `npm run igreen:add -- <item>`. Catálogo visual: **https://igreen-desingsystem-admin.vercel.app**.
+
+---
+
+## 7. ✅ Do / ❌ Don't
+
+```
+❌ 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 / min-h-form-lg (36/40px) · 44px = min-h-form-xl (WCAG mobile)
+❌ ring-3 / ring-ring-brand/30 → ✅ ring-4 / ring-ring-brand (alpha já embutido)
+❌ outline-none → ✅ focus-visible:outline-none
+❌ text-[14px] / text-sm font-medium → ✅ text-body-md font-medium (preset)
+❌ <label> cru em form → ✅ <FormField> (label + erro + helper + dark-mode corretos)
+❌ scale(0.95) no clique → ✅ feedback por mudança de bg/border
+❌ cor hex / #fff em className → ✅ token semântico
+❌ segunda cor de marca / azul → ✅ verde é a marca; info é roxo
+```
+
+- Form 2+ campos → `<FormField>` + `gap-form-gap`.
+- CTA único por contexto = único `filled`; destrutivo = `<Button color="critical">`.
+- Pai que precisa de altura (tabela `flex-1`) → wrapper `flex flex-col h-full min-h-0`.
+
+---
+
+## 8. Responsividade
+
+- Mobile <640px: gutter 16px; FloatingPanel/Sheet vira sheet full; PageHeader empilha ações em overflow; DataTable rola horizontal; CTA primário = `min-h-form-xl` (44px, WCAG).
+- Desktop default = `min-h-form-lg` (40px). Containers: `max-w-lg`(1024)/`max-w-xl`(1280) conforme densidade — **sem** o prefixo `container`, que não existe (ver tabela acima).
+- **AppShell**: o body tem 3 patamares de padding — 18px (<768) · 24px (768–1535) · **32px (≥1536)**, corte no breakpoint `2xl`. E o **menu nasce COLAPSADO abaixo de 1536px**: notebook 1366/1440 abre com o rail, ganhando ~264px de largura útil. Quer sempre aberto? passe **`defaultMenuCollapsed={false}` explícito** — o default responsivo só vale quando a prop é omitida, e é aplicado **só no mount** (não reage a resize, pra não brigar com quem abriu o menu na mão).
+- Os exemplos já são responsivos — herde o comportamento ao adaptar.
+
+---
+
+## 9. Filosofia (decisões por intenção, não por omissão)
+
+- **Flat por escolha** — sem gradiente/glass/neumorfismo. Profundidade = sombra 2-camadas (light) ou borda (dark).
+- **Verde é carga, não decoração** — acento de ação, com restraint. Cinza domina.
+- **Densidade confiante** — `body-sm` 13/500, 16px entre blocos, sem transform no clique.
+- **Tokens, sempre** — zero hex em código; cor por papel semântico; derivação por `color-mix` já está nos tokens.
+
+---
+
+## Como crescer este guia
+
+Novo padrão de tela recorrente → seção curta aqui + (se for fluxo guiado) skill em `.claude/skills/` + 1 linha no mapa (seção 6) e no `ds-kit`. Mantenha cada peça pequena: **este arquivo = composição · `USAGE.md` = API · exemplo = referência viva.**

package/dist-lib/ai/indice.json

@@ -0,0 +1,177 @@
+{
+  "rotas": [
+    {
+      "sinais": [
+        "tabela",
+        "grade",
+        "grid de dados",
+        "crud",
+        "datatable",
+        "planilha",
+        "colunas"
+      ],
+      "rota": "skill `crud-builder` (`/ds-create-crud`) — entrevista guiada"
+    },
+    {
+      "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)"
+    },
+    {
+      "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)"
+    },
+    {
+      "sinais": [
+        "lista de cards",
+        "árvore",
+        "hierarquia",
+        "rede/organograma",
+        "níveis",
+        "treeview",
+        "feed de cards"
+      ],
+      "rota": "skill `list-builder` (`/ds-create-list`) — entrevista guiada"
+    },
+    {
+      "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`"
+    },
+    {
+      "sinais": [
+        "detalhe",
+        "detalhamento",
+        "ficha",
+        "página de x com abas",
+        "visão geral do pedido"
+      ],
+      "rota": "skill `page-detail` → `example-order-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)"
+    },
+    {
+      "sinais": [
+        "dashboard",
+        "painel",
+        "visão geral",
+        "indicadores"
+      ],
+      "rota": "skill `dashboard-builder` (`/ds-create-dashboard`) — entrevista → gate → geração ancorada no `example-dashboard`"
+    },
+    {
+      "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)"
+    },
+    {
+      "sinais": [
+        "gráfico",
+        "chart",
+        "barras/linha/área/pizza"
+      ],
+      "rota": "skill `charts` → `Chart/USAGE.md` + `example-dashboard`"
+    },
+    {
+      "sinais": [
+        "financeiro",
+        "extrato",
+        "saldo",
+        "transações"
+      ],
+      "rota": "`example-finance` (puxar + adaptar)"
+    },
+    {
+      "sinais": [
+        "chat",
+        "inbox",
+        "conversas",
+        "atendimento"
+      ],
+      "rota": "skill `chat` → `example-chat`"
+    },
+    {
+      "sinais": [
+        "drawer/painel de criar/editar/ver detalhe"
+      ],
+      "rota": "skill `drawers` → drawers do `example-finance`"
+    },
+    {
+      "sinais": [
+        "cards",
+        "blocos",
+        "painéis soltos",
+        "seções"
+      ],
+      "rota": "skill `cards` → `Card`/`Panel` + showcase"
+    },
+    {
+      "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)"
+    },
+    {
+      "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"
+    },
+    {
+      "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"
+    }
+  ]
+}