G4 Atlas Design System

Biblioteca de componentes React, tokens de design e utilitários para construção de interfaces consistentes nos produtos G4.

Índice

• Instalação
• Setup
• Componentes
• Hooks
• Utilitários
• Providers
• Storybook

Instalação

O pacote é publicado no npm público — nenhuma configuração de autenticação é necessária.

pnpm add @g4business/design-system
# ou
npm install @g4business/design-system

Setup

1. Importe os estilos

No arquivo CSS principal da sua aplicação:

@import "@g4business/design-system/styles/theme";
@import "@g4business/design-system/styles/gradients"; /* opcional */

2. Configure o ThemeProvider

import { ThemeProvider } from "@g4business/design-system";

function App() {
  return (
    <ThemeProvider defaultTheme="system">
      {/* sua aplicação */}
    </ThemeProvider>
  );
}

Exports disponíveis

| Export | Conteúdo | |---|---| | @g4business/design-system | Componentes, hooks, utilitários e tipos | | @g4business/design-system/styles/theme | Tema completo com variáveis CSS | | @g4business/design-system/styles/gradients | Gradientes customizados |

Componentes

Foundations

| Componente | Descrição | |---|---| | Logomark | Marca G4 (minimal, illustration, app) | | Logo | Logo completo G4 (brand-default, brand-alternate, white, black) | | Payment Icons | Ícones de bandeiras de pagamento (Visa, Mastercard, Amex, etc.) |

Primitives

| Componente | Descrição | |---|---| | DSButton | Botão com 10 variantes, 5 tamanhos, suporte a ícones e loading | | ButtonClose | Botão de fechar (ícone X) | | ButtonGroup | Agrupador de botões com bordas unificadas | | DSTooltip | Tooltip acessível via React Aria | | Badge | Badge com 17 cores, 3 tamanhos, dot, avatar e dismiss | | Avatar | Avatar com foto, iniciais ou placeholder e indicador de status | | Checkbox | Checkbox acessível com label e supporting text | | Switch | Toggle switch acessível | | Radio | Radio button acessível | | RadioGroup | Container de agrupamento de radios | | Tag | Label compacta com checkbox, avatar, dot e count | | Tabs | Abas com variantes underline, button e button-brand | | TextareaField | Campo de texto multilinha com validação | | ContentDivider | Divisor horizontal com conteúdo centralizado | | BreadcrumbButton | Item de breadcrumb polimórfico (button/link) | | Table | Tabela composicional (Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption) | | ProgressBar | Barra de progresso linear | | ProgressCircle | Indicador de progresso circular SVG | | Slider | Slider com thumb único ou range | | DatePicker | Seletor de data com calendário | | PaginationItem | Botão de página individual | | PaginationDotIndicator | Indicador de posição dot/bar | | ActivityGauge | Gauge circular SVG com múltiplas séries | | BarChart | Gráfico de barras (Recharts) | | LineChart | Gráfico de linhas (Recharts) | | PieChart | Gráfico pizza/donut (Recharts) | | RadarChart | Gráfico radar/spider (Recharts) |

Composed

| Componente | Descrição | |---|---| | AvatarGroup | Grupo de avatares empilhados com "+N" e botão de adicionar | | AvatarLabelGroup | Avatar + título + subtítulo | | RadioGroupItem | Card selecionável para uso com RadioGroup | | EditorToolbar | Toolbar de editor de texto rico | | EditorColorPicker | Seletor de cores com grid de swatches | | VideoPlayer | Player de vídeo com controles customizados | | Breadcrumbs | Navegação breadcrumb semântica | | DateRangePicker | Seletor de intervalo de datas com presets | | MetricItem | Card de KPI com sparkline e trend | | Pagination | Controle de paginação (numbers, simple, compact, bar) | | TagInput | Campo de input multi-tag | | VerificationCodeInput | Input OTP/2FA multi-dígito |

Patterns

| Componente | Descrição | |---|---| | TextEditor | Editor de texto rico com toolbar integrada |

Hooks

| Hook | Descrição | |---|---| | useBreakpoint(breakpoint) | Retorna true quando o viewport atinge o breakpoint informado | | useBreakpoints() | Retorna o mapa completo de breakpoints ativos | | useClipboard(timeoutMs?) | Copia texto para o clipboard com feedback de estado | | useMask({ mask, onChange?, onChangeRaw? }) | Aplica máscaras de input (9 dígito, A letra, * qualquer) | | useTextEditor({ defaultValue?, onChange? }) | Editor rich text com contenteditable e rastreamento de formatações |

import { useBreakpoint, useClipboard, useMask } from "@g4business/design-system";

const isDesktop = useBreakpoint("lg");

const { copied, copy } = useClipboard(2000);

const cpfMask = useMask({ mask: "999.999.999-99", onChange: setMasked });

Utilitários

| Utilitário | Descrição | |---|---| | cn(...inputs) | Merge de classes Tailwind sem conflitos (clsx + tailwind-merge) | | applyMask(value, mask) | Aplica uma máscara a um valor bruto | | unmask(value, mask) | Remove a máscara de um valor formatado |

import { cn, applyMask, unmask } from "@g4business/design-system";

cn("p-4 bg-brand-500", isActive && "bg-brand-700", className);

applyMask("12345678901", "999.999.999-99"); // "123.456.789-01"
unmask("123.456.789-01", "999.999.999-99"); // "12345678901"

Providers

ThemeProvider

Gerencia o tema light/dark/system com persistência em localStorage:

import { ThemeProvider, useTheme } from "@g4business/design-system";

<ThemeProvider defaultTheme="system" storageKey="g4-theme" darkModeClass="dark-mode">
  <App />
</ThemeProvider>

// Em qualquer componente filho
const { theme, setTheme } = useTheme();
setTheme("dark");

| Prop | Tipo | Default | Descrição | |---|---|---|---| | defaultTheme | "light" \| "dark" \| "system" | "system" | Tema quando nenhum está salvo | | storageKey | string | "ui-theme" | Chave no localStorage | | darkModeClass | string | "dark-mode" | Classe aplicada no root no modo escuro |

Storybook

Todos os componentes e tokens visuais estão documentados no Storybook.
Consulte o Storybook para explorar variantes, props e exemplos interativos de cada componente.

Licença

Projeto proprietário — G4 Gestão 4.0. Todos os direitos reservados.