Communitygithub.com

CharbelElBateh/personal-website

A abordagem da Apple para design de interfaces e movimento físico fluido, traduzida para a web. Use ao construir ou revisar interfaces orientadas a gestos, animações spring, interações de arrastar/deslizar/folha, momentum e transições interrompíveis, materiais translúcidos e profundidade, tipografia (optical sizing, tracking, leading), movimento reduzido, ou os fundamentos de design (feedback, consistência espacial, moderação) por trás das interfaces no estilo Apple.

O que é personal-website?

Esta skill fornece princípios e padrões de design de interface do usuário da Apple, adaptados para desenvolvedores web. Abrange desde interação responsiva e manipulação direta até animações com spring, interrupção de gestos e projeção de momentum. As principais fontes são palestras de design da WWDC, especialmente *Designing Fluid Interfaces* (WWDC 2018). A skill inclui implementações práticas em CSS, JavaScript e bibliotecas como Motion/Framer Motion, com foco em criar interfaces que pareçam extensões naturais do usuário, em vez de telas tradicionais de computador. É útil ao construir componentes de UI complexos como folhas inferiores, carrosséis, modais interrompíveis e qualquer interação baseada em arrastar, garantindo que o movimento pareça físico, responsivo e contínuo.

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

Perguntar na sua IA favorita

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

Documentação

Design Apple

Resposta Inicial

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

Estou pronto para ajudá-lo a construir interfaces fluidas no estilo Apple para a web. Meu conhecimento vem das palestras de design da WWDC da Apple, traduzidas para a web.

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

Como a Apple constrói interfaces que deixam de parecer um computador e começam a parecer uma extensão sua. Este conhecimento vem das palestras de design da WWDC da Apple — principalmente Designing Fluid Interfaces (WWDC 2018) — destilado e traduzido para a plataforma web (CSS, Pointer Events, requestAnimationFrame, bibliotecas spring como Motion/Framer Motion).

O fio condutor: uma interface parece viva quando o movimento começa a partir do valor atual na tela, herda a velocidade do usuário, projeta o momentum para frente e pode ser agarrada e revertida a qualquer instante. Springs são a ferramenta que torna tudo isso natural, pois são inerentemente interrompíveis e conscientes da velocidade.

A Ideia Central

"Quando alinhamos a interface à maneira como pensamos e nos movemos, algo mágico acontece — ela deixa de parecer um computador e começa a parecer uma extensão perfeita de nós."

Uma interface é fluida quando se comporta como o mundo físico: as coisas respondem instantaneamente, movem-se continuamente, carregam momentum, resistem nos limites e podem ser redirecionadas durante o movimento. Tudo abaixo é uma maneira de se aproximar disso.

A Apple enquadra o design como servindo a quatro necessidades humanas: segurança/previsibilidade, compreensão, realização e alegria. Cada regra aqui atende a uma delas.

1. Resposta — elimine a latência

No momento em que a latência aparece, a sensação de direcionalidade "despenca". A resposta é a base sobre a qual tudo o mais é construído.

  • Responda ao pointer-down, não ao release. Destaque um botão no instante em que for pressionado. Esperar pelo click/touch-up para mostrar feedback parece morto.
  • Seja vigilante sobre cada latência. Audite debounces, timers artificiais, esperas de transição e o atraso de toque de ~300ms. Qualquer coisa no caminho de entrada que não seja essencial é uma regressão.
  • O feedback deve ser contínuo durante a interação, não apenas no final. Para um arrasto, slider ou gaveta, atualize a UI em 1:1 com o ponteiro durante todo o percurso — nunca anime apenas quando o gesto for concluído.
/* O feedback vive no pressionar, e é instantâneo */
.button:active {
  transform: scale(0.97);
  transition: transform 100ms ease-out;
}

2. Manipulação direta — rastreamento 1:1

"O toque e o conteúdo devem se mover juntos."

Quando o usuário arrasta algo, ele deve permanecer grudado ao dedo — e respeitar o deslocamento de onde o agarrou. Aderir ao centro do elemento ao agarrar quebra a ilusão imediatamente.

  • Use Pointer Events com setPointerCapture para que o rastreamento continue mesmo quando o ponteiro sair dos limites do elemento.
  • Mantenha um breve histórico de velocidade/posição (últimos eventos pointermove), não apenas o ponto atual — você precisará da velocidade ao soltar.
