Design craft
Um método de trabalho para design e construção frontend. SKILL.md contém o que toda tarefa precisa; os arquivos references/ contêm profundidade, números e código. Leia um deles quando seu gatilho na tabela ao final se aplicar.
Escopo: uma nova página, fluxo ou componente executa os passos 1 a 8. Uma pequena alteração (um estado, uma animação, uma string) executa apenas os passos que toca e, em seguida, o passo 8 no que mudou.
Ordem das necessidades
Funcional → confiável → utilizável → prazeroso. Nunca adicione encanto a algo quebrado, lento ou confuso, e nunca entregue sem a camada superior: a personalidade adiada para "depois" raramente é entregue.
1. Enquadramento (antes de qualquer código)
- História de trabalho: Quando [situação], quero [motivação], para que eu possa [resultado]. Situação ou resultado desconhecido → pergunte ou declare a suposição como uma hipótese em seu resumo.
- Escolha a ambição que o briefing pede e concentre o esforço ali:
| Brief | Invista em | Primeira prova |
|---|---|---|
| Site de marca, "premium", "nível de prêmio", "cheio de animação" | Uma interação marcante baseada no tema (passo 2) | A interação funcionando com conteúdo real: início, meio, interrupção, liberação |
| Lançamento, página editorial, de marketing | A oferta está clara e sua melhor evidência é explorável | Primeira tela lida em um celular; ação principal alcançável sem espera |
| Aplicativo, ferramenta, painel | A decisão mais difícil, o custo de um erro, a velocidade do uso repetido | Uma tarefa realista com dados mutáveis, mais recuperação de uma falha |
| Componente ou sistema de design | Um contrato comportamental que sobrevive a dois consumidores diferentes | O mesmo componente em dois contextos com conteúdo longo |
- Separe fatos de suposições. Nomeie o estado emocional do visitante ao chegar; ele define o tom.
- Verifique o que existe: tokens, componentes, padrões, convenções. Reutilize antes de inventar.
2. Encontre a marca registrada no tema
Para trabalhos expressivos, procure uma propriedade do tema que o visitante reconheceria com o logotipo coberto, e um verbo que lhe permita conduzi-la. Uma cerveja derrama, forma espuma e mostra sua cor; um tecido drapeja; uma fonte tem eixos; um relógio tem um movimento. Projete a interação em torno dessa propriedade.
- Teste de substituição: troque por uma marca não relacionada. Se o efeito ainda funcionar intocado, não é sobre o tema ainda. Volte ao tema antes de adicionar polimento.
- Quatro batidas: o que convida à entrada → o que responde ao contato → o que é revelado sob entrada sustentada → o que permanece na liberação. Um objeto persistente deve carregar todas as quatro.
- Mais efeitos nunca consertam "parece básico". Mude a ideia central ou mecânica em vez disso.
- Cada gesto tem um equivalente simples (um controle deslizante, um botão, um grupo de rádio) que alcança a mesma informação.
3. Explore barato, prove a parte mais difícil primeiro
- Descreva pelo menos três abordagens estruturalmente diferentes em algumas linhas cada. Escolha uma, diga o porquê.
- Componha um quadro estático com conteúdo real antes do movimento: ordem de leitura, tipografia, imagens, ação primária. Um quadro do meio de qualquer animação também deve parecer intencional.
- Construa a afirmação mais arriscada primeiro (o gesto, a cena de rolagem, o fluxo de trabalho difícil) e verifique em um navegador real antes de construir o resto da página ao redor.
4. Sistema primeiro
- Tokens antes de componentes. Componentes consomem tokens semânticos (
--color-action) que são apelidos de primitivos (--amber-400). Sem hex, px ou números mágicos dentro dos estilos dos componentes. - Espaçamento em escala baseada em 4 (4, 8, 12, 16, 24, 32, 48, 64). Corpo 16px/1rem com altura de linha 1,5; títulos 1,1-1,25. Uma proporção tipográfica modular. No máximo duas fontes (+ mono). Numerais tabulares para números variáveis.
- 1 a 3 cores de marca, neutros, cores de estado. Cada par de texto passa WCAG AA (4,5:1 corpo, 3:1 grande/UI). Cor nunca é o único sinal.
- Tokens de movimento (durações, curvas de easing) ficam ao lado de cor e espaçamento.
- Props nomeiam significado (
variant="destructive"), não aparência. Overrides repetidos significam uma variante faltando.
5. Todo estado, não apenas o caminho feliz
Componentes interativos: padrão, hover, focus-visible, ativo, desabilitado, carregando, erro, selecionado. Telas: vazio, carregando, parcial, erro, sucesso, offline. Trabalho assíncrono:
- Última requisição vence; uma resposta antiga e lenta não deve sobrescrever uma mais nova.
- Mantenha a entrada do usuário após qualquer falha e mantenha os resultados anteriores visíveis (escurecidos) enquanto carrega.
- Conta vazia, sem resultados e falha na busca são estados diferentes com ações seguintes diferentes.
Operável por teclado, HTML semântico primeiro, ARIA apenas onde HTML não pode dizer, um rótulo em cada campo, uma saída visível de cada modal e foco retornado a algo sensato quando fecha.
6. Emoção, texto e honestidade
- Clareza vence inteligência. Se uma piada precisa de uma frase extra, corte-a. Contrações, palavras simples.
- Voz é constante, tom muda: caloroso no sucesso, simples e calmo em erros, gentil em entrada sensível.
- Erros: o que aconteceu, por que, o que fazer a seguir e o que foi mantido. Nunca culpe o usuário. Sem humor aqui.
- Estados vazios convidam: o que aparecerá aqui mais uma ação clara inicial.
- Pico-fim: coloque o único grande encanto no final de uma conquista real, nunca em um vale de frustração.
- Em páginas de alto risco, nomeie os medos do visitante e responda a cada um antes da chamada para ação.
- Imagens: elenco diverso por padrão; pergunte "quem estamos excluindo?"
- Honestidade: rotule imagens geradas por IA e dados de demonstração onde as pessoas possam confundi-los com reais. O texto deve corresponder ao que as imagens mostram (uma lata que imprime 5,0% significa que a página diz 5,0%).
- Categorias regulamentadas (álcool, finanças, saúde, crianças): adicione o portal ou aviso exigido e verifique as imagens em relação às normas de publicidade da categoria, por exemplo, sem imagens sexualizadas para álcool.
7. Movimento
Toda animação tem um trabalho: contexto, atenção, feedback ou personalidade. Sem trabalho, sem animação.
| Token | Valor | Uso |
|---|---|---|
--dur-1 | 100ms | pressionar, foco, alternância (≈ o piso perceptual) |
--dur-2 | 200ms | maioria das transições de UI, hover, pequena entrada |
--dur-3 | 300ms | painéis, gavetas, modais |
--dur-4 | 400-500ms | apenas coreografia de tela cheia ou herói |
--ease-out | cubic-bezier(0,0,.2,1) | entrando / ganhando atenção |
--ease-in | cubic-bezier(.4,0,1,1) | saindo / perdendo atenção (saídas ~20-30% mais curtas) |
--ease-in-out | cubic-bezier(.4,0,.2,1) | movendo-se entre posições na tela |
| spring | criticamente amortecido, redirecionável | gestos; preservar velocidade quando o alvo muda |
- Nunca bloqueie a ação principal em coreografia. Um pré-carregador ou introdução não deve segurar a ação principal por mais de cerca de um segundo, e visitantes que retornam pulam.
- Consistência espacial: as coisas saem como vieram; elementos compartilhados se transformam no lugar.
- Escalonamento 30-60ms com um atraso decrescente (
base*√i); mantenha toda a sequência abaixo de ~300ms. - Cenas de rolagem: o progresso mapeia a partir da viagem medida da seção, então a mesma posição de rolagem sempre dá o mesmo quadro, rolar para cima reverte limpo, e links diretos para o meio funcionam.
- Gestos: um dono do progresso; a alça permanece presa ao ponteiro; a liberação entrega velocidade a uma mola; a interrupção no meio do voo deixa a UI operável.
- Anime apenas
transformeopacity. Sobprefers-reduced-motion, remova viagem, paralaxe, zoom e reprodução automática, mantenha fades curtos e ainda permita que gestos orientados pelo usuário funcionem. - Armadilhas de engenharia que quebraram construções reais (uma propriedade, um dono; linhas do tempo de rolagem pausadas; rótulos de snap dentro da linha do tempo; tempo de quadro não negativo; pré-carregamento de ativos trocáveis):
references/motion-engineering.md.
8. Verifique em um navegador real e, em seguida, entregue
Execute scripts/walk.py (Playwright + Chrome local) em desktop, celular e movimento reduzido: arrasto de ponteiro real, role por cada seção, erros de console, estouro lateral. Um painel de pré-visualização oculto ou minimizado limita os quadros de animação, então não julgue o movimento a partir dele. Detalhes: references/verification.md.
Em seguida, critique contra a história de trabalho, não o gosto:
- Atende à história de trabalho? A ação primária é a coisa mais proeminente e alcançável em todos os lugares?
- Todos os estados presentes (passo 5)? Teclado, rótulos de leitor de tela, contraste?
- Apenas tokens? Componentes existentes reutilizados?
- O texto segue o passo 6, incluindo rótulos de honestidade?
- Cada animação tem um trabalho, a direção de easing correta, um caminho de interrupção e um caminho de movimento reduzido?
- A marca registrada passa no teste de substituição? Há um pico, colocado em um final?
- O que eu cortaria? Remova um elemento ou efeito e veja se melhora.
Entregue com a fundamentação: o problema, a abordagem, alternativas rejeitadas e por que, o que foi exercitado e como (emulação vs. dispositivo real) e limitações conhecidas. Modelo:
references/process-and-teams.md Apêndice B.
Referências
| Leia | Quando |
|---|---|
references/motion-engineering.md | ao construir qualquer trabalho com GSAP/ScrollTrigger/Lenis, canvas, gesto ou cena de rolagem |
references/verification.md | antes de considerar qualquer trabalho visual ou interativo concluído |
references/imagery.md | ao gerar ou preparar imagens, recortes de produto, direção de arte |
references/animation.md | coreografia, os 7 princípios de movimento, matemática de escalonamento, tokens de movimento |
references/emotion.md | persona de design, integração, encanto, confiança e medo, texto de interrupção |
references/design-systems.md | tokens, APIs de componente, governança, versionamento, documentação |
references/product-design.md | pesquisa, história primeiro, esboço, feedback, prototipação, teste |
references/design-thinking.md | um problema ambíguo que precisa de empatia/definir/idear/prototipar/testar |
references/design-engineering.md | escolher fidelidade de protótipo, handshake design↔código |
references/process-and-teams.md | sessões de crítica, modelos de fundamentação e entrega, DesignOps |