Protonicwave/web-ui-craft

Web UI craft

UI genérica não é um estilo. É o que preenche toda decisão que ninguém tomou: o modelo, o template ou o framework fornece sua resposta mais comum, e o resultado poderia pertencer a qualquer produto. Os sites de melhor aparência (Linear, Vercel, Stripe, Family, os vencedores do Awwwards) deixam quase nada para o padrão. Eles computam um pequeno sistema, comprometem-se com uma ideia e mantêm detalhes funcionais em padrões mensuráveis.

Portanto, o trabalho é tomar decisões, escrevê-las e rastrear cada uma até o assunto, o usuário ou a física da percepção. Siga as cinco etapas abaixo em ordem. Escale-as para a tarefa: um único botão recebe uma frase de resumo e uma crítica rápida; uma landing page recebe o tratamento completo.

1. Leia o assunto

Antes de qualquer escolha visual, estabeleça:

• Assunto: o que o produto, organização ou conteúdo realmente é, e o mundo ao qual pertence (sua indústria, materiais, vocabulário, artefatos).
• Público: quem chega, o que já sabe, em qual dispositivo provavelmente está.
• Trabalho principal: a única coisa que a página ou tela deve realizar. Todo o resto está subordinado a isso.
• Restrições existentes: ativos da marca, um sistema de design existente, tokens, biblioteca de componentes ou framework no repositório. Se tokens existirem, use-os e aplique esta skill dentro deles. Não imponha uma nova identidade a um produto estabelecido, a menos que solicitado.

Se o usuário forneceu pouca informação, deduza a partir do assunto e declare suas suposições no resumo, em vez de fazer uma lista de perguntas.

2. Escreva o resumo de design

Escreva um resumo compacto em sua resposta antes de escrever código. É o design, portanto deve ser específico o suficiente para que outra pessoa possa construir a mesma coisa a partir dele.

Direção:      uma estética nomeada e por que se encaixa neste assunto (uma ou duas linhas)
Assinatura:   a única ideia pela qual esta página será lembrada, a peça herói que a carrega e como
              essa peça será feita (ativos fornecidos, imagem gerada ou construída em código)
Paleta:       neutro (matizado para ...), um acento (papel), cores semânticas; valores OKLCH
Tipografia:   família e papel para cada (display, texto, mono se necessário) e o que cada uma
              compartilha com o assunto; como a fonte de display atua na composição; proporção de
              escala; tamanho do corpo
Layout:       duas ou três opções para a primeira tela, cada uma com um conceito de uma linha e um
              wireframe ASCII; a escolhida e por quê; grade, medida, densidade, ritmo de seção
Profundidade: como as superfícies se separam (passos de tom, linhas finas, sombras), de onde vem a
              luz e sobre o que incide
Movimento:    o nível (produto ou marca), o momento de assinatura e seu elemento principal, o que
              mais se move e por quanto tempo, e o que deliberadamente não se move
Imagens:      fotografia, ilustração, 3D, UI do produto ou apenas tipografia; direção de arte em
              uma linha
Cópia:        o título e a ação principal, escritos para este público; o nome da ação, mantido do
              botão à confirmação
Orçamento:    script compactado para toda a página e a parcela que a camada de espetáculo pode
              ocupar (365 KiB no total por padrão; 75 KiB para uma página sem espetáculo)

Regras para o resumo:

• Derive, não decore. Cada linha responde "por que isso, para este assunto?". Uma paleta retirada dos materiais do produto, uma tipografia de seu vernáculo, um herói que abre com a coisa mais característica de seu mundo.
• Uma assinatura, todo o resto quieto. Stripe tem sua onda gradiente, Apple seus closes de produto com rolagem, Family suas bandejas voadoras. Gaste a ousadia uma vez. A contenção ao redor é o que a faz ser lida.
• Contenção é uma direção válida. Um sistema calmo, liderado pela tipografia, monocromático com um acento é tão deliberado quanto um herói WebGL e geralmente a escolha certa para ferramentas e documentação.
• Quieto não é vazio. A contenção limita quantas ideias uma página tem, não o quão rica cada uma é. A assinatura deve recompensar um olhar prolongado: uma ilustração desenhada para este assunto, dados reais dispostos com cuidado, textura, tipografia em escala real de display. Assuntos de comida, cultura, consumo e marca geralmente precisam de imagens ou ilustrações para transmitir calor, portanto uma página apenas com tipografia para um deles precisa de uma razão declarada.
• A peça herói é onde o esforço vai. Sites aclamados quebram muitas regras e ainda assim parecem caros porque uma peça é feita com um padrão muito alto: uma tela de produto com dados críveis, um objeto iluminado, uma ilustração própria. Escolha e construa-a com references/artefacts.md. Uma caixa arredondada com barras cinzas não é uma foto de produto.
• Tipografia é parte da composição, não um veículo para ela. Em tamanho de display, a configuração é o design: escala contra o menor texto na página, peso, largura, caixa, onde as linhas quebram, contra o que o título se assenta. O título de 64 px da Linear sobre texto de interface de 12 px é uma grande parte de seu efeito.
• Compare layouts antes de escolher um. Esboce duas ou três primeiras telas genuinamente diferentes (não um layout com a imagem movida) e escolha pelo trabalho principal do assunto. O primeiro layout que vem à mente é geralmente o template.
• Afirmação, prova, ação. A maioria das páginas precisa de uma declaração clara, uma evidência real (visão do produto, número ao vivo, cliente, demonstração) e uma ação principal. A estrutura segue o conteúdo, não um template.
• Um nome por ação. O botão que diz "Publicar" produz uma confirmação que diz "Publicado", não "Salvo". O vocabulário da interface é como as pessoas encontram seu caminho.

