borghei/ui-design-system

Sistema de Design UI

Gere tokens de design, crie paletas de cores, calcule escalas tipográficas, construa sistemas de componentes e prepare documentação para entrega ao desenvolvedor.

---

Índice

• Termos de Acionamento
• Esclareça Primeiro
• Fluxos de Trabalho
  • Fluxo 1: Gerar Tokens de Design
  • Fluxo 2: Criar Sistema de Componentes
  • Fluxo 3: Design Responsivo
  • Fluxo 4: Entrega para o Desenvolvedor
• Referência de Ferramenta
• Tabelas de Referência Rápida
• Base de Conhecimento

---

Termos de Acionamento

Use esta skill quando precisar de:

• "gerar tokens de design"
• "criar paleta de cores"
• "construir escala tipográfica"
• "calcular sistema de espaçamento"
• "criar sistema de design"
• "gerar variáveis CSS"
• "exportar tokens SCSS"
• "configurar arquitetura de componentes"
• "documentar biblioteca de componentes"
• "calcular breakpoints responsivos"
• "preparar entrega para desenvolvedor"
• "converter cor da marca em paleta"
• "verificar contraste WCAG"
• "construir sistema de grid 8pt"

---

Esclareça Primeiro

Antes de gerar os tokens ou o sistema, defina as entradas abaixo. Quando uma estiver faltando ou vaga e alteraria o resultado, pergunte sobre ela; quando não alterar, use um valor padrão sensato e informe qual você usou.

• Cor primária da marca (hex): a semente para a paleta completa (direciona a escala de cores e as verificações de contraste WCAG).
• Preset de estilo: moderno, clássico ou divertido (define fontes, raio de borda e estilo de sombra).
• Formato de saída e framework: CSS, SCSS ou JSON para Tailwind/styled-components/Figma (direciona a exportação e a entrega para o desenvolvedor).

Pergunte sobre as duas ou três entradas que mais importam para esta solicitação, não a lista toda. Se o usuário quiser um resultado imediato, produza-o e declare suas suposições no início.

Fluxos de Trabalho

Fluxo 1: Gerar Tokens de Design

Situação: Você tem uma cor de marca e precisa de um sistema completo de tokens de design.

Passos:

1. Identificar cor e estilo da marca

   • Cor primária da marca (formato hex)
   • Preferência de estilo: moderno | clássico | divertido

2. Gerar tokens usando script

   python scripts/design_token_generator.py "#0066CC" moderno json
   

3. Revisar categorias geradas

   • Cores: primária, secundária, neutra, semântica, superfície
   • Tipografia: fontFamily, fontSize, fontWeight, lineHeight
   • Espaçamento: escala baseada em grid 8pt (0-64)
   • Bordas: raio, espessura
   • Sombras: nenhuma até 2xl
   • Animação: duração, easing
   • Breakpoints: xs até 2xl

4. Exportar no formato de destino

   # Propriedades personalizadas CSS
   python scripts/design_token_generator.py "#0066CC" moderno css > design-tokens.css
   
   # Variáveis SCSS
   python scripts/design_token_generator.py "#0066CC" moderno scss > _design-tokens.scss
   
   # JSON para Figma/ferramentas
   python scripts/design_token_generator.py "#0066CC" moderno json > design-tokens.json
   

5. Validar acessibilidade

   • Verificar se o contraste de cores atende WCAG AA (4.5:1 normal, 3:1 texto grande)
   • Verificar se as cores semânticas possuem cores de contraste definidas

---

Fluxo 2: Criar Sistema de Componentes

Situação: Você precisa estruturar uma biblioteca de componentes usando tokens de design.

Passos:

1. Definir hierarquia de componentes

   • Átomos: Botão, Input, Ícone, Rótulo, Badge
   • Moléculas: CampoDeFormulário, BarraDePesquisa, Cartão, ItemDeLista
   • Organismos: Cabeçalho, Rodapé, TabelaDeDados, Modal
   • Templates: LayoutDoPainel, LayoutDeAutenticação

2. Mapear tokens para componentes

   Componente	Tokens Usados
   Botão	cores, dimensionamento, bordas, sombras, tipografia
   Input	cores, dimensionamento, bordas, espaçamento
   Cartão	cores, bordas, sombras, espaçamento
   Modal	cores, sombras, espaçamento, z-index, animação

3. Definir padrões de variantes

   Variantes de tamanho:

   sm: altura 32px, paddingX 12px, fontSize 14px
   md: altura 40px, paddingX 16px, fontSize 16px
   lg: altura 48px, paddingX 20px, fontSize 18px
   

   Variantes de cor:

   primária: fundo primary-500, texto branco
   secundária: fundo neutral-100, texto neutral-900
   fantasma: fundo transparente, texto neutral-700
   

4. Documentar API do componente

   • Interface de props com tipos
   • Opções de variantes
   • Tratamento de estados (hover, active, focus, disabled)
   • Requisitos de acessibilidade

5. Referência: Veja references/component-architecture.md

---

Fluxo 3: Design Responsivo

Situação: Você precisa de breakpoints, tipografia fluida ou espaçamento responsivo.

Passos:

1. Definir breakpoints

   Nome	Largura	Alvo
   xs	0	Celulares pequenos
   sm	480px	Celulares grandes
   md	640px	Tablets
   lg	768px	Laptops pequenos
   xl	1024px	Desktops
   2xl	1280px	Telas grandes

2. Calcular tipografia fluida

   Fórmula: clamp(mínimo, preferido, máximo)

   /* 16px a 24px entre viewport de 320px e 1200px */
   font-size: clamp(1rem, 0.5rem + 2vw, 1.5rem);
   

   Escalas pré-calculadas:

   --fluid-h1: clamp(2rem, 1rem + 3.6vw, 4rem);
   --fluid-h2: clamp(1.75rem, 1rem + 2.3vw, 3rem);
   --fluid-h3: clamp(1.5rem, 1rem + 1.4vw, 2.25rem);
   --fluid-body: clamp(1rem, 0.95rem + 0.2vw, 1.125rem);
   

3. Configurar espaçamento responsivo

   Token	Mobile	Tablet	Desktop
   --space-md	12px	16px	16px
   --space-lg	16px	24px	32px
   --space-xl	24px	32px	48px
   --space-section	48px	80px	120px

4. Referência: Veja references/responsive-calculations.md

---

Fluxo 4: Entrega para o Desenvolvedor

Situação: Você precisa entregar os tokens de design para a equipe de desenvolvimento.

Passos:

1. Exportar tokens nos formatos necessários

   # Para projetos CSS
   python scripts/design_token_generator.py "#0066CC" moderno css
   
   # Para projetos SCSS
   python scripts/design_token_generator.py "#0066CC" moderno scss
   
   # Para JavaScript/TypeScript
   python scripts/design_token_generator.py "#0066CC" moderno json
   

2. Preparar integração com framework

   React + Variáveis CSS:

   import './design-tokens.css';
   
   <button className="btn btn-primary">Clique</button>
   

   Configuração Tailwind:

   const tokens = require('./design-tokens.json');
   
   module.exports = {
     theme: {
       colors: tokens.colors,
       fontFamily: tokens.typography.fontFamily
     }
   };
   

   styled-components:

   import tokens from './design-tokens.json';
   
   const Button = styled.button`
     background: ${tokens.colors.primary['500']};
     padding: ${tokens.spacing['2']} ${tokens.spacing['4']};
   `;
   

3. Sincronizar com Figma

   • Instalar o plugin Tokens Studio
   • Importar design-tokens.json
   • Os tokens sincronizam automaticamente com os estilos do Figma

4. Checklist de entrega

   • Arquivos de tokens adicionados ao projeto
   • Pipeline de build configurado
   • Tema/variáveis CSS importados
   • Biblioteca de componentes alinhada
   • Documentação gerada

5. Referência: Veja references/developer-handoff.md

---

Referência de Ferramenta

design_token_generator.py

Gera sistema completo de tokens de design a partir da cor da marca.

Argumento	Valores	Padrão	Descrição
brand_color	Cor hex	#0066CC	Cor primária da marca
style	moderno, clássico, divertido	moderno	Preset de estilo de design
format	json, css, scss, summary	json	Formato de saída

Exemplos:

# Gerar tokens JSON (padrão)
python scripts/design_token_generator.py "#0066CC"

# Estilo clássico com saída CSS
python scripts/design_token_generator.py "#8B4513" classico css

# Visualização resumida estilo divertido
python scripts/design_token_generator.py "#FF6B6B" divertido summary

Categorias de Saída:

Categoria	Descrição	Valores Chave
colors	Paletas de cores	primary, secondary, neutral, semantic, surface
typography	Sistema de fontes	fontFamily, fontSize, fontWeight, lineHeight
spacing	Grid 8pt	escala 0-64, semântica (xs-3xl)
sizing	Tamanhos de componente	container, button, input, icon
borders	Valores de borda	radius (por estilo), width
shadows	Estilos de sombra	none até 2xl, inner
animation	Tokens de movimento	duration, easing, keyframes
breakpoints	Responsivo	xs, sm, md, lg, xl, 2xl
z-index	Sistema de camadas	base até notification

---

Tabelas de Referência Rápida

Geração de Escala de Cores

Passo	Brilho	Saturação	Caso de Uso
50	95% fixo	30%	Fundos sutis
100	95% fixo	38%	Fundos claros
200	95% fixo	46%	Estados de hover
300	95% fixo	54%	Bordas
400	95% fixo	62%	Estados desabilitados
500	Original	70%	Cor base/padrão
600	Original × 0.8	78%	Hover (escuro)
700	Original × 0.6	86%	Estados ativos
800	Original × 0.4	94%	Texto
900	Original × 0.2	100%	Títulos

Escala Tipográfica (Proporção 1.25x)

Tamanho	Valor	Cálculo
xs	10px	16 ÷ 1.25²
sm	13px	16 ÷ 1.25¹
base	16px	Base
lg	20px	16 × 1.25¹
xl	25px	16 × 1.25²
2xl	31px	16 × 1.25³
3xl	39px	16 × 1.25⁴
4xl	49px	16 × 1.25⁵
5xl	61px	16 × 1.25⁶