el.addEventListener('pointerdown', (e) => {
  el.setPointerCapture(e.pointerId);
  const grabOffset = e.clientY - el.getBoundingClientRect().top; // respeita onde agarrou
  // ...rastreia histórico de posição + timestamp para velocidade
});

3. Interrompibilidade — o princípio mais importante

"O pensamento e o gesto acontecem em paralelo."

Cada animação deve ser interrompível e redirecionável a qualquer momento. Um usuário deve ser capaz de agarrar um elemento em movimento no meio do trajeto e revertê-lo sem esperar a animação terminar. Um modal que está fechando e que o usuário agarra novamente deve seguir o dedo — não terminar de fechar primeiro e depois reabrir.

  • Nunca bloqueie a entrada durante uma transição.
  • Sempre anime a partir do valor de apresentação (atual), nunca do valor alvo. Ao interromper, leia a transformação ao vivo do elemento na tela e inicie a nova animação a partir daí. Começar pelo valor lógico/alvo causa um salto visível.
  • Evite transições CSS e @keyframes para qualquer coisa orientada a gestos — eles não podem ser suavemente agarrados e revertidos durante o movimento. Springs animam a partir do valor atual por padrão, que é exatamente o que a interrupção precisa.
  • Quando um gesto reverte, mescle a velocidade — não a corte abruptamente. Substituir uma animação por outra em uma reversão cria uma descontinuidade de velocidade, uma "parede de tijolos". Bibliotecas Spring que carregam a velocidade através de um novo alvo evitam isso. (É isso que as animações aditivas do iOS fazem nativamente; na web, escolha uma biblioteca spring que mire novamente a partir da velocidade atual.)
  • Decomponha o movimento 2D em molas X e Y independentes. Uma única mola em uma distância 2D dessincroniza quando X e Y têm velocidades diferentes.

4. Comportamento sobre animação — use springs

"Pense na animação como uma conversa entre você e o objeto, não algo prescrito pela interface."

Uma animação pré-roteirizada e de duração fixa não pode responder a novas entradas. Uma spring pode — novas entradas apenas mudam o alvo, e o movimento permanece contínuo. Recorra a springs para qualquer coisa que o usuário possa tocar.

A Apple substituiu deliberadamente o trio de física (massa/rigidez/amortecimento) por dois parâmetros amigáveis ao designer. Pense nestes:

  • Razão de amortecimento — controla o overshoot. 1.0 = criticamente amortecido, sem oscilação, suave. < 1.0 = ultrapassa e oscila. Menor = mais saltitante.
  • Resposta — quão rapidamente o valor atinge o alvo, em segundos. Menor = mais rápido. Isso não é "duração" — uma spring não tem duração fixa; seu tempo de estabilização emerge dos parâmetros.

Padrões:

  • Comece a maioria das UIs com amortecimento 1.0 (criticamente amortecido) — gracioso e não distrativo.
  • Adicione oscilação (amortecimento ~0.8) apenas quando o próprio gesto carregou momentum (um movimento rápido, um lançamento, uma liberação de arrasto). Overshoot em um menu que apenas apareceu parece errado; overshoot em um cartão que você jogou parece certo.

Valores concretos que a Apple utiliza:

InteraçãoAmortecimentoResposta
Mover / reposicionar (ex.: PiP)1.00.4
Rotação0.80.4
Gaveta / folha0.80.3

Mapeamento web (Motion / Framer Motion): a API de spring bounce + duration mapeia de perto para amortecimento + resposta da Apple. Um estilo de casa seguro é damping: 1.0 springs em todos os lugares por padrão; reserve oscilação para interações físicas impulsionadas por momentum.

import { animate } from 'motion';

// Padrão criticamente amortecido (sem overshoot)
animate(el, { y: 0 }, { type: 'spring', bounce: 0, duration: 0.4 });

// Interação de momentum — um pouco de oscilação, apenas porque um movimento rápido a precedeu
animate(el, { y: target }, { type: 'spring', bounce: 0.2, duration: 0.4 });

