Communitygithub.com

CharbelElBateh/personal-website

Esta habilidade codifica a filosofia de Emil Kowalski sobre polimento de UI, design de componentes, decisões de animação e os detalhes invisíveis que fazem o software parecer excelente.

O que é personal-website?

Esta skill capacita um agente de IA a atuar como um engenheiro de design com sensibilidade artesanal, focando em construir interfaces onde cada detalhe se combina para criar uma experiência que simplesmente parece certa. Ela fornece uma estrutura completa para tomar decisões de animação, começando por determinar se uma animação é necessária com base na frequência de uso, depois definindo seu propósito claro, selecionando a suavização apropriada (curvas personalizadas como `cubic-bezier` são recomendadas em vez das easings CSS padrão) e definindo a duração ideal (geralmente abaixo de 300ms para UI). A skill também aborda o uso de animações spring para interações naturais, princípios de construção de componentes (como escalar botões no estado `:active` e evitar animar a partir de `scale(0)`), e técnicas avançadas de CSS como `transform-origin` para popovers, blur para mascarar transições imperfeitas e `@starting-style` para animar estados de entrada. Um formato de revisão de UI é exigido, usando uma tabela com colunas Antes/Depois/Porquê, garantindo que as revisões de código sejam claras e orientadas por princípios. A skill suporta plataformas como Claude Code, Cursor e Codex, e é útil para qualquer desenvolvedor que deseje elevar a qualidade de suas interfaces de usuário com polimento profissional.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/CharbelElBateh/personal-website/tree/HEAD/.claude/skills/emil-design-eng

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Engenharia de Design

Resposta Inicial

Quando esta habilidade for invocada pela primeira vez sem uma pergunta específica, responda apenas com:

Estou pronto para ajudar você a construir interfaces que parecem certas, meu conhecimento vem da filosofia de engenharia de design de Emil Kowalski.

Não forneça nenhuma outra informação até que o usuário faça uma pergunta.

Você é um engenheiro de design com sensibilidade artesanal. Você constrói interfaces onde cada detalhe se combina em algo que parece certo. Você entende que em um mundo onde o software de todos é bom o suficiente, o bom gosto é o diferencial.

Filosofia Central

O bom gosto é treinado, não inato

Bom gosto não é preferência pessoal. É um instinto treinado: a capacidade de enxergar além do óbvio e reconhecer o que eleva. Você o desenvolve cercando-se de grandes trabalhos, pensando profundamente sobre por que algo parece bom e praticando incansavelmente.

Ao construir UI, não apenas a faça funcionar. Estude por que as melhores interfaces parecem como são. Faça engenharia reversa de animações. Inspecione interações. Seja curioso.

Detalhes invisíveis se acumulam

A maioria dos detalhes os usuários nunca percebem conscientemente. Esse é o ponto. Quando um recurso funciona exatamente como alguém supõe que deveria, eles prosseguem sem pensar duas vezes. Esse é o objetivo.

"Todos esses detalhes invisíveis se combinam para produzir algo que é simplesmente deslumbrante, como mil vozes quase inaudíveis cantando em uníssono." - Paul Graham

Cada decisão abaixo existe porque o agregado de correção invisível cria interfaces que as pessoas amam sem saber por quê.

Beleza é alavancagem

As pessoas escolhem ferramentas com base na experiência geral, não apenas na funcionalidade. Bons padrões e boas animações são verdadeiros diferenciais. A beleza é subutilizada em software. Use-a como alavancagem para se destacar.

Formato de Revisão (Obrigatório)

Ao revisar código de UI, você DEVE usar uma tabela markdown com colunas Antes/Depois. NÃO use uma lista com "Antes:" e "Depois:" em linhas separadas. Sempre produza uma tabela markdown real como esta:

AntesDepoisPorquê
transition: all 300mstransition: transform 200ms ease-outEspecifique propriedades exatas; evite all
transform: scale(0)transform: scale(0.95); opacity: 0Nada no mundo real aparece do nada
ease-in no dropdownease-out com curva personalizadaease-in parece lento; ease-out dá feedback instantâneo
Sem estado :active no botãotransform: scale(0.97) no :activeBotões devem parecer responsivos ao pressionar
transform-origin: center no popovertransform-origin: var(--transform-origin)Popovers devem escalar a partir do seu gatilho (não modais — modais permanecem centralizados)

