Crie um site com um agente de inteligência artificial: Claude Code e Refero

Materiais práticos sobre trabalhar com projetos e modelos: documentação da Ailoot.

Porque é que os sites do Claude Code parecem modelos Tailwind?#

No exemplo de janeiro descrito, estava a ser criado um pequeno projeto paralelo: um discador para vendas a frio. Num repositório vazio, pediu-se ao Claude Code que criasse a página inicial. O resultado foi genérico: fundo escuro slate-950, destaque purple-500, título em negrito com tipo de letra sem serifa e três cartões por baixo com sombras idênticas. A mesma disposição da primeira versão do ChatGPT, da primeira versão do Lovable e da primeira versão do v0. Após cinco alterações ao pedido, acrescentando «moderno», «premium» e «diferente de todos os outros» — nada mudou. A página continuava a parecer saída de um conjunto de Tailwind UI Templates.

Ou seja, Claude não «desconhece» como criar algo bonito. Sabe o que a maioria faz e reproduz essa maioria. Para obter um resultado que não seja uma média, o agente precisa de restrições específicas: que cores usar, que tipos de letra, que espaçamentos e que componentes considerar canónicos.

É aqui que entra um sistema de design como contexto. Não «torna isto bonito», mas «faz isto neste estilo específico; aqui estão os parâmetros».

O Refero Styles preenche essa lacuna com um artefacto pronto a usar: um ficheiro DESIGN.md com parâmetros de produtos reais.

O que é o Refero Styles?#

A página inicial de styles.refero.design é clara: «descubra mais de 2 000 sistemas de design de sites de produtos de referência, legíveis por agentes de IA». O catálogo inclui marcas que definem o padrão visual: Apple, Linear, Stripe, Notion, Vercel, ElevenLabs, Mercury, PostHog, xAI, Modal, Duolingo. Os sistemas não são extraídos manualmente: a equipa Refero executa um script que analisa o CSS e a marcação reais de um site e reúne o resultado num ficheiro Markdown estruturado. A própria biblioteca styles.refero.design é gratuita.

A palavra-chave é «estruturados». O ficheiro não contém capturas de ecrã nem descrições como «num estilo minimalista». É Markdown com cores hexadecimais específicas, tamanhos exatos de letra em pt, unidades de espaçamento e regras para componentes. O agente de IA lê este ficheiro e trabalha com dados concretos, em vez de tentar descrever o gosto por palavras.

Na página ai-agents, a equipa Refero indica que as ferramentas suportadas são «Cursor, Claude Code, Codex, v0 e Lovable». Por outras palavras, o DESIGN.md funciona como um artefacto universal: um ficheiro adequado a todos os principais agentes de desenvolvimento com IA.

O que contém um DESIGN.md?#

A equipa Refero descreve a estrutura do ficheiro na página design-md-template da seguinte forma:

A estrutura do ficheiro é normalmente semelhante a esta:

Os criadores também destacam um princípio que resolve 80% dos problemas de design com IA:

O código hexadecimal #5E6AD2 é, portanto, mais eficaz do que «ao estilo do Linear». O valor exato font-size: 13px / line-height: 18px é mais eficaz do que «texto compacto». Os dados concretos superam a interpretação.

O ficheiro DESIGN.md no repositório não é uma imagem para a equipa. É um bloco de construção do contexto permanente do seu projeto: conhecimento estruturado que a IA lê em cada pedido.

Como criar um site ao estilo do Linear em 4 passos#

Estes quatro passos formam a sequência descrita para iniciar um novo site. Não são «quatro passos em geral», mas uma sequência específica com uma ação por passo.

1. Instale Claude Code

   Instalador nativo com um único comando: curl -fsSL https://claude.ai/install.sh | bash (o método recomendado na documentação oficial). No macOS, funciona brew install --cask claude-code; no Windows, winget install Anthropic.ClaudeCode. Se já estiver instalado, verifique a versão: claude --version (é necessária a versão 2.1.178+ — esta versão introduziu as permissões Tool(param:value) e o bloqueio de comandos git perigosos no modo automático). Inicie sessão na sua conta: claude abre o assistente de configuração. Claude Code está incluído numa subscrição Pro ($17/mês com faturação anual ou $20/mês com faturação mensal).

2. Abra o Refero Styles e escolha uma marca

   Aceda a https://styles.refero.design e abra o catálogo. O principal critério de seleção é a proximidade ao seu produto, não se «gosta do aspeto». Está a criar um painel SaaS? Veja Linear, Vercel e Notion. Um produto fintech? Veja Stripe, Mercury e Column. Um produto para membros? Veja Duolingo. Abra o cartão de uma marca e clique em «Copy DESIGN.md».

