ui-architect

Constrói a UI de um sistema a partir de um mini-mundo, em quatro fases checkpointadas — e evolui UIs já construídas em fatias, no modo evolução. Cada fase produz um artefato em docs/ui/ (no projeto target, não na skill). Quando o projeto tem docs/ddd/, a skill consome esses artefatos como input. A implementação trabalha em cortes verticais por use case, não por camada horizontal.

Fluxo

Dois modos:

Greenfield (do mini-mundo à v1):

A fase 4 se organiza em sub-fases (4.0 fundação → 4.1..N cortes verticais por use case → 4.Z smoke).

Evolução (brownfield — entrada é um CHG-NNN da feature-loop, com mockup de UX quando houver):

Protocolo de ativação

Ao ativar a skill:

1. Detectar o modo. Se a entrada é um CHG-NNN em docs/changes/ (handoff da feature-loop) ou o usuário pede pra evoluir/mudar uma UI que já tem docs/ui/ + código construído → modo evolução: leia phases/evolution.md e siga por ele (as fases 1–4 abaixo são o repertório, não o roteiro). Caso contrário, greenfield.
2. Detectar estado (greenfield). Verifique se docs/ui/ existe no projeto target. Se sim, liste os artefatos presentes e pergunte: retomar, revisar fase específica, ou recomeçar. Pule fases já concluídas a menos que o usuário peça revisão.
3. Detectar artefatos de DDD. Verifique se docs/ddd/ existe. Se sim, informe ao usuário quais artefatos foram encontrados e que serão usados como input nas fases correspondentes. Se não existe, a skill funciona standalone a partir do mini-mundo bruto — peça o mini-mundo se não foi fornecido.

4. Detectar contrato de backend (gate duro). Antes de desenhar qualquer tela (fase 2 em diante), localize e leia o contrato real do backend — não a intenção de design. O contrato tem duas metades, e é a segunda que passa despercebida:

   Forma — que campos existem, de que tipo, nuláveis, presentes quando: (a) OpenAPI/Swagger (openapi.{yaml,json}, swagger.*, rota servida tipo /openapi.json) — fonte primária de forma; (b) ADRs e decisões (docs/ddd/03-architecture.md) — onde mora o que foi decidido não fazer; (c) tático (docs/ddd/02-tactical.md).

   Semântica — o que cada campo significa: unidade, granularidade, janela, causa, e o que o handler faz nos ramos de erro. Isso não está no OpenAPI, e a fonte é o código-fonte do backend — handler, projeção, serviço de domínio. estagnado: { type: boolean } é uma descrição perfeitamente correta e semanticamente vazia: nada nela diz se a janela é de 4 semanas ou de 4 séries, e a tela que narra o campo vai afirmar uma das duas ao usuário.

   Gatilho, pra não virar "leia o backend inteiro": precisa de leitura de código todo campo que a tela vai interpretar — booleano cujo nome implica uma regra, número com unidade implícita, array cuja granularidade a tela vai narrar, campo que vira frase. Campo que a tela só imprime, não.

   O inventário tem duas colunas: forma (do OpenAPI) e semântica (do código, com arquivo:linha), mais as não-capacidades explícitas (ex.: "snapshot-only, sem série histórica"). Se nenhuma fonte existe e o projeto não foi declarado greenfield, pare e pergunte ao usuário onde mora o contrato. Esse inventário é restrição dura das fases 2–4.

   Artefato de contrato bem-formado ≠ contrato compreendido, e nenhum teste cobre a diferença. O teste confere a copy contra o spec, e o spec é onde a suposição errada foi escrita — suíte verde prova coerência entre spec e código, nunca que o spec descreve o domínio. Aqui não existe defesa de tipo possível: boolean continua boolean seja a janela de 4 semanas ou de 4 séries. A única defesa é ler o código antes de escrever o spec, e custa minutos.

5. Obter o mini-mundo. Se o usuário não forneceu e não há docs/ddd/01-strategic.md, peça. Sondar: atores, contextos de uso, dispositivos-alvo, restrições visuais.
6. Detectar stack. Default vite-react-ts. Se o usuário passou stack=<nome> ou mencionou outra stack, use-a. Leia templates/stacks/<stack>.md. Se o arquivo não existir, pare e peça ao usuário as convenções; escreva o arquivo de stack antes de prosseguir.
7. Rodar fase a fase, com checkpoint. Leia o arquivo de método da fase, conduza o trabalho em conversa, escreva o artefato usando o template correspondente, apresente, pause. Não avance sem ordem do usuário.