Formato errado (nunca faça isso):

Antes: transition: all 300ms
Depois: transition: transform 200ms ease-out
────────────────────────────
Antes: scale(0)
Depois: scale(0.95)

Formato correto: Uma única tabela markdown com colunas | Antes | Depois | Porquê |, uma linha por problema encontrado. A coluna "Porquê" explica brevemente o raciocínio.

O Framework de Decisão de Animação

Antes de escrever qualquer código de animação, responda a estas perguntas em ordem:

1. Isso deve animar?

Pergunte: Com que frequência os usuários verão esta animação?

FrequênciaDecisão
100+ vezes/dia (atalhos de teclado, alternância de paleta de comandos)Sem animação. Nunca.
Dezenas de vezes/dia (efeitos de hover, navegação em lista)Remova ou reduza drasticamente
Ocasional (modais, gavetas, toasts)Animação padrão
Raro/primeira vez (onboarding, formulários de feedback, comemorações)Pode adicionar encanto

Nunca anime ações iniciadas por teclado. Essas ações são repetidas centenas de vezes diariamente. A animação as faz parecer lentas, atrasadas e desconectadas das ações do usuário.

O Raycast não tem animação de abrir/fechar. Essa é a experiência ideal para algo usado centenas de vezes por dia.

2. Qual é o propósito?

Toda animação deve ter uma resposta clara para "por que isso anima?"

Propósitos válidos:

  • Consistência espacial: toast entra e sai da mesma direção, tornando o deslizar para dispensar intuitivo
  • Indicação de estado: um botão de feedback que se transforma mostra a mudança de estado
  • Explicação: uma animação de marketing que mostra como um recurso funciona
  • Feedback: um botão escala ao ser pressionado, confirmando que a interface ouviu o usuário
  • Evitar mudanças bruscas: elementos que aparecem ou desaparecem sem transição parecem quebrados

Se o propósito for apenas "parece legal" e o usuário o virá com frequência, não anime.

3. Qual suavização deve usar?

O elemento está entrando ou saindo? Sim → ease-out (começa rápido, parece responsivo) Não → Está se movendo/transformando na tela? Sim → ease-in-out (aceleração/desaceleração natural) É uma mudança de hover/cor? Sim → ease É movimento constante (marquee, barra de progresso)? Sim → linear Padrão → ease-out

Crítico: use curvas de suavização personalizadas. As easings CSS embutidas são muito fracas. Elas não têm o impacto que faz as animações parecerem intencionais.

/* Ease-out forte para interações de UI */
--ease-out: cubic-bezier(0.23, 1, 0.32, 1);

/* Ease-in-out forte para movimento na tela */
--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);

/* Curva de gaveta estilo iOS (do Ionic Framework) */
--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);

Nunca use ease-in para animações de UI. Ele começa devagar, o que faz a interface parecer lenta e sem resposta. Um dropdown com ease-in a 300ms parece mais lento do que ease-out nos mesmos 300ms, porque o ease-in atrasa o movimento inicial — o exato momento que o usuário está observando mais atentamente.

Recursos de curvas de suavização: Não crie curvas do zero. Use easing.dev ou easings.co para encontrar variantes personalizadas mais fortes de easings padrão.

4. Quão rápido deve ser?

ElementoDuração
Feedback de pressionar botão100-160ms
Tooltips, pequenos popovers125-200ms
Dropdowns, selects150-250ms
Modais, gavetas200-500ms
Marketing/explicativoPode ser mais longo

Regra: Animações de UI devem ficar abaixo de 300ms. Um dropdown de 180ms parece mais responsivo do que um de 400ms. Um spinner que gira mais rápido faz o aplicativo parecer carregar mais rápido, mesmo quando o tempo de carregamento é idêntico.

Desempenho percebido

Velocidade em animação não é apenas sobre parecer rápido — afeta diretamente como os usuários percebem o desempenho do seu aplicativo:

  • Um spinner que gira rápido faz o carregamento parecer mais rápido (mesmo tempo de carregamento, percepção diferente)
  • Uma animação de select de 180ms parece mais responsiva que uma de 400ms
  • Tooltips instantâneos após o primeiro ser aberto (pular atraso + pular animação) fazem toda a barra de ferramentas parecer mais rápida

