design-brief

Brief de design

Deixado sozinho, um agente de codificação projeta de memória, e a memória entrega a média de tudo: o herói centralizado, o gradiente roxo, três cards com um ícone cada. Produtos reais já resolveram todas as telas que você está prestes a construir, e componentes prontos já existem e são melhores do que qualquer improviso em uma única sessão. Portanto, trate seus próprios instintos de design como medianos e pare de inventar. O trabalho é encontrar, comparar, escolher e adaptar.

Duas fontes fazem o trabalho, e cada uma faz um trabalho diferente:

Fonte	O que fornece	Use para
Refero	Telas, fluxos e estilos de produtos reais lançados	Decidir como uma tela deve se comportar e parecer
21st.dev	Componentes finalizados, feitos por pessoas e avaliados pela comunidade	O componente real que vai para o código

A Refero diz o que construir; a 21st.dev entrega a peça. Use ambas. Um componente escolhido sem uma referência frequentemente é bonito, mas errado para a tela; e uma referência sem um componente acaba sendo reconstruída manualmente, de forma ruim.

Configuração

# Refero (um servidor MCP). Em seguida, execute /mcp e faça login.
claude mcp add --transport http refero https://api.refero.design/mcp

# CLI da 21st.dev
npx @21st-dev/cli login     # abre o navegador; depois disso o comando é `21st`
21st whoami                 # verifique se você está logado

Pesquisas e prévias são gratuitas na 21st.dev. Puxar o código de um componente usa uma cota diária (21st usage mostra o que resta), então compare primeiro e puxe apenas o que você escolheu.

Se uma ferramenta estiver faltando ou desconectada, avise o usuário uma vez, com o comando que a corrige, e continue com a que funciona. Não caia silenciosamente em uma UI construída manualmente.

Ordem de trabalho

1. Defina a direção: cores e tipografia.
2. Encontre o padrão para cada tela e fluxo na Refero.
3. Escolha o componente para cada seção da 21st.dev.
4. Adapte tudo a um único conjunto de tokens.
5. Verifique o resultado contra o padrão de qualidade, no aplicativo em execução.

Para qualquer coisa maior que um componente, escreva o plano de UI antes de codificar (modelo no final). É uma pequena tabela, e é o que impede que uma tela seja improvisada no meio da construção.

1. Direção

• Cores e tipografia vêm do que o usuário já possui: seu DESIGN.md, seu sistema de design existente ou uma referência que ele nomeie. Não o substitua.
• Se ele não deu nada, baseie a direção em estilos da Refero de produtos de primeira linha: refero_search_styles, depois refero_get_style nos dois ou três mais fortes. Não use o tema padrão do framework ou a paleta da marca da plataforma em que você está construindo. É assim que todo projeto naquela plataforma acaba parecendo igual.
• Escolha um estilo dominante e mantenha suas características marcantes. Pegue emprestado um ou dois detalhes dos outros. Fazer a média de várias referências dá o meio termo seguro que você estava tentando evitar.
• Suporte claro e escuro.
• Entregue um design. Não entregue ao usuário três conjuntos de opções para escolher, a menos que ele peça opções; escolher é o trabalho que ele lhe deu.
• Escreva o resultado como tokens (papéis de cores, escala tipográfica, espaçamento, raio, sombras) antes de instalar qualquer componente, para que cada escolha posterior seja resolvida em um token.

2. Padrões da Refero

Ferramenta	Responde	Exemplo de consulta
refero_search_styles, depois refero_get_style	Como deve ser a aparência e a sensação?	site fintech premium com tipografia contida
refero_search_screens, depois refero_get_screen	O que vai nesta tela, e em quais estados?	estado vazio de dashboard, filtros de tabela de dados
refero_search_flows, depois refero_get_flow	Quais são as etapas desta jornada?	onboarding de cadastro, cancelamento de assinatura

Pesquisas de telas e fluxos precisam de uma platform: web ou ios.

