@g4-educacao/g4-apollo-design-system v0.10.0

G4 Apollo Design System

Design System da organização G4 Educação, construído com React, Vite, Tailwind CSS, ShadCN, Radix UI e tokens CSS personalizados.

✨ Totalmente modular com suporte a Atomic Design e distribuição via NPM.

📦 Instalação

1. Via NPM (produção ou consumo externo)

pnpm add @g4-educacao/g4-apollo-design-system@develop
# ou
npm install @g4-educacao/g4-apollo-design-system@develop

💡 Importando componentes e CSS

Após instalar o pacote, importe os componentes que desejar e o CSS global do Design System no seu projeto consumidor:

import {
    Badge,
    BreadcrumbBuilder,
    Button,
    Checkbox,
    DropdownMenu,
    DropdownMenuContent,
    Icon,
    SearchBar,
    Switch,
    TextArea,
} from '@g4-educacao/g4-apollo-design-system';
import '@g4-educacao/g4-apollo-design-system/css';

2. Desenvolvimento local via npm link

Caso deseje contribuir com o design system e testá-lo em um projeto local:

# Dentro da pasta do design system
pnpm install
pnpm build
pnpm link

# Em outro projeto que irá consumir o design system
pnpm link @g4-educacao/g4-apollo-design-system

⚠️ Após alterações no design system, sempre rode pnpm build novamente para refletir as mudanças no projeto consumidor.

💡 Criação de novos componentes.

Componentes baseados no Shadcn

Para criar novos componentes baseados no shadcn, você pode rodar um dos scripts abaixo, de acordo com o local onde deseja que ele seja criado:

pnpm add:atom nome-do-componente
pnpm add:molecule nome-do-componente
pnpm add:organism nome-do-componente
pnpm add:template nome-do-componente

Ao executar esse script, além de criar a pasta onde ficará o componente e o componente.tsx em si, o mesmo será exportado no index.ts da pasta destino.

Por exemplo, ao rodar o comando:

pnpm add:molecule button

será criada a pasta src/components/molecules/buttom, o componente button.tsx baseado no shadcn e será adicionado o seguinte trecho de código em src/components/molecules/index.ts:

export * from './button/button';

Criação de componentes manualmente

Para criar componentes de forma manual ou que não faça parte do acervo do Shadcn , basta seguir os passos do processo dos scripts descritos acima:

1- Criar a pasta referente ao componente desejado, dentro da estrutura que fizer sentido (atoms, molecules, organisms ou templates). 2- Criar o componente.tsx na pasta criada anteriormente. Exemplo: src/components/molecules/button 3- Reexportar o componente dentro do index.tsda pasta criada.

Arquivos CSS

Em casos de componentes mais complexos onde faz sentido a criação de um arquivo css separado, é preciso importar o CSS no na folha de estilo raiz do projeto src/index.css.

Por exemplo, na criação do arquivo button.css é preciso adicionar o seguinte trecho de código em src/index.css:

@import './components/molecules/button/button.css';

🧪 Scripts úteis

🎨 Criar novo ícone SVG automaticamente

pnpm create:icon nome-do-icone

Gera o componente no padrão e registra no iconsMap.ts. Exemplo: ao rodar o comando pnpm create:icon novo-icone, irá gerar o arquivo NovoIcone.tsx em src/componentes/atoms/icon/icons, com a seguinte estrutura:

import { SvgWrapper } from '@/components/atoms/icon/svgWrapper';
import { IconProps } from '@/components/atoms/icon/iconsMap';

export const NovoIcone = ({ size, className, color = 'var(--color-icon-g400)' }: IconProps) => (
  <SvgWrapper size={size} className={className}>
    {/* Cole aqui o <path> do SVG */}
  </SvgWrapper>
);

Basta atualizar o arquivo com o <path> do svg e atualizar os imports do arquivo iconsMap.tsx para enxergar o novo componente.

Pronto, o Design System está pronto para enxergar o novo ícone.

📚 Desenvolvimento

• pnpm dev: roda o Vite em modo dev
• pnpm preview: preview da build

🧼 Qualidade e formatação

• pnpm lint: analisa o projeto com ESLint
• pnpm format: formata todos os arquivos com Prettier

🧪 Testabilidade

Todos os componentes do Apollo Design System aceitam a propriedade data-testid para facilitar testes automatizados (como com Testing Library ou Cypress).

Como usar:

<Button data-testid="submit-button" label="Salvar" icon="check" />
<Icon data-testid="trash-icon" name="trash" />

Caso o data-testid não seja informado, um identificador padrão será atribuído automaticamente (ex: icon-trash, button, etc.).

💡 Recomendamos fortemente sempre informar o data-testid ao usar os componentes, para garantir testes mais claros e consistentes.

🚀 Publicação

Para publicar versões com versionamento semântico e tags (develop, master, etc):

pnpm release

Esse comando interativo pergunta:

1. Tipo de versão (patch, minor, major)
2. Tag a ser publicada (develop, master, etc.)

📦 Pacote NPM

O G4 Apollo Design System está disponível no NPM:

@g4-educacao/g4-apollo-design-system no npmjs.com

Instalação

npm install @g4-educacao/g4-apollo-design-system
# ou
yarn add @g4-educacao/g4-apollo-design-system
# ou
pnpm add @g4-educacao/g4-apollo-design-system

---

## 🧠 Tecnologias usadas

- React 19
- TypeScript
- Tailwind CSS 4
- ShadCN + Radix UI
- Class Variance Authority (`cva`)
- CSS tokens com `@theme` e `:root`
- Storybook
- Vitest

---

## 📮 Contato

Projeto mantido por G4 Educação.
Dúvidas ou sugestões? Entre em contato com o time de tecnologia interno.