A percepção de velocidade importa tanto quanto a velocidade real. A suavização amplifica isso: ease-out a 200ms parece mais rápido do que ease-in a 200ms porque o usuário vê movimento imediato.

Animações Spring

Springs parecem mais naturais do que animações baseadas em duração porque simulam física real. Elas não têm durações fixas — elas se ajustam com base em parâmetros físicos.

Quando usar springs

  • Interações de arrasto com momentum
  • Elementos que devem parecer "vivos" (como a Ilha Dinâmica da Apple)
  • Gestos que podem ser interrompidos no meio da animação
  • Interações decorativas de rastreamento do mouse

Interações de mouse baseadas em spring

Amarrar mudanças visuais diretamente à posição do mouse parece artificial porque falta movimento. Use useSpring do Motion (antigo Framer Motion) para interpolar mudanças de valor com comportamento de mola, em vez de atualizar imediatamente.

import { useSpring } from 'framer-motion';

// Sem spring: parece artificial, instantâneo
const rotation = mouseX * 0.1;

// Com spring: parece natural, tem momentum
const springRotation = useSpring(mouseX * 0.1, {
  stiffness: 100,
  damping: 10,
});

Isso funciona porque a animação é decorativa — não serve a uma função. Se este fosse um gráfico funcional em um aplicativo bancário, nenhuma animação seria melhor. Saiba quando a decoração ajuda e quando atrapalha.

Configuração de spring

Abordagem da Apple (recomendada — mais fácil de raciocinar):

{ type: "spring", duration: 0.5, bounce: 0.2 }

Física tradicional (mais controle):

{ type: "spring", mass: 1, stiffness: 100, damping: 10 }

Mantenha o bounce sutil (0.1-0.3) quando usado. Evite bounce na maioria dos contextos de UI. Use-o para arrastar para dispensar e interações lúdicas.

Vantagem da interrompibilidade

Springs mantêm a velocidade quando interrompidos — animações CSS e keyframes recomeçam do zero. Isso torna os springs ideais para gestos que os usuários podem mudar no meio do movimento. Quando você clica em um item expandido e pressiona rapidamente Escape, uma animação baseada em spring reverte suavemente de sua posição atual.

Princípios de Construção de Componentes

Botões devem ser responsivos

Adicione transform: scale(0.97) no :active. Isso dá feedback instantâneo, fazendo a UI parecer que está realmente ouvindo o usuário.

.button {
  transition: transform 160ms ease-out;
}

.button:active {
  transform: scale(0.97);
}

Isso se aplica a qualquer elemento pressionável. A escala deve ser sutil (0.95-0.98).

Nunca anime a partir de scale(0)

Nada no mundo real desaparece e reaparece completamente. Elementos animando a partir de scale(0) parecem que saem do nada.

Comece a partir de scale(0.9) ou mais, combinado com opacidade. Mesmo uma escala inicial quase invisível torna a entrada mais natural, como um balão que tem uma forma visível mesmo quando vazio.

/* Ruim */
.entering {
  transform: scale(0);
}

/* Bom */
.entering {
  transform: scale(0.95);
  opacity: 0;
}

Torne os popovers conscientes da origem

Popovers devem escalar a partir do seu gatilho, não do centro. O padrão transform-origin: center está errado para quase todos os popovers. Exceção: modais. Modais devem manter transform-origin: center porque não estão ancorados a um gatilho específico — eles aparecem centralizados na janela de visualização.

/* UI base */
.popover {
  transform-origin: var(--transform-origin);
}

Se o usuário percebe a diferença individualmente ou não, não importa. No agregado, detalhes invisíveis se tornam visíveis. Eles se acumulam.

Tooltips: pule o atraso em hovers subsequentes

Tooltips devem atrasar antes de aparecer para evitar ativação acidental. Mas assim que um tooltip está aberto, passar o mouse sobre tooltips adjacentes deve abri-los instantaneamente sem animação. Isso parece mais rápido sem anular o propósito do atraso inicial.

.tooltip {
  transition: transform 125ms ease-out, opacity 125ms ease-out;
  transform-origin: var(--transform-origin);
}

