🌈 Kaleidoscope Design System

Um Design System brasileiro open source, multimarcas e agnóstico a frameworks.

Desenvolvido pela Zoetrope Design Studio com ❤️ para a comunidade brasileira de design e desenvolvimento.

🎯 Visão

O Kaleidoscope DS é um sistema de design robusto e extenso, criado para democratizar o acesso a componentes de interface de alta qualidade no Brasil. Nossa missão é fornecer uma base sólida e consistente para produtos digitais, respeitando as melhores práticas internacionais enquanto atende às necessidades específicas do mercado brasileiro.

🌟 Características Principais

• 🔧 Agnóstico a Frameworks: Construído com Web Components nativos
• 🎨 Multimarcas: Suporte completo a múltiplas identidades visuais
• 🤖 IA-Ready: Componentes específicos para interfaces com IA e LLMs
• ♿ Acessibilidade: Conformidade com WCAG 2.1 AA
• 🚀 Performance: Otimizado para carregamento rápido
• 📱 Responsivo: Mobile-first e adaptável
• 🔄 Automação Completa: CI/CD integrado com GitLab

🏗️ Arquitetura

Design Tokens como Fonte da Verdade

O Kaleidoscope utiliza um sistema robusto de Design Tokens que serve como a única fonte da verdade para todas as decisões de design:

Figma (TokenStudio) → JSON Tokens → Style Dictionary → SASS → CSS

⚠️ IMPORTANTE: Os tokens são imutáveis durante o desenvolvimento. Eles representam decisões de design consolidadas e não devem ser alterados diretamente no código.

Stack Tecnológica

• Web Components: Componentes nativos do navegador
• SASS: Pré-processador CSS para estilização
• Style Dictionary: Transformação e distribuição de tokens
• Storybook: Documentação e playground de componentes
• GitLab CI/CD: Automação e deploy
• Figma + TokenStudio: Design e geração de tokens
• Figma MCP: Integração para compreensão de componentes

🚀 Início Rápido

Instalação

# NPM
npm install @zoetropeds/kaleidoscope-ds

# Yarn
yarn add @zoetropeds/kaleidoscope-ds

# PNPM
pnpm add @zoetropeds/kaleidoscope-ds

Uso Básico

<!-- Importe os estilos -->
<link
  rel="stylesheet"
  href="node_modules/@zoetropeds/kaleidoscope-ds/dist/kaleidoscope.css"
/>

<!-- Use os componentes -->
<kds-button variant="primary" size="medium"> Meu Botão </kds-button>

<kds-input label="Nome" placeholder="Digite seu nome" required> </kds-input>

Configuração de Tema

:root {
  /* Tokens customizados para sua marca */
  --kds-color-primary-500: #your-brand-color;
  --kds-font-family-primary: "Your Font", sans-serif;
}

Uso dos scripts de geração de tokens

# Validar tokens
npm run tokens:validate

# Gerar tokens compilados
npm run tokens:build

# Build completo (validação + geração)
npm run build:tokens

# Watch mode para desenvolvimento
npm run dev:tokens

📚 Documentação

Storybook

Acesse nossa documentação interativa e playground de componentes:

• Storybook - Produção
• Storybook - Desenvolvimento (local)

Componentes Disponíveis

O Kaleidoscope DS segue os padrões estabelecidos pelo The Component Gallery e inclui:

🧱 Componentes Base

• Buttons: Primário, secundário, terciário, ícone
• Inputs: Text, email, password, textarea, select
• Navigation: Header, sidebar, breadcrumb, pagination
• Feedback: Alerts, toasts, modals, tooltips
• Data Display: Cards, tables, lists, badges
• Layout: Grid, container, spacer, divider

🤖 Componentes IA (Inspirados no IBM Carbon)

• AI Chat: Interface de conversação
• AI Status: Indicadores de processamento
• AI Suggestions: Sugestões automáticas
• AI Content: Conteúdo gerado por IA
• AI Feedback: Avaliação de respostas

🛠️ Desenvolvimento

Pré-requisitos

• Node.js 18+
• NPM/Yarn/PNPM
• Git

Setup Local

# Clone o repositório
git clone https://gitlab.com/zoetropeds/kaleidoscope-ds.git
cd kaleidoscope-ds

# Instale as dependências
npm install

# Gere os tokens CSS/SASS
npm run build:tokens

# Inicie o Storybook
npm run storybook

# Inicie o servidor de desenvolvimento
npm run dev

Scripts Disponíveis

# Desenvolvimento
npm run dev              # Servidor de desenvolvimento
npm run storybook        # Storybook local

