moraneus/preview-first

O que preview-first faz?

Olhe antes de construir. Esta skill insere uma etapa de design antes de qualquer código de aplicação ser escrito: o desenvolvedor vê várias direções de design completas e claramente diferentes em seu navegador, escolhe uma, e a escolha se torna um contrato escrito que toda sessão posterior segue.

Este é um estúdio de design, não um gerador de sites. A skill nunca escreve o código da aplicação do desenvolvedor. Ela produz uma decisão e um contrato. Os scripts são determinísticos e usam apenas a biblioteca padrão do Python; o julgamento (ler o briefing, nomear as direções, escrever o texto) é seu.

Quando executar, quando oferecer

Execute o estágio completo quando o desenvolvedor estiver prestes a iniciar, reiniciar ou reformular um projeto web: "construa uma landing page para X", "inicie o frontend", "não gosto de como isso está", "escolha cores e fontes", ou um /preview-first explícito.

Ofereça em uma linha quando um projeto já tem código de UI, mas não possui design/DESIGN.md: "Quer ver direções de design primeiro? Posso mostrar a aparência atual ao lado de alternativas." Se aceito, importe a aparência existente como uma direção (veja Importações) para que seja comparada em termos iguais.

Nunca acione para pequenas edições em um aplicativo já estilizado ("adicione um botão", "corrija o padding"). Quando design/DESIGN.md existir, pule para Após a entrega.

O fluxo

Todos os scripts residem no diretório scripts/ desta skill. Execute-os com python3 (ou uv run python3 onde o projeto usa uv). Os caminhos abaixo são relativos à raiz do projeto.

1. Leia o projeto, depois faça no máximo quatro perguntas

Leia o que existe antes de perguntar qualquer coisa: package.json, configuração Tailwind, propriedades CSS personalizadas, um logo SVG, fontes existentes, um README. Tudo encontrado é uma restrição, não uma pergunta.

Pergunte apenas o que o repositório não pode responder, em linguagem simples, em uma única mensagem:

1. Qual é o produto e para quem é, em uma frase.
2. Três palavras para como deve parecer, ou um site que admiram.
3. Algo fixo: uma cor de marca, um logotipo, uma fonte, apenas claro ou escuro.
4. Qual tipo de página é mais importante: marketing, aplicativo, conteúdo ou loja.

2. Escreva o briefing

Normalize as respostas em .design-preview/brief.json:

{
  "product": "Ledgerline, uma ferramenta de faturamento para desenvolvedores freelancers",
  "audience": "desenvolvedores solo e pequenos estúdios",
  "product_type": "product-type.saas",
  "moods": ["preciso", "calmo", "confiável"],
  "page_type": "marketing",
  "constraints": {"brand_colors": ["#154d8c"], "fonts": [], "scheme": "both"},
  "admired": ["https://linear.app"],
  "words": {"name": "Ledgerline", "tagline": "Faturas que combinam com seu git log"}
}

Mapeie texto livre para IDs de nós com recommend.py --list product-types e --list moods. Palavras desconhecidas são aceitáveis; o recomendador faz fallback por alias e sobreposição de tokens. Texto livre em product_type também é aceito.

3. Escreva o texto, depois abra a pré-visualização em menos de um minuto

Escreva .design-preview/copy.json primeiro; leva uma resposta curta e é o que faz um rascunho ler como o produto em vez de um template. Use os próprios substantivos do produto: a navegação são suas seções, os recursos são as coisas que ele faz, o título é uma afirmação que um usuário repetiria.

{
  "headline": "Placar ao vivo para 501, Críquete e Volta ao Mundo",
  "subhead": "Oche mantém a pontuação para que os jogadores possam continuar jogando.",
  "lead": "Feito para jogadores de liga de pub e amigos em casa.",
  "cta_primary": "Novo jogo", "cta_secondary": "Continuar",
  "nav": ["Jogos", "Jogadores", "Estatísticas", "Configurações"],
  "features": [{"title": "501 e 301 com fechamentos", "body": "Cada pontuação restante mostra a rota de fechamento padrão."}],
  "proof": "", "meta": {"city": "Leeds", "year": "2026"},
  "footer": "Oche mantém a pontuação."
}

