@snksergio/design-system 0.19.1 → 0.30.2

package/README.md

@@ -10,7 +10,7 @@ Escolha o caminho conforme seu objetivo:
 
 - **Quero ver o DS funcionando** → catálogo + documentação viva em **[igreen-desingsystem-admin.vercel.app](https://igreen-desingsystem-admin.vercel.app/#/introduction)** (componentes, tokens, exemplos e pipeline).
 - **Quero consumir o DS num projeto** → veja [`## Consumir em outro projeto`](#consumir-em-outro-projeto) (CLI/registry) e [`DISTRIBUICAO.md`](DISTRIBUICAO.md).
-- **Quero desenvolver no DS** → veja [`## Setup (desenvolvimento no DS)`](#setup-desenvolvimento-no-ds) e [`CLAUDE.md`](CLAUDE.md).
+- **Quero contribuir com o DS (primeira PR)** → comece em **[`CONTRIBUTING.md`](CONTRIBUTING.md)** — o fluxo, o que o CI verifica e as regras que não têm exceção. Depois, [`## Setup (desenvolvimento no DS)`](#setup-desenvolvimento-no-ds).
 - **Sou operador (não-dev)** → veja [`INICIO-DE-SESSAO.md`](INICIO-DE-SESSAO.md).
 
 ---
@@ -123,7 +123,13 @@ Cria o projeto já conectado ao registry, com tema/`cn`/`tv` configurados, tela
 
 **Projeto existente:** configure o registry `@igreen` no `components.json` (Bearer `IGREEN_TOKEN`) e puxe componentes com `npx shadcn add @igreen/<nome>` (ou o wrapper `npm run igreen:add` no scaffold, que mantém o manifesto).
 
-> ⚠️ O pacote npm `@snksergio/design-system` está **DEPRECIADO** (era uma tentativa antiga de virar lib). **Não use `npm install` dele** — o canal vivo é o registry/CLI acima. Modelo e versionamento explicados em `DISTRIBUICAO.md` e na página **Distribution** do catálogo.
+> **Canal recomendado é o registry/CLI acima** (copy-in): é ele que entrega o código
+> editável no seu `src/` e é onde as versões saem primeiro. O pacote npm
+> `@snksergio/design-system` **existe e funciona** (lib buildada: ESM + CJS + types +
+> `theme.css`), mas é **secundário** e publicado por passo manual do mantenedor, então
+> pode estar atrás do registry. Use-o só quando precisar consumir como dependência em
+> vez de copy-in. Modelo e versionamento em `DISTRIBUICAO.md` e na página
+> **Distribution** do catálogo.
 
 **O que NÃO vem no copy-in:** o pipeline interno do DS (`.claude/agents|skills|hooks`, `.ai/context`, lições) vive só neste repositório. O **kit do consumidor** (orquestrador `ds-kit` + skills de tela + `DESIGN.md` + proteção por hook) vem via CLI no scaffold.
 
@@ -134,11 +140,32 @@ Cria o projeto já conectado ao registry, com tema/`cn`/`tv` configurados, tela
 > Cenário: seu app tem o DS clonado numa **subpasta** (monorepo, `vendor/`,
 > git submodule) e a sessão do Claude Code abre na raiz do SEU projeto.
 > Nesse caso o Claude **não** descobre o `.claude/` do DS sozinho — os slash
-> commands e skills do pipeline ficam invisíveis. A solução é **apontar**:
-> skills são markdown, e a IA lê e segue os arquivos quando o prompt indica
-> a porta de entrada.
+> commands e skills do pipeline ficam invisíveis.
 
-### Passo 1 — Bootstrap de contexto (início de toda sessão)
+### Recomendado — `ds-link` (setup uma vez)
+
+Se o DS está no disco (submódulo/subpasta), rode o **`ds-link`** na raiz do SEU
+projeto: ele projeta o mesmo kit de IA que o CLI npm instala (skills
+`crud-builder`/`list-builder`/`dashboard-builder`, commands, rules) pra dentro do
+seu `.claude/` — aí `/ds-create-crud`, `/ds-create-dashboard` etc. viram
+**descobríveis nativamente**, sem bootstrap por sessão.
+
+```bash
+# ajuste "design-system" pro caminho real do submódulo
+npm --prefix design-system run ds:link
+# ou:  node design-system/scripts/ds-link.mjs
+```
+
+Escreve `.claude/ds-config.json` (`mode: submodule`) — as skills leem componentes/
+exemplos direto de `<submódulo>/src` (sem `igreen:add`/registry) e importam pelo
+alias detectado no seu `tsconfig`/`vite` (fallback `@ds`). Re-rode após
+`git pull --recurse-submodules` (idempotente); `--unlink` desfaz. Guia completo:
+[`SUBMODULE-SETUP.md`](SUBMODULE-SETUP.md).
+
+> Sem poder rodar o script? O caminho **manual** (apontar por prompt) abaixo
+> continua válido como fallback.
+
+### Passo 1 — Bootstrap de contexto (fallback manual, início de toda sessão)
 
 Antes de qualquer tarefa que use o DS, mande (troque `<pasta-do-ds>` pelo
 caminho real, ex: `packages/igreen-ds`):
@@ -176,10 +203,10 @@ sample e confirma com você). Nada é gerado antes de você aprovar o blueprint.
 
 | Forma | Quando usar |
 |---|---|
-| **Apontar via prompt** (passos acima) | Default — zero setup, funciona em qualquer projeto |
-| **Abrir a sessão dentro da pasta do DS** | Quer o pipeline nativo (`/ds-create-crud`, hooks, rules auto-carregadas) |
-| **Copiar pro seu `.claude/`** | Copie `ds-create-crud.md` (commands) + `crud-builder/` (skills) pro `.claude/` do seu projeto — o slash command vira nativo; a skill detecta que está num consumer e adapta imports |
-| **Consumo só via npm** (sem o repo no disco) | A skill não está no pacote — aponte pros arquivos no GitHub (`igreenlab/igreen-desingsystem-admin` → `.claude/skills/crud-builder/`) ou clone o repo |
+| **`ds-link`** (recomendado) | DS no disco (submódulo/subpasta) — projeta o kit no seu `.claude/`, slash commands nativos, sem bootstrap por sessão. `npm --prefix <ds> run ds:link` |
+| **Apontar via prompt** (Passo 1) | Fallback — não pode rodar o script; zero setup, funciona em qualquer projeto |
+| **Abrir a sessão dentro da pasta do DS** | Quer o pipeline de desenvolvimento nativo (agents/hooks/rules do DS, não só o kit de telas) |
+| **Consumo só via npm** (sem o repo no disco) | O kit vem no scaffold do CLI (`npx @snksergio/create-design-system`); num projeto já existente, aponte pros arquivos no GitHub ou clone o repo |
 
 Detalhes do mecanismo: [`README-PIPELINE-WORKFLOW.md`](README-PIPELINE-WORKFLOW.md) §8 "Usando skills quando o DS é subprojeto".
 
@@ -234,7 +261,7 @@ Tokens DS usam prefixos para não colidir com utilities nativas do Tailwind:
 | shadow | `shadow-sh-md` | `shadow-md` |
 | form height | `min-h-form-lg` (40px) | `h-10` |
 | icon | `size-icon-md` (20px) | `size-5` |
-| container | `max-w-container-md` | `max-w-md` |
+| container | `max-w-md` (escala do DS: 768px) | — **única exceção: não dobra prefixo** |
 
 ---
 
@@ -267,7 +294,7 @@ Pipeline de 6 agentes (4 ativos + 2 placeholders 🚧 aguardando primeira tela d
 
 A infraestrutura inclui:
 - **Skills** atômicas por agente (`.claude/skills/`)
-- **Hooks** PreToolUse/PostToolUse (`format-on-save`, `block-rm-rf`, `block-sensitive-edit`)
+- **Hooks** PreToolUse/PostToolUse (`ds-lint-styles`, `block-rm-rf`, `block-sensitive-edit`)
 - **Output style** terse aplicado a toda sessão
 - **MCP servers** (Figma, filesystem, chrome-devtools)
 - **Memory system 4 camadas** (user, project, audit log, lessons system)