3. Coloque o DESIGN.md no projeto como contexto

   Crie um ficheiro docs/DESIGN.md na raiz do projeto e cole o conteúdo copiado. Depois, abra CLAUDE.md e adicione uma linha: @docs/DESIGN.md. Trata-se de uma diretiva de importação: Claude Code carrega o conteúdo para o contexto quando uma sessão começa. Para saber mais sobre importações em CLAUDE.md, consulte o guia sobre um ficheiro de instruções para Claude Code, Codex e Cursor.

4. Peça uma página específica

   Não diga «torna isto bonito». Seja específico: «Usando o DESIGN.md no contexto, cria uma página inicial para um produto SaaS de gestão de tarefas. Estrutura: secção principal com título e subtítulo, dois botões CTA (primário e secundário), uma secção abaixo com 3 funcionalidades e ícones e, depois, uma secção de testemunhos. Usa exatamente as cores e a tipografia do DESIGN.md; não inventes as tuas.»

Depois do quarto passo, Claude cria a página. Na experiência descrita, uma página inicial demora em média 8–12 minutos — e fica mesmo próxima do estilo da marca escolhida. Não é uma cópia perfeita ao píxel, mas tem uma estética reconhecível: os mesmos tipos de letra, a mesma paleta, o mesmo ritmo de espaçamento e as mesmas pequenas decisões nos botões.

Os criadores do Refero descrevem o mesmo princípio de três passos de forma um pouco mais breve na página ai-agents/design-resources:

Esta sequência de quatro passos segue a mesma lógica, com a adição explícita da instalação de Claude Code e da importação do ficheiro para CLAUDE.md.

Que estilo deve escolher para o seu produto?#

Os criadores do Refero dão este conselho logo no primeiro passo do guia: escolha uma referência não só pelo nome da marca, mas também pela densidade, pelo tom e pelo público.

Na prática, cores, tipografia, hierarquia e movimento discreto inspirados na Apple podem servir um painel SaaS, enquanto o espaço generoso de uma página de marketing específica pode não servir. Examine a referência concreta em vez de escolher só a marca. Num painel de contabilidade, defina alturas de linhas, espaçamento e densidade compactos, mantendo números e controlos legíveis; não copie uma apresentação espaçosa sem adaptação.

Um guia simples para escolher por tipo de produto:

Se ainda tiver dúvidas, escolha Linear. Tem uma base muito versátil: paleta neutra, tipografia legível (Inter / Söhne) e espaçamento discreto. Um site baseado no Linear terá um aspeto profissional em 9 de cada 10 tipos de produto.

Porque incluir o DESIGN.md no contexto permanente do seu projeto?#

Na prática descrita, DESIGN.md é guardado ao lado de CLAUDE.md em todos os projetos geridos com agentes de IA. Este ficheiro não é considerado «temporário para uma tarefa». É um cânone permanente em que todas as sessões futuras se baseiam. Daqui a um mês, pode pedir a Claude que adicione uma nova página ao projeto — abrirá o mesmo DESIGN.md e criá-la-á no mesmo estilo. Daqui a seis meses, pode entregar o projeto a outro membro da equipa — também poderá executar Claude e obter um resultado coerente, porque DESIGN.md está no repositório.

No design, o princípio funciona assim: toma-se uma decisão uma vez — paleta, tipografia e ritmo de espaçamento. Depois, todos os agentes de IA a consideram definida.

Ou seja, o design vive como código (Markdown é código), e não num ficheiro Figma que a IA não consegue ler. Quando o design está num ficheiro no repositório, Claude Code lê-o, Codex lê-o e qualquer ferramenta futura também o poderá ler. Quando está no Figma, fica num plano separado e tem de ser convertido manualmente em cada sessão.

Nos projetos paralelos descritos, foi utilizada esta estrutura:

project/
├── CLAUDE.md            (imports @docs/DESIGN.md)
├── docs/
│   ├── DESIGN.md        (visual canon, copied from Refero)
│   ├── ARCHITECTURE.md  (project structure)
│   └── BRAND.md         (tone of voice, vocabulary)
└── ...

Estes três ficheiros são uma forma de organizar o contexto permanente do projeto. DESIGN.md trata dos elementos visuais, ARCHITECTURE.md da estrutura e BRAND.md da voz. Qualquer agente de IA com acesso ao repositório recebe os três como contexto.

O que são o Refero MCP e o refero_skill?#

Refero Styles é a camada de base (DESIGN.md como ficheiro). A próxima vaga consiste em integrações que tornam o acesso à biblioteca «nativo» para agentes de IA.

Refero MCP (oficial). É uma API de servidor em https://api.refero.design/mcp à qual Claude Code se liga através de um bearer token. O agente passa então a ter acesso a mais de 150 000 ecrãs e 6 000 fluxos de utilizador de produtos reais. Pode instalá-lo com uma skill:

npx skills add https://github.com/referodesign/refero_skill --skill refero-design