Então um comando:

python3 <skill>/scripts/quick_start.py --brief .design-preview/brief.json --copy .design-preview/copy.json --count 5 --open

Ele recomenda pacotes, cria directions.json, constrói a pré-visualização e inicia o servidor. Forneça a URL ao desenvolvedor imediatamente. Se você pular --copy, os rascunhos usarão texto derivado dos próprios substantivos do briefing; nunca deixe isso em uma direção que você apresenta como finalizada. Refine directions.json (nomes, justificativa, layout, programa) enquanto eles olham, e reconstrua; a página atualiza para a mesma URL.

Cada página de pré-visualização carrega três geradores em sua barra, para que o desenvolvedor nunca precise voltar para obter mais: Surpreenda-me (uma direção composta aleatoriamente: um estilo não utilizado, uma paleta e combinação adequadas, um sorteio aleatório de ideias, seções e programa), Variações (cinco versões da direção que estão vendo: mesmo estilo, outras paletas, combinações, ideias e programas) e, na galeria, Mostrar todos os estilos (uma direção por estilo para este briefing). Cada um leva ao novo rascunho, que carrega os mesmos botões. Do terminal: random_direction.py --directions .design-preview/directions.json --build .design-preview [--like B | --all].

3a. Pacotes candidatos manualmente

python3 <skill>/scripts/recommend.py --brief .design-preview/brief.json --count 4

Cada pacote é um estilo, paleta, combinação tipográfica, tratamentos de componentes, padrões de movimento, conjunto de ícones e oito a doze ideias de design (ideas: movimentos originados como uma navegação dividida com hora ao vivo, um herói de espécime, numerais gigantes, granulado de filme, botões de colchete, um rodapé de colofão), com as arestas do grafo que o justificaram e alternativas dinâmicas para troca. Diversidade é garantida: famílias de estilos distintas, no máximo duas paletas de uma temperatura, no máximo duas combinações de uma categoria tipográfica, nenhuma paleta ou combinação usada duas vezes. Três a cinco pacotes por padrão, até oito quando o desenvolvedor pedir para ver mais. Não fique abaixo de três; se o briefing for estreito (apenas escuro, uma cor de marca), diga isso e ainda mostre três.

4. Crie directions.json

Transforme pacotes em .design-preview/directions.json (esquema em knowledge/schema.json, files.directions). Para cada direção, forneça o que um script não pode:

• name: uma ideia, não um estilo ("Ledger", "Greenhouse", "Night shift"). Nunca "Moderno" ou "Limpo".
• rationale: um parágrafo que cita as próprias palavras do briefing e diz por que esta direção as responde. Mencione a única escolha ousada e o que permanece discreto.
• copy: texto real do briefing: título, subtítulo, duas chamadas para ação, quatro rótulos de navegação, três a seis recursos com um título e uma frase cada, uma linha de prova honesta (ou vazia), um título de formulário com rótulos de campo e texto de envio, uma linha de rodapé. Frase em letra minúscula, voz ativa, substantivos do produto, sem travessões, sem emojis, sem setas, sem "Seja você X ou Y", sem tricólons, sem lorem ipsum, sem números inventados. O texto é o mesmo em todas as direções, a menos que a voz de uma direção realmente difira.
• layout (opcional): substitua variantes de seção; caso contrário, as ideias da direção e depois os padrões do estilo as escolhem.
• bundle.ideas (manter ou editar): as ideias que o recomendador anexou. Remova uma que não se encaixe no produto, adicione uma de recommend.py --list ideas quando o briefing ou um site admirado pedir. Ideias com um gancho de renderização alteram o rascunho; o resto vai para o contrato.
• copy.numbers e copy.stats (opcional): figuras originadas {value, label, source}; o herói de números e a parede de estatísticas renderizam apenas quando estes existem, nunca com figuras inventadas.
• copy.meta (opcional): {"city": "Lisbon"} para a navegação dividida, colofão e relógio sobreposto.
• O tipo de produto carrega um kit de tópicos (tipos de arte, um componente de tópico como um terminal, um saldo, uma agenda, um compositor, um placar e os substantivos do produto). A primeira tela e a seção seguinte o usam, então um placar abre em uma pontuação e uma loja em produtos. Defina layout.topic como none para remover o componente de tópico.
• overrides (opcional): {"brand_primary": "#hex", "brand_accent": "#hex"} quando o briefing fixa uma cor de marca. O construtor recalcula as cores de realce e relata qualquer falha de contraste.

