Luz fixa do canto superior esquerdo. Três naturezas de superfície: raised, floating, carved. Sombra é cor-do-fundo deslocada — nunca preto puro.
Direção de luz
A luz parte do canto superior esquerdo e não se move. Cada elemento da cena — card, botão, campo de busca, modal — recebe highlight em cima e sombra embaixo a partir dessa mesma origem. Quando a direção varia por elemento, a interface perde coerência espacial e começa a parecer montada de peças separadas.
Três naturezas de superfície
O sistema opera com três naturezas de superfície — raised, floating e carved — cada uma descrevendo uma relação física entre o elemento e o plano-base da cena. Um elemento só pode ter uma natureza por vez.
Raised
O elemento pousa sobre a superfície-base. Sombra fraca no canto inferior-direito (rgba(0,0,0,0.05)) mais highlight branco opaco no canto superior-esquerdo (rgba(255,255,255,1)). A assimetria de opacidade entre os dois é o que garante a direção da luz e distingue esta técnica do neumorphism genérico. Uso canônico: cards, botão secondary.
Token: --shadow-raised
Floating
O elemento flutua acima da cena. Sombra única e mais longa embaixo, sem highlight no topo. A ausência de highlight sinaliza que o elemento não compartilha o plano-base dos cards — ele vem de cima, como uma folha sobreposta. Uso canônico: modais, popovers, tooltips.
Token: --shadow-floating
Carved
O elemento está escavado no plano — afundado em vez de pousado. Sombra interna vinda de cima: a borda superior do sulco recebe a sombra enquanto a borda inferior permanece iluminada. A inversão da lógica raised confirma a relação física: o elemento não paira sobre a superfície, foi retirado dela. Uso canônico: Search Field, inputs.
Token: --shadow-carved
Tokens da tecla (V-B)
A tecla é o único componente V-B materializado. Seus tokens de sombra são separados por contrato semântico: mudanças futuras na gramática de cards não arrastam a tecla. Três variantes cobrem rest, compacta em repouso e o estado pressionado.
Tecla — rest
Valores idênticos ao --shadow-raised — mesmo offset, mesmo blur, mesma assimetria de opacidade. Token separado pelo contrato semântico da tecla: a tecla é peça distinta do sistema de cards e precisa de margem de evolução independente. Uso: tecla large (65 px) em repouso.
Token: --shadow-tecla
Tecla compacta — rest
Variante compacta da tecla (cap aproximadamente 40 px, socket 52 px). Offsets e blur proporcionalmente menores — offset 4 px (X e Y) e blur 12 px, contra 8 px / 8 px / 24 px da large. A assimetria de opacidade e a direção de luz são as mesmas.
Token: --shadow-tecla-sm
Tecla — pressionada
No estado active, a sombra externa desaparece e entra uma sombra interna (inset) vinda de cima. O mesmo princípio do carved, com opacidade maior — 20% contra 8% — para expressar o afundamento físico do botão pressionado.
Token: --shadow-tecla-pressed
Tokens
Seis tokens cobrem as três naturezas de superfície e as três variantes da tecla. Os valores completos estão em design-system/tokens/tokens.css.
Regras de uso
- Sombra é cor-do-fundo deslocada em luminosidade — nunca preto puro. O valor de cor de qualquer sombra é derivado do fundo da cena, com deslocamento de luminosidade. Aplicar
rgba(0,0,0,x)com opacidade acima de 10% produz sombra preta visível que faz o elemento parecer colado sobre a tela em vez de integrado a ela. - Três níveis máximos de elevação: base, raised e floating. Base é o plano. Raised pousa sobre o plano. Floating paira acima de raised. Além de três níveis, a interface começa a parecer estratificada — o painel único se desfaz.
- Raised e carved nunca coexistem no mesmo elemento. Um elemento ou pousa (raised) ou foi escavado (carved) — nunca os dois ao mesmo tempo. Combinar sombra externa com sombra interna no mesmo elemento não tem referente físico e confunde a leitura espacial.
- Direção da luz é global — variar por elemento é violação. Todos os elementos da cena compartilham a mesma fonte de luz. Um card com sombra vindo de cima e um botão com sombra vindo da direita, na mesma tela, é incoerência espacial. A direção é propriedade da cena, não do componente.
Neumorphism direcional vs. genérico
O Peppe abraça o que .claude/ui-design/examples.md §2.2 chama de neumorphism direcional — e recusa o neumorphism genérico que ficou popular por volta de 2020. O teste não é "tem duas sombras?". É: as sombras e os gradientes respeitam uma fonte de luz única e coerente com as demais superfícies da cena?
Aceito — direcional
Highlight forte (rgba(255,255,255,1)) no canto superior-esquerdo, sombra fraca (rgba(0,0,0,0.05)) no canto inferior-direito. Gradiente de fundo e gradiente de borda reforçam a mesma direção. Todas as outras superfícies da cena respeitam a mesma fonte de luz.
Recusado — genérico
Highlight e sombra com intensidade simétrica (-6px -6px 12px #fff + 6px 6px 12px #ccc). Fundo chapado, borda chapada, sem gradiente que confirme a direção. Os outros elementos da cena não seguem a mesma lógica. O volume não vem de luz — vem de efeito.
Direcional é Rams com matéria: uma fonte de luz, superfícies que reagem de forma coerente. Genérico é efeito sem cena — volume que não sabe de onde vem a luz. A distinção operacional está em três critérios: (a) assimetria calibrada de opacidade entre highlight e sombra; (b) gradientes de fundo e de borda que acompanham a direção da luz; (c) coerência com as outras superfícies da mesma tela. Se qualquer um dos três faltar, é genérico — recusar.
Referência completa: .claude/ui-design/examples.md §2.2 (tecla V-B como caso positivo) e .claude/ui-design/anti-patterns.md §7 (distinção operacional detalhada).
Anti-padrões referenciados
Anti-padrões com relação direta a decisões de sombra e elevação. O arquivo-fonte está em .claude/ui-design/anti-patterns.md. Links permanentes serão atualizados quando a seção de anti-padrões visuais for publicada.
- #1 — Sombra preta ou pesadaAplicar sombra como filtro preto puro com opacidade alta, ou com blur e offset grandes que produzem escuro visível sob o elemento. A interface parece empilhada e teatral — o princípio do painel único e sólido se desfaz.
- #7 — Neumorphism genéricoSombras duplas com opacidade e blur simétricos, sem gradiente de preenchimento ou borda que confirme a direção. Volume não vem de luz — vem de moda. Distinção completa em §6 desta página e em
anti-patterns.md §7. - #10 — Luz não-direcional ou com origem invertidaSombras e highlights com origem inconsistente entre elementos da mesma tela. Um card com sombra vindo de cima e outro com sombra vindo da direita destroem a percepção de cena única. A direção de luz é propriedade global — não pode variar por elemento.
Consultar .claude/ui-design/anti-patterns.md na íntegra para demais anti-padrões visuais.