@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/framework/skills/core/morph-uiux/SKILL.md

@@ -1,160 +1,102 @@
 ---
 name: morph-uiux
-description: Conduz a fase opcional de UI/UX — design system, mockups, componentes e fluxos — entre o Gate 1 e o plan, despachando a persona ui-designer para o trabalho visual.
+description: Conduz a fase opcional de UI/UX de uma feature com plano aprovado — design system, mockups com checklist de tela, componentes e fluxos — despachando a persona ui-designer, e apresenta o Gate uiux antes da implementação.
 version: core
-when_to_use: Use quando o ramo uiux for tomado (morph-spec advance --design), depois do Gate 1 e antes do morph-plan
+when_to_use: Use quando o ramo de design for tomado (morph-spec advance {feature} --design, depois do gate do plano) e antes de /morph-apply
 user-invocable: true
-cliVersion: "8.47.0"
+cliVersion: "9.1.0"
 ---
 
 # morph-uiux
 
-## Objetivo
-
-Produzir os artefatos de `1-design/` com qualidade de produção — boas práticas de UI/UX, usabilidade, consistência com o padrão visual do projeto, tecnologia de ponta do stack instalado — e apresentar o Gate uiux antes de entregar a feature ao `morph-plan`.
-
-## Quando invocar
-
-Ao tomar o ramo opcional uiux: feature/bug cuja mudança cria ou altera superfície de UI (componente, página, tela, estilo, fluxo de navegação) — critério objetivo em `MORPH.md` §2.1. Normalmente invocada pela `morph-proposal` logo após o Gate 1, via `morph-spec advance {feature} --design`. Sem essa condição a feature segue direto para `morph-plan` e esta skill nunca é chamada.
-
-## O que fazer
-
-1. **Garanta os insumos em contexto** — use a tool Read se não estiver:
-   - `.morph/features/{feature}/0-proposal/proposal.md` — problema, escopo, usuários e fluxos.
-   - `.morph/context/design-system.md` (se existir) — o design system **vivo** do projeto: toda decisão de token/componente parte dele, nunca do zero. Ausente → greenfield de design; use `.morph/framework/templates/context/design-system.md` como forma de partida.
-   - `.morph/config/config.json` → `project.stack` — decide a tecnologia de ponta a aplicar (`nextjs` → Tailwind + shadcn + Framer Motion; outro stack → o equivalente idiomático dele). Nunca hardcode Next.js quando o stack detectado é outro.
-   - `.morph/features/{feature}/0-proposal/stack-scan.md` (se existir) — desvios de stack já detectados.
-
-2. **Princípios de qualidade** (decisão do produto — não são opcionais):
-   - **Usabilidade e acessibilidade:** WCAG AA, todos os estados de componente interativo cobertos (default/hover/focus/disabled/loading/error) — não só o caminho feliz.
-   - **Consistência:** reusa tokens/componentes existentes de `.morph/context/design-system.md` antes de criar novos; um token novo precisa de justificativa (o existente não cobre o caso).
-   - **Tecnologia de ponta condicionada ao stack real** (passo 1) — nunca a suposição de que o projeto é Next.js.
-   - **Sistemas, não telas isoladas** — mesmo critério da persona `ui-designer`: componentes reutilizáveis antes de composições de uso único.
-   - **Toda tela sai com o checklist de tela preenchido** (template no passo 3) — a superfície, o volume esperado de dados, paginação, ordenação, filtro, os três estados (vazio, carregando, erro), o comportamento no mobile e abas × página longa. "Não se aplica" vale, **desde que escrito**. É o checklist que faz a lista de 2 000 linhas paginar: o que o design não decide não vira `doneCriteria` (`morph-plan` §5d), e o que não é critério ninguém entrega. Tela de dados segue os standards de `admin-app` (lista/tabela, formulário, feedback, estrutura de página), que a persona cita na superfície `admin-app`.
-
-3. **Despache `morph-ui-designer`** para o trabalho visual — dispatch é o default aqui (domínio diferente do Orchestrator, MORPH.md §6). `morph-ui-designer` tem o escopo das implementadoras (com Bash) + `Skill` + MCPs `stitch`/`playwright`/`context7`/`graphify` + o MCP de mídia morph-assets (imagem e vídeo). Bash serve para `morph-spec standards --find`, `npx`, screenshot e leitura de `git`; build/test da suíte, `verify` e aprovação de gate continuam do orquestrador (cláusula 3, como nas outras personas).
-
-   **Persona universal** (`ui-designer.stack = ["*"]` em `agents.json`, mesmo mecanismo de `evaluator`/`scout`): UI/UX importa sempre que há superfície de UI, então o subagent está registrado em **todo** projeto — .NET/Blazor incluído, não só Next.js. **Fallback** (caso raro: instalação anterior a essa mudança, `.claude/agents/morph-ui-designer.md` ainda não regenerado): `general-purpose` colando o campo `persona` (Read em `.morph/framework/agents.json`) no prompt, registrando o fallback no relatório — resolvido rodando `morph-spec setup-infra --reinstall`.
-
-   Template do prompt (contrato do relatório em forma curta — copia o padrão de `morph-implement` §4; a cláusula de build/isolamento vira "sem build/test da suíte", porque o design não entrega código a verificar):
-   ```
-   Produzir os artefatos de UI/UX de [feature] em `.morph/features/{feature}/1-design/`.
-
-   Contexto: [problema/escopo do proposal.md] + design system atual
-   (`.morph/context/design-system.md`, tokens/componentes a reusar) + stack: [stack real do config.json]
-
-   Produza, NESTA ORDEM — design-system.md primeiro, os demais só como aplicável ao escopo:
-   1. `design-system.md` — tokens (cor, tipografia, espaço, motion) consistentes com o projeto
-   2. `mockups.md` — descrição estruturada de cada tela nova/alterada (+ imagem via MCP
-      stitch ou o MCP de mídia (imagem/vídeo) quando disponível; fallback: descrição textual detalhada).
-      Cada tela é um `## Tela: <nome>` e traz, dentro dela, o checklist abaixo, com cada `…`
-      trocado pela decisão — "não se aplica" vale se escrito; `…`, vazio ou "a definir" não.
-      O que cada item decide: Superfície (admin-app | marketing-site — ela escolhe que
-      standards você lê para ESSA tela, seção "Standards by surface" da sua persona),
-      Volume esperado (registros hoje e em 1 ano), Paginação (servidor, N por página — ou
-      por que não pagina), Ordenação (colunas + padrão, no servidor), Filtro (filtros e
-      busca, no servidor), Estado vazio (sem registros × sem resultado para o filtro),
-      Estado carregando, Estado de erro (mensagem + como tentar de novo), Mobile (o que a
-      tela vira abaixo de md), Abas (abas × página longa × wizard, e por quê).
-      ### Checklist de tela
-      | Item | Decisão |
-      |---|---|
-      | Superfície | … |
-      | Volume esperado | … |
-      | Paginação | … |
-      | Ordenação | … |
-      | Filtro | … |
-      | Estado vazio | … |
-      | Estado carregando | … |
-      | Estado de erro | … |
-      | Mobile | … |
-      | Abas | … |
-   3. `components.md` — inventário de componentes novos/reusados, com props e os estados do
-      princípio 2 acima
-   4. `flows.md` — fluxos de navegação/interação entre as telas
-
-   Done quando: os artefatos aplicáveis existem, cada um cita os tokens/componentes do
-   design-system.md em vez de reinventar valores soltos, e toda `## Tela:` do mockups.md
-   tem o checklist completo.
-
-   Contrato do relatório final:
-   1. GRAVE um relatório por artefato produzido em
-      `1-design/reports/[artefato]-report.md` (ex.: `1-design/reports/design-system-report.md`)
-      ANTES de encerrar — é o retorno autoritativo, não a sua mensagem final (cortesia
-      best-effort, pode não chegar inteira). NÃO chame SendMessage.
-   2. Bash só para consulta (`morph-spec standards --find`, `npx`, screenshot, `git log/diff`):
-      NÃO rode build, testes nem `morph-spec verify`/`approve`/`advance` — a verificação e a
-      aprovação do Gate uiux são do orquestrador.
-   3. NÃO toque em tasks.json, feature.json, state.json nem no board de sessão.
-
-   Cada relatório contém: (1) o que foi feito em 2-3 frases, (2) o artefato produzido,
-   (3) decisões de design e por quê (token reusado vs. novo, padrão de acessibilidade
-   aplicado), (4) o que ficou em aberto. Relatório ausente ou oco é falha de protocolo.
-   ```
-
-   Após o retorno: **leia primeiro** `1-design/reports/*-report.md` — valor de retorno autoritativo, a mensagem de texto é atalho best-effort quando chega inteira. `design-system.md` é o único output obrigatório (`phases.json → uiux.requiredOutputs`); sem ele em disco, `morph-spec advance` recusa avançar — confirme que existe antes de rodar `advance` no passo 6.
-
-4. **Atualize o design system vivo do projeto** — se a Parte 3 introduziu tokens/componentes novos, aplique o mesmo protocolo do `morph-brainstorming` (Parte 0): **reescreva o corpo** de `.morph/context/design-system.md` com a adição — o token ou a regra que mudou é substituído na própria seção, nunca empilhado ao lado do antigo — e registre no changelog só data e motivo. `1-design/design-system.md` é o artefato **da feature** (o que ela usa/introduz); `.morph/context/design-system.md` é o acervo vivo do **projeto** — não confunda os dois.
-
-5. **Os artefatos alimentam o `morph-plan` seguinte.** Use cases e tasks de UI referenciam `1-design/mockups.md`/`components.md` **por path** (ex.: doneCriteria citando a seção do mockup) — não redigite conteúdo visual em `spec.md`.
-
-6. Apresente o Gate uiux.
-
-   Rode `morph-spec gate-check {feature} uiux [--json]` — mesma mecânica de `morph-plan`/`morph-review`: lê `trust`, decide via `shouldPauseGate` e persiste `gateDecisions.uiux` com timestamp server-side. **O checklist de tela é cobrado aqui, por código:** com `1-design/mockups.md` presente, tela sem o bloco, item ausente, resposta vazia ou "a definir" — ou nenhuma `## Tela:` — **pausa** o gate nomeando tela e item (`signals.screenChecklist`), e o `approve`/`advance` com assinatura `auto` recusam encerrar a fase pela mesma regra (só o mockup no formato antigo, telas `## S001:`, é isento — e o sinal diz isso). Complete o mockup antes de apresentar o gate: não peça ao humano que aprove um design que ainda não decidiu se a lista pagina. Divergência de design-system detectada aqui (fonte do projeto vs. o que a feature precisa) é uma das poucas chaves que `--signals` aceita sobrescrever:
-   ```
-   morph-spec gate-check {feature} uiux --signals '{"designSystemDivergence":true}'
-   ```
-
-   **Se `pause === true`**, use `AskUserQuestion`:
-   ```
-   question: "Gate uiux — Design de {feature} aprovado?{ reason ? ' Sinal: ' + reason : '' }"
-   header: "Gate uiux"
-   options:
-     - { label: "aprovado, prosseguir", description: "Aceitar design-system/mockups/components/flows e avançar para o plano" }
-     - { label: "preciso ajustar", description: "Apontar mudanças no design antes de prosseguir" }
-     - { label: "cancelar feature", description: "Abortar" }
-   ```
-
-   Aguardar resposta. Se "preciso ajustar", aplicar e reapresentar.
-
-   **Hook state-sync reconhece este gate, como os demais.** Igual a Gate 1/2/3, o hook `state-sync.js` (`gateFromQuestion`) reconhece o texto "Gate uiux" — uma resposta "aprovado" ao template acima grava sozinha `approvalGates.uiux = { approved: true, timestamp, approvedBy: "manual" }` no `feature.json` autoritativo, atribuído pelo nome da feature que a pergunta cita (MORPH.md §5). Sem nome na pergunta, ou fora de `AskUserQuestion` (headless/CI): aprove explicitamente:
-   ```
-   morph-spec approve {feature} uiux --approver <quem respondeu>
-   # ou, para já aprovar e criar 2-plan/ num passo só:
-   morph-spec advance {feature} --approver <quem respondeu>
-   ```
-   (o `--approver` importa aqui: sem ele, num terminal não-interativo `advance`/`approve` resolvem `approvedBy: "auto"` — que MORPH.md §5 proíbe registrar quando quem aprovou foi um humano.)
-
-   **Se `pause === false`** (auto-aprovação, sem `AskUserQuestion`), exibir summary curto e já aprovar via CLI:
-   ```
-   ## Gate uiux (auto-aprovado)
-
-   **Design system:** {tokens novos, se houver} | **Mockups:** {N telas}
-   **Components:** {N novos / N reusados} | **Flows:** {N fluxos}
-   ```
-   ```
-   morph-spec advance {feature}
-   ```
-
-   Os 4 outputs de `1-design/` (`protected: true, approvalGate: 'uiux'`) travam na aprovação — retrabalho de design depois do gate passa pelo gate de novo (revogar, ajustar, reapresentar), nunca por Edit direto no arquivo travado.
-
-   **Próximo passo (não é desta skill):** com o Gate uiux aprovado e `2-plan/` criado, devolva o controle a quem invocou (`morph-proposal`, passo 4/5) — ela invoca `Skill(morph-plan)`. Não invoque `morph-plan` diretamente daqui.
-
-## Output esperado
-
-- `.morph/features/{feature}/1-design/design-system.md` — obrigatório
-- `.morph/features/{feature}/1-design/mockups.md`, `components.md`, `flows.md` — conforme o escopo exigir; no `mockups.md`, toda `## Tela:` com o `### Checklist de tela` completo (cobrado pelo `gate-check uiux` e pelo `approve`/`advance` com assinatura `auto`)
-- `.morph/features/{feature}/1-design/reports/*-report.md` — relatório(s) bruto(s) do `morph-ui-designer` despachado no passo 3
-- `.morph/context/design-system.md` com o corpo reescrito (se tokens/componentes novos entraram) e uma entrada de changelog (data, motivo)
-- Gate uiux registrado aprovado em `.morph/features/{feature}/feature.json` (autoritativo)
-
-## Referências
-
-- `.morph/framework/MORPH.md` §2.1 — critério objetivo de entrada no ramo uiux
-- `.morph/framework/MORPH.md` §6 — protocolo de dispatch e contrato do relatório final
-- `.morph/framework/MORPH.md` §5 — regras de pausa de gate (trust mode)
-- `.morph/framework/agents.json` — persona `ui-designer` (tools, MCPs, standards; `surfaces` separa os de `marketing-site` e os de `admin-app`)
-- `.morph/framework/standards/frontend/admin-app/` — lista e tabela, formulário, confirmação e toast, abas × página longa × wizard: o que o checklist de tela decide numa tela de dados
-- `.morph/framework/templates/context/design-system.md` — forma de partida quando o projeto não tem design system vivo
-- `.claude/skills/morph-brainstorming/SKILL.md` — protocolo de reconciliação/changelog do design-system vivo (Parte 0), reaplicado no passo 4
-- `.claude/skills/morph-plan/SKILL.md` — consome os artefatos desta fase por path
+Entra depois do gate do plano, quando a `morph-plan` §6 decidiu que a feature cria ou altera superfície de UI (componente, página, tela, estilo, fluxo de navegação). Sai com `1-design/` aprovado; o próximo passo é `/morph-apply {feature}`.
+
+## 1. Insumos
+
+- `2-plan/plan.md` — problema, cenários e as fatias de UI (`persona: ui-designer`, com `superfície:`). O plano está congelado: esta fase **nunca** edita `plan.md` nem `checks.json`; refere as fatias pelo id (`F2`).
+- `.morph/context/design-system.md` — o design system **vivo**: toda decisão de token ou componente parte dele. Ausente, o `advance --design` já o escreveu a partir do template do pacote como forma de partida.
+- `.morph/config/config.json` → `project.stack` decide a tecnologia (`nextjs` → Tailwind + shadcn + Framer Motion; outro stack, o equivalente idiomático). Nunca suponha Next.js.
+- `2-plan/stack-scan.md`, se existir.
+
+## 2. Princípios (não são opcionais)
+
+- WCAG AA e todos os estados de componente interativo (default/hover/focus/disabled/loading/error), não só o caminho feliz.
+- Reusa token e componente existentes antes de criar; token novo precisa de justificativa. Sistemas, não telas isoladas.
+- **Toda tela sai com o checklist de tela preenchido.** O `advance --design` já escreveu `1-design/mockups.md` a partir do template do pacote, a fonte única dos dez itens (tabela `### Checklist de tela` dentro de cada `## Tela:`). "Não se aplica" vale se escrito; `…`, vazio ou "a definir" reprovam. Design sem tela nova ou alterada (só componente ou estilo): apague o `1-design/mockups.md` semeado. É o checklist que faz a lista de 2 000 linhas paginar: o verificador do Gate 3 cobra cada item decidido em `## Checklist de tela`. Tela de dados segue os standards de `admin-app` (lista/tabela, formulário, feedback, estrutura de página); login, onboarding, primeira tela, estado vazio de destaque e sucesso são `brand-moment`.
+- **Conformidade não basta: a régua estética vale junto.** Direção escrita antes de componente (`1-design/direcao.md`: conceito, metáfora, o que torna a tela memorável, o que ela não pode parecer; 2 ou 3 direções para tela nova ou momento de marca), celular desenhado e não derivado, movimento com versão estática digna. A régua é o standard `frontend-design-system-art-direction`.
+- **Toda tela nova ou alterada tem protótipo renderizado e conferido por print.** `1-design/prototipos/{tela}.html` autossuficiente, com os tokens reais do projeto (lidos do CSS de tokens), desktop e celular lado a lado, controles animado/estático/pausar; prints `{tela}-1280.png` e `{tela}-390.png` ao lado, saídos do laço de autocrítica. A `## Tela:` aponta o protótipo na linha `**Protótipo:**`.
+
+## 3. Dispatch
+
+Despache `subagent_type: "morph-ui-designer"` — persona universal, registrada em todo projeto. Não registrado (instalação antiga): `general-purpose` com o campo `persona` de `.morph/framework/agents.json` colado no prompt, registrando o fallback; resolve com `morph-spec setup-infra --reinstall`. O corpo da persona já carrega o contrato fixo (teto de turnos, relatório `PARCIAL`); o prompt leva só o que varia:
+
+```
+Feature [feature]: artefatos de UI/UX em `.morph/features/[feature]/1-design/`.
+Plano: `2-plan/plan.md` — fatias de UI [F2 (admin-app), F3 …]. Stack: [project.stack].
+Design system: `.morph/context/design-system.md` (tokens e componentes a reusar).
+
+Nesta ordem, só o aplicável ao escopo:
+1. `1-design/direcao.md` — antes de qualquer componente: conceito em uma frase, metáfora visual,
+   o que torna a tela memorável, o que ela NÃO pode parecer. Tela nova ou momento de marca:
+   2 ou 3 direções distintas, uma recomendada com o porquê (standard `frontend-design-system-art-direction`).
+2. `1-design/design-system.md` (obrigatório: sem ele o `advance` recusa) — tokens (cor, tipografia, espaço, motion) que a feature usa ou acrescenta, lidos do CSS de tokens real do projeto; token novo também reescreve `.morph/context/design-system.md` (§4).
+3. `1-design/prototipos/{tela}.html` por tela nova ou alterada — autossuficiente, tokens reais,
+   desktop e celular (folha inferior, zona do polegar, 44px) lado a lado em moldura de aparelho,
+   controles animado/estático/pausar e `prefers-reduced-motion`. Laço de autocrítica: sirva a pasta
+   por HTTP local (o Playwright MCP recusa `file:`), print em 1280 e em 390 (`{tela}-1280.png`,
+   `{tela}-390.png` ao lado do HTML), avalie (hierarquia, contraste, ritmo, celular, "parece template?"),
+   corrija e repita até passar.
+4. `mockups.md` — um `## Tela: <nome>` por tela nova ou alterada, com a fatia que a entrega, a linha
+   `**Protótipo:** 1-design/prototipos/{tela}.html` e a tabela `### Checklist de tela` que o
+   `advance --design` já escreveu em `1-design/mockups.md`, cada item decidido.
+5. `components.md` — componentes novos e reusados, com props e estados.
+6. `flows.md` — navegação entre as telas.
+
+Relatório por artefato em `1-design/reports/[artefato]-report.md`: o que foi feito (2-3 frases),
+o artefato, as decisões de design e por quê, o que ficou aberto; o do protótipo lista as rodadas
+do laço e o que cada uma corrigiu. É o retorno; a mensagem final é cortesia.
+Bash só para consulta (`morph-spec standards --find`, `npx`, screenshot, `git log/diff`) e para o
+servidor estático do protótipo (`npx http-server <pasta> -p <porta>` em background; ao fim, encerre
+esse processo pelo id do background ou pelo PID dono da porta, nunca por nome de executável):
+sem build, teste, `verify`, `approve` ou `advance`.
+Não toque `feature.json`, `state.json`, `plan.md` nem `checks.json`.
+```
+
+Ao retomar, **leia primeiro** `1-design/reports/*-report.md`. `design-system.md` é o único output obrigatório: sem ele, o `advance` recusa.
+
+## 4. Design system vivo
+
+Tokens ou componentes novos: aplique o protocolo da `morph-plan` §2 — **reescreva o corpo** de `.morph/context/design-system.md` (o valor que mudou substitui o antigo na própria seção) e registre no changelog só data e motivo. `1-design/design-system.md` é da feature; `.morph/context/design-system.md` é do projeto.
+
+## 5. Todo aviso de capacidade tem destino
+
+Antes do gate:
+
+```bash
+grep -riE "capacidade nova|precisa de backend|dimensionar junto" .morph/features/{feature}/1-design/
+```
+
+Cada ocorrência **nunca fica sem destino**: a fatia do plano que já a cobre (cite o id no mockup), uma exclusão registrada no `mockups.md` com o motivo, ou — se é escopo novo — `morph-spec unapprove {feature} plan`, ajuste do plan.md, `morph-spec plan-check {feature}` e o gate do plano de novo. Sem hits, o passo é um no-op.
+
+## 6. Gate uiux
+
+```
+morph-spec gate-check {feature} uiux [--json]
+```
+
+O checklist é cobrado por código: tela sem a tabela, item ausente ou não decidido, ou nenhuma `## Tela:` **pausa** o gate nomeando tela e item, e `approve`/`advance` com assinatura `auto` recusam pela mesma regra (só o mockup antigo, telas `## S001:`, é isento). Com o checklist completo, cada tela ainda deve o protótipo: sem a linha `**Protótipo:**`, o HTML ou um dos prints de 1280/390, o gate **pausa** nomeando a tela e o arquivo. Complete o mockup antes de apresentar: não peça aprovação de um design que ainda não decidiu se a lista pagina, nem de um que ninguém renderizou.
+
+**Apresente o design aberto, não descrito.** Antes da pergunta do gate, abra cada protótipo no navegador do usuário (sirva `1-design/prototipos/` por HTTP local e abra a URL: `start` no Windows, `open` no macOS, `xdg-open` no Linux) e cite a direção escolhida de `direcao.md` em uma frase. Divergência de design system vista aqui: `--signals '{"designSystemDivergence":true}'`.
+
+**`pause === true`**: `AskUserQuestion`, header "Gate uiux":
+
+```
+question: "Gate uiux — Design de {feature} aprovado?{ reason ? ' Sinal: ' + reason : '' }"
+options: "aprovado, prosseguir" | "preciso ajustar" | "cancelar feature"
+```
+
+O hook `state-sync` reconhece "Gate uiux" e grava a aprovação pela feature nomeada. Sem `AskUserQuestion` (headless): `morph-spec advance {feature} --approver <quem>` — sem `--approver`, um terminal não interativo grava `approvedBy: "auto"` num gate que um humano aprovou.
+
+**`pause === false`**: resumo (tokens novos, N telas, componentes novos/reusados, fluxos) e `morph-spec advance {feature}`.
+
+Aprovado o gate, os quatro artefatos de `1-design/` travam: retrabalho de design passa pelo gate de novo, nunca por Edit no arquivo travado. Diga ao usuário que `/morph-apply {feature}` está pronto; não despache a apply.