🎨 zark-design — Design System anti-cara-de-IA (gerador agnóstico de marca)

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.

# 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

O que é

zark-design é um scaffolder de design system híbrido parte do ecossistema ZARK. 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

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.

🚀 Quick start

Modo preset (ZARK pronto)

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)

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

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

npx zark-design@latest presets

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:

• zark-dev — metodologia + contexto pra IA (orquestra todo o método)
• zark-design ← você está aqui
• zark-seo — 17 skills SEO/GEO especialistas, foco BR
• zark-skills — 5 skills Claude Code user-level

Quem está por trás

Maycon Jordan — fundador da ZARK. Design system derivado do CRM real da ZARK + clientes (Limppetec, AllSec, VipCar, VipSeg, MixShop), refinado em produção.

Tags

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

Licença

MIT — Maycon Jordan / ZARK · 2026