@snksergio/design-system 0.61.0 → 0.62.0

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

@@ -0,0 +1,88 @@
+> **Nota de portabilidade.** Este roteiro foi extraído do pipeline do iGreen DS
+> para Claude Code. Menções a slash command (`/ds-create-…`), a `.claude/` e a
+> ferramentas daquele ambiente descrevem **como ele é acionado lá** — aqui o
+> equivalente é carregar este roteiro pelo `indice.json`. O conteúdo de decisão
+> (entrevista, blueprint, regras de composição) vale igual.
+
+> **Modo submódulo (`ds-link`).** Existe `.claude/ds-config.json` com `"mode": "submodule"`?
+> Então **NÃO rode `igreen:add`** — esse script não existe no seu projeto. Os componentes e
+> exemplos já estão no disco em `<dsPath>/src`: importe pelo `importBase` do config
+> (compostos) e pelo `primitivesBase` (primitivos shadcn), e **leia** o exemplo direto de
+> `<dsPath>/src/examples/`.
+
+# Dashboard Builder (consumidor) — Geração
+
+Só após o gate aprovado. Abort-on-error.
+
+## 1. Puxar + ler ANTES de montar (nunca de memória)
+
+```bash
+npm run igreen:add -- example-dashboard kpi chart panel
+# + data-table (se tabela embutida) / data-list (se lista embutida)
+```
+Ler `src/examples/dashboard/dashboard-screen.tsx` (referência runnable) + `Kpi/USAGE.md`
++ `Chart/USAGE.md`. Catálogo visual: **https://igreen-desingsystem-admin.vercel.app** (`#/dashboard-showcase`).
+**Prefira adaptar o example-dashboard** a montar do zero.
+
+## 2. Receitas canônicas (as 6 — resumo; o example-dashboard tem o código completo)
+
+**Shell**: `<div className="flex flex-col h-full min-h-0 gap-gp-2xl">` + `PageHeader`
+(actions = PeriodSelector) + rows.
+
+**§1 KPI-group "Painel do Líder"** (faixa de KPIs rápidos):
+```tsx
+<KpiGroup columns={N} divided>
+  <Kpi label="..." value="..." icon={<Icon />} tone="success|brand|info|warning|danger|neutral"
+       hint="..." delta={<KpiDelta value="+34" signed />} />
+</KpiGroup>
+```
+Tone colore SÓ o ícone (círculo `size-form-lg rounded-radius-full`); valor default (só KPI de
+alerta ganha cor). `signed` deriva verde/vermelho + seta do sinal; use tom explícito quando
+"subir" não é bom (tempo ↓ = success).
+
+**§2 Chart-card**: SectionCard (`flex flex-col gap-gp-2xl p-pad-3xl bg-bg-surface border
+border-border-subtle rounded-radius-xl shadow-sh-sm`) com head discreto (título `text-body-md
+font-medium`, subtítulo `text-body-xs text-fg-muted`, gap `gap-gp-2xs` (2px)) + `<ChartContainer
+className="h-[160px]">`. Cor só por token. Big-number liderando: `text-stat-lg
+leading-none tabular-nums` (30px/bold — o preset existe; NÃO hardcode `text-[30px]`). Legenda/metric-row: ícone-**quadrado** `size-comp-xl rounded-radius-base`
++ label/sub + valor à direita, sob `border-t border-border-subtle`.
+
+**§3 Fusão KPI+evolução / ranking** (linha rica): identidade (rank badge `size-comp-sm
+rounded-radius-full` + nome) · mini-KPIs em colunas (`hidden sm:flex gap-gp-6xl`, cada = quadrado
+`size-comp-lg rounded-radius-base` tonal + valor `text-body-md font-semibold tabular-nums` +
+label `text-caption-sm text-fg-muted`) · bloco headline à direita `ml-auto shrink-0 border-l
+border-border-subtle pl-gp-3xl` (valor `text-title-lg font-bold` + delta Chip `shape="rounded"`,
+seta 180° se negativo + micro-label `uppercase tracking-[0.04em]`).
+
+**§4 Card dividido em 2**: 1 surface SEM padding + `grid lg:grid-cols-2`; cada painel `p-pad-3xl`
+com ColHead; divisor no **2º painel**: `border-t border-border-subtle ... lg:border-l lg:border-t-0`.
+
+**§5 Tabela embutida** → delega ao `crud-builder`: ordem identidade → status → categóricos →
+muted → moeda/data à direita (`align:"right" tabular-nums`); primário `isPrimary`+`minWidth`+
+`font-medium`; status `Chip variant="soft" size="sm" shape="rounded"`; filtros nativos
+pré-aplicados (`defaultViews`/`presetView`), sem form solto acima.
+
+**§6 Lista/kanban embutida** → delega ao `list-builder`: linha1 título bold `body-md` + `·`
+secundário muted · linha2 meta muted `caption-md` (lugar · pessoa · data) · status Chip soft pill ·
+valor à direita fixo `font-semibold tabular-nums`. **Sem botão de ação na linha.**
+
+## 3. Registro
+Registrar a página no roteador do app (perguntar ao usuário onde/como). Página órfã = incompleto.
+
+## 4. Sequência (abort-on-error)
+1. `igreen:add` dos itens + ler o example-dashboard.
+2. Montar seção por seção (as § acima; adaptar o exemplo).
+3. Registrar rota.
+4. `npx tsc --noEmit` → erro: corrigir e repetir.
+5. (recomendado) rodar o app e conferir: KPI-group divided, gráficos com token, ranking com
+   `border-l`, card dividido, tabela/lista embutida, responsivo + dark.
+
+## 5. Checklist final
+- [ ] Compõe 2+ tipos de seção espelhando o example-dashboard
+- [ ] KPI-group divided + KpiDelta (signed só onde cabe); ícone círculo vs quadrado certo
+- [ ] Gráficos só com token; tabela/lista via crud/list-builder
+- [ ] Zero Tailwind literal com equivalente DS · zero hardcode
+- [ ] Registro completo · `npx tsc --noEmit` limpo
+
+## Handoff
+`DASHBOARD_PRONTO: <Painel>` (+ onde foi registrada)

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