Leia references/exemplars.md ao escolher uma direção ou assinatura, references/visual-system.md ao definir paleta, tipografia, layout e profundidade, e a seção de movimento de references/interaction.md ao escrever a linha de Movimento.

3. Desafie o resumo

Antes de construir, ataque-o:

• Teste de troca. O nome de um concorrente poderia substituir este sem que ninguém percebesse? Se sim, o resumo ainda não tomou suas decisões.
• Teste por escolha. Para cada linha, pergunte se ela poderia pertencer a qualquer produto. Se puder, deve ser um padrão deliberado e bem ajustado da folha de construção abaixo, ou deve mudar.
• Teste de convergência. Esboce em algumas linhas o resumo que você escreveria para um assunto vizinho: outra ferramenta na mesma categoria, outro criador no mesmo ofício. Toda linha que sai igual é um padrão, não uma decisão. Mude-a e diga no resumo o que mudou e por quê. Uma linha pode permanecer apenas quando decorre de um fato que os dois assuntos compartilham (ambos os produtos são hardware, ambos os públicos leem código); nomeie o fato.
• Verificação de marcas. Compare com references/slop-tells.md, incluindo os clusters de aparência geral. Não troque um padrão pelo próximo mais comum (Inter por Space Grotesk, roxo por verde-azulado). Substitua-o por uma escolha que tenha uma razão.

Revise o resumo, depois construa.

4. Construa

• Tokens primeiro. Escreva a paleta, escala tipográfica, espaçamento, raios, sombras e movimento como propriedades personalizadas CSS (ou o sistema de tokens do projeto) antes de qualquer componente. Os componentes usam apenas nomes de tokens, nunca valores brutos como bg-indigo-500 ou #6366f1.
• Estrutura depois. HTML semântico, links reais para navegação, cabeçalhos em ordem, depois estilo.
• Aplique a folha de construção abaixo e os detalhes em references/visual-system.md e references/interaction.md.
• Projete todos os estados. Hover, ativo, focus-visible, desabilitado, carregando, vazio, erro, sucesso, conteúdo longo e conteúdo curto. A UI gerada é mais fraca aqui, e as correções são mais baratas aqui.
• Mantenha o espetáculo barato e opcional. Efeitos pesados (WebGL, vídeo, desfoque grande) vivem em uma camada isolada dentro do orçamento do resumo, começam após a primeira pintura, têm um fallback estático e ficam atrás de prefers-reduced-motion: no-preference.

5. Critique e corte

Trate a primeira construção como um rascunho.

1. Execute o verificador estático, usando o próprio diretório da skill para o caminho do script. Ele precisa de Python 3.12 ou posterior e sem pacotes. Aponte-o para toda a pasta de código-fonte do front-end, não apenas para os arquivos que você alterou: as regras de foco e movimento reduzido procuram por um estilo global em qualquer lugar na varredura, portanto uma varredura parcial relata defeitos falsos.

   python <skill-dir>/scripts/check_slop.py <pasta de código-fonte do front-end>
   

   Corrija todo defeito (código de saída 1 significa que pelo menos um permanece). Para cada marca, mude-a ou diga em seu relatório por que ela permanece. O verificador lê apenas o texto-fonte, portanto um resultado limpo é necessário, não suficiente.

2. Renderize a página e olhe para ela com 1440 px e 375 px de largura, em ambos os esquemas de cores se houver dois. Use uma ferramenta de navegador se a sessão tiver uma. Caso contrário, a maioria das máquinas tem Chrome ou Edge headless; escreva capturas de tela e o perfil do navegador em uma pasta temporária, depois leia as imagens:

   chrome --headless=new --hide-scrollbars --user-data-dir=<temp>/profile --window-size=1440,2600 --virtual-time-budget=4000 --screenshot=<temp>/desktop.png <arquivo ou URL http>
   

   A captura de tela é uma viewport do tamanho dado, não a página inteira, portanto torne a janela alta o suficiente para conter o conteúdo que você precisa ver. O Chrome headless não criará uma janela mais estreita que cerca de 500 px, portanto uma captura de tela de 390 px é silenciosamente cortada de um layout mais largo. Uma peça que se reproduz é capturada em um ponto aleatório de seu loop: adicione --force-prefers-reduced-motion para o quadro finalizado e tire mais uma captura de tela sem ele para ver um quadro no meio do loop. Para a verificação no celular, capture uma pequena página wrapper que segure o site em um <iframe> de 375 px de largura. Elementos revelados na rolagem podem não aparecer em capturas de tela headless; verifique no código-fonte se seu estado inicial oculto é aplicado por script (veja references/interaction.md). Com uma ferramenta de navegador real, também tabule através de cada fluxo.