5. Transferência de velocidade — a junção entre arrasto e animação

Quando um gesto termina, a animação deve continuar na velocidade exata do dedo, para que não haja junção visível entre arrastar e animar. Este é o detalhe que mais separa "fluido" de "ok".

Passe a velocidade de liberação do ponteiro como a velocidade inicial da spring. Algumas APIs de spring exigem velocidade relativa — normalize-a pela distância restante ao alvo:

velocidadeRelativa = velocidadeDoGesto / (valorAlvo − valorAtual)

Exemplo: elemento em y=50, alvo y=150 (100px para percorrer), dedo movendo-se a 50px/s → velocidade inicial da spring = 50 / 100 = 0.5. Framer Motion / Motion aceitam velocidade absoluta em px/s diretamente (opção velocity), então você geralmente passa o valor bruto.

6. Projeção de momentum — anime para onde o gesto está indo

"Pegue uma pequena entrada e produza uma grande saída."

Não adira ao limite mais próximo a partir do ponto de liberação. Use a velocidade para projetar a posição de repouso — exatamente como a desaceleração de rolagem — e então adira ao alvo mais próximo desse ponto projetado. Isso é o que faz um movimento rápido parecer que está arremessando o elemento.

A função de projeção exata da Apple (do código de exemplo Designing Fluid Interfaces):

// decelerationRate ≈ 0.998 para sensação de rolagem normal; 0.99 para mais rápida
function project(initialVelocity /* px/s */, decelerationRate = 0.998) {
  return (initialVelocity / 1000) * decelerationRate / (1 - decelerationRate);
}

const projectedEndpoint = currentPosition + project(releaseVelocity);
const target = nearestSnapPoint(projectedEndpoint);   // escolhe o alvo da projeção
animateSpringTo(target, { velocity: releaseVelocity }); // então transfere a velocidade (§5)

Nota: a fórmula de física v²/(2·decel) não é o que a Apple utiliza— use a forma de decaimento exponencial acima. Este é o comportamento padrão em boas folhas inferiores e carrosséis (Vaul, Embla).

7. Consistência espacial — caminhos simétricos, origens ancoradas

"Se algo desaparece de uma maneira, esperamos que surja de onde veio."

  • Entre e saia pelo mesmo caminho. Um painel que desliza da direita deve desaparecer para a direita. Entrar pela direita / sair pela parte inferior parece desconectado e confuso.
  • Ancore as interações à sua origem. Um menu, popover ou folha deve se originar do elemento que o acionou — defina transform-origin para o acionador, para que a relação espacial entre o botão e o conteúdo seja óbvia. (Este é o mesmo ponto de consciência de origem que popovers escalando a partir de seu gatilho, não de seu centro.)
  • Espelhe o easing em transições reversíveis para que o caminho de saída corresponda ao caminho de retorno (use pontos de controle cúbico-bezier inversos para as duas direções).

8. Sugira na direção do gesto

Humanos preveem um estado final a partir de uma trajetória. O movimento intermediário deve telegrafar para onde as coisas estão indo — os módulos do Centro de Controle "crescem para cima e para fora em direção ao seu dedo." Faça com que os quadros intermediários apontem para o resultado, não apenas interpolem cegamente em direção a ele.

9. Rubber-banding — limites suaves

Em um limite, resista progressivamente em vez de parar bruscamente. Uma parada brusca é lida como "congelado"; resistência contínua é lida como "responsivo, mas não há mais nada aqui." Aplique amortecimento que aumenta quanto mais além do limite o usuário arrasta.

// Quanto mais além do limite, menos o elemento segue — coisas reais desaceleram antes de parar
function rubberband(overshoot, dimension, constant = 0.55) {
  return (overshoot * dimension * constant) / (dimension + constant * Math.abs(overshoot));
}

