joo6077/design-mockup

Gotchas

1. Variação apenas de cor não conta como variante distinta — distinguibilidade é calculada, não declarada — As variantes devem representar diferentes abordagens de layout/composição. Substituir cores, valores de token, texto de cópia ou ícones não conta como elementos do axis_vector. Portanto, duas variantes que diferem apenas nesses aspectos têm distância Hamming 0 e são REPROVADAS. Fórmula de julgamento e portão executável: ../../references/visual-change-protocol.md §5 Variant Contract Matrix. Evidência empírica é a REJEIÇÃO global UI-04 — o contrato já havia especificado 4 eixos, mas ambas as variantes tinham o mesmo valor em todos os eixos.

2. Proibido duplicar IDs — Todos os IDs de componentes em todas as variantes geradas devem ser globalmente únicos. Use o formato {nome-do-componente}-{hash-curto}. Se o mesmo hash aparecer, regenere-o.

3. Não ignorar princípios de acessibilidade — Mesmo em mockups de alta fidelidade, respeite a taxa de contraste WCAG 2.2 AA (4.5:1) e os alvos de toque mínimos. WCAG 2.2 SC 2.5.8 AA = 24×24 CSS px / SC 2.5.5 AAA = 44×44 CSS px / Apple HIG 44pt são recomendações práticas para dispositivos de toque. Definir 44pt como padrão no mockup (AAA/recomendação da plataforma) torna a transição Figma/HTML → código mais segura. Mesmo que seja visualmente bonito, não pode violar a acessibilidade. Fonte: W3C WCAG 2.2 SC 2.5.8.

4. Figma MCP não configurado não gera erro — Ao solicitar envio para o Figma, se o MCP não estiver configurado, trate como um aviso, não um erro. Informe "Para enviar ao Figma, é necessário configurar o Figma MCP" junto com o caminho do arquivo HTML.

5. Proibido Lorem Ipsum — Texto placeholder é lido de forma diferente do conteúdo real que o usuário encontrará. Use conteúdo real ou dados de exemplo realistas. Títulos, rótulos de botões e textos descritivos com lorem ipsum impedem a avaliação correta da intenção do layout.

6. Não rotule variantes apenas como "Opção A/Opção B" — Cada variante deve refletir uma prioridade estratégica diferente. O rótulo deve carregar essa intenção. Exemplos: Otimizada para conversão, Focada em navegabilidade, Impacto da marca. Isso incentiva uma discussão baseada em critérios de seleção, não em votos de preferência.

7. Moldura de dispositivo: use seletivamente conforme o objetivo — Para apresentações ao cliente ou demonstrações quase finais, a moldura do dispositivo transmite uma impressão de produto final. No entanto, para comparação de estrutura de layout ou revisão de densidade de conteúdo, é melhor exibir sem moldura. A "cromagem" da moldura pode atrapalhar o julgamento do layout, que é o ponto central da discussão.

8. Se o ponto central é a interação, não dependa de comparação estática — Dropdowns, overlays, fluxos de várias etapas, estados de carregamento e transições modais são difíceis de julgar apenas com imagens estáticas lado a lado. Inclua interações hover/focus/click nos mockups HTML ou forneça links para protótipos interativos.

9. Mockups responsivos não se resumem a snapshots por breakpoint — Ao apresentar as 3 configurações (mobile/tablet/desktop), certifique-se de que cada uma mostra o mesmo estado do cenário de usuário para que a comparação seja significativa. Especifique também as regras de layout: número de colunas, gutters, max-width, etc.

10. Recomenda-se o uso de Container Queries — Em mockups responsivos, use media queries para divisão no nível de página e container-type: inline-size + @container queries para divisão no nível de componente. Size queries são suportadas a partir do Chrome 105, Firefox 110 e Safari 16 (style e scroll-state queries têm suporte diferente). É possível especificar tamanhos relativos ao container com unidades cqw/cqi. Defina breakpoints nos pontos onde o conteúdo quebra, evitando basear-se em dispositivos alvo. Fonte: research-log §J.

11. Aplicar Tipografia Fluida — Aplique tamanhos de fonte fluidos baseados em clamp(min, preferred, max) nos textos do mockup para transições naturais de tamanho em todas as viewports, sem breakpoints. Particularmente eficaz em textos hero/display. Fonte: research-log §E.