• Pesquise pelo que está literalmente na tela ("alternância anual mensal de página de preços"), não por adjetivos. Adjetivos pertencem a uma pesquisa de estilos.
• Tente três a cinco ângulos por tela, incluindo um produto conhecido que faça bem aquilo. O primeiro resultado raramente é o melhor.
• Consulte também os estados, não apenas a tela feliz: vazio, carregando, erro, sucesso.
• Quando uma tela estiver próxima, refero_get_similar_screens encontra rapidamente suas parentes.
• Mantenha duas ou três referências por tela e anote o que você tira de cada uma: estrutura, hierarquia, estados, redação. As referências informam a tela. Elas não são um modelo a ser copiado.

3. Componentes da 21st.dev

21st.dev é um catálogo selecionado de componentes finalizados, não geração de IA. Para cada peça de UI (cabeçalho, entradas, cards, dropdowns, chat, estados de carregamento, animações), pesquise, compare e use o melhor.

21st search "<componente>" --type c --limit 10     # apenas componentes
21st get <id>                                     # exibe o código e a demonstração do escolhido
21st add <autor>/<slug>                           # instala (usa shadcn internamente)
npx shadcn@latest add "https://21st.dev/r/<autor>/<slug>"   # mesma instalação com shadcn padrão
21st logo <marca>                                 # logotipos reais de marca como SVG, grátis

Como escolher:

1. Pesquise pelo slot, não pelo clima. "Tabela de preços", "menu de comandos", "upload de arquivo", não "seção moderna limpa". Tente duas ou três formulações.
2. Compare vários, e nunca pegue o primeiro resultado. Abra as prévias. Um nome e uma descrição não dizem como um componente se parece ou se move.
3. Prefira o mais baixado ou favoritado. As contagens estão na página de cada componente na 21st.dev. Popularidade é evidência de que um componente funciona em projetos reais. Não prova adequação, que é a próxima verificação.
4. Verifique a adequação à referência da Refero para aquela tela. Ele deve fazer o mesmo trabalho na densidade certa e ter os estados que você precisa (hover, foco, desabilitado, carregando, vazio). Verifique se ele se sustenta na largura do celular e com o teclado, e analise as dependências que ele traz.
5. Adapte uma ou duas coisas para seus tokens: cor, raio, fonte. Se você perceber que está reescrevendo o componente, escolheu o errado. Volte e escolha de novo.
6. Mantenha os irmãos coerentes. Componentes de autores diferentes devem parecer um único produto depois de serem reestilizados.
7. Construa manualmente apenas a cola que não tem candidato, e diga isso.

Relate cada escolha para que o usuário possa trocá-la: seção · componente · autor · motivo em uma linha.

4. Padrão de qualidade

• Logotipos reais, não ícones genéricos e pontos coloridos.
• Pouco texto. Sem paredes de cópia; deixe a interface carregar o conteúdo.
• Padrões de UI reais: abas, dropdowns, modais, alternâncias, gráficos. Nem tudo é uma pilha de cards.
• Bons estados de carregamento, vazio e erro, com progresso para ações lentas.
• Movimento, e som e háptica quando apropriados.
• Tudo encontrável: toda página acessível de onde as pessoas já estão, e tudo que é clicável parece clicável.
• Onboarding de baixo atrito.
• Fluxos permanecem dentro do aplicativo em vez de enviar as pessoas para sites de terceiros.
• Responsivo, e o mobile parece nativo em vez de um desktop encolhido.
• Uma reclamação é um padrão. Quando o usuário sinalizar uma coisa, encontre e corrija suas irmãs em todo o aplicativo.

Medíocre nunca é uma opção.

5. Verifique no aplicativo em execução

Abra o aplicativo no navegador ou simulador e use-o: claro e escuro, desktop e largura de celular, os estados vazio e de carregamento. Compare cada tela com suas referências e corrija os desvios. A pesquisa não é a linha de chegada; a tela renderizada é.

Modelo de plano de UI

**Direção:** <o DESIGN.md do usuário, ou estilos da Refero: nome, nome> · claro e escuro
**Tokens:** <papéis de cores, fontes, raio, espaçamento>

| Tela ou fluxo | Referências da Refero | O que pegamos | Componente da 21st.dev |
|---|---|---|---|
| Onboarding | <app: tela>, <app: fluxo> | Três etapas, barra de progresso, pular | <autor>/<slug> |

**Construído manualmente (sem candidato):** <o que, e porquê>