Design Harness

O que Design Harness faz?

Execute um fluxo de trabalho de interface web retomável. Mantenha o usuário no controle da intenção e mantenha a produção de design separada da revisão.

Iniciar e retomar

Resolva <skill-dir> como o diretório que contém este SKILL.md; não presuma que o diretório de trabalho atual contém os scripts agrupados.

1. Execute node <skill-dir>/scripts/preflight.mjs --root <projeto> antes de fazer perguntas. Leia seu relatório de capacidade; não instale nada. Trate um caminho de sistema de arquivos ausente como consultivo: verifique o inventário de habilidades/plugins carregados do host antes de declarar Impeccable ou Jakub indisponíveis.
2. Execute node <skill-dir>/scripts/state.mjs init --root <projeto>. Isso atualiza com segurança um estado legado porque init é um comando mutante. Se o estado existir, execute o comando somente leitura status e retome na sua nextPhase; nunca reinicie fases concluídas. Use migrate explícito ao verificar ou atualizar uma execução legada sem reinicializá-la.
3. Leia apenas a referência necessária para a fase atual:
   • descoberta/confirmação: references/interview.md
   • contexto/direção: references/context-contract.md
   • construção/escolhas de ferramentas: references/routing.md
   • seleção de fonte opcional: references/optional-tool-registry.json, somente após uma condição de ativação ser confirmada
   • revisão/QA/entrega: references/review-and-qa.md
4. Avance o estado após cada fase concluída com node <skill-dir>/scripts/state.mjs advance <fase> --root <projeto>. Para human-feedback, passe também --outcome used ou --outcome not-used. Para feedback-fixes, passe --outcome applied ou --outcome not-applicable.

Use esta sequência monotônica fixa:

preflight → discovery → confirmation → context → direction → build → internal-review → human-feedback → feedback-fixes → independent-review → fixes → qa → handoff → complete

Armazene apenas estado de máquina em .design-harness/state.json; relatórios e capturas de tela pertencem a .design-harness/reports/. Nunca armazene transcrições completas de chat, tokens, cookies, credenciais ou dados ambientais não relacionados.

Reforçar a barreira de aprovação

Entreviste adaptativamente e resuma as respostas em um cartão de confirmação conciso. Inclua produto, público, objetivo principal, conteúdo, páginas/superfícies, qualidades desejadas e indesejadas, referências positivas e negativas, restrições, movimento, estados necessários, pilha, delegação, estados específicos de IA, tolerância WebGL, política de fontes externas e qualquer limite de licença paga. Pergunte apenas por detalhes ausentes ou consequentes.

Não escreva, edite ou gere código de produção de IU antes que o usuário aprove explicitamente o cartão de confirmação. Pré-verificação, perguntas, inspeção somente leitura e um rascunho do cartão de confirmação ou conteúdo de intenção proposto no chat são permitidos. Não crie ou modifique arquivos .md de intenção do projeto até a aprovação.

Se as referências estiverem ausentes, trate palavras descritivas como suficientes. Derive duas ou três direções nomeadas com trade-offs concretos e peça ao usuário para escolher. Gere quadros visuais apenas quando a ferramenta visual existir e o usuário se beneficiar; nunca torne um quadro um pré-requisito.

Criar contexto aprovado

Após a confirmação, preencha estes arquivos a partir das respostas do usuário ou propostas que o usuário aprove explicitamente:

• PRODUCT.md, incluindo um registro brand ou product aprovado
• REFERENCES.md
• DESIGN.md
• ACCEPTANCE.md
• pelo menos um .impeccable/surfaces/<slug>.md

Copie estruturas dos modelos de PRODUCT, references, design, acceptance e surface. Marque cada arquivo de intenção como aprovado somente após o usuário aprovar seu conteúdo. Execute node <skill-dir>/scripts/validate-context.mjs --root <projeto> antes da construção.

Mantenha as seções H2 de DESIGN.md exatamente, uma vez cada, nesta ordem: Overview, Colors, Typography, Elevation, Components, Do’s and Don’ts.

Trate PRODUCT.md e DESIGN.md como protegidos após a aprovação. Para qualquer alteração posterior, mostre o diff proposto, peça aprovação explícita e, em seguida, aplique-a. Nunca racionalize desvio silenciosamente.

Registre cada componente externo aprovado, receita, efeito ou integração de feedback em REFERENCES.md com sua fonte exata, item selecionado, versão ou commit fixado quando disponível, data de acesso, finalidade pretendida, resultado atual de licença/termos, adaptações e fallbacks necessários. "Usar bibliotecas externas" não é aprovação para uma fonte específica.

Construir através do Impeccable

