Design System TellusCompany

Biblioteca de componentes oficial da TellusCompany para desenvolvimento de interfaces consistentes e escaláveis. Um sistema de design completo que centraliza padrões visuais, componentes reutilizáveis e diretrizes de experiência do usuário.

Mais, detalhes sobre o NPM token em: https://gs3tellus.atlassian.net/wiki/x/AYAIEg

Características

🎯 Consistência: Padrões visuais unificados em todos os produtos

🛠️ TypeScript: Tipagem completa para melhor experiência de desenvolvimento

🎨 Customizável: Sistema de tokens para personalização de temas

📚 Documentação: Storybook interativo com exemplos práticos

Instalação

pnpm (recomendado), npm ou yarn

Usando pnpm (recomendado)

pnpm add @telluscompany/design-system

Usando npm

npm install @telluscompany/design-system

Usando yarn

yarn add @telluscompany/design-system

Uso

Importe os componentes desejados no seu projeto:

import { Button, Input } from '@telluscompany/design-system';

Documentação

Para rodar a documentação interativa dos componentes com Storybook:

pnpm storybook

Acesse http://localhost:6006 após o comando acima.

A versão em produção pode ser acessada em https://tecnologia-tellus.github.io/design-system/

Testes

Para rodar os testes automatizados:

pnpm test

Uso local (desenvolvimento)

Para testar alterações do Design System em outro projeto antes de publicar uma nova versão no npm, utilize o pnpm link.

1. No repositório do Design System, gere o build:

pnpm build

2. No projeto que vai consumir o Design System, execute na raiz:

pnpm link ../caminho/para/seu-design-system

A partir daqui, o projeto apontará para a versão local. A cada alteração feita no Design System, basta rodar pnpm build novamente — as mudanças serão refletidas automaticamente no projeto consumidor.

Nota: localmente não é necessário alterar o campo version no package.json para que as mudanças tenham efeito. O versionamento só importa no momento da publicação no npm.

Pipeline CI & Publish

A pipeline é executada automaticamente a cada push na branch master (ou manualmente via workflow_dispatch) e realiza as seguintes etapas:

1. Checkout — Clona o repositório.
2. Setup Node.js 20 — Configura o Node.js com o registry do npm.
3. Instala pnpm — Gerenciador de pacotes utilizado no projeto.
4. Instala dependências — pnpm install.
5. Testes — Executa a suíte de testes (pnpm test:ci). A pipeline falha se algum teste quebrar.
6. Build — Compila a biblioteca (pnpm build).
7. Build Storybook — Gera o site estático de documentação do Storybook.
8. Deploy Storybook — Publica o Storybook no GitHub Pages (branch gh-pages).
9. Publish npm — Publica o pacote no npm (autenticado via secret NPM_TOKEN).

Resumo do fluxo

push master → testes → build lib → build storybook → deploy docs (GitHub Pages) → publish pacote (npm)

Secrets necessários

| Secret | Uso | |---|---| | GITHUB_TOKEN | Gerado automaticamente pelo GitHub, usado no deploy do Storybook | | NPM_TOKEN | Token de acesso ao npm para publicação do pacote |

Versionamento

O projeto segue o padrão Semantic Versioning (SemVer): MAJOR.MINOR.PATCH

| Segmento | Quando incrementar | |---|---| | MAJOR | Mudanças que quebram compatibilidade com versões anteriores | | MINOR | Novas funcionalidades compatíveis com versões anteriores | | PATCH | Correções de bugs sem quebrar compatibilidade |

Importante: antes de cada push para a branch master que deva gerar uma nova publicação no npm, atualize o campo version no package.json:

{
  "version": "0.17.9"
}

O npm rejeita a publicação caso a versão informada já exista no registro. Sem essa atualização, a etapa de Publish npm da pipeline falhará.

Visão técnica

Stack principal

| Camada | Tecnologia | |---|---| | UI | React 19 + TypeScript 5.8 (strict mode) | | Build | Vite 6 — saída ES Module + CommonJS | | Estilização | Tailwind CSS v4 + tw-animate-css | | Primitivos headless | Radix UI (checkbox, dialog, dropdown, select, tabs, tooltip…) | | Ícones | Lucide React + MUI Icons | | Variantes de componente | class-variance-authority (CVA) | | Composição de classes | clsx + tailwind-merge (cn()) | | Formulários | React Hook Form + Zod | | Máscaras de input | Maskito | | Datas | date-fns + react-day-picker | | Notificações | Sonner | | Carrossel | Embla Carousel | | Temas | next-themes (dark/light) | | Posicionamento flutuante | Floating UI |

Testes

| Ferramenta | Papel | |---|---| | Vitest + jsdom | Runner de testes unitários e de integração | | @testing-library/react | Utilitários de renderização e interação | | @testing-library/jest-dom | Matchers DOM customizados | | @vitest/coverage-v8 | Cobertura de código (HTML, JSON, text) |

Documentação e qualidade

• Storybook 9 (adapter React + Vite) — documentação interativa por componente
• ESLint (flat config) com plugins: TypeScript, React Hooks, Storybook, Prettier
• Husky + lint-staged — pre-commit: ESLint fix + type-check

Arquitetura e padrões

Estrutura por componente — cada componente segue a convenção:

src/components/NomeDoComponente/
├── NomeDoComponente.tsx        # implementação
├── NomeDoComponente.test.tsx   # testes
├── NomeDoComponente.stories.tsx # stories Storybook
└── index.ts                    # re-export público

src/components/ui/ — primitivos base no estilo shadcn/ui, usados internamente pelos componentes de alto nível.

Design tokens como CSS custom properties — cores, espaçamentos, tipografia, raios e animações definidos em src/index.css via @theme, consumidos pelo Tailwind CSS.

CVA (class-variance-authority) — API de variantes declarativas nos componentes (ex: variant, size), garantindo consistência e type-safety.

Padrão Slot / asChild — componentes polimórficos via @radix-ui/react-slot, permitindo troca do elemento HTML raiz sem perder comportamento.

Alias @/ — caminho absoluto configurado em tsconfig e vite.config.ts apontando para src/.

Tree-shaking — todos os componentes são exportados individualmente em src/index.ts, garantindo que apenas o que for importado entre no bundle do consumidor.

Peer dependencies — react, react-dom e tailwindcss são peer dependencies e não são empacotados na build, evitando duplicação no projeto consumidor.

Saída de build

dist/
├── index.es.js        # ES Module (tree-shakeable)
├── index.cjs.js       # CommonJS
├── index.d.ts         # declarações de tipos
└── design-system.css  # bundle CSS unificado

Licença

Este projeto é privado e de uso exclusivo da TellusCompany.