@lugom.io/hefesto 0.3.0 → 1.0.0

package/skills/hefesto-design/references/polish.md

@@ -1,339 +0,0 @@
-# Micro-Polish — 16 Princípios de Refinamento Visual
-
-Detalhes imperceptíveis isoladamente, mas que juntos separam interfaces amadoras de interfaces profissionais. Cada princípio inclui a regra, o valor exato e CSS pronto para copiar. Aplicar sistematicamente após a estrutura base estar funcional.
-
----
-
-## Superfícies
-
-**POL-01 — Border Radius Concêntrico**
-Raio externo = raio interno + padding. Card com padding 16px e inner radius 8px deve ter outer radius 24px. Raios que não seguem essa regra criam uma sensação "errada" difícil de identificar.
-- Regra: `outer-radius = inner-radius + padding`
-- Valor: calculado por contexto (ex: inner 8px + padding 16px = outer 24px)
-```css
-.card {
-  border-radius: 24px;
-  padding: 16px;
-}
-.card-inner {
-  border-radius: 8px;
-}
-```
-- Por quê: raios não-concêntricos criam espessura visual irregular nas bordas, quebrando a percepção de profundidade uniforme
-
-**POL-02 — Alinhamento Óptico vs Geométrico**
-Ícones de play (triângulos), elementos assimétricos e alguns glyphs precisam de ajuste manual. Centralizar geometricamente nem sempre é centralizar visualmente.
-- Regra: ajustar 1-2px para compensar peso visual assimétrico
-- Valor: `translate(1px, 0)` a `translate(2px, 0)` para triângulos/play icons
-```css
-.play-icon {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-}
-.play-icon svg {
-  transform: translateX(1px); /* compensação óptica */
-}
-```
-- Por quê: o olho humano percebe centro de massa, não centro geométrico — triângulos parecem deslocados à esquerda quando centrados matematicamente
-
-**POL-03 — Sombras > Bordas**
-Usar múltiplas `box-shadow` com transparência em vez de `border: 1px solid`. Sombras se adaptam a qualquer fundo sem criar linhas duras.
-- Regra: substituir bordas sólidas por sombras em camadas
-- Valor: 2-3 camadas de shadow com opacidade entre 0.04 e 0.12
-```css
-/* Em vez de: border: 1px solid #e5e5e5 */
-.card {
-  box-shadow:
-    0 1px 2px rgba(0, 0, 0, 0.05),
-    0 4px 12px rgba(0, 0, 0, 0.08);
-}
-
-/* Elevated state */
-.card-elevated {
-  box-shadow:
-    0 2px 4px rgba(0, 0, 0, 0.04),
-    0 8px 24px rgba(0, 0, 0, 0.12);
-}
-```
-- Por quê: bordas sólidas criam contraste abrupto e não escalam entre temas claro/escuro — sombras com alpha se adaptam naturalmente
-
-**POL-04 — Outlines em Imagens**
-Adicionar contorno sutil em imagens para criar separação contra fundos claros sem borda visível.
-- Regra: aplicar inset shadow ou outline com opacidade 0.06 em toda imagem
-- Valor: `rgba(0, 0, 0, 0.06)` com 1px
-```css
-.image {
-  box-shadow: inset 0 0 0 1px rgba(0, 0, 0, 0.06);
-  border-radius: 8px;
-}
-
-/* Alternativa com outline (não afeta layout) */
-.image-alt {
-  outline: 1px solid rgba(0, 0, 0, 0.06);
-  outline-offset: -1px;
-  border-radius: 8px;
-}
-```
-- Por quê: imagens com áreas claras nas bordas "sangram" no fundo branco — o outline sutil define a fronteira sem parecer uma moldura
-
----
-
-## Animação
-
-**POL-05 — Animações Interrompíveis**
-Usar CSS transitions (não keyframes) para estados interativos (hover, active, focus). Transitions podem ser interrompidas mid-animation; keyframes completam o ciclo.
-- Regra: states interativos = transition, sequências = keyframes
-- Valor: `transition` para hover/active/focus, `@keyframes` apenas para loaders/decorativos
-```css
-/* Correto: transition interrompível */
-.button {
-  background: var(--color-primary);
-  transition: background-color 150ms ease, transform 100ms ease;
-}
-.button:hover {
-  background: var(--color-primary-hover);
-}
-
-/* Errado: keyframe não-interrompível */
-.button:hover {
-  animation: highlight 200ms forwards; /* completa mesmo se mouse sair */
-}
-```
-- Por quê: quando o usuário move o mouse rapidamente, transitions revertem suavemente — keyframes criam "flicker" ao completar antes de reiniciar
-
-**POL-06 — Split & Stagger Enters**
-Separar conteúdo em chunks semânticos e aplicar delay incremental entre eles. Nunca animar um container inteiro como bloco único.
-- Regra: ~100ms de delay entre chunks, máximo 5-6 itens staggered
-- Valor: `transition-delay` de 0ms, 100ms, 200ms, 300ms...
-```css
-.stagger-item {
-  opacity: 0;
-  transform: translateY(8px);
-  transition: opacity 300ms ease, transform 300ms ease;
-}
-.stagger-item.visible {
-  opacity: 1;
-  transform: translateY(0);
-}
-.stagger-item:nth-child(1) { transition-delay: 0ms; }
-.stagger-item:nth-child(2) { transition-delay: 100ms; }
-.stagger-item:nth-child(3) { transition-delay: 200ms; }
-.stagger-item:nth-child(4) { transition-delay: 300ms; }
-```
-- Por quê: entradas em bloco parecem "flash" — stagger cria narrativa visual e dá tempo para o olho processar cada elemento
-
-**POL-07 — Exits Sutis**
-Usar `translateY(-12px)` fixo para saídas, nunca a altura total do elemento. Saídas devem ser menores e mais rápidas que entradas.
-- Regra: exit = metade da duração do enter, distância fixa de 12px
-- Valor: enter 300ms, exit 150ms; enter `translateY(8px)`, exit `translateY(-12px)`
-```css
-/* Enter */
-.panel-enter {
-  animation: fadeIn 300ms ease forwards;
-}
-@keyframes fadeIn {
-  from { opacity: 0; transform: translateY(8px); }
-  to   { opacity: 1; transform: translateY(0); }
-}
-
-/* Exit */
-.panel-exit {
-  animation: fadeOut 150ms ease forwards;
-}
-@keyframes fadeOut {
-  from { opacity: 1; transform: translateY(0); }
-  to   { opacity: 0; transform: translateY(-12px); }
-}
-```
-- Por quê: atenção do usuário já está no próximo elemento — exits longos ou distantes distraem do novo conteúdo
-
-**POL-08 — Animação Contextual de Ícones**
-Ícones que aparecem devem ter animação própria, não herdar a animação do container.
-- Regra: ícones entram com scale + blur + opacity simultâneos
-- Valor: `scale: 0.25→1`, `opacity: 0→1`, `filter: blur(4px)→blur(0)`
-```css
-.icon-enter {
-  animation: iconReveal 250ms ease forwards;
-}
-@keyframes iconReveal {
-  from {
-    opacity: 0;
-    transform: scale(0.25);
-    filter: blur(4px);
-  }
-  to {
-    opacity: 1;
-    transform: scale(1);
-    filter: blur(0);
-  }
-}
-```
-- Por quê: ícones são pequenos e de alta densidade visual — sem animação própria, parecem "pop" abrupto quando o container anima
-
-**POL-09 — Nunca `transition: all`**
-Sempre especificar propriedades explicitamente. `all` causa re-renders desnecessários e pode animar propriedades inesperadas.
-- Regra: listar cada propriedade animada individualmente
-- Valor: `transition-property: transform, opacity` (nunca `all`)
-```css
-/* Errado */
-.element {
-  transition: all 200ms ease;
-}
-
-/* Correto */
-.element {
-  transition:
-    transform 200ms ease,
-    opacity 200ms ease,
-    background-color 150ms ease;
-}
-```
-- Por quê: `transition: all` anima padding, margin, border-radius, width, height — causando layout thrashing e efeitos visuais indesejados
-
-**POL-10 — `will-change` com Moderação**
-Só usar para propriedades GPU-compositable e apenas quando houver stutter observável.
-- Regra: aplicar apenas em `transform`, `opacity`, `filter`; nunca preventivamente
-- Valor: `will-change: transform` apenas quando necessário
-```css
-/* Aplicar apenas se observar stutter no primeiro frame */
-.heavy-animation {
-  will-change: transform, opacity;
-}
-
-/* Remover após animação (em JS) */
-element.addEventListener('transitionend', () => {
-  element.style.willChange = 'auto';
-});
-
-/* NUNCA fazer: */
-* { will-change: transform; } /* desperdiça memória GPU */
-```
-- Por quê: `will-change` cria uma camada compositing dedicada — usar em tudo consome memória GPU e pode causar o stutter que tentava evitar
-
-**POL-11 — Skip Animation on Page Load**
-Evitar animações de entrada no primeiro render. Conteúdo deve aparecer instantaneamente no carregamento.
-- Regra: desabilitar enter animations no mount inicial
-- Valor: `initial={false}` (Framer Motion) ou classe `.loaded` via JS
-```css
-/* CSS: desabilitar transitions até página carregar */
-.no-transition * {
-  transition: none !important;
-}
-
-/* JS: remover classe após load */
-/* document.addEventListener('DOMContentLoaded', () => {
-  document.body.classList.remove('no-transition');
-}); */
-
-/* Framer Motion / Motion */
-/* <AnimatePresence initial={false}> */
-```
-- Por quê: animações no load atrasam o tempo percebido de carregamento e fazem a UI parecer lenta — conteúdo deve estar "lá" imediatamente
-
-**POL-12 — Scale on Press**
-Botões devem ter feedback tátil via scale no estado `:active`.
-- Regra: exatamente `scale(0.96)` no active, nunca menor que 0.95
-- Valor: `transform: scale(0.96)`, `transition: transform 100ms ease`
-```css
-.button {
-  transition: transform 100ms ease;
-}
-.button:active {
-  transform: scale(0.96);
-}
-
-/* Com hover combinado */
-.button:hover {
-  transform: scale(1.02);
-}
-.button:hover:active {
-  transform: scale(0.96);
-}
-```
-- Por quê: scale simula a física de um botão real sendo pressionado — abaixo de 0.95 parece "borracha", acima de 0.98 é imperceptível
-
----
-
-## Tipografia
-
-**POL-13 — Font Smoothing**
-Sempre aplicar antialiasing subpixel no body. Texto fica mais nítido e com peso visual consistente no macOS.
-- Regra: aplicar no `body` ou `:root`, uma vez
-- Valor: `-webkit-font-smoothing: antialiased` + `-moz-osx-font-smoothing: grayscale`
-```css
-body {
-  -webkit-font-smoothing: antialiased;
-  -moz-osx-font-smoothing: grayscale;
-}
-```
-- Por quê: sem antialiasing, fontes ficam mais "gordas" no macOS (subpixel rendering padrão adiciona peso visual), especialmente em fontes claras sobre fundo escuro
-
-**POL-14 — Tabular Numbers**
-Usar `tabular-nums` em qualquer número que mude dinamicamente. Evita shift de layout quando dígitos têm larguras diferentes.
-- Regra: aplicar em preços, contadores, timers, colunas numéricas de tabelas
-- Valor: `font-variant-numeric: tabular-nums`
-```css
-.price,
-.counter,
-.timer,
-.table-number {
-  font-variant-numeric: tabular-nums;
-}
-
-/* Alternativa via font-feature-settings */
-.number {
-  font-feature-settings: "tnum";
-}
-```
-- Por quê: fontes proporcionais têm "1" mais estreito que "0" — sem tabular nums, o layout "pula" a cada atualização de valor
-
-**POL-15 — Text Wrapping**
-Usar `balance` em headings e `pretty` em parágrafos para distribuição inteligente de texto entre linhas.
-- Regra: `balance` para headings (distribui palavras igualmente), `pretty` para body (evita orphans)
-- Valor: `text-wrap: balance` e `text-wrap: pretty`
-```css
-h1, h2, h3, h4, h5, h6 {
-  text-wrap: balance;
-}
-
-p, li, blockquote {
-  text-wrap: pretty;
-}
-```
-- Por quê: `balance` evita headings com uma linha cheia e outra com uma palavra; `pretty` evita palavras órfãs (sozinhas) na última linha de parágrafos
-
----
-
-## Touch & Hit Areas
-
-**POL-16 — Hit Area Mínimo 40x40px**
-Área interativa mínima de 40x40px em desktop, 44x44px em mobile. Se o elemento visual é menor, estender a área clicável com pseudo-element.
-- Regra: todo alvo de toque/clique deve ter pelo menos 40x40px de área interativa
-- Valor: 40x40px desktop, 44x44px mobile (Apple HIG)
-```css
-/* Elemento visual pequeno com hit area expandida */
-.icon-button {
-  position: relative;
-  width: 24px;
-  height: 24px;
-}
-.icon-button::before {
-  content: '';
-  position: absolute;
-  top: 50%;
-  left: 50%;
-  transform: translate(-50%, -50%);
-  width: 40px;
-  height: 40px;
-}
-
-/* Mobile: expandir para 44px */
-@media (pointer: coarse) {
-  .icon-button::before {
-    width: 44px;
-    height: 44px;
-  }
-}
-```
-- Por quê: dedos são imprecisos (~7mm de contato) — alvos menores que 40px causam taps errados e frustração, especialmente em mobile