Antes de construir, execute a verificação anti-clichê em references/anti-patterns.md em cada direção. Recuse um clichê a menos que o briefing o tenha solicitado pelo nome, e nesse caso, diga isso na justificativa.

A regra da primeira tela: nenhuma direção abre com o template genérico (título centralizado, dois botões, uma captura de tela, depois três cartões idênticos). Cada estilo padroniza para um arquétipo de layout observado em sites admirados (parágrafo de declaração com figuras legendadas, tipo envolvendo um disco plano, palco primeiro do produto, face de exibição ao lado de um objeto, arte em sangria total, índice lateral, tipo pôster) e para arte gerada a partir da paleta (planta baixa, figuras isométricas, terminal, composição suíça, contornos, meio-tom, anéis de órbita, adesivos, sparklines, uma única marca). Mantenha esses padrões a menos que o briefing peça a aparência familiar pelo nome. Pelo menos duas das direções vêm de estilos marcados como distinct; o recomendador garante isso, e também garante que nenhuma direção compartilhe um dispositivo de navegação, um dispositivo de primeira tela ou uma textura.

5. Construa e abra a pré-visualização

python3 <skill>/scripts/build_preview.py --directions .design-preview/directions.json
python3 <skill>/scripts/serve_preview.py --dir .design-preview --open

build_preview.py escreve .design-preview/: uma galeria, e para cada direção um azulejo de estilo (paleta com notas de contraste em ambos os modos, escala tipográfica, espaçamento, raio, elevação, ícones, cada componente em cada estado, padrões de movimento reproduzíveis), uma página rascunhada para o tipo de página do briefing e uma visualização de dispositivos que renderiza o rascunho dentro de molduras CSS dos telefones, dobráveis, tablets e notebooks mais populares em tamanhos de viewport reais. Controles em cada página trocam paleta, combinação tipográfica, raio, densidade, nível de movimento e tema dinamicamente.

serve_preview.py inicia um servidor localhost destacado, escreve .design-preview/server.json, imprime a URL e retorna imediatamente. Adicione --vendor-fonts à construção para uma sessão offline; caso contrário, o azulejo mostra um aviso visível quando uma fonte da web falhou ao carregar.

Se o navegador não puder abrir (SSH, contêiner, CI), imprima a URL e a lista de direções com uma linha cada, e continue no chat.

6. Informe o desenvolvedor, depois aguarde

Diga o que você construiu, forneça a URL, nomeie as direções em uma linha cada e pare. Não escolha por eles, não comece a codificar, não faça polling. O desenvolvedor pode passar muito tempo na pré-visualização. Quando eles responderem:

