G4OS-DS
Site e documentação: https://gestao-quatro-ponto-zero.github.io/G4OS-DS/ · npm: @g4ai/ds
Design system para construir qualquer aplicação G4 OS — CRM, ATS, ERP, financeiro, IA, portal do cliente, produto SaaS — com a mesma linguagem visual:
- Tokens em três camadas (primitivos → semânticos → utilitários), com tema escuro e marcas de cliente trocando só variáveis.
- Componentes: React 19 (compatível com 18.2+) + Base UI + Tailwind v4, em português, acessíveis, responsivos. Gráficos em SVG sem dependência.
- Blocos: 85+ telas completas (dashboards, pipelines, registros, listas, IA, login, configurações) para copiar e trocar os dados.
- Feito para agentes: servidor MCP,
llms.txt, guiaai/gerado do código e skills para Claude Code.
Instalar
Requisitos: React 18.2+ ou 19, Tailwind CSS 4, Node 20+ (React 18).
pnpm add @g4ai/ds @base-ui/react lucide-react # ou npm i / yarn add
pnpm add -D tailwindcss @tailwindcss/postcss # Vite: @tailwindcss/vite
npx g4os-ds doctor # confere React, Tailwind, CSS, tema e fonte
npx g4os-ds init # auditoria contínua: config, scripts ds:*, CI (ver "Qualidade")
/* app/globals.css (Next) ou src/index.css (Vite) */
@import "tailwindcss";
@import "@g4ai/ds/styles.css"; /* tokens, temas, componentes; já traz os @source do DS */
O pacote publica JavaScript compilado (ESM com "use client") e tipos, junto com o CSS e o código-fonte que o Tailwind lê. Não precisa de transpilePackages nem plugin extra.
Next.js (App Router)
// app/layout.tsx
import { themeScript } from "@g4ai/ds";
import { DsSetup } from "@/lib/ds";
import "./globals.css";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="pt-BR" className="ds-app" data-theme="system" suppressHydrationWarning>
<head><script dangerouslySetInnerHTML={{ __html: themeScript }} /></head>
<body><DsSetup />{children}</body>
</html>
);
}
// lib/ds.tsx — registra o Link do Next nos componentes com href
"use client";
import Link from "next/link";
import { setLinkComponent } from "@g4ai/ds";
setLinkComponent(Link);
export function DsSetup() { return null; }
Starter completo: templates/next-app · guia: docs/guias/next.md.
Vite
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";
import { themeScript } from "@g4ai/ds/lib/theme";
// Aplica o tema salvo antes da primeira pintura (sem piscar).
const dsTheme = { name: "ds-theme", transformIndexHtml: () => [{ tag: "script", children: themeScript, injectTo: "head-prepend" as const }] };
export default defineConfig({ plugins: [react(), tailwindcss(), dsTheme] });
<!-- index.html -->
<html lang="pt-BR" class="ds-app" data-theme="system">
Guia: docs/guias/vite.md.
Usar
import { AppShell, Sidebar, Page, PageHeading, KpiGrid, KpiCard, ChartCard, AreaChart, formatCurrency } from "@g4ai/ds";
Para começar uma tela, copie o bloco mais parecido de node_modules/@g4ai/ds/src/blocks/ (ou do site, aba Código) e troque os dados.
Tema, dark mode e marca
<html data-theme="dark"> <!-- light | dark | system; ThemeToggle/useTheme trocam e salvam -->
<html data-brand="g4os"> <!-- presets de marca; ou o seu [data-brand="acme"] com --ds-primary… -->
<html data-type="editorial"> <!-- presets de tipografia -->
Marca de cliente com contraste AA (claro e escuro): skill ds-theme, ferramenta MCP theme_from_colors ou docs/fundamentos/temas-e-dark-mode.md.
Usar com IA
MCP (Claude Code, Codex, Cursor, VS Code, Gemini CLI, Zed, Windsurf, pi, qualquer cliente MCP). Roda local, lê a versão instalada do DS, sem rede:
claude mcp add g4os-ds -- npx -y @g4ai/ds mcp # Claude Code
codex mcp add g4os-ds -- npx -y @g4ai/ds mcp # Codex
// Cursor, Claude Desktop, Windsurf, Gemini CLI… · VS Code (.vscode/mcp.json) usa "servers" no lugar de "mcpServers"
{ "mcpServers": { "g4os-ds": { "command": "npx", "args": ["-y", "@g4ai/ds", "mcp"] } } }
Config de cada cliente, Windows, modo HTTP (npx -y @g4ai/ds mcp --http) e problemas comuns: docs/guias/mcp.md.
Ferramentas: search, get_component, list_blocks, get_block, get_guide, get_tokens, theme_from_colors, audit, doctor. Prompts: criar-tela, revisar-tela, adaptar-projeto.
Web (para agentes que só leem URLs):
- https://gestao-quatro-ponto-zero.github.io/G4OS-DS/llms.txt — índice
- https://gestao-quatro-ponto-zero.github.io/G4OS-DS/llms-full.txt — tudo num arquivo
…/ai/core.md,…/ai/components/<módulo>.md,…/ai/blocks/<slug>.md,…/ai/manifest.json,…/docs/…
No projeto: node_modules/@g4ai/ds/ai/core.md é a porta de entrada. Cole templates/AGENTS.snippet.md no AGENTS.md/CLAUDE.md do app.
Plugin do Claude Code (skills g4os-ds, ds-create, ds-migrate, ds-review, ds-theme):
/plugin marketplace add Gestao-Quatro-Ponto-Zero/G4OS-DS
/plugin install g4os-ds@g4os
Depois peça: "Adapte este projeto ao G4OS-DS", "Crie a tela de pedidos com o design system", "Revise esta tela", "Tema do cliente Acme, azul #0b5cff". Guia: docs/guias/usar-com-ia.md · no site: Guias › Agentes de IA.
Qualidade: auditoria, lint e CI
As regras do DS (tokens, tipografia, anatomia de página, composição de componentes, acessibilidade, formatação e escrita pt-BR, imports, React) viram checagens automáticas. Um motor só, usado pelo CLI, pelo plugin ESLint, pelo CI e pela tool audit do MCP. Guia completo: docs/guias/auditoria.md.
npx g4os-ds init # g4os-ds.config.json + scripts ds:* + workflow de CI (--eslint, --hook lefthook, --baseline)
npx g4os-ds doctor # pré-requisitos: React 18.2+/19, Tailwind v4, ordem do CSS, tema, fonte, React duplicado
npx g4os-ds audit # o que foge do DS, com a troca sugerida
npx g4os-ds audit --fix # aplica as trocas seguras (bg-white→bg-surface, rounded-[12px]→rounded-card…)
npx g4os-ds audit --changed # só o que mudou (--staged no pre-commit, --since origin/main no PR)
npx g4os-ds audit --baseline # projeto legado: só achado novo falha
npx g4os-ds audit --format sarif # também: pretty, json, markdown, github (anotações no PR)
npx g4os-ds rules # lista as 47 regras
// eslint.config.mjs: as mesmas regras no editor e no `eslint .`
import g4osDs from "@g4ai/ds/eslint";
export default [/* …sua config */ g4osDs.configs.recommended];
Exit code: 0 ok · 1 achados que falham · 2 erro de uso/config. Exceção com motivo: // g4os-ds-disable-next-line <regra> -- motivo.
As regras de anatomia e composição pegam o que deixa uma tela migrada "esquisita" mesmo com 0 erros: corpo centralizado fora do eixo do título (page-width-wrapper), botão desabilitado apagado por wrapper (disabled-wrapper), rótulo duplicado (field-double-label), controles crus (raw-input), Select por linha (select-per-row), texto em inglês ou "com sucesso!" (english-copy, copy-tone). Para medir se agentes de IA acertam com essas instruções, há um eval em scripts/eval/ (usar com IA).
CLI
npx g4os-ds init # prepara o projeto (config, scripts, CI)
npx g4os-ds doctor # o projeto pode usar o DS?
npx g4os-ds audit [pastas] # auditoria (--fix, --format, --changed, --baseline)
npx g4os-ds rules # regras, categorias e gravidades
npx g4os-ds guide # imprime o caminho do guia ai/core.md
npx g4os-ds mcp # servidor MCP (stdio; --http para Streamable HTTP)
Atualizar de versão
pnpm up @g4ai/ds # ou npm i @g4ai/ds@latest
npx g4os-ds audit --fix # troca nomes renomeados e o que for seguro; aponta regras novas
Leia o CHANGELOG entre a sua versão e a nova: cada entrada diz o que o app precisa fazer. Renomeações ficam em ai/renames.json; com o plugin, peça "Atualize o @g4ai/ds e ajuste o código" (skill ds-migrate, modo atualização). Seguimos SemVer: enquanto estivermos em 0.x, mudança que quebra sobe o minor e vem com "como migrar".
Documentação
| Para | Onde |
|---|---|
| Ver e copiar componentes e blocos | site (⌘K busca tudo) |
| Instalar e configurar | instalação · Next · Vite · shadcn/21st.dev |
| Migrar um projeto existente | migração |
| Montar telas | anatomia de página · padrões · blocos |
| Montar um app inteiro | receitas: CRM, ATS, ERP, financeiro, portal do cliente |
| Fundamentos | tokens · temas e dark mode · escrita |
| Regras para quem constrói (pessoas e agentes) | AGENTS.md |
Componentes
Todos exportados por @g4ai/ds (ou por módulo: @g4ai/ds/components/<arquivo>).
| Família | Arquivo | Exporta |
|---|---|---|
| Primitivos | primitives | Button, IconButton, buttonClass, FilterChip, Badge, Dot, CriticalFlag, Avatar, AvatarGroup, EntityMark, Card, LinkedCard, CardAction, Section, Field, FactLine, Metric, StatGrid, StatCell, Meter, Empty, Page, Kbd, DsLink, setLinkComponent, Tone, toneDot, toneText |
| Formulários base | forms | FieldBlock, FieldGrid, fieldClass, areaClass, Select, Combobox, Checkbox, Switch, SearchInput |
| Campos | inputs | TextField, TextareaField, PasswordField, passwordStrength, NumberField, CurrencyField, MaskedField, masks, applyMask, OtpInput, TagInput, Slider, RadioGroup, ChoiceCards, ToggleGroup, FileDropzone, Rating, InlineEdit |
| Data | date-picker | DatePicker, toDate, toIso, formatIsoDate |
| Navegação | navigation | Sidebar, ProductMark, SyncStatus, PageHeading, StickyHeader, Breadcrumb, ContextBar, Tabs, SegmentedControl, ActionMenu, actionMenuTriggerClass |
| Layout | layout | AppShell, ShellBanner, EntityHeader, SplitLayout, ReadingColumn |
| Recolhíveis | disclosure | Accordion, Collapsible, TreeView, DescriptionToggle |
| Sobreposições | overlays | Modal, ConfirmDialog, Drawer, Popover, popupClass |
| Sobreposições extras | overlays-extra | Tooltip, TooltipGroup, HoverCard, Menu, ContextMenu, Sheet, CommandPalette, useCommandShortcut, Lightbox |
| Feedback | feedback | notify, Toaster, Callout, useOperation, OperationButton, OperationFeedback, UncertainFailure, Skeleton |
| Estados | states | StateView, NotFoundState, ErrorState, ForbiddenState, OfflineState, MaintenanceState, SuccessState, LoadingState, LoadingOverlay, Spinner, Banner, InlineMessage, AlertCard, CountBadge, NotificationDot |
| Status e progresso | status | StatusLabel, HealthDot, StatusBar, Stepper, NextStep, Timeline, statusColor, statusLabel, statusOrder |
| Coleções | collections | TableToolbar, FacetFilter, DataTable, Column, DisplayControls, DensityControl, useCollectionDisplay, ListPanel, ListRow, KanbanBoard, KanbanColumn, KanbanCard, collectionThresholds |
| Estado de tabela | data | useSort, SortHeader, useSelection, selectionColumn, BulkBar, usePagination, Pagination, PropertyList |
| Pipelines | pipeline | StagePath, RecordCard |
| Dashboard | dashboard | KpiCard, KpiGrid, Delta, ChartCard, GoalMeter, CompareStat, ActivityFeed, Leaderboard |
| Gráficos | charts | AreaChart, LineChart, BarChart, Sparkline, BarList, DonutChart, FunnelChart, CalendarHeatmap, ProgressRing, ChartTooltip, ChartLegend, chartColor |
| Gráficos avançados | charts-advanced | Treemap, WaterfallChart, ScatterChart, RadarChart, GaugeChart, BulletChart, SankeyChart, HeatmapMatrix, ComboChart, ProportionBar, GanttChart |
| Mídia e conteúdo | media | Carousel, SlideDeck, Slide, SlideTitle, SlideBullets, SlideSplit, SlideStat, SlideQuote, SlideCanvas, ImageGallery, AspectFrame, FileCard, FileIcon, formatBytes |
| Utilitários | lib/* | cn, formatCurrency, formatNumber, formatPercent, formatDelta, formatCompact, formatDate, formatRelative, normalize, plural, initials, usePortalContainer, tokens |
Exemplos vivos, regras e props: site ou ai/components/<arquivo>.md. A lista completa está em src/index.ts.
Blocos
Arquivos em src/blocks/ (também no pacote: node_modules/@g4ai/ds/src/blocks/). Cada bloco importa só de @g4ai/ds, traz os dados de exemplo no topo, funciona de 320 a 1440 px e explica o conceito (objetivo, padrões, quando usar, o que evitar) em ai/blocks/<slug>.md.
| Categoria | Exemplos |
|---|---|
| SaaS | saas-dashboard, saas-customers, saas-plans, saas-usage, saas-analytics, saas-mrr-bridge, saas-retention, saas-journey, saas-unit-economics, saas-regions, saas-explore, saas-usage-horizon |
| CRM | crm-sales-dashboard, crm-pipeline, crm-leads, crm-quotes, crm-deal, crm-contacts |
| ATS | ats-dashboard, ats-jobs, ats-pipeline, ats-candidate, ats-requisitions, ats-reports |
| ERP | erp-dashboard, erp-orders, erp-products, erp-purchase-orders, erp-receiving, erp-shipping, erp-invoice |
| Serviços (ERP de serviços) | srv-dashboard, srv-work-orders, srv-work-order, srv-contracts, srv-invoices, srv-billing |
| Financeiro | fin-dashboard, fin-cashflow, fin-receivables, fin-bank-accounts, fin-dre, fin-reconciliation |
| Contratos | clm-dashboard, clm-contracts, clm-contract, clm-approvals, clm-obligations |
| Comunicação | comms-home, comms-announcement, comms-channels, comms-people, comms-surveys |
| IA | ai-agents-dashboard, ai-agents, ai-agent, ai-runs, ai-approvals, ai-agent-evals, ai-agent-run, ai-workspace, ai-chat, ai-answer, ai-delegate, ai-codex |
| Aplicação | app-command-palette, app-notifications, app-file-manager, app-error-pages, app-presentation, app-help-center, app-legal |
| Autenticação, configurações, onboarding | auth-login, auth-otp, settings-organization, settings-roles, settings-team, settings-billing, settings-storage, onboarding-wizard, onboarding-intro |
Catálogo completo com objetivo de cada um: ai/llms.txt ou list_blocks no MCP. Qual bloco usar por tipo de app: AGENTS.md.
shadcn/ui e 21st.dev
Para o que o DS não tem, traga do shadcn/ui ou do 21st.dev e importe @g4ai/ds/shadcn.css: as variáveis do shadcn passam a apontar para os tokens do DS. Colisões (bg-accent, bg-muted) e checklist: docs/guias/shadcn.md.
Contribuir
git clone https://github.com/Gestao-Quatro-Ponto-Zero/G4OS-DS.git && cd G4OS-DS
npm ci
npm run showcase:watch # site local em showcase/dist
npm run check # tokens + tipos + lint + ai/ em dia + auditoria + testes (critério de pronto)
npx changeset # descreve a mudança: patch, minor ou major
Como sai uma versão: o PR com changeset entra na main → o GitHub Actions abre (ou atualiza) o PR "Versão de lançamento" com o novo número e o CHANGELOG → ao mesclar esse PR, o pacote é publicado no npm automaticamente (Trusted Publishing, com provenance). Ninguém roda npm publish à mão. O site é republicado a cada push na main.
Fluxo completo: CONTRIBUTING.md · contratos técnicos (componente, bloco, página do site): docs/guias/contribuir.md.
| Comando | Faz |
|---|---|
npm run check | tokens CSS ↔ TS + TypeScript + ESLint + ai/ em dia + auditoria do próprio DS + testes do lint e do MCP |
npm run lint | ESLint (typescript-eslint, hooks, jsx-a11y e o plugin @g4ai/ds/eslint) |
npm run audit:self | g4os-ds audit em src/, templates/ e showcase/ |
npm run test:lint | fixtures de cada regra, RuleTester do ESLint, config, baseline, formatos, init e doctor |
npm run build | compila dist/ (o que vai para o npm) |
npm run ai:build | regenera ai/ (guia para agentes) a partir do código |
npm run showcase | compila o site e serve em http://localhost:4173 |
npm run showcase:watch | recompila o site a cada mudança |
Mapa do repositório
src/ styles/ (tokens, temas, componentes, shadcn.css) · tokens/ · lib/ · components/ · blocks/ · index.ts
showcase/ site de documentação (main.tsx, kit.tsx, pages/*.tsx, build.mjs → também gera llms.txt)
docs/ fundamentos · padroes · receitas · guias
ai/ gerado: core.md · tokens.md · components/*.md · blocks/*.md · manifest.json · llms.txt · renames.json
scripts/ cli.mjs (g4os-ds audit | doctor | init | rules | guide | mcp) · lint/ (regras, motor, formatos, plugin ESLint) · mcp.mjs · build-ai-docs.mjs
plugin/ plugin do Claude Code (skills) · .claude-plugin/marketplace.json
templates/ next-app (starter) · AGENTS.snippet.md
AGENTS.md regras obrigatórias e qual bloco usar · CHANGELOG.md o que mudou e o que o app precisa fazer
Licença
Código sob licença MIT. Os nomes e marcas "G4", "G4 OS" e "G4 Educação" não são cobertos pela licença: ao usar o DS em outro produto, troque a marca (ProductMark, nome do produto) pela sua.