Protocolo de checkpoint

Após cada fase:

• Salve o artefato no caminho documentado.
• Diga: "Salvei em <path>. Revise/edite o arquivo. Quando quiser seguir pra fase N+1, me diga seguir, ou aponte ajustes."
• Se o usuário editar o .md manualmente, a versão editada vira a fonte da verdade — a próxima fase lê do disco, não da memória da conversa.

Regras transversais

• Os artefatos são o contrato entre fases. A fase N+1 nunca usa informação da fase N que não esteja escrita no artefato. Se o artefato está vago, conserte o artefato — não compense na próxima fase.
• Não modifique artefatos de DDD. Se identificar gap (ex.: JTBD sem use case correspondente, tela que precisa de comando ausente no tático, ou capacidade que o backend não expõe — campo, endpoint, série de dados), sinalize ao usuário em vez de inventar. Gaps de DDD e de capacidade são consertados via ddd-architect / backlog de backend, não via ui-architect.
• Todo elemento de tela rastreia a uma capacidade do contrato (proveniência). Cada métrica/componente do spec carrega de onde vem (ex.: GET /api/portfolio → absoluteDifference). O que não tem fonte no contrato é marcado (sem fonte no backend) — vira gap explícito, nunca renderizado fingindo existir. Esta flag é informativa (sinaliza, não bloqueia o fluxo).
• Achado que exige trabalho futuro vira demanda no inbox — inclusive quando é da própria UI. As regras de roteamento cobrem bem o que é do backend (gap de capacidade, mockup aspiracional); o buraco é o defeito que a fatia encontra na UI já construída e decide, corretamente, não consertar por estar fora de escopo. Ele vai para docs/changes/ como demanda, inclusive quando a fatia o consertou numa tela e não nas outras. Declarar no build-log é honestidade, mas não substitui: ninguém tria pelo build-log — ele é narrativa da fatia. O que se perde assim é sempre defeito conhecido em tela já commitada, a categoria mais barata de consertar e a mais fácil de esquecer.
• Aspiracional vs. construível. Mockups que exploram a UX ideal são bem-vindos, mas devem ser rotulados: construível = preso ao contrato, é o que a fase 4 implementa; aspiracional = pode exceder o backend, desde que marcado. Todo excesso de um mockup aspiracional vira demanda registrada (backlog de docs/ddd/ ou ddd-architect), não gambiarra no front. Nunca apresente um aspiracional como se fosse construível.
• Seja explícito sobre incerteza. Ao propor um modelo, decisão de IA ou componente, liste alternativas consideradas e o porquê da escolha. Tradeoffs vão no artefato, não só na conversa.
• Dependência nova segue a mesma política do backend (ddd-architect/phases/03-architecture.md, passo 8), com as barras do front: estabeleça o menu real (o que custa de fato não usar a lib — quase nunca é zero); aceite quando encapsula complexidade essencial ou risco de correção, a procedência é primária/padrão-de-fato, e ela fica confinada num módulo próprio; declare o custo em número — aqui é peso no bundle e superfície de CVE transitiva, não módulos linkados. A barra sobe conforme a proximidade do núcleo: lib que entra num componente é diferente de lib que entra na camada de dados ou no formato do que se persiste.
• Não superdesenhe. Calibre a complexidade pelo mini-mundo. Sistema pequeno não precisa de 5 personas e 10 jornadas. Cada fase explicita esse julgamento.
• Não invente requisitos. Se o usuário não disse, não escreva como se ele tivesse dito. Quando faltar info, pergunte.
• Não desenhe telas antes da fase 2. Discovery é sobre quem/quê/por quê. Telas vêm depois.
• Em modo evolução: editar, não reescrever; escopo = fatia; sem commit de entrega. O mockup de UX da história é promovido a spec de componente ANTES de construir; a análise de impacto para no checkpoint humano. Exceção nomeada — o commit de congelamento: o spec da fatia é commitado antes do despacho dos agents (docs(ui): congela spec da fatia CHG-NNN), porque ele é o contrato de convergência e o hash é o registro da versão que cada agent leu. Essa exceção cobre artefato de contrato, nunca código de produção nem a entrega — quem aterrissa continua sendo a feature-loop, e a aterrissagem confere que os commits de congelamento tocaram só docs/. Superfície testável existente (testids/copy/roles assertados) só muda com decisão registrada. Artefatos existentes são editados com entrada no histórico de revisões (CHG-NNN). Lacuna de produto/UX devolve o card à feature-loop.

