@lugom.io/hefesto 0.2.0 → 0.3.0

package/skills/hefesto-design/references/color-psychology.md

@@ -0,0 +1,203 @@
+# Psicologia das Cores e Aplicação
+
+## Tabela de Significados
+
+| Cor | Emoção primária | Emoção secundária | Indústrias |
+|---|---|---|---|
+| Azul | Confiança, segurança | Calma, profissionalismo | Finanças, tech, saúde, corporate |
+| Verde | Crescimento, natureza | Saúde, dinheiro, equilíbrio | Sustentabilidade, saúde, fintech, agro |
+| Vermelho | Urgência, paixão | Energia, perigo, apetite | Food, entretenimento, vendas, alertas |
+| Amarelo | Otimismo, atenção | Calor, cautela | Infantil, food delivery, avisos |
+| Laranja | Entusiasmo, criatividade | Acessibilidade, energia | Startups, food, esportes, CTA buttons |
+| Roxo | Luxo, criatividade | Mistério, espiritualidade | Beleza, tech premium, gaming, wellness |
+| Rosa | Carinho, feminilidade | Calma, doçura | Beleza, moda, saúde feminina, dating |
+| Preto | Sofisticação, poder | Elegância, exclusividade | Luxo, moda, tech, editorial premium |
+| Branco | Pureza, simplicidade | Limpeza, espaço | Saúde, tech minimalista, casamento |
+| Cinza | Neutralidade, maturidade | Estabilidade, equilíbrio | Corporate, industrial, tech B2B |
+| Marrom | Estabilidade, terra | Conforto, tradição | Café, artesanal, outdoor, jurídico |
+| Dourado | Prestígio, qualidade | Riqueza, tradição | Luxo, finanças premium, awards |
+| Ciano/Teal | Clareza, frescor | Modernidade, equilíbrio | Tech, saúde digital, fintech |
+| Coral | Calor, energia | Acessibilidade, otimismo | Lifestyle, wellness, social |
+| Indigo | Integridade, intuição | Profundidade, sabedoria | Tech, educação, fintech |
+
+---
+
+## Regra 60/30/10
+
+Distribuição clássica para equilíbrio visual:
+
+```
+┌──────────────────────────────────────────────────┐
+│                                                  │
+│               60% — COR DOMINANTE                │
+│         (fundo, superfícies, base visual)        │
+│                                                  │
+│    ┌────────────────────────────────┐             │
+│    │                                │             │
+│    │      30% — COR SECUNDÁRIA     │             │
+│    │    (cards, seções, sidebar)    │             │
+│    │                                │             │
+│    │    ┌──────────────┐            │             │
+│    │    │ 10% — ACENTO │            │             │
+│    │    │ (CTA, links, │            │             │
+│    │    │  ícones)     │            │             │
+│    │    └──────────────┘            │             │
+│    └────────────────────────────────┘             │
+└──────────────────────────────────────────────────┘
+```
+
+- **60% dominante**: geralmente branco, off-white, ou cinza claro (light) / cinza escuro (dark). É o respiro.
+- **30% secundária**: containers, headers, cards, sidebars. Cria estrutura.
+- **10% acento**: botões primários, links, ícones de destaque, badges. Direciona atenção.
+
+Erro comum: tratar o acento como 30% → interface gritante e cansativa.
+
+---
+
+## Modos de Combinação
+
+### Complementar
+Cores opostas na roda (azul ↔ laranja). Máximo contraste. Usar com cautela — funciona para CTA que precisa se destacar do fundo.
+
+### Análogo
+Cores vizinhas na roda (azul, azul-verde, verde). Harmônico e sereno. Pouco contraste — precisa de cor neutra para âncora.
+
+### Split-complementar
+Uma cor + as duas vizinhas da complementar. Contraste alto mas menos tensão que complementar pura. Versátil e difícil de errar.
+
+### Triádico
+Três cores equidistantes na roda (vermelho, amarelo, azul). Vibrante e equilibrado. Funciona se uma domina e as outras são acento.
+
+### Monocromático
+Uma cor em diferentes lightness/saturação. Elegante, coeso, seguro. Risco: monotonia. Resolver com um acento de cor diferente.
+
+---
+
+## Cores por Indústria
+
+### Fintech / Banking
+- **Primária**: Azul (confiança) ou verde (dinheiro/crescimento)
+- **Secundária**: Cinza neutro, branco limpo
+- **Acento**: Verde para positivo, vermelho para negativo/alerta
+- **Evitar**: Vermelho como primária (associação com perda), cores infantis
+- **Referências**: Nubank (roxo — diferenciação), Stripe (roxo/índigo), Mercury (preto/branco)
+
+### Saúde / Wellness
+- **Primária**: Azul claro (calma), verde (saúde), branco (limpeza)
+- **Secundária**: Tons pastéis, off-white quente
+- **Acento**: Verde para ações, azul para informação
+- **Evitar**: Vermelho dominante (sangue/emergência), preto pesado, neon
+- **Referências**: Headspace (laranja/azul), Calm (azul escuro/gradientes)
+
+### Tech / SaaS
+- **Primária**: Azul (95% do mercado) ou roxo (diferenciação)
+- **Secundária**: Cinza neutro para interface
+- **Acento**: Saturado para CTAs
+- **Oportunidade**: fugir do azul. Linear (roxo), Vercel (preto), Notion (off-white)
+- **Evitar**: Gradientes AI roxo-rosa-azul (clichê saturado desde 2023)
+
+### Food / Restaurantes
+- **Primária**: Vermelho (apetite), laranja (energia), amarelo (calor)
+- **Secundária**: Marrom (craft), verde (orgânico/saudável)
+- **Acento**: Vermelho para urgência, verde para saudável
+- **Evitar**: Azul (supressor natural de apetite), roxo, cinza frio
+- **Referências**: iFood (vermelho), Uber Eats (preto/verde)
+
+### Luxo / Premium
+- **Primária**: Preto (poder), branco (pureza), dourado (prestígio)
+- **Secundária**: Burgundy, navy, emerald
+- **Acento**: Dourado sutil, nunca brilhante demais (parece falso)
+- **Evitar**: Cores primárias saturadas (infantil), gradientes chamativos
+- **Referências**: Rolex, LVMH, Bottega Veneta
+
+### Sustentabilidade / Eco
+- **Primária**: Verde (natureza) em tons terrosos, não neon
+- **Secundária**: Bege, marrom claro, terracota
+- **Acento**: Verde mais saturado para CTAs
+- **Evitar**: Verde neon (parece tech, não eco), preto pesado, plástico visual
+- **Referências**: Patagonia, Aesop
+
+### Kids / Educação infantil
+- **Primária**: Cores primárias saturadas e quentes
+- **Secundária**: Mix vibrante, contrastes fortes
+- **Acento**: Variado — cada seção pode ter cor diferente
+- **Evitar**: Monocromático (entediante), tons pastéis demais (sem energia), dark mode
+- **Referências**: Duolingo, Khan Academy Kids
+
+---
+
+## Dark Mode — Cores
+
+Não é inversão. É re-composição para fundo escuro:
+
+1. **Dessaturar**: reduzir saturação 10-20% em cores sobre fundo escuro. Cores saturadas "vibram" e causam fadiga
+2. **Clarear**: usar tons mais claros da escala (blue-400 em vez de blue-600)
+3. **Fundo**: nunca #000000 puro — olho humano percebe glow/bleeding em OLED. Usar #0a0a0a a #1a1a1a
+4. **Texto**: nunca #ffffff puro — contraste extremo causa fadiga. Usar #f0f0f0 a #fafafa
+5. **Elevação**: em dark, camadas mais elevadas são mais claras (oposto de light). Card no topo = fundo mais claro
+6. **Brand colors**: manter reconhecíveis. Ajustar lightness, não mudar a cor
+
+---
+
+## Armadilhas Culturais
+
+Cores têm significados diferentes por cultura. Considerar antes de internacionalizar:
+
+| Cor | Ocidente | Ásia Oriental | Oriente Médio | Observação |
+|---|---|---|---|---|
+| Vermelho | Perigo, paixão, pare | Sorte, prosperidade, casamento | Perigo, cautela | China: vermelho é COR de celebração |
+| Branco | Pureza, casamento | Luto, morte, funerais | Pureza, paz | Japão/China: branco em funerais |
+| Verde | Natureza, go, eco | Juventude, fertilidade | Islã, sagrado, prosperidade | Cuidado em contextos islâmicos |
+| Roxo | Luxo, realeza, poder | Nobreza (similar) | Luto (alguns países) | Tailândia: cor do luto |
+| Amarelo | Otimismo, cautela | Imperial, sagrado | Sabedoria | Egito: luto |
+| Preto | Formalidade, morte | Formalidade | Mistério, mal | Relativamente universal |
+
+Recomendação: em produtos globais, pesquisar significados nas culturas-alvo. Na dúvida, azul é a cor mais universalmente positiva.
+
+---
+
+## Acessibilidade de Cores
+
+### Cor como indicador
+
+Nunca usar cor como único meio de comunicar informação:
+- Erro em formulário: vermelho + ícone ⚠ + texto de erro
+- Sucesso: verde + ícone ✓ + texto de confirmação
+- Gráficos: cores + padrões (listras, pontos) + labels
+
+### Pares seguros para daltonismo
+
+O daltonismo mais comum é protanopia/deuteranopia (vermelho-verde). Evitar distinguir informação apenas por vermelho vs verde.
+
+Pares que funcionam para todos:
+- Azul + laranja
+- Azul + vermelho
+- Preto + amarelo
+- Roxo + laranja
+- Azul + cinza
+
+Pares problemáticos:
+- Vermelho vs verde (protanopia/deuteranopia)
+- Azul vs roxo (tritanopia)
+- Verde vs marrom
+- Vermelho vs marrom
+
+### Teste prático
+
+Usar simuladores de daltonismo:
+- Chrome DevTools → Rendering → Emulate vision deficiencies
+- Figma → View → Color blindness simulation (plugin Stark)
+- Testar: protanopia, deuteranopia, tritanopia, achromatopsia
+
+---
+
+## Tendências a Evitar
+
+| Tendência | Por que evitar | Alternativa |
+|---|---|---|
+| Gradiente roxo-rosa-azul AI | Clichê desde 2023. Parece "mais um produto AI" | Escolher paleta que diferencie do mercado |
+| Rainbow gradient em tudo | Sem hierarquia visual, distrai do conteúdo | Gradiente mesh sutil com 2-3 cores |
+| Neon sobre branco | Contraste péssimo, ilegível, não acessível | Neon apenas sobre fundos escuros |
+| Cinza sobre cinza | "Elegante" mas impossível de ler | Manter contraste mínimo 4.5:1 |
+| Cores sazonais | Redesign constante, marca inconsistente | Cor de marca fixa + acentos sazonais sutis |
+| Preto puro (#000) como fundo | Glow em OLED, contraste extremo causa fadiga | Usar #0f0f0f a #1a1a1a |

package/skills/hefesto-design/references/component-specs.md

@@ -0,0 +1,318 @@
+# Especificação de Componentes UI
+
+## Atomic Design — Quando Usar Cada Nível
+
+### Átomos
+Elementos indivisíveis: Button, Input, Label, Icon, Badge, Avatar, Checkbox, Radio, Toggle, Tooltip.
+Não dependem de outros componentes. Têm variantes e estados próprios.
+
+### Moléculas
+Composição de 2-4 átomos com propósito definido: Form Field (Label + Input + Helper), Card (Surface + Content + Actions), Search Bar (Input + Icon + Button), Menu Item (Icon + Label + Badge).
+
+### Organismos
+Seções completas e independentes: Navigation Bar, Header, Footer, Sidebar, Form completo, Data Table, Modal/Dialog.
+Gerenciam estado próprio e contêm moléculas.
+
+### Templates
+Layout esquelético sem conteúdo real: define grid, posição de organismos, responsive breakpoints. É o wireframe estrutural da página.
+
+### Páginas
+Template + conteúdo real. Onde se testa com dados verdadeiros: textos longos, imagens reais, estados vazios, estados de erro.
+
+---
+
+## Template de Spec por Componente
+
+Toda spec de componente deve seguir esta estrutura:
+
+```
+# ComponentName (nível atomic)
+
+## Propósito
+Uma frase descrevendo o que faz e quando usar.
+
+## Anatomia
+Partes visuais do componente (container, label, icon, etc.)
+
+## Variantes
+Lista de variantes visuais com quando usar cada uma.
+
+## Estados
+Todos os estados interativos (default, hover, active, focus, disabled, loading, error).
+
+## Props / API
+Propriedades aceitas com tipos e defaults.
+
+## Acessibilidade
+Role ARIA, keyboard interaction, focus management.
+
+## Tokens Utilizados
+Quais design tokens o componente consome.
+
+## Exemplos
+Código de uso para cada variante principal.
+```
+
+---
+
+## Specs Completas
+
+### Button (Átomo)
+
+**Propósito**: Ação primária do usuário. Todo botão deve comunicar claramente o que acontece ao clicar.
+
+**Anatomia**: Container → [Icon opcional] → Label → [Icon trailing opcional]
+
+**Variantes**:
+
+| Variante | Quando usar | Visual |
+|---|---|---|
+| `primary` | Ação principal da página (1 por tela) | Fundo sólido cor primária, texto branco |
+| `secondary` | Ações complementares | Fundo cinza claro, texto escuro |
+| `destructive` | Deletar, remover, ações irreversíveis | Fundo vermelho, texto branco |
+| `outline` | Ações terciárias, menos ênfase | Borda, fundo transparente |
+| `ghost` | Ações sutis, dentro de cards/toolbars | Sem fundo nem borda, apenas texto |
+| `link` | Navegação inline, ações sem peso visual | Texto com underline, sem container |
+
+**Estados**:
+
+| Estado | Visual | Comportamento |
+|---|---|---|
+| `default` | Estilo base da variante | — |
+| `hover` | Fundo levemente mais escuro/claro | Cursor pointer |
+| `active/pressed` | Fundo mais escuro, scale(0.98) | Feedback tátil |
+| `focus-visible` | Focus ring 2px offset 2px cor primária | Tab navigation |
+| `disabled` | Opacidade 50%, cor dessaturada | Cursor not-allowed, aria-disabled, não clickável |
+| `loading` | Spinner substitui ícone ou label | Desabilitar click, manter largura |
+
+**Acessibilidade**:
+- Role: `button` (nativo) ou `role="button"` + `tabindex="0"` se não for `<button>`
+- Keyboard: `Enter` e `Space` ativam. `Tab` navega
+- Sempre ter texto acessível: label visível ou `aria-label` para icon-only
+- Loading: `aria-busy="true"`, `aria-disabled="true"`
+- Nunca usar `<div>` ou `<a>` como botão sem role e keyboard handling
+
+**Animação**:
+- Hover: `transition: background-color 150ms ease, transform 100ms ease`
+- Active: `transform: scale(0.98)` — 100ms
+- Loading spinner: `animation: spin 600ms linear infinite`
+
+**Dimensões**:
+
+| Tamanho | Altura | Padding X | Font Size | Icon Size |
+|---|---|---|---|---|
+| `sm` | 32px | 12px | 14px | 16px |
+| `md` | 40px | 16px | 14px | 18px |
+| `lg` | 48px | 24px | 16px | 20px |
+
+---
+
+### Input (Átomo)
+
+**Propósito**: Captura de dados textuais do usuário. Sempre acompanhado de label.
+
+**Anatomia**: Container → [Icon leading] → Texto input → [Clear button] → [Icon trailing]
+
+**Tipos**: `text`, `email`, `password` (com toggle show/hide), `number`, `search`, `tel`, `url`, `date`, `textarea`
+
+**Estados**:
+
+| Estado | Visual |
+|---|---|
+| `default` | Borda `--border-default`, fundo `--surface-primary` |
+| `hover` | Borda `--border-strong` |
+| `focus` | Borda `--border-focus`, ring 2px `--color-blue-100` |
+| `filled` | Igual default, label pode flutuar |
+| `disabled` | Fundo `--surface-secondary`, opacidade 60%, cursor not-allowed |
+| `error` | Borda `--status-error`, mensagem vermelha abaixo |
+| `success` | Borda `--status-success` (usar com parcimônia) |
+
+**Validação**:
+- Inline: validar on blur, não on change (exceto password strength)
+- Erro: exibir mensagem abaixo do campo, nunca apenas mudar cor
+- Padrão de mensagem: descrever como corrigir, não o que está errado
+  - Ruim: "Email inválido"
+  - Bom: "Inclua um @ no endereço de email"
+
+**Acessibilidade**:
+- `<label for="id">` obrigatório — nunca usar placeholder como label
+- `aria-describedby` para helper text e mensagens de erro
+- `aria-invalid="true"` em estado de erro
+- `autocomplete` com valor correto (name, email, tel, etc.)
+- Não desabilitar paste em campos de senha
+
+---
+
+### Card (Molécula)
+
+**Propósito**: Container visual para agrupar conteúdo relacionado com hierarquia clara.
+
+**Anatomia**: Container → [Header (título + ações)] → Body (conteúdo) → [Footer (ações)]
+
+**Layouts**:
+
+| Layout | Uso |
+|---|---|
+| Vertical | Conteúdo empilhado, mais comum |
+| Horizontal | Imagem lateral + conteúdo, listagens |
+| Media top | Imagem hero + conteúdo abaixo |
+| Compact | Menor padding, para listas densas |
+
+**Interação**:
+- Card clicável inteiro: `<a>` ou `<button>` wrapper, cursor pointer, hover elevation
+- Card com ações internas: botões dentro, card em si não é clicável
+- Nunca misturar: card clicável + links/botões dentro (conflito de click targets)
+
+**Elevação**:
+- Default: `--card-shadow` (sutil)
+- Hover (se clicável): `--card-shadow-hover` com `transition: box-shadow 200ms ease`
+- Não usar borda + sombra simultaneamente (escolher um)
+
+**Acessibilidade**:
+- Card clicável: aria-label descritivo, focus-visible ring
+- Conteúdo semântico: usar `<article>` se card é autocontido
+- Imagens: alt text significativo ou `alt=""` se decorativa
+
+---
+
+### Modal/Dialog (Molécula)
+
+**Propósito**: Interrupção contextual que requer atenção ou ação do usuário. Usar com moderação — modais interrompem o fluxo.
+
+**Anatomia**: Overlay → Container → Header (título + close) → Body → [Footer (ações)]
+
+**Tamanhos**:
+
+| Tamanho | Max-width | Uso |
+|---|---|---|
+| `sm` | 400px | Confirmações simples |
+| `md` | 560px | Formulários curtos |
+| `lg` | 720px | Conteúdo complexo |
+| `full` | 90vw/90vh | Edição imersiva, previews |
+
+**Comportamento de close**:
+- Click no overlay: fechar (exceto modais de formulário com dados)
+- Tecla Escape: sempre fechar
+- Botão X: sempre presente no header
+- Confirmação antes de fechar se há unsaved changes
+
+**Focus trap**:
+- Ao abrir: focus no primeiro elemento interativo (ou no close button)
+- Tab/Shift+Tab: ciclar apenas dentro do modal
+- Ao fechar: retornar focus para o elemento que abriu o modal
+- Implementar com `inert` no conteúdo por trás
+
+**Scroll lock**:
+- Body recebe `overflow: hidden` enquanto modal está aberto
+- Compensar scrollbar width para evitar layout shift
+- Conteúdo do modal scrolla internamente se necessário
+
+**Acessibilidade**:
+- `role="dialog"` + `aria-modal="true"`
+- `aria-labelledby` apontando para o título
+- `aria-describedby` para descrição adicional se houver
+
+---
+
+### Form Field (Molécula)
+
+**Propósito**: Composição de Label + Input + Helper Text + Error Message em um único componente coeso.
+
+**Anatomia**:
+```
+┌─────────────────────────┐
+│ Label*          (badge)  │  ← label + required indicator
+│ ┌─────────────────────┐ │
+│ │ Input               │ │  ← qualquer tipo de input
+│ └─────────────────────┘ │
+│ Helper text / Error msg  │  ← contextual, um ou outro
+└─────────────────────────┘
+```
+
+**Composição**:
+- Label: sempre visível, posição acima do input, `font-weight: medium`
+- Required: asterisco `*` na label ou texto "(obrigatório)" — nunca marcar opcionais
+- Helper: texto cinza abaixo do input para instrução proativa
+- Error: substitui helper, cor vermelha, ícone de alerta, descreve como corrigir
+
+**Estados**:
+- Default: label + input + helper (se houver)
+- Error: label + input(borda vermelha) + error message
+- Disabled: tudo com opacidade reduzida
+- Readonly: sem borda de input, apenas texto
+
+**Acessibilidade**:
+- Label conectada via `for`/`id`
+- Helper via `aria-describedby`
+- Error via `aria-describedby` + `aria-invalid="true"` no input
+- `fieldset` + `legend` para grupos de campos relacionados (ex: endereço)
+
+---
+
+### Navigation Bar (Organismo)
+
+**Propósito**: Navegação global persistente do app. Acesso rápido às seções principais.
+
+**Anatomia Desktop**: Container → Logo → Nav Links → [Search] → Actions (CTA, avatar, notificações)
+
+**Anatomia Mobile**: Container → Logo/Hamburger → [Search icon] → Actions mínimas
+
+**Responsivo**:
+
+| Breakpoint | Comportamento |
+|---|---|
+| Desktop (≥1024px) | Horizontal completa, todos os links visíveis |
+| Tablet (768-1023px) | Links prioritários visíveis, rest em "More" dropdown |
+| Mobile (<768px) | Hamburger menu, slide-in panel ou bottom sheet |
+
+**Active state**: Item atual com indicador visual claro (underline, fundo, cor) — nunca apenas cor de texto.
+
+**Mobile collapse**:
+- Hamburger: 3 linhas → anima para X ao abrir
+- Panel: slide da esquerda ou top, overlay no conteúdo
+- Alternativa: bottom navigation bar (máximo 5 itens)
+
+**Acessibilidade**:
+- `<nav aria-label="Navegação principal">`
+- `aria-current="page"` no item ativo
+- Skip link: primeiro elemento focável da página, link para `#main-content`
+- Hamburger: `aria-expanded`, `aria-controls`
+- Mobile panel: focus trap enquanto aberto
+
+---
+
+## Quality Gates
+
+Antes de considerar um componente pronto:
+
+- [ ] Zero CSS hardcoded — todos os valores vêm de tokens
+- [ ] WCAG AA — contraste ≥ 4.5:1 texto normal, ≥ 3:1 texto grande
+- [ ] Focus-visible — ring visível em navegação por teclado
+- [ ] Keyboard nav — Tab, Enter, Space, Escape funcionam conforme esperado
+- [ ] Estados completos — default, hover, active, focus, disabled (e loading/error quando aplicável)
+- [ ] Responsive — testado em 320px, 768px, 1024px, 1440px
+- [ ] Dark mode — testado com tema escuro, contraste verificado
+
+---
+
+## Referência de Estados e Variantes
+
+### Estados universais de interação
+- **default**: aparência base, sem interação
+- **hover**: mouse sobre (desktop), não usar em mobile
+- **active/pressed**: durante click/tap, feedback imediato
+- **focus-visible**: navegação por teclado (Tab), não em click
+- **disabled**: não interagível, comunicar visualmente
+- **loading**: aguardando resposta, desabilitar interação
+
+### Estados de dados
+- **empty**: sem dados, mostrar ilustração + CTA
+- **error**: falha, mostrar mensagem + ação de recuperação
+- **success**: operação concluída, feedback temporário
+- **partial**: carregamento parcial, skeleton onde falta
+
+### Variantes de ênfase (hierarquia visual)
+- **primary**: ação principal (1 por contexto)
+- **secondary**: ações complementares
+- **tertiary/ghost**: ações de menor importância
+- **destructive**: ações irreversíveis (sempre confirmar)