3. Meça a página em vez de estimá-la. Sirva-a via HTTP (para uma pasta estática, python -m http.server nessa pasta), execute o Lighthouse em seu perfil móvel padrão, depois leia o relatório com o leitor de orçamento:

   npx [email protected] <URL http> --output=json --output-path=<temp>/report.json --quiet --chrome-flags="--headless=new --user-data-dir=<temp>/lh-profile"
   python <skill-dir>/scripts/check_budgets.py <temp>/report.json --script-kib <orçamento do resumo>
   

   Ele verifica LCP (2,5 s), CLS (0,1), tempo total de bloqueio (200 ms, o substituto de laboratório para INP), peso do script contra o resumo e lista todas as animações não compostas por elemento. Corrija toda violação (código de saída 1). Código de saída 2 significa que um valor está não medido ou o relatório é inutilizável: execute novamente e, se ainda falhar, relate o valor como não medido, nunca como aprovado. http.server não compacta, portanto o peso do script é lido alto, o que erra pelo lado seguro. Defina CHROME_PATH se o Lighthouse não conseguir encontrar o Chrome. Se o Node ou a rede não estiverem disponíveis, diga isso no relatório. O Lighthouse não mede a taxa de quadros do momento de assinatura: grave um trace de desempenho com uma ferramenta de navegador se a sessão tiver uma e, caso contrário, diga que não foi medido.

4. Pergunte se a primeira tela dá ao olho algo que vale a pena olhar e execute a lista de verificação de fidelidade em references/artefacts.md na peça herói. Uma página que está correta, mas esquecível, tem uma assinatura tímida: fortaleça a assinatura em vez de adicionar mais elementos.

5. Compare a página com uma referência. Escolha um site aclamado na direção escolhida, um que um designer na área do assunto admiraria (references/exemplars.md nomeia alguns), capture a tela inicial com 1440 px usando o comando no item 2 e olhe para as duas imagens lado a lado. Compare a fidelidade da peça herói, a extensão entre o maior tipo e o menor detalhe, quanto detalhe crível existe e a luz. Nomeie a maior lacuna e feche-a, ou diga no relatório por que ela permanece. A referência define o padrão para o acabamento, não a aparência: não tire nada de sua superfície. Se o site não puder ser acessado, diga isso no relatório.

6. Percorra a lista de verificação em references/interaction.md (estados, foco, alvos, formulários, desempenho).

7. Re-execute a verificação de marcas em references/slop-tells.md contra a página construída, não o resumo. Ela cobre marcas estruturais que o verificador não pode ver, como o herói de selo centralizado, três cartas idênticas e os clusters de aparência geral.

8. Remova qualquer coisa que não sirva ao assunto ou ao usuário: divisores decorativos, rótulos acima de conteúdo autoexplicativo, selos, brilhos, ícones que repetem seu texto, uma segunda cor de acento. Deletar é geralmente a maior melhoria disponível.

9. Relate o resumo, o que a crítica mudou, a maior lacuna em relação à referência, os valores medidos contra seus orçamentos e qualquer coisa que você não pôde verificar (por exemplo, contraste renderizado sem um navegador).

Folha de construção

Valores iniciais bem fundamentados. Eles protegem boas decisões; eles não substituem as decisões de identidade no resumo.

Dimensão	Padrão
Texto do corpo	16 a 20 px, altura da linha cerca de 1,5, medida 45 a 90 caracteres (mire em cerca de 65)
Cabeçalhos	Altura da linha 1,0 a 1,2, tracking cerca de -0,02em a partir de 24 px, text-wrap: balance
Parágrafos	text-wrap: pretty; negrito e itálico nunca juntos
Escala tipográfica	Fluida via clamp(), proporção cerca de 1,2 em telas pequenas a 1,25 em telas grandes
Maiúsculas	Raro, abaixo de uma linha, espaçamento entre letras 0,05em a 0,12em
Cor	OKLCH; uma escala neutra matizada, um acento, três ou quatro cores semânticas, cada uma com etapas baseadas em papel
Contraste	WCAG 4,5:1 corpo, 3:1 texto grande e partes da UI; mire em APCA Lc 75 ou mais no texto do corpo
Modo escuro	Uma paleta separada: base cinza escuro (cerca de oklch(0.18 0.01 h)), superfícies mais claras para elevação, acento dessaturado
Gradientes	Interpolar in oklch; matizes adjacentes; granulação fina opcional; no máximo um gradiente deliberado
Espaçamento	Base 4 px: 4, 8, 12, 16, 24, 32, 48, 64, 96, 128; lacuna entre grupos pelo menos o dobro da lacuna dentro
Profundidade	Passos de tom e bordas finas primeiro; sombras em camadas, uma fonte de luz, matizadas com o matiz da superfície
Raios	Dois ou três valores; raio aninhado = raio externo menos padding
Ícones	Uma família, uma grade, um traço...