Após a instalação, Claude inicia uma «pesquisa de design» no início de cada sessão como primeiro passo obrigatório: analisa que opções visuais se adequam à tarefa e, se necessário, propõe três direções associadas à referência selecionada. Em 23 de junho de 2026, o repositório refero_skill tinha 67 commits e 135 estrelas. Um novo produto em desenvolvimento ativo.

A prática descrita segue uma abordagem simples: abrir o site manualmente, copiar DESIGN.md e colocá-lo num ficheiro. O MCP é útil quando o trabalho com sistemas de design passa a ser rotineiro — por exemplo, quando gere vários projetos de clientes e muda de cânone visual todos os dias. Para saber mais sobre a ligação de servidores MCP ao Claude Code, consulte o guia sobre NotebookLM e MCP.

Que 4 erros comprometem o processo?#

Estes quatro erros surgem na experiência descrita de trabalho com contexto de design. Cada um parece inofensivo, mas todos fazem o resultado regressar ao modelo Tailwind padrão.

Erro 1. O pedido «faz com que pareça moderno». É o padrão de erro mais comum. As pessoas abrem Claude Code e escrevem: «faz-me um site SaaS, estilo moderno, aspeto premium». Recebem um fundo escuro com um destaque roxo. Nos dados de treino, a palavra «moderno» está associada a todas as landing pages de 2022–2024 construídas a partir do mesmo modelo. Sem os parâmetros exatos de DESIGN.md, «moderno» significa «médio».

Erro 2. Colar DESIGN.md no chat como uma mensagem. Por vezes, as pessoas copiam DESIGN.md para a janela de chat do Claude Code e dizem: «aqui está o estilo, usa-o». Funciona uma vez — até ao fim da sessão. Abra uma nova sessão (ou passe a outra tarefa, /clear) e o contexto perde-se. Para que o estilo persista, o ficheiro tem de estar no repositório e ser importado em CLAUDE.md. Para saber mais sobre a razão pela qual CLAUDE.md é o ponto de contexto permanente, consulte o guia sobre a memória do Claude.

Erro 3. Escolher um estilo porque «gosta dele». Uma referência espaçosa de marketing Apple pode ser má para copiar sem alterações num painel imobiliário com 30 anúncios no ecrã. Isso não exclui tipografia, paleta ou hierarquia inspiradas na Apple: adapte espaçamento e densidade à tarefa e verifique a informação visível no tamanho de ecrã pretendido. Escolha a referência concreta pela densidade, tom e público, não só pela marca.

Erro 4. Não mencionar DESIGN.md no próprio pedido. DESIGN.md pode estar no repositório, importado através de CLAUDE.md e visível para o agente. Mas, se o pedido disser «cria um site», Claude poderá seguir o caminho habitual sem se referir explicitamente ao ficheiro. Para cada pedido de design, esta frase é útil: «Usa exatamente as cores, os tipos de letra e os espaçamentos de docs/DESIGN.md. Não inventes valores; vai buscá-los ao ficheiro.» Assim, o agente usa DESIGN.md em vez de o contornar.

Os tokens exatos são códigos hexadecimais, tamanhos de letra em pt e unidades de espaçamento em DESIGN.md. A linguagem natural significa «moderno», «premium», «limpo» ou «como a Apple». Os tokens exatos funcionam; as palavras livres não.

O que fazer a seguir?#

Já conhece o processo básico: Claude Code + DESIGN.md do Refero + 4 passos = um site sem modelos. Isto cobre 70% das necessidades. Os 30% restantes correspondem a situações em que precisa de mais precisão, rapidez ou verificação.

Depois de dominar o básico, pode avançar em três direções:

1. Frontend Design Skill. É uma skill oficial para Claude Code que acrescenta feedback visual. O agente captura um ecrã da página montada com Puppeteer, observa-o com os seus «olhos» (um modelo de visão), compara-o com DESIGN.md e propõe correções por si próprio. É um ciclo automatizado de «pedido → código → captura de ecrã → crítica → pedido». É útil quando a página é complexa e não consegue acertar à primeira.

2. Refero MCP em modo de produção. Quando gere 3–5 projetos em paralelo, adicionar manualmente DESIGN.md a cada um torna-se cansativo. O Refero MCP consegue encontrar 3 estilos adequados com base na descrição de um projeto e permite escolher. Reduz o tempo de início de um novo projeto de 30 minutos para 3.

3. Combinação com Context Engineering. DESIGN.md é um dos artefactos de contexto. Junto dele, encontrará normalmente ARCHITECTURE.md (estrutura do projeto), BRAND.md (tom de voz) e business/audience.md (público-alvo). Todos são importados em CLAUDE.md. Quando Claude cria uma página, baseia-se nos elementos visuais, no público e na estrutura do produto. Essencialmente, isto é Context Engineering: trabalhar sistematicamente naquilo que fornece ao agente antes de um pedido.

Materiais práticos: documentação da Ailoot.

Materiais práticos: Ailoot.

Mais materiais e ferramentas: Ailoot.