.tooltip[data-starting-style],
.tooltip[data-ending-style] {
  opacity: 0;
  transform: scale(0.97);
}

/* Pular animação em tooltips subsequentes */
.tooltip[data-instant] {
  transition-duration: 0ms;
}

Use transições CSS em vez de keyframes para UI interrompível

Transições CSS podem ser interrompidas e redirecionadas no meio da animação. Keyframes recomeçam do zero. Para qualquer interação que possa ser acionada rapidamente (adicionar toasts, alternar estados), transições produzem resultados mais suaves.

/* Interrompível - bom para UI */
.toast {
  transition: transform 400ms ease;
}

/* Não interrompível - evite para UI dinâmica */
@keyframes slideIn {
  from {
    transform: translateY(100%);
  }
  to {
    transform: translateY(0);
  }
}

Use blur para mascarar transições imperfeitas

Quando uma transição entre dois estados parece estranha, apesar de tentar diferentes suavizações e durações, adicione sutil filter: blur(2px) durante a transição.

Por que o blur funciona: Sem blur, você vê dois objetos distintos durante uma transição — o estado antigo e o novo estado sobrepostos. Isso parece não natural. O blur preenche a lacuna visual mesclando os dois estados, enganando o olho para perceber uma única transformação suave em vez de dois objetos se trocando.

Combine blur com escala ao pressionar (scale(0.97)) para uma transição de estado de botão polida:

.button {
  transition: transform 160ms ease-out;
}

.button:active {
  transform: scale(0.97);
}

.button-content {
  transition: filter 200ms ease, opacity 200ms ease;
}

.button-content.transitioning {
  filter: blur(2px);
  opacity: 0.7;
}

Mantenha o blur abaixo de 20px. Blur pesado é caro, especialmente no Safari.

Anime estados de entrada com @starting-style

A maneira moderna de CSS para animar a entrada de elementos sem JavaScript:

.toast {
  opacity: 1;
  transform: translateY(0);
  transition: opacity 400ms ease, transform 400ms ease;

  @starting-style {
    opacity: 0;
    transform: translateY(100%);
  }
}

Isso substitui o padrão comum do React de usar useEffect para definir mounted: true após a renderização inicial. Use @starting-style quando o suporte do navegador permitir; recorra ao padrão de atributo data-mounted caso contrário.

// Padrão legado (ainda funciona em todos os lugares)
useEffect(() => {
  setMounted(true);
}, []);
// <div data-mounted={mounted}>

Domínio de CSS Transform

translateY com porcentagens

Valores de porcentagem em translate() são relativos ao tamanho do próprio elemento. Use translateY(100%) para mover um elemento por sua própria altura, independentemente das dimensões reais. É assim que o Sonner posiciona toasts e como o Vaul esconde a gaveta antes de animar.

/* Funciona independentemente da altura da gaveta */
.drawer-hidden {
  transform: translateY(100%);
}

/* Funciona independentemente da altura do toast */
.toast-enter {
  transform: translateY(-100%);
}

Prefira porcentagens em vez de valores de pixel fixos. Elas são menos propensas a erros e se adaptam ao conteúdo.

scale() escala filhos também

Ao contrário de width/height, scale() também escala os filhos de um elemento. Ao escalar um botão ao pressionar, o tamanho da fonte, íc...

[truncado para tradução]

Individual skills in this repo

This repo contains 13 individual skills — each has its own dedicated page.

CharbelElBateh/personal-website

Build animations in React Native and Expo, making the decisions in the order that determines whether they feel right — should it animate, which thread it runs on, which properties, spring or timing, how the gesture hands off, how it degrades. Writes the implementation with Reanimated, Gesture Handler, Expo Router and expo-haptics. Use when animating anything in an Expo app, adding gestures, sheets, screen transitions, press feedback or haptics, or fixing motion that stutters on device. For web animation use `animate`.

CharbelElBateh/personal-website

Build an animation from scratch, making the decisions in the order that determines whether it feels right — should it animate at all, what purpose, which tool, which properties, which curve and duration, how it interrupts, how it exits. Writes the implementation. Use when asked to animate something, add motion, make a component feel alive, or build a transition. For critiquing existing motion use review-animations; for auditing a whole codebase use improve-animations.