@@ -0,0 +1,88 @@
+> **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.
+
+
+# Dashboard Builder (consumidor) — Router
+
+Você guia a criação de uma tela de **dashboard/painel** que **compõe** os primitivos
+do DS (`Kpi`/`KpiGroup`/`KpiDelta`, `Chart`, `Panel`, `DataTable`, `DataList`) nos
+**padrões canônicos**. NÃO inventa API, NÃO gera de memória, NÃO toca em arquivo
+antes do gate.
+
+> Irmão do `crud-builder` (tabela) e do `list-builder` (lista). Dashboard não é um
+> componente — é **composição** de seções. Uma tabela/lista DENTRO do dashboard é
+> delegada ao crud/list-builder.
+
+## ⚠️ Desambiguação ANTES de tudo
+
+| Dashboard (ESTA skill) | Não é dashboard |
+|---|---|
+| **compõe** 2+ tipos de seção: KPIs + gráfico(s) + ranking/resumo numa "visão geral" | 1 tabela densa → `crud-builder` |
+| foco em métrica/tendência/comparação, pouca edição | 1 lista de cards standalone → `list-builder` |
+| ex: painel do líder, resumo de categoria, visão da rede | 1 gráfico isolado → skill `charts` |
+
+Só 1 grade/lista/gráfico → **PARAR** e rotear pro builder certo.
+
+## Ambiente (projeto CONSUMIDOR, copy-in)
+
+| Variável | Valor |
+| --- | --- |
+| `IMPORT_PATH` | `@/components/ui/Kpi`, `@/components/ui/Chart`, `@/components/ui/Panel`, etc (copy-in via alias) |
+| `EXEMPLO_CANÔNICO` | `example-dashboard` → `npm run igreen:add -- example-dashboard` → ler `src/examples/dashboard/dashboard-screen.tsx` |
+| `DOC` | `src/components/ui/Kpi/USAGE.md` + `Chart/USAGE.md` (após `igreen:add`) + types ao lado; catálogo visual hospedado `#/dashboard-showcase` |
+| `PAGES_DIR` / `REGISTRO` | perguntar ao usuário (onde mora a página + como registra rota) |
+
+Se o componente/exemplo não está no disco, **puxe via `igreen:add`** antes de ler.
+
+> **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/<Nome>`)
+> e leia o exemplo canônico direto em `<dsPath>/src/examples/dashboard/dashboard-screen.tsx` —
+> **NÃO** rode `igreen:add`. `PAGES_DIR`/`REGISTRO` continuam do projeto pai.
+
+## Fluxo — 3 estágios
+
+```
+/ds-create-dashboard
+   ▼ interview.md
+1. ENTREVISTA (fases 0-6)   — KPIs → gráficos → ranking/fusão → dividido/mapa → tabela/lista → layout; ZERO edição
+   ▼ blueprint.md
+2. BLUEPRINT [GATE]         — mapa de rows + pré-validações → aguarda "aprovar"
+   ▼ generate.md
+3. GERAÇÃO                  — igreen:add example-dashboard → ler → montar → registrar → tsc → handoff
+```
+
+Carregue cada sub-arquivo só no estágio: `interview.md` agora, `blueprint.md` ao fim
+da entrevista, `generate.md` só após o gate.
+
+## ⚠️ Precedência de fontes (anti-drift)
+
+```
+1. src/examples/dashboard/dashboard-screen.tsx (exemplo real — vence tudo)
+2. src/components/ui/Kpi/USAGE.md + Chart/USAGE.md + types ao lado
+3. Snippets/receitas desta skill (generate.md)
+4. Memória da IA  ← NUNCA confiar sozinha
+```
+
+## Guardrails (não-negociáveis)
+
+1. LER `example-dashboard` ANTES de montar — nunca de memória.
+2. **KPI rápido = "Painel do Líder"**: `<KpiGroup divided>` + `<Kpi>` + `<KpiDelta>`.
+   Tone colore SÓ o ícone (círculo); valor default (só KPI de alerta ganha cor).
+   Delta: `signed` só quando sinal = bom/ruim; senão `tone` explícito ("-12s" é melhora → success).
+3. Gráfico = SEMPRE `<ChartContainer>`, cor só por token (`--color-chart-1..5`); ver skill `charts`.
+4. Ranking/fusão + card dividido: divisor via `border-l`/`border-t` (nunca só gap);
+   ícone mini-stat = **quadrado** `size-comp-lg rounded-radius-base`, KPI-group = **círculo** `size-form-lg rounded-radius-full`.
+5. Tabela/lista embutida → delegar a `crud-builder`/`list-builder`; filtros nativos pré-aplicados, sem form solto acima.
+6. Classes DS antes de Tailwind literal; zero hardcode (ver `.claude/rules/ds-design.md`, `DESIGN.md`). Números grandes literais só onde não há preset.
+7. Shell: `flex flex-col h-full min-h-0 gap-gp-2xl` (PageHeader → 16px → rows). Estreito → 1 card/row.
+8. Página registrada no roteador do usuário — órfã = incompleto.
+9. `npx tsc --noEmit` limpo antes do handoff.
+
+## Handoff
+
+- Entrevista pronta → `BLUEPRINT_PRONTO: <Painel> (dashboard) — aguardando gate`
+- Pós-geração → `DASHBOARD_PRONTO: <Painel>` (+ onde foi registrada)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snksergio/design-system",
-  "version": "0.61.0",
+  "version": "0.62.0",
   "//distribuicao": "Canal PRIMARIO = registry shadcn (copy-in) + CLI @snksergio/create-design-system; sobe sozinho no merge (Vercel). Canal SECUNDARIO = este pacote npm (@snksergio/design-system), publicado por passo MANUAL do mantenedor, entao costuma ficar atras do registry. SECUNDARIO descreve a ORDEM DE PUBLICACAO, nao o nivel de suporte: NAO e depreciado, e desde a 0.37.0 entrega 41 dos 42 componentes ui/ no barrel raiz + os 41 primitivos shadcn no subpath ./shadcn (so TabelaTeste, demo interno, fica de fora). Publish so pelo Passo 7 do .claude/skills/ds-dev/release.md (valida com `npm run lib:verify`, pede o token, publica, revoga). Ver DISTRIBUICAO.md.",
   "description": "iGreen Design System — internal library for SaaS CRM, admin panels and dashboards. React 19 + Tailwind v4 + Shadcn + Radix.",
   "license": "UNLICENSED",
@@ -19,8 +19,10 @@
     "dist-lib/chunks/**",
     "dist-lib/src/**",
     "dist-lib/tokens/**",
+    "dist-lib/ai/**",
     "README.md"
   ],
+  "//ai-bundle": "dist-lib/ai/ é o pacote de conteúdo pra IA fora do Claude Code (roteiros, regras, exemplos, guias, manifesto com versão+commit). É LIDO POR CAMINHO, não importado — por isso só o manifest.json tem entrada em exports, como âncora resolvível e verificada pelo lib-verify; os outros 60+ arquivos seguem o precedente de dist-lib/fonts/**, que está em files sem export e o gate aprova. Enumerar 60 markdowns em exports seria ruído, e wildcard não é verificado (ver //exports-theme-marcas). Gerado no closeBundle do vite.lib.config.ts.",
   "engines": {
     "node": ">=20.0.0"
   },
@@ -44,6 +46,7 @@
       "import": "./dist-lib/shadcn.mjs",
       "require": "./dist-lib/shadcn.cjs"
     },
+    "./ai/manifest.json": "./dist-lib/ai/manifest.json",
     "./theme.css": "./dist-lib/theme.css",
     "./theme/brand-blue.css": "./dist-lib/theme/brand-blue.css",
     "./theme/brand-green.css": "./dist-lib/theme/brand-green.css",