# Build
npm run build            # Build completo
npm run build:tokens     # Gera apenas os tokens
npm run build:components # Compila apenas componentes

# Testes
npm run test             # Executa todos os testes
npm run test:watch       # Testes em modo watch
npm run test:coverage    # Relatório de cobertura

# Qualidade
npm run lint             # ESLint
npm run format           # Prettier
npm run type-check       # TypeScript

Estrutura do Projeto

kaleidoscope-ds/
├── .gitlab/
│   └── ci/                 # Configurações CI/CD
├── src/
│   ├── components/         # Web Components
│   ├── styles/
│   │   ├── tokens/         # Design Tokens (JSON)
│   │   ├── tokens-output/  # Tokens compilados
│   │   └── base/          # Estilos base
│   └── assets/            # Recursos estáticos
├── storybook/             # Configuração Storybook
├── docs/                  # Documentação adicional
└── dist/                  # Build final

🔄 Workflow de Desenvolvimento

Design Tokens (Fluxo Protegido)

⚠️ ATENÇÃO: Este fluxo é automatizado e protegido. Não altere tokens manualmente!

1. Design no Figma com TokenStudio
2. Export automático para JSON
3. Style Dictionary processa os tokens
4. Geração automática de SASS/CSS
5. CI/CD atualiza automaticamente

Desenvolvimento de Componentes

1. Análise no Figma via Figma MCP
2. Criação do Web Component seguindo padrões
3. Aplicação dos tokens via SASS
4. Documentação no Storybook
5. Testes automatizados
6. Review e merge

Estratégia de Branches

Utilizamos GitFlow adaptado para Design Systems:

• main: Produção estável
• develop: Desenvolvimento ativo
• feature/*: Novos componentes/funcionalidades
• release/*: Preparação de releases
• hotfix/*: Correções urgentes
• tokens/*: Atualizações de tokens (automático)

🎨 Guia de Contribuição

Para Designers

1. Figma: Crie/edite componentes seguindo o sistema
2. TokenStudio: Configure tokens adequadamente
3. Documentação: Descreva comportamentos e estados
4. Review: Valide com a equipe de desenvolvimento

Para Desenvolvedores

1. Fork o repositório
2. Crie uma branch feature/nome-do-componente
3. Desenvolva seguindo os padrões estabelecidos
4. Teste completamente o componente
5. Documente no Storybook
6. Abra um Merge Request

Padrões de Código

• Web Components: Seguir especificação W3C
• SASS: BEM methodology para classes
• TypeScript: Tipagem forte obrigatória
• Acessibilidade: ARIA labels e keyboard navigation
• Performance: Lazy loading e tree shaking

📋 Versionamento

Seguimos Semantic Versioning (SemVer) adaptado para Design Systems:

Formato: MAJOR.MINOR.PATCH

• MAJOR (1.0.0): Breaking changes, remoção de componentes
• MINOR (0.1.0): Novos componentes, novas funcionalidades
• PATCH (0.0.1): Bug fixes, melhorias de performance

Exemplos de Grandes DS

• Material Design: v3.0.0 (major redesign)
• Carbon Design: v11.0.0 (React 18 support)
• Fluent UI: v9.0.0 (complete rewrite)
• Ant Design: v5.0.0 (CSS-in-JS removal)

Releases Planejadas

• v0.1.0: Componentes base + tokens
• v0.2.0: Componentes de navegação
• v0.3.0: Componentes de dados
• v1.0.0: Release estável completa
• v1.1.0: Componentes IA

🤝 Comunidade

Links Importantes

• GitLab: Código fonte
• Storybook: Documentação
• Figma: Design System
• NPM: Pacote

Suporte

• Issues: Reporte bugs e solicite features
• Discussions: Tire dúvidas e compartilhe ideias
• Email: [email protected]

Roadmap

• [ ] Q3 2025: Componentes base (v0.1.0)
• [ ] Q4 2025: Sistema de temas avançado (v0.2.0)
• [ ] Q1 2026: Componentes IA (v0.3.0)
• [ ] Q2 2026: Release v1.0.0 estável

📄 Licença

Este projeto está licenciado sob a MIT License - veja o arquivo LICENSE para detalhes.

🙏 Agradecimentos

O Kaleidoscope DS é inspirado pelos melhores Design Systems do mundo:

• Apple Human Interface Guidelines
• IBM Carbon Design System
• Google Material Design
• Microsoft Fluent Design
• Ant Design

Feito com ❤️ pela Zoetrope Design Studio para a comunidade brasileira.