Requisitos de Contraste WCAG

Nível	Texto Normal	Texto Grande
AA	4,5:1	3:1
AAA	7:1	4,5:1

Texto grande: ≥18pt regular ou ≥14pt negrito

Presets de Estilo

Aspecto	Moderno	Clássico	Divertido
Fonte Sans	Inter	Helvetica	Poppins
Fonte Mono	Fira Code	Courier	Source Code Pro
Raio Padrão	8px	4px	16px
Sombras	Em camadas, sutis	Camada única	Suaves, pronunciadas

---

Base de Conhecimento

Guias de referência detalhados em references/:

Arquivo	Conteúdo
token-generation.md	Algoritmos de cor, espaço HSV, contraste WCAG, escalas de tipo
component-architecture.md	Design atômico, convenções de nomenclatura, padrões de props
responsive-calculations.md	Breakpoints, tipografia fluida, sistemas de grid
developer-handoff.md	Formatos de exportação, configuração de framework, sincronização Figma

---

Checklist de Validação

Geração de Tokens

• Cor da marca fornecida em formato hex
• Estilo corresponde aos requisitos do projeto
• Todas as categorias de tokens geradas
• Cores semânticas incluem valores de contraste

Sistema de Componentes

• Todos os tamanhos implementados (sm, md, lg)
• Todas as variantes implementadas (primária, secundária, fantasma)
• Todos os estados funcionando (hover, active, focus, disabled)
• Usa apenas tokens de design (sem valores fixos)

Acessibilidade

• Contraste de cores atende WCAG AA
• Indicadores de foco visíveis
• Alvos de toque ≥ 44×44px
• Elementos HTML semânticos usados

Entrega para o Desenvolvedor

• Tokens exportados no formato necessário
• Integração com framework documentada
• Ferramenta de design sincronizada
• Documentação do componente completa

---

Solução de Problemas

Problema	Causa	Solução
Cores geradas falham no contraste WCAG	Cor da marca muito clara ou muito saturada	Use tons mais escuros (600+) para texto em fundos claros; verifique com ferramenta de contraste
Exportação de token tem valores incorretos	Argumento de formato ou sintaxe de cor errada	Certifique-se de que a cor hex está entre aspas (ex. "#0066CC"); verifique se o formato é json, css ou scss
Escala tipográfica muito grande/pequena	Proporção padrão 1.25x não se adequa ao design	Modifique type_scale_ratio na classe DesignTokenGenerator (1.125 para mais apertado, 1.333 para mais solto)
Variáveis SCSS conflitam com as existentes	Colisão de nomes de tokens	Prefixe todos os tokens com o namespace do projeto (edite a função de exportação)
Ferramentas de design mostram cores diferentes	Arredondamento hex na geração da escala de cores	Use a exportação JSON como fonte da verdade; sincronize com o plugin Tokens Studio
Valores de espaçamento não se alinham com o grid	Espaçamento personalizado misturado com grid 8pt	Use apenas valores do sistema de espaçamento gerado; evite valores de pixel arbitrários
Tokens de sombra parecem errados no modo escuro	Sombras projetadas para fundos claros	Crie tokens de sombra separados para modo escuro com valores de opacidade mais claros

---

Critérios de Sucesso

Critério	Alvo	Como Medir
Consistência de tokens	Zero valores fixos de cor/espaçamento na base de código	Contagem de violações de regras de lint
Conformidade WCAG AA	Todas as cores de texto atendem proporção de contraste 4.5:1	Verificador de contraste automatizado ou auditoria manual
Cobertura de formato de exportação	CSS, SCSS e JSON geram corretamente	Execute o gerador com cada formato; valide a saída
Sincronia design-dev	<24h entre atualização de token e implantação de código	Tempo desde a mudança no Figma até a produção
Cobertura de tokens de componentes	100% dos componentes usam tokens de design	Audite estilos de componentes em busca de valores fixos
Consistência tipográfica	Todo texto usa escala de tipo do sistema de design	Auditoria visual em todas as páginas
Comportamento responsivo	Tipografia fluida funciona em todos os breakpoints	Teste nas larguras xs, sm, md, lg, xl, 2xl

---

Escopo e Limitações

No escopo:

• Geração completa de tokens de design a partir da cor da marca
• Geração de paleta de cores (primária, secundária, neutra, semântica)
• Sistema tipográfico com escala modular
• Sistema de espaçamento baseado em grid 8pt
• Tokens de dimensionamento de componentes, bordas, sombras, animação
• Exportação para propriedades personalizadas CSS, variáveis SCSS e JSON
• Definições de breakpoints responsivos
• Tabelas de referência de contraste WCAG

Fora do escopo:

• Geração de tokens para modo escuro (requer mapeamento de paleta separado)
• Biblioteca de animação/movimento de design
• Geração de sistema de ícones
• Implementação de alternância de tema em tempo de execução
• Plugin Figma ou integração de API (use Tokens Studio)
• Testes de regressão visual
• Conversão de design para código (use Figma Dev Mode ou Locofy)

---

Pontos de Integração

…

[truncado para tradução]