Faça do skill Impeccable instalado e seu contexto aprovado a única autoridade de design e produção para esta passagem. Carregue seu skill e referências de domínio relevantes, depois forneça a ele os arquivos de intenção e superfícies aprovados. Não permita que ele repita a descoberta ou reinterprete a intenção aprovada. Deixe o Impeccable gerar ou atualizar .impeccable/design.json; nunca edite esse sidecar manualmente e nunca aceite uma alteração resultante em PRODUCT.md ou DESIGN.md sem o fluxo de diff e aprovação protegido.

Não carregue nenhum outro skill amplo de gosto ou sistema de design na mesma passagem de produção. Roteie ajudantes restritos apenas sob references/routing.md. Preserve a biblioteca de componentes e a pilha existentes, a menos que o contexto aprovado autorize a alteração. Nunca instale ou copie automaticamente uma entrada de registro opcional; explique o uso exato e limitado e obtenha aprovação primeiro.

Execute uma auto-revisão do Impeccable após a construção e registre as descobertas; isso é internal-review, não a revisão independente. Assim que a IU estiver estável o suficiente para inspecionar, entre em human-feedback: ofereça o checkpoint Agentation aprovado quando útil, ou registre Not used com --outcome not-used e avance. Mantenha o Agentation apenas para desenvolvimento e manual/local por padrão; MCP, webhooks e resolução autônoma requerem aprovação explícita separada. Em feedback-fixes, aplique apenas as anotações do usuário julgadas e registre --outcome applied; quando o feedback foi ignorado, registre Not applicable com --outcome not-applicable e avance sem editar. Resolva as anotações do usuário antes da revisão independente.

Revisão, correções e QA separados

Para independent-review, inicie um novo subagente/contexto somente leitura com o skill better-interface atual de Jakub e seus seis skills de domínio. Forneça a ele capturas de tela, arquivos de implementação relevantes, restrições da biblioteca de componentes e os documentos de intenção aprovados. Solicite uma revisão completa após a construção. O revisor deve relatar apenas descobertas e não deve editar ou redesenhar silenciosamente.

Julgue cada descoberta no contexto raiz contra PRODUCT.md, DESIGN.md, as especificações de superfície, critérios de aceitação e biblioteca de componentes. Registre aceitar/rejeitar/adiar mais a justificativa. Aplique as correções aceitas separadamente através da autoridade de produção, em seguida, solicite uma revisão focada e rápida somente leitura das áreas alteradas.

Siga references/review-and-qa.md. Execute o detector Impeccable, capturas de tela Playwright em mobile/tablet/desktop, axe e Lighthouse. Cubra rotas representativas e estados aplicáveis de carregamento, vazio, erro, texto longo, hover, foco e movimento reduzido. Para fontes opcionais, também exercite suas portas de registro: fallbacks semânticos/estáticos, comportamento sem WebGL, navegadores aprovados, orçamentos de CPU/GPU ou pacote mobile e exclusão de ferramentas de desenvolvimento da produção, conforme aplicável. Marque estados não suportados ou não exercitados como Not reviewed; nunca os relate como aprovados.

Para interfaces com movimento de scroll de documento significativo ou para prontidão de vídeo/demo, inicie a nova construção de produção em uma porta local dedicada e execute node <skill-dir>/scripts/verify-motion.mjs --root <projeto> --base-url <url> --routes /,<outras-rotas> --config .design-harness/qa/motion.config.json após adaptar a configuração scaffoldada. O verificador testa mobile, tablet e desktop por padrão, isola cada rota em um novo contexto, requer uma resposta de rota bem-sucedida, raiz de conteúdo configurada, URL esperada observada/cadeia de redirecionamento e scroll de documento mensurável, e não simula solicitações de aplicação ou permite redirecionamentos, a menos que a configuração explícita do projeto declare cada exceção. Retenha sua proveniência de esquema-versão 4 do Playwright/navegador e hashes de captura de tela/mock com a entrega. Trate os limites de primeiro quadro/sonda de inicialização e ritmo de quadro como evidência para aquela máquina e navegador apenas, nunca como uma garantia universal de 60 FPS.

Use node <skill-dir>/scripts/scaffold-qa.mjs --root <projeto> para visualizar um scaffold de QA genérico e adicione --apply após o cartão de confirmação autorizar o plano de QA. Pergunte novamente apenas quando os arquivos existentes forem substituídos. Ele nunca instala dependências.

Entregar

Declare o estado Ready somente quando os critérios de aceitação aprovados passarem e nenhuma descoberta bloqueadora ou lacuna de QA inexplicada permanecer; caso contrário, declare Not ready. Liste arquivos alterados, capturas de tela, descobertas de revisão e disposições, verificações automatizadas e resultados, estados não suportados, lacunas restantes e cada fonte externa realmente usada com sua proveniência fixada e resultado de licença. Avance handoff, depois execute node <skill-dir>/scripts/state.mjs complete --root <projeto> somente quando o fluxo de trabalho estiver genuinamente completo.