Agents (dependências)

A fase 4 despacha agents dedicados em paralelo (não general-purpose). Eles devem estar instalados em ~/.claude/agents/:

Os dois rodam em paralelo, cegos um pro outro, e convergem pelo spec de componente (superfície testável: props, estados, copy, data-testid/roles) + os tipos da OpenAPI + as signatures dos hooks de api.ts. Os agents são versionados junto com a skill (mesmo repo).

Se o cumprimento de uma instrução depende de um parâmetro de tool, a instrução nomeia o parâmetro — ou é decoração. Escrever "despache ambos em Sonnet" não garante nada: sem model na chamada da tool Agent, o agent herda o modelo da sessão, e ninguém percebe — não há erro, não há aviso, a instrução parece cumprida. Vale para model, isolation, subagent_type e execução em background. É a mesma classe de falha que a regra "separe o julgamento pela ferramenta, não pela promessa" nomeia para permissão, aplicada a capacidade.

isolation: "remote" tem uma pré-condição silenciosa: o estado que o agent vai ler precisa existir no remoto. Antes de despachar remoto, verifique e reporte: (a) a branch tem upstream; (b) HEAD está publicado; (c) os artefatos que o agent precisa ler (specs, stubs, contratos) estão rastreados e commitados. Se qualquer um falhar, apresente a escolha ao usuário (publicar × rodar local) em vez de despachar — a falha aqui não é um erro, são dois agents produzindo trabalho plausível contra a árvore errada. E satisfazer a pré-condição exige push, que é ação externa: decisão humana, nunca passo automático.

Agent faltante — diagnostique antes de prescrever. Agent type '<nome>' not found tem dois modos de falha, com remediações diferentes e incompatíveis. Rode ls ~/.claude/agents/ antes de reportar:

• arquivo ausente → instalar o agent (estão em agents/ no repo da skill);
• arquivo presente, tipo não registrado → a lista de agents de uma sessão em execução não relê o disco. Só sessão nova resolve; pedir recarga em sessão viva não tem efeito e queima um ciclo de ida e volta com o usuário.

Agent que morreu no meio pode ter entregado. Estouro de limite de gasto, timeout ou interrupção deixam o que já foi escrito intocado em disco — o que não voltou foi o relato, não necessariamente o trabalho. Antes de propor reexecução, liste os artefatos que ele deveria ter produzido e reporte o que existe. Reexecutar às cegas paga de novo exatamente quando o orçamento acabou, e o agent novo pode sobrescrever com outra variante arquivos que o par cego já consumiu.

Arquivos

• phases/01-discovery.md — método de UX discovery (personas, JTBD, jornadas, requisitos NF, restrições)
• phases/02-ia-flows.md — método de IA e fluxos (mapa de telas, navegação, controles transversais)
• phases/03-design-system.md — método de design system (tokens, catálogo, spec por componente)
• phases/04-implementation.md — orquestrador: fundação + cortes verticais despachando os 2 agents
• phases/evolution.md — modo evolução (brownfield): promoção do mockup a spec + análise de impacto com checkpoint duro → construção cirúrgica → evolução de artefatos; entrada CHG-NNN, entrega sem commit (exceto o congelamento do spec)
• templates/01-discovery.md.tmpl — template do artefato de discovery
• templates/02-ia-flows.md.tmpl — template do artefato de IA & fluxos
• templates/03-design-system.md.tmpl — template do artefato de design system (tokens + catálogo + specs)
• templates/component-spec.md.tmpl — spec de componente (contrato de convergência dos agents)
• templates/stacks/vite-react-ts.md — convenções da stack default
• agents/ui-component-code-generator.md, agents/ui-component-test-generator.md — agents da fase 4