teqo-backup/.agents/skills/plan-issue/ui-design-html.md

Design hi-fi do gate (plan-issue)

Quando o item muda UI (classe Impeccable B / C / D, ou qualquer superfície que o usuário vê/toca), o gate obrigatoriamente apresenta o design hi-fi da intenção — não ASCII sozinho, não wireframe de implementação. O meio é HTML + Tailwind com tokens reais, brand e shadcn, commitado no repo Teqo junto do plano. O artefato é a fonte de verdade do port: quem implementa (work-issue / agent-work-issue) porta classe-a-classe para React/Next.

Para que serve — e para que NÃO serve

Serve para aprovar o design final antes de qualquer código e, depois, portar e criticar com paridade: layout, espaçamentos, tamanhos, hierarquia, estados, tokens, copy. É a linguagem do gate para "é isso que o usuário vê/toca".

NÃO é implementação da feature, NÃO é protótipo funcional, NÃO é entrega de app, NÃO é decisão de engenharia. Não há lógica de negócio, dados reais, chamadas de rede ou persistência.

• Imutável como registro: o design aprovado viaja com a Issue e fica no repo; planos antigos (docs/plans/**) não se migram.
• Mutável durante o work-issue: o designer pode estender/ajustar o artefato na execução; mudança material volta ao humano no PR — nunca em silêncio.

Quem produz e quem critica

Mesma doutrina para os dois papéis (fonte única — os prompts dos agentes apontam para cá, não copiam as regras):

• Criar: o agente designer (.opencode/agent/designer.md) produz ou estende o hi-fi a partir do plano de intenção aprovado — tokens/brand reais, copy pt-BR real, cenas 390/1280, estados críticos. O artefato nasce antes da implementação e é o alvo do gate.
• Criticar: o designer relê a implementação renderizada contra o artefato aprovado e devolve lista numerada de ajustes concretos — hierarquia (o CTA primário domina?), contraste, tipografia, espaçamento, mobile, acessibilidade. Capture as telas com playwright-cli (§Skills de design; MCP Playwright/Chrome DevTools como fallback) e rode a revisão web-design-guidelines (file:line) quando a superfície for código. A referência é o alvo — nunca a critique.
• Visão nativa (fail-closed): leia screenshots, prints e referências direto com a tool Read; nunca peça ao humano para descrever o que você pode ver. Se a leitura da imagem falhar (modelo da sessão sem visão), pare e peça a troca de modelo via /models antes de julgar a tela; nunca descreva o que não viu.
• Tier degradado: o designer-degraded cria/estende/critica, mas marca todo output DEGRADED e nunca certifica — exige sign-off humano explícito. DEGRADED não é design aprovado.
• Escrita só no artefato (file tools + bash): os dois agentes têm permission fail-closed — edit/write/patch negados fora de docs/plans/<slug>-ui-design*; o designer frontier também pode gravar DESIGN.md, o designer-degraded não (evolução de regra visual é proposta, nunca aplicada por tier que não certifica). O bash nega os vetores de escrita enumerados (redirecionamento, sed -i, tee, shells/interpretadores) fora do artefato; o resto do shell fica em ask. Não tente contornar por shell (o guard cobre os vetores enumerados, não é sandbox de SO) — leia/inspecione à vontade (cat, sed -n, git diff) e grave o artefato pelas file tools.

Escopo de dispatch — o designer frontier só roda design de fato

O tier frontier (designer com pin openai/gpt-5.6-sol) é recurso escasso e caro: ele é despachado apenas nos dois modos de design — Criar ou Criticar o artefato (e, como consequência, evoluir DESIGN.md) — e apenas para item que muda UI. Todo trabalho que não é isso roda no modelo padrão da sessão, nunca no frontier.

Provider openai reservado aos agentes de design. O provider openai (OAuth ChatGPT Plus) existe só para o design: todo modelo openai/* — gpt-5.6-sol/sol-fast, gpt-6-astra, gpt-5.6-luna/-fast, gpt-5.6-terra — é usado apenas pelos agentes de design (designer, e designer-campanha-solla na própria sessão) e apenas para criar/criticar design. Nenhuma outra sessão ou agente (build, explore, general, skills, subagentes), nem small_model, compaction ou worker de orquestração, troca para openai/* via /models, --model ou config — esses rodam no modelo padrão (deepseek/deepseek-flash). A reserva cobre todo o consumo do provider, não só o dispatch do designer.

Lista fechada do que NUNCA vai para o designer frontier:

• smoke/validação de permission, guard de escrita, frontmatter, model: ou config de agente — a semântica de permission é do frontmatter, não do modelo: valide estaticamente, ou rode o smoke com o designer-degraded (barato); o resultado do guard é o mesmo;
• teste de visão/sanidade de imagem ("qual a cor dominante") — use o modelo padrão da sessão, que tem visão;
• exploração de código (@explore), review geral (@general), @solla-comunicacao;
• escrever/revisar plano de intenção, impl plan, PR, changelog ou doc;
• qualquer coisa cujo output não seja docs/plans/<slug>-ui-design* (exceção: DESIGN.md, que é decisão de design — ver §Skills de design).

Gate antes de disparar (as três têm de ser "sim"):

1. O item muda UI (Impeccable B/C/D)? 2. É Criar ou Criticar o artefato hi-fi? 3. O output é docs/plans/<slug>-ui-design* ou a evolução de DESIGN.md?

Qualquer "não" ⇒ não despache o designer frontier: segue com o implementador ou com o modelo padrão da sessão.

Fan-out: prefira uma sessão designer para N itens UI do mesmo lote (cache reusado; o system prompt frio de ~25K tokens é pago uma vez) a N sessões frias em paralelo. Paralelismo maximiza velocidade e consumo — sob quota, agrupe.

Agente de design sem model: herda a sessão. designer-campanha-solla não tem pin: ele roda no modelo da sessão-mãe. Dispare essa sessão em modelo barato e só troque para o frontier quando a task for de fato criar/criticar design.

O que o design DEVE ter (fidelidade mínima)

1. Layout real das superfícies tocadas: zonas (lista, detalhe, formulário, mapa, empty, erro), hierarquia de atenção, CTA primário vs secundário.
2. Espaçamentos e tamanhos reais — a mesma escala do app (Tailwind v4: p-4, gap-3, h-11, text-sm, rounded-lg). É disso que o gate discorda ou aprova.
3. Breakpoints reais: cena mobile (~390px) e cena desktop (~1280px) quando o fluxo tocar os dois. Um design mobile sem viewport mobile não valida nada.
4. Estados críticos se mudarem o aceite (vazio, loading, sem permissão, fail-closed) — como cenas, nunca escondidos atrás de clique não descoberto. Podem ser cenas estáticas e/ou interação mínima (abaixo); o gate não pode depender de clicar para ver o essencial.
5. Texto real pt-BR; valores obviamente genéricos ("Nome da liderança", "12 municípios"); barras cinza para conteúdo desconhecido. Claims/números só os aprovados no plano — nunca invente o que não pode ser verificado.

O teto (é design de gate, não implementação)

1. JS mínimo, só de apresentação. Permitido: abrir/fechar modal, trocar de tab, dropdown/accordion, toggle, hover/scroll reveal — coisas que existem para mostrar o design. Proibido: lógica de negócio, fetch/rede, persistência, validação, cálculo de produto, roteamento, qualquer coisa que decida o comportamento do produto. Sem build e sem imports além do Tailwind CDN; JS inline e autocontido no próprio .html.
2. Zero código de app. Não importar de src/, não escrever o componente final, não nomear componentes/arquivos obrigatórios. O design é portado, não copiado como entrega.
3. Zero decisão de engenharia. Sem schema, migration, nomes de arquivos obrigatórios, assinaturas — o design mostra superfície e tokens, não solução.
4. Zero dado real de terceiro. Sem KPIs realistas, nomes reais, números de votos — placeholders óbvios ou barras cinza.
5. Um CTA primário. Nunca dois CTAs de peso igual acima da dobra.
6. LGPD/TSE. Consentimento explícito e link de privacidade visíveis onde houver captação; nada de promessa irrealista; identificação da campanha onde couber.
7. NEEDS ASSET. Marque claramente o que precisa de ativo real (foto, selo, depoimento, cobertura de imprensa). Nunca invente nem use banco de imagens genérico como se fosse real.

Tokens, brand e shadcn (elevados)

• Tokens reais são esperados. Use as cores, raios, sombras e a tipografia da superfície-alvo; se data-theme='campaign' for o alvo, os tokens da campanha valem no artefato (definidos inline via CSS variables/classes, na mesma escala do app).
• Brand é permitida e esperada — gradiente, sombra, motion de apresentação, logo quando aprovado. O teto protege contra virar implementação, não contra ter acabamento.
• Marca e tokens são vivos. DESIGN.md §7 (Evolution) é o dono das decisões visuais e evolui quando um padrão melhor aparece. O kit 1313 (public/campaign-kit/README.md, manual em docs/campaign-kit/manual-campanha-jorge-solla-1313.pdf) é acervo de ativos disponível, não camisa de força: use os arquivos oficiais quando servirem e derive/recrie quando o design evoluir. Os quirks técnicos dos ativos (trim da moldura, disco da estrela, faixas seguras) continuam valendo ao usar cada arquivo.
• shadcn/lucide primeiro. Componentes e ícones seguem o vocabulário do app (button, card, dialog, tabs, badge); custom só quando não houver equivalente.
• Skeleton completo abaixo é ponto de partida — o artefato real traz o conteúdo do item.

Skills de design (toolkit)

O design do Teqo combina a doutrina própria (PRODUCT.md, DESIGN.md, este arquivo) com skills de execução. Nenhuma skill externa substitui o gate; elas são entrada para desenhar, criticar e evoluir — origem e licença em .agents/skills/UPSTREAM.md.

Skill	Papel
impeccable	Doutrina de craft/modos (persuade/operate/read/experience) e comandos de polimento — dono existente para o desk /campanha (operate).
design-taste-frontend	Anti-slop para persuade (site, campanha, landing): lê o brief, infere a direção, pre-flight. Use gpt-taste quando a sessão for GPT/Codex (inclui o designer frontier).
redesign-existing-projects	Auditoria + upgrade de superfície existente sem quebrar função — o caminho para evoluir telas atuais (públicas e desk).
high-end-visual-design, minimalist-ui, industrial-brutalist-ui	Briefs de estilo opt-in quando o item pede um mundo visual específico.
stitch-design-taste	Gera DESIGN.md semântico (formato Stitch). No Teqo, merge no DESIGN.md raiz — nunca sobrescrever; a §7 decide.
web-design-guidelines	Review de a11y/UX/perf com findings file:line — piso obrigatório antes de fechar UI.
awesome-design-md	Biblioteca de referências (DESIGN.md de sites reais) para explorar direção visual. Copiar o craft, nunca a identidade.
playwright-cli	Browser automation token-efficient: screenshots, snapshots, sessões — capture para a crítica e para o port fiel. MCP Playwright/Chrome DevTools como fallback.
full-output-enforcement	Anti-truncamento/placeholder — qualquer task longa, não só design.

Precedência quando as regras conflitarem: PRODUCT.md (posicionamento, anti-referências) → DESIGN.md (identidade viva e tokens) → este contrato (gate e artefato) → skills de execução. Conflito é sinal de evolução, não de impasse: decida o melhor padrão, registre o porquê e atualize o dono (DESIGN.md §7) na mesma mudança — nunca deixe a regra dividida nem siga a doutrina antiga em silêncio.

Escopo por superfície: taste/estilo valem para persuade/read (site público, página de campanha, editorial); o desk /campanha é operate — lá mandam impeccable (operate), redesign-existing-projects, a lista canônica de componentes do DESIGN.md e web-design-guidelines. Não aplique anti-slop de landing page no desk sem critério.

<!doctype html>
<html lang="pt-BR" data-theme="campaign">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
    <title>Design — <título do item></title>
  </head>
  <body class="bg-background text-foreground antialiased">
    <main class="mx-auto max-w-5xl p-8">
      <p class="text-sm text-muted-foreground">Persona/job em uma linha + cenas abaixo</p>
      <section class="mt-6">… desktop (1280) …</section>
      <section class="mt-6 w-[390px]">… mobile …</section>
      <section class="mt-6">… vazio …</section>
    </main>
    <script>
      // JS mínimo de apresentação (ex.: abrir/fechar modal, alternar tabs).
    </script>
  </body>
</html>

SVG (assets próprios)

1. lucide/shadcn primeiro — se existe equivalente, use o ícone da biblioteca.
2. Custom só quando não houver equivalente: grid 24px, currentColor, stroke no padrão lucide.
3. Salve em docs/plans/<slug>-ui-design-assets/*.svg e referencie por caminho relativo — o artefato continua autossuficiente com a pasta ao lado.

Ladder de modelo (quota/indisponibilidade não pula design)

openai/gpt-5.6-sol → openai/gpt-6-astra → opencode-go/deepseek-v4.1-flash (DEGRADED) → deepseek/deepseek-flash (DEGRADED, inline)

• Tier 1 (openai/gpt-5.6-sol): pin do designer. Tier 2 (openai/gpt-6-astra): mesmo agente, troca via /models (ou --model no headless) quando a crítica for contestada/pixel-critical.
• Tier 3 (opencode-go/deepseek-v4.1-flash, agente designer-degraded) e tier 4 (deepseek/deepseek-flash, feito inline pelo orquestrador): sempre DEGRADED, nunca certificam, exigem sign-off humano.
• Queda explícita e auditável: quota/indisponível/visão falhou ⇒ desce o tier e registra no PR (Design tier: …) — nunca pula design em silêncio. Se todos os tiers falharem, o design bloqueia: o humano decide, não se "segue sem".

Como fazer (artefato no repo)

1. Escreva docs/plans/<slug>-ui-design.html — um arquivo por item, autossuficiente (Tailwind v4 browser CDN; rede só na hora de renderizar no browser).
2. Assets em docs/plans/<slug>-ui-design-assets/*.svg quando ícones/ilustrações próprios forem necessários.
3. Commitado com o plano: o design aprovado é o registro do aceite visual (ver "Imutável como registro" no topo).

Relação com o plano em docs/plans/

• Campo do cabeçalho do plano aponta o caminho do artefato (Design UI:) — ou N/A — sem UI.
• Link do .html no corpo do plano.
• Esboço ASCII no markdown vira opcional (backup textual).

Gate

Antes de pnpm agent:register, mostre o overview do lote e o link do .html — o humano abre no browser para validar. Itere: editar HTML (e pedir crítica ao designer) até confirmação explícita. Só então registre a Issue. Se o tier for degradado, o sign-off humano é obrigatório e o rótulo DEGRADED fica visível.