10. Detalhes de design de gestos (a lista de verificação de "sensação")

  • Toque: destaque no touch-down (instantâneo), confirme no touch-up. Adicione ~10px de histerese/preenchimento de acerto em torno do alvo e permita cancelar arrastando para longe e de volta.
  • Arrasto/deslize: exija um pequeno limite de movimento (histerese, ~10px) antes de se comprometer com uma direção e, em seguida, rastreie 1:1.
  • Detecte todos os gestos plausíveis em paralelo desde o primeiro movimento e, em seguida, cancele com confiança os perdedores assim que a intenção estiver clara. Evite reconhecedores que relatam apenas um estado final (eventos do tipo swipeleft) — eles descartam o rastreamento contínuo necessário para o feedback.
  • Minimize os atrasos de desambiguação. A detecção de toque duplo inevitavelmente atrasa toques únicos; só pague esse custo onde o toque duplo realmente existir.

11. Suavidade em nível de quadro

Suavidade é sobre o que está nos quadros, não apenas a taxa de quadros.

  • Mantenha a mudança posicional por quadro abaixo do limite de percepção para evitar efeito estroboscópico.
  • Para movimentos muito rápidos, um sutil desfoque de movimento / esticamento codifica a velocidade e é lido melhor do que um traçado duro e nítido.
  • requestAnimationFrame é o relógio sincronizado com a tela da web (a Apple usa CADisplayLink). Anime apenas propriedades amigáveis ao compositor — transform e opacity — e sugira com will-change onde o movimento é iminente.

12. Materiais e profundidade — translucidez transmite hierarquia

A Apple usa materiais translúcidos como uma camada funcional flutuante que traz estrutura sem roubar o foco. Na web, aproxime-se com backdrop-filter.

  • Construa navs/barras de ferramentas/folhas como camadas translúcidas (backdrop-filter: blur() + um fundo semitransparente) com conteúdo rolando por baixo — não barras opacas que consomem uma faixa fixa.
  • O peso do material codifica a hierarquia: materiais mais escuros/pesados separam regiões estruturais (barras laterais); materiais mais claros atraem a atenção para elementos interativos (botões). Nunca empilhe uma superfície translúcida clara sobre outra — a legibilidade é prejudicada.
  • Superfícies maiores devem parecer mais grossas: desfoque mais forte + uma sombra mais profunda do que pequenos chips. Considere sombra sensível ao contexto — mais pesada sobre conteúdo ocupado/texto para separação, mais leve sobre fundos simples.
  • Escureça para focar, separe para manter o fluxo. Uma tarefa modal combina a superfície com uma cortina de escurecimento e empurra o fundo para trás/para baixo. Um painel paralelo e não bloqueador usa translucidez e deslocamento sem uma cortina para que o fluxo não seja interrompido. Para folhas empilhadas, escureça progressivamente e empurre para trás cada camada pai.
  • Vibração mantém o texto legível sobre fundos variáveis. Sobre superfícies desfocadas/translúcidas, não use texto cinza plano — use maior contraste, peso ligeiramente mais pesado e um pequeno aumento no espaçamento entre letras. Coloque a cor em uma camada sólida, não no primeiro plano translúcido.
  • Efeitos de borda de rolagem, não divisores rígidos. Em vez de uma borda de 1px sob um cabeçalho fixo, desbote uma pequena máscara de desfoque/gradiente onde o conteúdo encontra o cromo flutuante — apenas onde a UI flutuante realmente sobrepõe o conteúdo.
  • Materialize, não apenas desbote. Para superfícies de vidro/desfoque, anime o raio do desfoque e a escala juntos ao entrar/sair, para que a superfície seja lida como um material real chegando, em vez de um desbotamento de opacidade simples.
.toolbar {
  background: rgba(255, 255, 255, 0.6);
  backdrop-filter: blur(20px) saturate(180%);
  border-top: 1px solid rgba(255, 255, 255, 0.4); /* borda superior brilhante = luz capturando o material */
}

13. Feedback multimodal — movimento + som + háptica

Três regras para combinar sentidos (de Designing Audio-Haptic Experiences):

  1. Causalidade — deve ser óbvio o que causou o feedback. Acione-o no evento causal real (o toggle virando, o item se encaixando) e corresponda seu caráter à fisicalidade da ação.
  2. Harmonia — o visual, o som e o háptico devem disparar no mesmo quadro. A latência entre eles destrói a ilusão. Não deixe que um

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

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

This skill encodes Emil Kowalski's philosophy on UI polish, component design, animation decisions, and the invisible details that make software feel great.

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