12. mockup.html em formato HTML é o artefato esperado — A saída deste skill (.design/mockups/*.html) utiliza intencionalmente o formato HTML. A estrutura diferente de padrões de contrato .md como design-tokens.md, audit-report.md é uma diferença proposital de design, não um erro. Se uma ferramenta de avaliação QA apontar "o formato HTML difere do padrão .md", trate como falso positivo e ignore com base neste Gotcha.

13. Confirmação = criar arquivo de registro de aprovação (não terminar apenas no log da conversa) — Quando o usuário confirmar um mockup, na Etapa 5, crie o arquivo .design/approvals/{YYYYMMDD}-{nome-da-tela}.md. Inclua a variante escolhida, o caminho do artefato, os valores visuais confirmados (cores, tipografia, espaçamento) e a justificativa original. Aprovar apenas na conversa sem deixar arquivo resulta em REJEIÇÃO na QA posterior: "não é possível verificar a evidência de medição da condição de objetivo (registro de aprovação do mockup)" — esta é a razão real da REJEIÇÃO global UI-06 em 2026-07-13. Mesmo que a aprovação seja feita em modo autônomo, registre-a e especifique o responsável como "modo autônomo" . Especificação: ../../references/visual-change-protocol.md §4.

14. Não substituir valores de mockup aprovados por tokens (Precedência da Fonte Visual da Verdade) — Cores e espaçamentos de mockups que o usuário visualizou e aprovou no navegador têm precedência sobre os tokens da paleta do projeto. Ao processar solicitações de alteração no mockup, não normalize os valores aprovados para um único tint ou accent existente "para se adequar ao sistema de tokens". Se a tokenização for necessária, não altere o valor; em vez disso, defina um token com aquele valor e proponha separadamente. Se o projeto já possui um sistema de cores, primeiro enumere e apresente os valores existentes antes de introduzir uma nova paleta. Tabela de precedência: ../../references/visual-change-protocol.md §1.

15. Solicitações de alteração parcial devem modificar apenas aquela propriedade — Change Manifest obrigatório — Em solicitações como "só a borda deste card mais grossa", "a cor está certa, mas volta o gradiente para o anterior", não altere outras propriedades visuais não mencionadas (background, fill, radius, shadow, spacing, typography). Antes de editar, deixe na resposta duas listas: Alterar / Manter. Após a modificação, verifique se os valores da lista Manter permanecem inalterados. Se uma área não intencional foi alterada, considere como falha, reverta e reaplique. Solicitações de reversão parcial devem reverter apenas o eixo mencionado. Detalhes: ../../references/visual-change-protocol.md §2.

16. Antes de gerar, acorde a Matriz de Contrato de Variantes (contrato de quantidade + portão de distinguibilidade) — Antes de criar qualquer mockup, preencha as 6 colunas da ../../references/visual-change-protocol.md §5 Variant Contract Matrix e acorde com o usuário. Se o usuário especificar a quantidade, deve ser exatamente essa quantidade; se não especificar, gere no mínimo 5 e quantas forem necessárias para a comparação, sem limite superior. A regra de quantidade, número de eixos primários e a proibição de artefatos auxiliares (arquivos de tokens, sistema de design, surface lane, catálogo) têm como fonte original harness/docs/guides/skill-design-guide.md §5.6 Variant Budget e não são redefinidos aqui. Se, ao pedir "alguns mockups", o assistente gerar dezenas de tiles e arquivos de tokens, o usuário terá que deletar tudo — isso já aconteceu.

17. Captura de mockup é artifact_snapshot — não afirme que a tela do aplicativo está normal — O fato de o HTML do mockup abrir bem é uma proposição diferente de o usuário ver aquela tela no aplicativo real. Ao citar evidências, inclua o nome do canal e, na frase PASS, insira 5 elementos: viewport · route/state · visible locator · count/height · screenshot id. Definição de canais: ../../references/visual-change-protocol.md §7 Evidence Channels. Se o usuário relatar "ainda está quebrado", não refute; reproduza — o texto canônico do protocolo está em harness/docs/guides/skill-design-guide.md §3.8 User-Reported Failure Gate.

Processo

Etapa 0: Detecção e carregamento automáticos

Navegue pelos artefatos de etapas anteriores no projeto:

# Alvos de detecção
.design/concept.md          → Carregar conceito
**/theme/** **/tokens/**    → Carregar tokens de design
**/design-tokens.*          → Carregar tokens de design
.design/approvals/*.md      → Carregar configurações confirmadas · alternativas descartadas para a mesma tela
.planning/prd-*.md          → Carregar decisões descartadas da tabela de não-escopo (## Non-goals (incluindo decisões descartadas) · ## No-gos)

• Conceito existente → Reflita no mockup as palavras-chave de mood, direção de cor/tipografia e padrões de UI
• Tokens existentes → Aplique valores específicos de cor, escala tipográfica e espaçamento no mockup
• Nenhum dos dois → Crie mockup apenas com base nos requisitos do usuário
• Registro de aprovação existente → Mantenha a configuração confirmada; alternativas/elementos descartados não devem ser reintroduzidos no mockup a menos que o usuário peça explicitamente (../../references/visual-change-protocol.md §4)
• Tabela de não-escopo do PRD existente → Os itens dessa tabela não devem ser incluídos no mockup. Mesmo que haja vestígios no código, não os interprete como requisitos; se parecer que devem ser ressuscitados, pergunte ao usuário antes de criar (planning-kit plan-prd Gotcha 14)
• Célula de descarte no registro de aprovação aponta para um caminho → Abra o arquivo e leia o texto original. Se for um caminho PRD, use os itens da tabela de não-escopo. Se for um caminho de contrato de trabalho, na seção limites de escopo, use as linhas que terminam com sem PRD como itens descartados e não os inclua no mockup. Se o arquivo não existir ou não puder ser lido (.harness não rastreado não acompanha a nova árvore de trabalho), informe Não foi possível ler: <caminho> e pergunte ao usuário antes de criar o mockup
• Código do aplicativo existente → A tabela de convenções §0 é criada somente após definir a tela alvo na Etapa 1 — sem tela alvo, não é possível escolher "mesmo papel". Leia o número de telas existentes com o mesmo papel conforme definido em §0 (fonte original harness skill-design-guide.md §8.9) e use apenas os nomes reais confirmados por grep para componentes reutilizáveis. As convenções são inseridas nos constants da matriz da Etapa 2-a

Etapa 1: Levantamento dos requisitos da tela

Identifique a partir da solicitação do usuário:

• Qual página/tela (login, dashboard, configurações, etc.)
• Principais funcionalidades e elementos de informação
• Público-alvo

Antes de criar o arquivo, deixe na resposta o alvo e a paráfrase da seção §0 de ../../references/visual-change-protocol.md — o caminho do arquivo e a rota da tela alvo (se for nova tela, nova), e uma frase que parafraseie a solicitação incluindo nomes de elementos e posicionamento. Se houver ambiguidade, pergunte e comece.

Se algo não estiver claro, confirme com o usuário.

Etapa 2: Acordar quantidade · Variant Contract Matrix e gerar mockups HTML de alta fidelidade

Etapa 2-a: Fixar primeiro a quantidade e os eixos (antes de criar os arquivos)

Preencha a ../../references/visual-change-protocol.md §5 Variant Contract Matrix e acorde com o usuário. A regra de quantidade, número de eixos e proibição de artefatos auxiliares têm como fonte original harness/docs/guides/skill-design-guide.md §5.6.

Situação	Quantidade a gerar
Usuário especifica a quantidade	Exatamente essa — exceder ou ficar abaixo é violação
Não especificado	Mínimo de 5 — mais se necessário para comparação. Sem limite superior

Após preencher as 6 colunas da matriz (variant_id · strategy_label · axis_vector · constants · intended_user_scenario · arquivo gerado), execute a auto-verificação de distinguibilidade — se houver 3 ou mais eixos especificados, a distância Hamming entre todos os pares deve ser ≥ 2; se 2 ou menos eixos, ≥ 1. O portão executável está em §5. Se houver pares sobrepostos, não submeta aquele conjunto; redesenhe o lado sobreposto (REJEIÇÃO global UI-04).

Não crie arquivos de tokens, sistema de design, surface lane ou catálogo de componentes não solicitados. Se parecer necessário, apresente como proposta separada e crie somente após aprovação.

Etapa 2-b: Gerar a quantidade acordada

Consulte references/mockup-guidelines.md e gere os mockups no formato do modelo ../../templates/mockup.html:

Cada mockup é um arquivo HTML independente:

• .design/mockups/{nome-da-pagina}-{caracteristica}.html (ex: dashboard-sidebar.html)
• Nível de alta fidelidade com cores, tipografia e espaçamento reais
• Todos os elementos UI com ID {nome-do-componente}-{hash4digitos}
• Incluir overlay JavaScript que exibe o ID ao passar o mouse
• Proibido lorem ipsum — usar conteúdo real ou dados de exemplo realistas

Pool de candidatos a strategy_label (escolha a quantidade acordada. Se a quantidade acordada for maior que o pool, crie estratégias adicionais fora do pool adequadas à tela solicitada — esta lista é exemplificativa, não limitante):

• Otimizada para conversão — Navegação lateral + conteúdo principal, CTA principal fixo no topo
• Focada em navegabilidade — Barra superior + grade de cards, filtros/ordenação em destaque
• Alta densidade de informação — Baseado em abas + visualização em lista, hierarquia de texto escaneável
• Impacto da marca — Hero em tela cheia + seções de rolagem, entrada focada no visual
• Dashboard/controle — Layout de painéis de widgets, resumo de status + ações rápidas prioritárias

O template tem 5 slots de mockup (A–E) por padrão. A partir do sexto mockup, adicione slots em grupos (f, g, …) — botões de aba · painel · dois locais de option na comparação · cartão de voto · campo de nota · entrada MOCKUP_CONFIG.variants · texto T.ko.tab / T.en.tab. O script do template lê a lista de mockups apenas de MOCKUP_CONFIG.variants, portanto não altere o script. Também não altere o CSS — a linha de cartões de voto · campo de nota usa grid-auto-flow: column, então em telas largas eles ficam em uma linha de acordo com o número de mockups, em telas ≤768px quebram em duas colunas, e cartões de voto ≤400px quebram em uma coluna.

Se responsividade for um requisito, adicione em cada mockup seções de breakpoints mobile/tablet/desktop e especifique regras de colunas, gutters e max-width.

Etapa 3: Explicação da intenção de design

Para cada mockup, explique:

• A prioridade estratégica que o mockup reflete (conversão, navegação, marca, etc.)
• A razão da escolha do layout e a estrutura da informação
• Pontos de destaque visual — onde o olhar do usuário se detém
• Para qual cenário/contexto de usuário o mockup é mais adequado
• Breve justificativa das principais decisões (por que esta configuração)

Organize a apresentação não como uma "lista de telas", mas como um fluxo de cenário de usuário. Em vez de descrever cada mockup independentemente, compare como cada um resolve um problema de forma diferente para facilitar a discussão sobre critérios de seleção.

Etapa 4: Seleção e modificação pelo usuário

• O usuário seleciona um mockup ou fornece feedback

• Comunique-se usando IDs: "aumente o card-product-a3f2"

• Ao solicitar comparação entre mockups, escolha a técnica:

  • Comparação de estruturas muito diferentes → lado a lado (side-by-side)
  • Comparação de mudanças em elementos na mesma tela → sobreposição antes/depois com explicação
  • Comparação com justificativa de decisão/handoff → adicionar anotações
  • Comparação de interações/mudanças de estado → incluir comportamentos hover/focus/click

• Se a solicitação de modificação visar uma única propriedade ou elemento (só a borda, só a cor, só o espaçamento, só este chip), deixe um Change Manifest antes da edição (Gotcha 15 · ../../references/visual-change-protocol.md §2):

  ## Change Manifest
  - Alterar: [propriedade — ID alvo — valor atual → valor alvo]
  - Manter: [demais propriedades visuais do mesmo elemento — background / fill / radius / shadow / spacing / typography, conforme aplicável · se um único elemento foi visado, também os elementos vizinhos na mesma linha/área e sua posição]
  

  Após a modificação, verifique se os valores da lista Manter permanecem inalterados. Se algo mudou, reverta e aplique apenas a propriedade visada. A ordem das correções, confirmação de aplicação e limite de autocorreções seguem §3 Comparação de ordem de repetição (fonte original harness skill-design-guide.md §8.9), e a cada captura, consulte a lista de verificação de captura §3.

• Atualize o arquivo HTML após a modificação

• Ao confirmar, mantenha a versão final em .design/mockups/

Etapa 5: Gerar registro de aprovação (obrigatório na confirmação)

Quando o usuário confirmar o mockup, crie o arquivo .design/approvals/{YYYYMMDD}-{nome-da-tela}.md. Apenas o log da conversa não é suficiente para verificar a justificativa de aprovação na QA futura, resultando em REJEIÇÃO (Gotcha 13 · UI-06 global).

# Registro de aprovação — {nome-da-tela}

- Data de aprovação: {YYYY-MM-DD}
- Responsável pela aprovação: {Confirmação direta do usuário | Modo autônomo (justificativa do julgamento)}
- Artefato alvo: .design/mockups/{nome-do-arquivo}.html
- Variante selecionada: {rótulo da estratégia + ID do mockup}
- Valores visuais confirmados: {cores, tipografia, espaçamento fixados no momento da aprovação — estes prevalecem em caso de conflito com tokens posteriores}
- Configuração confirmada: {elementos e posicionamento que permanecem na tela}
- Alternativas/elementos descartados e motivo: {variantes ou elementos descartados e motivo — se a decisão foi remover uma funcionalidade ou item de configuração, não reescreva o motivo aqui. Apenas anote o caminho da tabela de não-escopo do PRD daquela funcionalidade e a linha "não fazer" correspondente (planning-kit plan-prd Gotcha 14) · se não houver, escreva `Nenhum(a)`}
- Não confirmado/pendente: {itens não acordados deixados como pendentes}
- Justificativa original: {citação da fala do usuário}

Se não houver PRD (.planning/prd-<slug>.md) para aquela funcionalidade, o texto da decisão deve ser registrado em um único local no contrato de trabalho, na seção limites de escopo, com as mesmas quatro colunas da tabela de não-escopo do plan-prd (não fazer · motivo · escopo · vestígio no código) e ao final da linha adicione sem PRD. Na célula de descarte, anote apenas o caminho do contrato — se o texto da decisão estiver em dois lugares, apenas um será atualizado (../../references/visual-change-protocol.md §4). Se também não houver contrato de trabalho para a funcionalidade, o texto da decisão é único nesta célula de descarte do registro de aprovação — escreva as mesmas quatro colunas por decisão, uma linha por item, indentado abaixo da célula de descarte, como itens de lista iniciados com -, e ao final da linha adicione sem PRD. Antes do próximo mockup, a Etapa 0 seguirá o caminho na célula de descarte para ler o texto original. Não crie um PRD apenas para armazenar registros de descarte (plan-prd Gotcha 1).

Imediatamente após a criação, verifique:

ls .design/approvals/                      # Arquivo existe
grep -c 'Valores visuais confirmados' .design/approvals/{nome-do-arquivo}.md   # → 1
grep -cE '^- (Configuração confirmada|Alternativas/elementos descartados e motivo):' .design/approvals/{nome-do-arquivo}.md   # → 2

Se o mockup for modificado novamente após a aprovação, atualize este registro. Um registro de aprovação desatualizado é pior do que a ausência dele.

Etapa 6: Envio para o Figma (opcional)

Se o usuário solicitar o envio para o Figma:

• Verifique se o Figma MCP está configurado
• Configurado → Envie o mockup selecionado ou componentes individuais (por ID) para o Figma
• Não configurado → Informe "Para enviar ao Figma, é necessário configurar o Figma MCP" + reexiba o caminho do arquivo HTML
• Falha no envio → Mensagem de erro + caminho do arquivo HTML

Referências

• references/mockup-guidelines.md — Detalhamento dos critérios de criação de mockups
• ../../templates/mockup.html — Formato de saída HTML do mockup (template compartilhado)
• ../../references/visual-change-protocol.md — Precedência visual · Isolamento de alterações parciais · Especificação do registro de aprovação · §5 Variant Contract Matrix · §7 Evidence Channels (SSOT)
• harness/docs/guides/skill-design-guide.md §5.6 Variant Budget · §3.8 User-Reported Failure Gate — Fonte original da regra de quantidade, proibição de artefatos auxiliares e protocolo de relato do usuário