zark-design 3.0.4 → 3.1.0

package/README.md

@@ -1,60 +1,135 @@
-# zark-design
+# 🎨 zark-design — Design System anti-cara-de-IA (gerador agnóstico de marca)
 
-> ZARK SAAS Design System — instale via `npx zark-design init` em qualquer projeto.
+> **`npx zark-design init` em qualquer pasta cria um design system completo (HTML + JSX side-by-side) com a sua cor primária e regras explícitas pra IA não gerar UI "cara de IA": sem pill, sem rounded extremo, sem travessão em copy, sem brand color dominante, sem glassmorphism.**
 
-O design system fica como **REFERÊNCIA pra IA**, não como dependência runtime. A IA lê os arquivos JSX + tokens + screenshots e adapta pra qualquer stack (React, Vue, Svelte, Blade, Django templates, HTML puro com Tailwind, etc.).
-
-## Uso
+[![npm version](https://img.shields.io/npm/v/zark-design.svg?style=flat-square&color=f56f10)](https://www.npmjs.com/package/zark-design)
+[![weekly downloads](https://img.shields.io/npm/dw/zark-design.svg?style=flat-square&color=f56f10)](https://www.npmjs.com/package/zark-design)
+[![license](https://img.shields.io/npm/l/zark-design.svg?style=flat-square)](./LICENSE)
 
 ```bash
-# Em qualquer pasta de projeto
-npx zark-design init
-
-# Cria ./design-system/ com:
-#   REFERENCE.md       (cérebro: tokens + primitivos + patterns documentados)
-#   tokens.css         (light + dark themes)
-#   primitives.jsx     (Button, Input, Tag, etc. — referência visual)
-#   components.jsx
-#   layouts.jsx
-#   patterns.jsx
-#   icons.jsx
-#   brand.jsx
-#   foundations.jsx
-#   SHOWCASE.html      (preview offline)
-#   visual-references/ (15 screenshots — ground truth visual)
-#   assets/            (logo + ícone)
+# Custom (recomendado — sua cor de marca + paleta 50→900 gerada automaticamente)
+npx zark-design@latest init --name "MinhaEmpresa" --primary "#3B82F6" --yes
+
+# Preset ZARK de referência (cor #F56F10 + logos ZARK)
+npx zark-design@latest init --preset zark --yes
 ```
 
-Depois, abra a IA na pasta:
+---
+
+## O que é
+
+`zark-design` é um **scaffolder de design system híbrido** parte do ecossistema [ZARK](https://github.com/mayconjordanr/zark-dev). Em modo `preset zark` ele entrega o design system ZARK pronto pra usar (paleta ember, logos, tipografia). Em modo `custom` ele **gera** um design system completo a partir de **1 cor hex** (escala 50→900 calculada via HSL) ou de uma paleta JSON pronta.
+
+A IA (Claude Code, Cursor, Codex) lê os arquivos como **referência visual e estrutural** — não como dependência runtime — e adapta os componentes pra qualquer stack: React, Vue, Svelte, Solid, Blade (Laravel), Django templates, ERB (Rails), HTML puro com Tailwind, CSS modules, styled-components.
+
+### O que vem instalado
 
-```bash
-claude   # ou cursor . / codex / aider
 ```
+design-system/
+├── README.md                  # cérebro pra IA
+├── html/
+│   ├── tokens.css             # light + dark themes
+│   ├── components.css         # 50+ classes utilitárias (.btn, .tag-dot, .stat...)
+│   ├── index.html             # exemplo mínimo
+│   └── showcase.html          # galeria completa (light/dark toggle)
+├── jsx/
+│   ├── tokens.css/.js
+│   ├── components.css
+│   ├── icons.jsx              # 35 ícones outline
+│   ├── App.example.jsx        # exemplo completo
+│   └── components/            # 24 componentes individuais
+└── assets/                    # logos (preset = ZARK; custom = SVG dinâmico com sua cor)
+```
+
+24 componentes individuais: `Button` · `Input` · `Tag` · `TagDot` · `Badge` · `Toggle` · `Segmented` · `Chip` · `Avatar` · `Kbd` · `Spec` · `Panel` · `Section` · `Modal` · `Toast` · `Banner` · `CodeBlock` · `StatCard` · `AlertCritical` · `Funnel` · `KanbanColumn` · `LeadCard` · `EmptyState` · `TableActions` · `Sidebar`. **App Patterns derivados do CRM real ZARK** — não componentes genéricos de portfólio.
 
-A IA detecta `design-system/REFERENCE.md` e usa como fonte de verdade pra qualquer trabalho de UI/frontend.
+---
 
-## Pasta customizada
+## 🚀 Quick start
+
+### Modo preset (ZARK pronto)
+
+```bash
+mkdir meu-projeto && cd meu-projeto
+npx zark-design@latest init --preset zark --yes
+open design-system/html/showcase.html   # vê tudo renderizado no browser
+```
+
+### Modo custom (sua marca)
 
 ```bash
-npx zark-design init ./ui                 # instala em ./ui em vez de ./design-system
-npx zark-design init ./src/zark           # instala em src/zark
+mkdir meu-projeto && cd meu-projeto
+
+# Interativo
+npx zark-design@latest init
+
+# Ou com flags
+npx zark-design@latest init --name "MinhaEmpresa" --primary "#3B82F6" --yes
 ```
 
-## Sobrescrever instalação existente
+A paleta `--brand-50` até `--brand-900` é gerada automaticamente via HSL manipulation a partir da cor primária. Ring focus, tons dark mode e variações suaves também são derivados.
+
+### Listar presets disponíveis
 
 ```bash
-npx zark-design init --force
+npx zark-design@latest presets
 ```
 
-## Integração com `.ai-context/CONTEXT.md` ou `CLAUDE.md`
+---
+
+## Filosofia visual (anti-cara-de-IA)
+
+A paleta é sua. O padrão visual é universal: foge das assinaturas óbvias de UI gerada por IA.
+
+**Visual**
+- Warm + neutral + brand-on-paper. Fundo cremoso quente (`#fafaf8`), nunca branco puro.
+- Cor da marca usada com moderação. Só CTA primário, focus ring, ícone-acento. Nunca background dominante.
+- Sem pill. Raio máx 6px em tags/chips/toggles; 8-12px em cards; 16px em modal. Avatares 50% (círculo geométrico).
+- Hairlines de 1px em `--line-200`. Borders grossos banidos.
+- Sombras warm (`rgba(20, 17, 12, ...)`), nunca frias.
+- Sem glassmorphism, gradiente colorido, neon, blur exagerado.
+
+**Copy**
+- Sem travessão (—) nem en-dash (–) em qualquer texto da UI. Vírgula, ponto, dois-pontos.
+- Sem emoji em label de botão, título de campo, título de página.
+- Frase ≤ 12 palavras em UI. Voz ativa.
+- Sem vocabulário marketing-IA: "transforme", "potencialize", "descubra", "experimente".
+
+**Tipografia**
+- Editorial: Inter (UI) + JetBrains Mono (código) + Space Grotesk (display).
+- Dark mode nativo via `[data-theme="dark"]` ou `prefers-color-scheme`.
+
+---
+
+## Integração com `CLAUDE.md`
+
+Se o projeto já tem ZARK acoplado (via `npx zark-dev start`), o `init` detecta e adiciona automaticamente uma nota em `.ai-context/CONTEXT.md` ou `CLAUDE.md` instruindo a IA a ler `design-system/README.md` antes de qualquer trabalho de UI.
+
+---
+
+## O Ecossistema ZARK
+
+`zark-design` é uma das 4 peças do método [ZARK](https://github.com/mayconjordanr/zark-dev):
+
+- [**`zark-dev`**](https://www.npmjs.com/package/zark-dev) — metodologia + contexto pra IA (orquestra todo o método)
+- **`zark-design`** ← você está aqui
+- [**`zark-seo`**](https://www.npmjs.com/package/zark-seo) — 17 skills SEO/GEO especialistas, foco BR
+- [**`zark-skills`**](https://www.npmjs.com/package/zark-skills) — 5 skills Claude Code user-level
+
+---
+
+## Quem está por trás
+
+[**Maycon Jordan**](https://github.com/mayconjordanr) — fundador da [ZARK](https://grupozark.com.br). Design system derivado do CRM real da ZARK + clientes (Limppetec, AllSec, VipCar, VipSeg, MixShop), refinado em produção.
+
+---
 
-Se o projeto já tem ZARK acoplado (via `zark-dev start` ou `audit`), o `init` adiciona automaticamente uma nota em `CLAUDE.md` ou `.ai-context/CONTEXT.md` instruindo a IA a ler o `REFERENCE.md` antes de qualquer UI.
+## Tags
 
-## Filosofia
+`zark` `design-system` `zark-design-system` `react-design-system` `html-design-system` `dual-implementation` `dark-mode` `design-tokens` `tailwind-alternative` `palette-generator` `app-patterns` `crm-ui` `brazil` `pt-br` `metodologia-zark`
 
-ZARK é warm + neutral + ember-on-paper. Cor de marca: Liquid Lava (`#f56f10`).
-Os primitivos JSX são **referência estrutural** — adapte pra stack alvo, nunca copie literal.
+---
 
 ## Licença
 
-MIT — Maycon Jordan
+[MIT](./LICENSE) — Maycon Jordan / ZARK · 2026

package/bin/cli.js

@@ -202,15 +202,18 @@ function printHelp(version) {
   console.log(`    ${c.green('help')}             mostra esta ajuda`);
   console.log(`    ${c.green('version')}          mostra a versão\n`);
   console.log(`  ${c.bold('Modos:')}`);
-  console.log(`    ${c.green('preset ZARK')}       paleta + logos ZARK prontos (Liquid Lava #F56F10)`);
-  console.log(`    ${c.green('custom')}            sua cor primária + suas logos\n`);
-  console.log(`  ${c.bold('Uso interativo:')}`);
-  console.log(`    npx zark-design init                       ${c.dim('# pergunta tudo')}`);
+  console.log(`    ${c.green('custom')} ${c.dim('(padrão)')}    sua cor primária → paleta 50→900 gerada via HSL`);
+  console.log(`    ${c.green('preset ZARK')}       configuração pronta de referência (Liquid Lava #F56F10)\n`);
+  console.log(`  ${c.bold('Uso custom (recomendado — sua marca):')}`);
+  console.log(`    npx zark-design init                                           ${c.dim('# pergunta tudo')}`);
+  console.log(`    npx zark-design init --name "MinhaEmpresa" --primary "#3B82F6" --yes`);
+  console.log(`    npx zark-design init --palette ./minha-paleta.json --yes\n`);
+  console.log(`  ${c.bold('Uso preset ZARK:')}`);
   console.log(`    npx zark-design init --preset zark         ${c.dim('# usa ZARK direto')}`);
   console.log(`    npx zark-design init --preset zark --yes   ${c.dim('# sem confirms')}\n`);
-  console.log(`  ${c.bold('Uso custom (flags):')}`);
-  console.log(`    npx zark-design init --name "ALLSEC" --primary "#E74C3C" --yes`);
-  console.log(`    npx zark-design init --palette ./minha-paleta.json --yes\n`);
+  console.log(`  ${c.bold('Filosofia:')}`);
+  console.log(`    Anti "cara de IA": sem pill, sem rounded extremo, sem travessão em copy, sem`);
+  console.log(`    brand color dominante, sem glassmorphism. App patterns derivados de CRM real.\n`);
   console.log(`  ${c.bold('Output:')}`);
   console.log(`    design-system/                  ${c.dim('# default; mude com [pasta]')}`);
   console.log(`      ├── README.md`);
@@ -298,15 +301,15 @@ async function buildCtx({ flags, prompt }) {
       fonts: { ui: 'Inter', mono: 'JetBrains Mono', display: 'Space Grotesk' },
     };
   }
-  // 4) Interativo
+  // 4) Interativo — modo custom é o padrão (sua marca, sua cor)
   if (!prompt) throw new Error('Modo interativo precisa de TTY. Use --preset zark ou --primary <hex>.');
   console.log(c.dim('  Pressione Enter pra usar o default em parênteses.\n'));
-  const usePreset = await prompt.yn('Usar preset ZARK pronto?', true);
-  if (usePreset) return await loadPreset('zark');
+  const useCustom = await prompt.yn('Customizar com sua cor de marca?', true);
+  if (!useCustom) return await loadPreset('zark');
 
   const name = await prompt.ask('Nome do projeto/empresa:', 'Custom');
   const slug = await prompt.ask('Slug (lowercase, sem espaços):', slugify(name));
-  const primary = await prompt.ask('Cor primária (hex, ex: #E74C3C):');
+  const primary = await prompt.ask('Cor primária (hex, ex: #3B82F6):');
   if (!primary) throw new Error('Cor primária é obrigatória.');
   const palette = generatePalette(primary);
   return {
@@ -425,7 +428,7 @@ async function runInit(args) {
 }
 
 async function appendNoteToContextFiles(targetRoot, designDirName, ctx) {
-  const note = `\n\n## Design system\nEste projeto usa o **${ctx.name} Design System** (gerado por \`zark-design\`${ctx.preset ? `, preset ${ctx.preset}` : ', modo custom'}). Antes de qualquer trabalho de UI/frontend, leia \`${designDirName}/README.md\`.\n\n2 implementações lado a lado consumindo \`tokens.css\` + \`components.css\` idênticos:\n- \`${designDirName}/html/\` — HTML puro (Blade/Django/Rails/HTML)\n- \`${designDirName}/jsx/\` — React (24 componentes individuais)\n\nVue/Svelte/Solid: use \`tokens.css\` + \`components.css\` direto, adapte os JSX mantendo as classes.\n\nCor de marca: \`var(--brand-500)\` = ${ctx.brand['500']}. Abra \`${designDirName}/html/showcase.html\` no browser pra inspeção visual.\n`;
+  const note = `\n\n## Design system\nEste projeto usa o **${ctx.name} Design System** (gerado por \`zark-design\`${ctx.preset ? `, preset ${ctx.preset}` : ', modo custom'}). Antes de qualquer trabalho de UI/frontend, leia \`${designDirName}/README.md\` — em especial o bloco "LEIA ANTES DE GERAR UI (regras anti-IA-genérica)".\n\n**Regras críticas resumidas (detalhes no README):**\n- Sem pill (border-radius 999px / --r-pill). Tag/chip/toggle: raio máx 6px. Avatar 50%.\n- Sem rounded extremo. Card 8-12px, modal 16px máx. Botão 6px.\n- Sem travessão (—) nem en-dash (–) em copy/UI/labels. Use vírgula, ponto, dois-pontos.\n- Sem emoji em label de botão, título de campo, título de página.\n- Sem brand color como background dominante. Use \`var(--paper)\` / \`var(--canvas)\`.\n- Sem hex hardcoded. SEMPRE \`var(--brand-500)\` (= ${ctx.brand['500']}) ou tokens.\n- Sem sombra fria. Use as warm \`rgba(20,17,12,...)\` dos tokens.\n\n2 implementações lado a lado consumindo \`tokens.css\` + \`components.css\` idênticos:\n- \`${designDirName}/html/\` — HTML puro (Blade/Django/Rails/HTML)\n- \`${designDirName}/jsx/\` — React (24 componentes individuais)\n\nVue/Svelte/Solid: use \`tokens.css\` + \`components.css\` direto, adapte os JSX mantendo as classes.\n\nReceitas prontas (botão, card, KPI, formulário, status, empty state, alerta, toast) na seção "Receitas prontas" do README. Comece daí em vez de inventar do zero.\n\nAbra \`${designDirName}/html/showcase.html\` no browser pra inspeção visual.\n`;
   const candidates = [
     path.join(targetRoot, '.ai-context', 'CONTEXT.md'),
     path.join(targetRoot, 'CLAUDE.md'),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zark-design",
-  "version": "3.0.4",
-  "description": "Design system scaffolder seguindo método ZARK — `npx zark-design init` em modo preset (ZARK pronto) ou custom (cor e logos suas, paleta 50→900 gerada). HTML + JSX side-by-side. Dark mode nativo. Sem dependência runtime.",
+  "version": "3.1.0",
+  "description": "Design system scaffolder anti-cara-de-IA. `npx zark-design init` gera um DS completo a partir da sua cor primária (paleta 50→900 via HSL) ou usa o preset ZARK. Regras explícitas pra IA: sem pill, sem rounded extremo, sem travessão em copy, sem brand color dominante. HTML + JSX side-by-side. Dark mode nativo. Sem dependência runtime.",
   "type": "module",
   "bin": {
     "zark-design": "bin/cli.js"
@@ -20,7 +20,11 @@
     "ai-context",
     "scaffold",
     "tokens",
-    "ui"
+    "ui",
+    "anti-ai-look",
+    "palette-generator",
+    "dark-mode",
+    "brand-agnostic"
   ],
   "author": "Maycon Jordan",
   "license": "MIT",

package/templates/README.md.hbs

@@ -6,6 +6,39 @@ Versão: **v3 · {{date}}** · gerado por `npx zark-design init{{#if preset}} --
 
 ---
 
+## ⚠️ LEIA ANTES DE GERAR UI (regras anti-IA-genérica)
+
+Este design system existe pra **fugir do "cara de IA"**. Se você é uma IA gerando UI ou copy pra este projeto, siga estas regras SEM EXCEÇÃO:
+
+### Visual
+- ❌ **Nada de pill como indicador.** Tag, badge, chip, toggle: raio máximo `var(--r-md)` (6px). Pill (`border-radius: 999px`, `9999px`, `--r-pill`) está banido. Único uso de raio 50%: **avatar circular** e **status dot** (8px).
+- ❌ **Nada de bordas extremamente arredondadas.** Cards, panels, modals: raio máximo `var(--r-2xl)` (16px) pra modal, `var(--r-xl)` (12px) pra card grande, `var(--r-lg)` (8px) pra card padrão. Botões: `var(--r-md)` (6px), nunca mais. Se você está pensando em `border-radius: 24px+`, **pare**.
+- ❌ **Nada de glassmorphism, gradiente colorido, neon, blur exagerado.** Sombra é warm (`rgba(20, 17, 12, ...)`), nunca azul-fria.
+- ❌ **Brand color dominante.** A cor de marca (`var(--brand-500)`) só aparece em: CTA primário, focus ring, link, ícone-acento. Nunca como background de tela inteira, hero, card. Use neutros warm pro grosso (`--paper`, `--canvas`, `--surface`).
+- ❌ **Hex hardcoded** (`#f56f10`, `#3B82F6`). SEMPRE `var(--brand-500)` ou variável do token.
+- ❌ **Border-radius percentual aleatório** (`30%`, `40%`). Só `50%` pra círculos geométricos.
+
+### Copy / texto gerado
+- ❌ **NUNCA use travessão (—) ou en-dash (–) em texto da UI ou copy gerada.** É a assinatura mais óbvia de texto de IA. Use:
+  - **vírgula** quando a pausa for curta
+  - **dois-pontos** quando o que vem depois explica o anterior
+  - **ponto final** quando o pensamento acabou
+  - **parênteses** ou nova linha pra aposto/extensão
+- ❌ Nada de "Não apenas X, mas também Y" / "It's not just A — it's B".
+- ❌ Nada de bullet com travessão na frente. Use traço simples `-` ou ponto `•`.
+- ❌ Frases longas com 3 vírgulas + travessão + "ou seja". Texto direto: sujeito, verbo, complemento.
+- ✅ Exemplo ruim: "Esta plataforma oferece — além da automação — recursos avançados de análise, que permitem decisões mais estratégicas."
+- ✅ Exemplo bom: "Plataforma com automação e análise. Decisões mais rápidas."
+
+### Layout
+- Hairlines de 1px em `var(--line-200)`. Nunca borders grossos (2px+) em componentes de UI.
+- Espaçamento múltiplo de 4px (use os tokens `--sp-*`).
+- Animação ≤ 280ms. Microinterações ≤ 180ms. Nada de `bounce` exagerado.
+
+> Estas regras estão refletidas em `tokens.css` (não há `--r-pill`) e `components.css` (todos os componentes seguem). Se você sentir necessidade de quebrar alguma, **fale com o humano antes**.
+
+---
+
 ## Estrutura
 
 ```
@@ -63,13 +96,14 @@ design-system-apps/
 
 ## Filosofia
 
-**Warm, neutral, ember-on-paper.**
-- `--paper` (#fafaf8) cremoso, NÃO branco puro.
-- `--brand-500` (#f56f10 — Liquid Lava) é a única cor de marca. Use com **moderação** em CTAs, focus, brand moments.
+**Warm, neutral, brand-on-paper.**
+- `--paper` (#fafaf8) cremoso, NÃO branco puro. Fundo dominante é sempre neutro warm.
+- `--brand-500` ({{brand.500}}) é a sua cor de marca, gerada da paleta 50→900 a partir da primária. **A paleta é sua** — o sistema é agnóstico: troque a cor primária via `npx zark-design init --primary "#SUACOR"` e tudo se recalcula (50→900 + ring + dark mode). O preset ZARK é só uma das infinitas configurações.
+- Cor de marca usada com **moderação**: CTA primário, focus ring, link, ícone-acento. Nunca background dominante.
 - Hairlines de 1px em `--line-200`. Nunca borders grossos.
 - Sombras warm (`rgba(20,17,12,...)`), nunca azuis-frias.
-- Tipografia editorial: **Inter** pra UI e números · **JetBrains Mono** pra código e labels · **Space Grotesk** pra títulos.
-- **Sem pill.** Tags, chips, toggles, badges usam raio sm/md (4-6px). Avatares usam 50% (são círculos geométricos, não pills).
+- Tipografia editorial: **{{fonts.ui}}** pra UI e números · **{{fonts.mono}}** pra código e labels · **{{fonts.display}}** pra títulos.
+- **Sem pill, sem rounded extremo.** Tags, chips, toggles, badges usam raio sm/md (4-6px). Avatares usam 50% (círculos geométricos, não pills). Veja o bloco anti-IA no topo.
 
 ---
 
@@ -224,6 +258,161 @@ function Dashboard() {
 
 ---
 
+## Receitas prontas (copy-paste, HTML)
+
+> Padrões testados em produção. Comece daqui em vez de inventar do zero.
+
+### Botão primário + secundário (ação padrão)
+
+```html
+<div style="display:flex; gap:8px;">
+  <button class="btn btn-primary btn-md">Salvar</button>
+  <button class="btn btn-secondary btn-md">Cancelar</button>
+</div>
+```
+
+Regra: **um** primário por bloco/modal. Outros viram secondary, soft ou ghost.
+
+### Botão de perigo (ação destrutiva)
+
+```html
+<button class="btn btn-danger btn-md">Excluir conta</button>
+```
+
+Não é vermelho dominante; é texto vermelho em fundo branco com hover suave (`--danger-50`). Vermelho cheio só em `.alert-critical` (banner de erro imediato).
+
+### Card básico (panel)
+
+```html
+<div class="panel">
+  <div class="panel-head">
+    <div class="panel-title">Resumo do mês</div>
+    <div class="panel-kicker">Atualizado agora</div>
+  </div>
+  <div class="panel-body">
+    Conteúdo do card. Texto direto, sem travessão.
+  </div>
+</div>
+```
+
+Raio `var(--r-lg)` (8px). Hairline 1px em `--line-200`. Sombra `--shadow-sm`. Sem gradiente, sem glassmorphism.
+
+### Card KPI (StatCard)
+
+```html
+<div class="stat">
+  <div class="stat-head">
+    <span class="stat-label">CONCLUÍDAS · SEMANA</span>
+    <span class="stat-icon green">✓</span>
+  </div>
+  <div class="stat-value">8</div>
+  <div class="stat-sub">+18% vs anterior</div>
+</div>
+```
+
+Label em uppercase `--ls-widest`. Valor em display font. Sub-texto pequeno, com cor neutra.
+
+### Formulário (campo + label + erro)
+
+Use o primitivo `.input` com HTML semântico. Label acima do input, help text abaixo. Sem classes inventadas — o sistema é minimalista, você compõe com flex/grid e tokens:
+
+```html
+<label style="display:flex; flex-direction:column; gap:6px; max-width:360px;">
+  <span style="font-size:var(--fs-sm); font-weight:500; color:var(--ink-700);">Email</span>
+  <span class="input input-md">
+    <input type="email" placeholder="voce@exemplo.com"/>
+  </span>
+  <span style="font-size:var(--fs-xs); color:var(--ink-400);">Usaremos pra notificações importantes.</span>
+</label>
+
+<label style="display:flex; flex-direction:column; gap:6px; max-width:360px; margin-top:16px;">
+  <span style="font-size:var(--fs-sm); font-weight:500; color:var(--ink-700);">Senha</span>
+  <span class="input input-md invalid">
+    <input type="password"/>
+  </span>
+  <span style="font-size:var(--fs-xs); color:var(--danger-700);">Mínimo 8 caracteres.</span>
+</label>
+```
+
+Erro = `.input` com classe `.invalid` (borda vermelha) + help em `var(--danger-700)`. Help text curto, direto, sem travessão.
+
+### Status (TagDot) — quando há fluxo
+
+```html
+<span class="tag-dot s-todo">A FAZER</span>
+<span class="tag-dot s-progress">EM ANDAMENTO</span>
+<span class="tag-dot s-review">EM REVISÃO</span>
+<span class="tag-dot s-done">CONCLUÍDO</span>
+<span class="tag-dot s-canceled">CANCELADO</span>
+```
+
+Use `tag-dot` (raio 4px) **NUNCA** `border-radius: 999px`. Texto sempre uppercase, weight 600.
+
+### Empty state (quando lista vazia)
+
+```html
+<div class="empty-state">
+  <div class="ico">📭</div>
+  <div class="text">Nenhum lead ainda.</div>
+  <button class="btn btn-primary btn-sm">Adicionar primeiro lead</button>
+</div>
+```
+
+Sem ilustração 3D, sem gradiente. Ícone simples + CTA único.
+
+### Alerta crítico (ação imediata)
+
+```html
+<div class="alert-critical">
+  <div class="alert-critical-head">⚠ Atenção necessária</div>
+  <div class="alert-critical-list">
+    <div class="alert-critical-row">
+      <span>3 leads sem follow-up há mais de 7 dias.</span>
+      <span class="src">crm/pipeline</span>
+    </div>
+    <div class="alert-critical-row">
+      <span>Limite de envios próximo do teto mensal.</span>
+      <span class="src">billing</span>
+    </div>
+  </div>
+  <div class="alert-critical-foot">2 itens · revisar agora</div>
+</div>
+```
+
+Único componente onde vermelho é background dominante. Use SÓ pra coisa que precisa ação humana imediata.
+
+### Toast (feedback rápido)
+
+```html
+<div class="toast toast-success">Salvo.</div>
+<div class="toast toast-danger">Falhou ao salvar.</div>
+```
+
+Texto curto. **Uma frase.** Sem "Operação realizada com êxito! 🎉" — direto.
+
+---
+
+## Regras de copy (texto da UI)
+
+Quando a IA gera **labels de botão, mensagens, placeholders, títulos**:
+
+| Faça | Não faça |
+|------|----------|
+| "Salvar" | "Salvar alterações no sistema agora" |
+| "Email inválido." | "O endereço de email fornecido não atende — é inválido." |
+| "Adicionar lead" | "✨ Crie seu próximo lead com nossa IA! 🚀" |
+| "Limite atingido." | "Você atingiu o limite — entre em contato com nosso time" |
+| "8 concluídas hoje" | "Olha só — você concluiu 8 tarefas hoje, parabéns!" |
+
+**Princípios:**
+1. Sem travessão (—) nem en-dash (–). Use vírgula, ponto ou dois-pontos.
+2. Sem emoji em label de botão / título de campo. Emoji só em empty state, toast informativo, ou banner.
+3. Frases ≤ 12 palavras em UI. Se passou, quebra ou corta.
+4. Voz ativa. Sujeito + verbo + complemento. "Você concluiu 8" não "Foram concluídas 8 por você".
+5. Sem "experimente", "descubra", "transforme", "potencialize" — vocabulário de landing page de IA, não app real.
+
+---
+
 ## Dark mode
 
 Toggle automático via OS, ou manual:
@@ -239,14 +428,32 @@ A cor de marca (`--brand-500`) **NUNCA muda no dark mode** — é assinatura da
 
 ## Regras importantes (NÃO fazer)
 
-- ❌ Trocar `--brand-500` por outra cor.
-- ❌ Hardcode de hex (`#f56f10` no código). SEMPRE use `var(--brand-500)`.
-- ❌ Sombras frias (`rgba(0,0,0,...)`). Use as warm `rgba(20,17,12,...)`.
-- ❌ `border-radius: 999px` ou `--r-pill`. Pill foi removido v3.
-- ❌ Display font (Space Grotesk) em UI body — só títulos h1/h2/h3, modal titles, brand.
-- ❌ Inter em títulos — display font é Space Grotesk.
+> Resumo prático. Detalhes no bloco "anti-IA-genérica" no topo deste README.
+
+**Cor**
+- ❌ Trocar `--brand-500` no meio do projeto (regenere o DS com nova primária).
+- ❌ Hex hardcoded. SEMPRE `var(--brand-500)` ou token.
+- ❌ Sombras frias `rgba(0,0,0,...)`. Use warm `rgba(20,17,12,...)`.
+- ❌ Brand color como bg dominante.
+
+**Geometria**
+- ❌ `border-radius: 999px` / `9999px` / `--r-pill`. Pill banido.
+- ❌ Raio > `var(--r-2xl)` (16px) em qualquer componente.
+- ❌ Borda > 1px em UI normal.
+
+**Texto / copy**
+- ❌ Travessão (—) ou en-dash (–) em qualquer texto da UI/copy.
+- ❌ Emoji em label de botão, título de campo, título de página.
+- ❌ Frase > 12 palavras em UI.
+- ❌ Vocabulário de marketing IA: "transforme", "potencialize", "descubra", "experimente".
+
+**Tipografia**
+- ❌ {{fonts.display}} em UI body. Só títulos h1/h2/h3, modal titles, brand.
+- ❌ {{fonts.ui}} em h1 grande de página — display font é {{fonts.display}}.
+
+**Motion**
 - ❌ Animação > 280ms em microinterações.
-- ❌ Brand color como bg dominante de tela inteira.
+- ❌ Bounce/elastic em UI — só `--ease-spring` em entradas de modal.
 
 ---