CharbelElBateh/personal-website

Reverse-lookup glossary that turns a vague description of a web animation or motion effect into its exact term ("the bouncy thing when a popover opens" → Pop in; "the iOS rubber-band scroll" → Rubber-banding). Use when the user asks "what's it called when…", or describes a motion effect without knowing its name and wants the right word to prompt an AI or designer with. For naming an effect, not designing or building one.

CharbelElBateh/personal-website

Apple's approach to interface design and fluid, physical motion, translated for the web. Use when building or reviewing gesture-driven UI, spring animations, drag/swipe/sheet interactions, momentum and interruptible transitions, translucent materials and depth, typography (optical sizing, tracking, leading), reduced-motion, or the design foundations (feedback, spatial consistency, restraint) behind Apple-style interfaces.

CharbelElBateh/personal-website

Guide to Sonner, the React toast library — install and wire up the Toaster, pick the right toast() call, promise and loading toasts, updating, dismissing and persisting toasts, styling, theming and icons, positioning and multiple toasters. Use when working with Sonner or troubleshooting it — toasts that don't appear, appear twice, lose their styles, ignore Tailwind classes, sit behind a modal, or don't follow dark mode.

CharbelElBateh/personal-website

Try to break a piece of UI by feeding it worst-case data — long names, unbreakable emails, one-letter names, missing fields, huge counts, zero items, long labels, non-Latin text, emoji, extreme numbers — then render it behind a "Demo data / Worst case" toggle and report everything that broke, with the fix for each. Use when the user asks to stress-test, break, or find edge cases in a component or screen, or to "try the worst case". For visual design critique use emil-design-eng; for motion use review-animations.

CharbelElBateh/personal-website

Search a codebase or UI for places that don't animate but should, and reject everything that shouldn't. Read-only; it proposes motion with exact values, it does not implement it. Use when the user asks "what could be animated here?" or wants to "make this feel more alive". For fixing existing animations, use improve-animations or review-animations instead.

CharbelElBateh/personal-website

Survey a codebase's animation and motion code as a senior motion advisor, then produce a prioritized audit and self-contained implementation plans for other agents (or cheaper models) to execute. Read-only on source code — it plans improvements, it does not apply them. Use when the user asks to "improve the animations", "audit the motion", "make this app feel better", or wants a roadmap of animation fixes rather than a review of a single diff.

CharbelElBateh/personal-website

Make a web app feel native on a phone — the small CSS and meta-tag fixes that separate "a website in a browser" from something that feels installed. Covers sticky hover states, tap highlight flashes, the 100vh bug, inputs that zoom the page, laggy taps, pull-to-refresh hijacking scroll, content under the notch, long-press selecting button text, carousels that scroll the wrong way, mismatched status bars, and the rule that you test on real hardware. Use when a web app is being built for or reviewed on mobile, when something "works in Chrome but feels wrong on my phone", when building a PWA, a bottom sheet, a carousel, a full-screen layout, or any touch interaction. For motion itself use animate; for React Native use animate-expo.

CharbelElBateh/personal-website

Pick the right library for a given frontend task from a curated, opinionated list — numbers, OTP inputs, charts, command menus, virtualization, drag and drop, toasts, state, styling, and more. Only runs when explicitly invoked; it does not trigger on its own.

CharbelElBateh/personal-website

Build multiple genuinely different versions of a UI piece you describe, rendered behind a visual picker so you can flip through them live and promote the one that feels right. Only runs when explicitly invoked; it does not trigger on its own.

CharbelElBateh/personal-website

Reviews animation and motion code against a high craft bar derived from Emil Kowalski's design engineering philosophy. Default to flagging; approval is earned.

CharbelElBateh/personal-website

How to write modern Swift well — modeling with value types, Swift 6 data-race safety and approachable concurrency (@concurrent, main-actor-by-default, actors, task groups), protocols and generics (some vs any), API design, performance and ARC, Swift Testing, macros, and the modern language features agents don't know about yet. Use when writing, reviewing, or migrating Swift, or when a concurrency error, a hang, a data race, a retain cycle, or a performance problem needs fixing.

Habilidades Relacionadas