• Se .design-preview/selection.json existir, leia-o. Ele contém o ID da direção e as substituições dinâmicas (paleta, combinação, raio, densidade, movimento, tema) em que pararam.
• Caso contrário, pegue a escolha de suas palavras ("B", "a escura", "A mas com o tipo de D") e escreva selection.json você mesmo com as substituições correspondentes.
• Para uma mutação ("B mas mais quente", "menos cantos arredondados", "troque a fonte do título"), edite directions.json (ou use uma alternativa do pacote), reconstrua e aponte-os de volta para a mesma URL. O servidor continua rodando; peça para eles atualizarem a página.
• Para "mostre-me mais", execute recommend.py novamente com --count 5 ou um briefing alterado, adicione as novas direções sob novos IDs e reconstrua.

serve_preview.py --dir .design-preview --wait 1800 bloqueia até que uma seleção exista, apenas para uso em script. --status e --stop gerenciam o servidor.

7. Exporte o contrato

python3 <skill>/scripts/export_design.py --selection .design-preview/selection.json \
  --directions .design-preview/directions.json --project .

Isso escreve design/DESIGN.md (o contrato: identidade, ideias de design com fontes e notas de construção, paleta com tabela de contraste, tipografia, espaçamento e raio, elevação, layout, cada componente com estados e tokens, tokens de movimento e padrões permitidos, iconografia, imagens, estilo de escrita, piso de acessibilidade, verificações de dispositivos e uma lista de "não fazer"), design/tokens.json (formato W3C Design Tokens), design/tokens.css, design/tailwind.css quando Tailwind v4 for detectado, uma linha de ponteiro em CLAUDE.md e uma entrada .gitignore para .design-preview/. Reexportar mantém a seção "Notas do projeto" e copia os arquivos anteriores para design/history/.

Confirme em uma mensagem curta o que foi escrito e o que o desenvolvedor deve commitar (design/ e a linha do CLAUDE.md). Então construa sob o contrato.

Após a entrega

Sempre que design/DESIGN.md existir:

• Leia-o antes de qualquer alteração de UI. Use tokens --pf-* de design/tokens.css, nunca valores brutos de hex, pixel ou milissegundos em componentes.
• Mantenha-se nos padrões de movimento permitidos e no nível de movimento. Respeite movimento reduzido.
• Execute contrast.py FG BG --role body|label|large|ui em cada novo par de cores.
• Siga a lista de "não fazer"; quando uma solicitação conflitar com o contrato, diga isso e ofereça-se para reexecutar o estágio em vez de divergir silenciosamente.
• Após uma página significativa ser construída, ofereça a verificação de dispositivo: abra .design-preview/<id>/devices.html?url=http://localhost:PORT/path para ver a página real nas mesmas molduras. Páginas que enviam cabeçalhos de bloqueio de quadro não podem ser exibidas; diga isso.
• Mantenha as seções livres de design/DESIGN.md (abaixo do marcador de fim) para decisões do projeto.

Importações

Para comparar a aparência atual do projeto, ou um site que o desenvolvedor admira, como uma direção:

python3 <skill>/scripts/import_direction.py --css src/styles.css --into .design-preview/directions.json --name "Atual"
python3 <skill>/scripts/import_direction.py --tailwind tailwind.config.js --into .design-preview/directions.json
python3 <skill>/scripts/import_direction.py --tokens design-tokens.json --into .design-preview/directions.json
python3 <skill>/scripts/import_direction.py --url https://example.com --into .design-preview/directions.json --name "Referência"

A importação deriva uma paleta, combinação e estilo mais próximo, depois reconstrói. Paletas importadas são verificadas como qualquer outra; falhas aparecem no azulejo.

Conhecimento e atualização

As decisões vêm de knowledge/graph.json: estilos, paletas (OKLCH, ambos os modos), combinações tipográficas, tratamentos de componentes, padrões de movimento, tipos de produto, humores, conjuntos de ícones, recursos de plataforma, sites de referência, unidos por arestas ponderadas pairs_with, suits, avoid_with, requires, excludes e is_alternative. Execute rebuild_graph.py após editar para reindexar.

Execute validate_knowledge.py antes da construção para garantir que todos os nós e arestas sejam válidos e que as triagens de contraste estejam atualizadas.