a9a7a328e6
Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD across contents and paths, upstream package/repo coordinates -> @golem15/msd-core and golem15com/msd-core. Deep links into upstream history, sibling upstream packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is. Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line, package/plugin identity, regenerated lockfile, install-tree fixtures, derived registries and benchmark baseline; migration checksum baseline re-locked (MSD keeps its own install state, so no install had applied the old sums); sort-order and regex-escaped expectations in tests adjusted.
150 lines
7.5 KiB
Markdown
150 lines
7.5 KiB
Markdown
# Como projetar uma fase de UI
|
|
|
|
**Objetivo:** Produzir um contrato de design de UI bloqueado (`UI-SPEC.md`) que fixe decisões de espaçamento, cores, tipografia e textos antes que o planejador escreva as tarefas, prevenindo inconsistências visuais causadas por escolhas de estilo ad-hoc durante a execução.
|
|
|
|
**Pré-requisitos:** `.planning/ROADMAP.md` deve existir. A fase precisa ter trabalho de frontend ou UI. Executar `/msd-discuss-phase N` antes é fortemente recomendado — o pesquisador de UI lê `CONTEXT.md` para evitar fazer perguntas sobre decisões que você já tomou.
|
|
|
|
---
|
|
|
|
## Decida se esta fase precisa de um contrato de UI
|
|
|
|
Nem todas as fases precisam de `/msd-ui-phase`. Use quando:
|
|
|
|
- A fase introduz novas superfícies de UI (páginas, fluxos, layouts)
|
|
- Vários componentes serão construídos e a consistência visual é importante
|
|
- Você está iniciando o frontend de um novo projeto e precisa de uma linha de base do sistema de design
|
|
- Você está adicionando trabalho significativo de UI a um projeto existente e deseja bloquear tokens, espaçamento e cores antes da execução
|
|
|
|
Pule quando:
|
|
|
|
- A fase é puramente de backend, infraestrutura ou dados, sem saída voltada ao usuário
|
|
- Um UI-SPEC.md já existe para uma fase anterior e esta fase constrói sobre padrões visuais idênticos sem introduzir novas superfícies
|
|
|
|
Se não tiver certeza, a trava de segurança irá alertá-lo: quando `workflow.ui_safety_gate` está habilitado (padrão), `/msd-plan-phase` avisa ao detectar trabalho de frontend sem `UI-SPEC.md` e pergunta se deve executar `/msd-ui-phase` primeiro.
|
|
|
|
---
|
|
|
|
## Execute o contrato de design de UI
|
|
|
|
```bash
|
|
/msd-ui-phase 2
|
|
```
|
|
|
|
Se nenhum número de fase for fornecido, o MSD Core usa a fase atual como alvo.
|
|
|
|
O comando é executado em dois estágios:
|
|
|
|
1. **`msd-ui-researcher`** — lê `CONTEXT.md`, `RESEARCH.md` e `REQUIREMENTS.md` em busca de decisões existentes, detecta o estado do sistema de design (shadcn `components.json`, configuração do Tailwind, tokens existentes), e faz apenas as perguntas de design não respondidas em cinco áreas: espaçamento, cores, tipografia, textos e segurança do registro.
|
|
2. **`msd-ui-checker`** — valida o `UI-SPEC.md` resultante em sete dimensões. Se problemas forem encontrados, um ciclo de revisão reexecuta o pesquisador (até duas iterações) visando apenas os itens sinalizados.
|
|
|
|
**Saída:** `{padded_phase}-UI-SPEC.md` em `.planning/phases/{phase-dir}/`.
|
|
|
|
---
|
|
|
|
## O que o UI-SPEC cobre
|
|
|
|
O pesquisador bloqueia decisões em cinco áreas:
|
|
|
|
| Área | Exemplos |
|
|
|---|---|
|
|
| **Espaçamento** | Escala base (4px ou 8px), alinhamento de grid, padding de componentes |
|
|
| **Cores** | Paleta primária, de destaque e neutra; regra 60/30/10; considerações de modo escuro |
|
|
| **Tipografia** | Famílias de fontes, restrições de escala de tamanho/peso, hierarquia de títulos |
|
|
| **Textos** | Rótulos de CTA, mensagens de estado vazio, textos de estado de erro, indicadores de carregamento |
|
|
| **Segurança do registro** | Protocolo de inspeção de componentes shadcn (veja abaixo) |
|
|
|
|
O verificador valida a especificação em suas sete dimensões — Textos, Visuais, Cores, Tipografia, Espaçamento, Segurança de Registro e Proveniência do Inventário — retornando PASS, FLAG ou BLOCK para cada uma. (A rubrica de 6 pilares com pontuação de 1 a 4 pertence à auditoria retroativa do `/msd-ui-review`, não a este verificador.)
|
|
|
|
---
|
|
|
|
## Inicialização do shadcn
|
|
|
|
Para projetos React, Next.js e Vite, o pesquisador oferece inicializar o shadcn se nenhum `components.json` for encontrado. O fluxo:
|
|
|
|
1. Acesse `ui.shadcn.com/create` e configure seu preset (cores, raio de borda, fontes)
|
|
2. Copie a string do preset
|
|
3. Execute:
|
|
|
|
```bash
|
|
npx shadcn init --preset <cole aqui>
|
|
```
|
|
|
|
A string do preset torna-se um artefato de planejamento de primeira classe do MSD Core, reproduzível entre fases e marcos.
|
|
|
|
---
|
|
|
|
## Trava de segurança do registro
|
|
|
|
Registros shadcn de terceiros podem injetar código arbitrário. Quando `workflow.ui_safety_gate` está habilitado (padrão), a especificação exige estas etapas antes de instalar qualquer componente não oficial:
|
|
|
|
```bash
|
|
npx shadcn view <component> # inspect source before installing
|
|
npx shadcn diff <component> # compare against the official registry
|
|
```
|
|
|
|
O verificador sinalizará a especificação como BLOCKED se a segurança do registro não for tratada. Desative a trava via `/msd-settings` se o seu projeto não usa shadcn ou você tem um processo alternativo de verificação.
|
|
|
|
---
|
|
|
|
## Use os achados do sketch como ponto de partida
|
|
|
|
Se você já executou `/msd-sketch --wrap-up`, o pesquisador de UI carrega `.claude/skills/sketch-findings-[project]/` automaticamente. Decisões pré-validadas (layout, paleta, tipografia, espaçamento) são tratadas como bloqueadas — o pesquisador não as pergunta novamente. Você verá uma nota no início da execução:
|
|
|
|
```text
|
|
⚡ Sketch findings detected: .claude/skills/sketch-findings-[project]/SKILL.md
|
|
Pre-validated decisions (layout, palette, typography, spacing) should be treated
|
|
as locked — not re-asked.
|
|
```
|
|
|
|
Esta é a principal razão para executar `/msd-sketch --wrap-up` antes de `/msd-ui-phase`: transforma a exploração conversacional de design em entrada vinculante para o contrato.
|
|
|
|
---
|
|
|
|
## Auditoria visual retroativa com `/msd-ui-review`
|
|
|
|
`/msd-ui-review` é executado após a execução, não antes. Use-o para auditar o frontend implementado em relação ao UI-SPEC (ou em relação aos padrões abstratos de 6 pilares quando nenhuma especificação existir).
|
|
|
|
```bash
|
|
/msd-ui-review # audit the current phase
|
|
/msd-ui-review 3 # audit phase 3 specifically
|
|
```
|
|
|
|
Funciona em qualquer projeto com código frontend — a inicialização de projeto MSD não é necessária.
|
|
|
|
**O que verifica (6 pilares, pontuação de 1 a 4 cada):**
|
|
|
|
1. Textos — rótulos de CTA, estados vazios, estados de erro
|
|
2. Visuais — pontos focais, hierarquia visual, acessibilidade de ícones
|
|
3. Cores — disciplina de uso de destaque, conformidade 60/30/10
|
|
4. Tipografia — aderência às restrições de tamanho e peso de fonte
|
|
5. Espaçamento — alinhamento de grid, consistência de tokens
|
|
6. Design de Experiência — cobertura de estados de carregamento, erro e vazio
|
|
|
|
**Saída:** `{padded_phase}-UI-REVIEW.md` com pontuações e as três principais correções prioritárias. Quando um servidor MCP de navegador como `msd-browser` estiver configurado, a auditoria também captura capturas de tela com evidências visuais.
|
|
|
|
**Armazenamento de capturas de tela:** As capturas de tela são salvas em `.planning/ui-reviews/`. Um `.gitignore` é criado automaticamente para evitar que arquivos binários cheguem ao git. As capturas de tela são limpas durante `/msd-complete-milestone`.
|
|
|
|
---
|
|
|
|
## Posição recomendada no ciclo de vida da fase
|
|
|
|
```text
|
|
/msd-discuss-phase N ← lock implementation preferences
|
|
/msd-ui-phase N ← lock design contract (frontend phases)
|
|
/msd-plan-phase N ← research + plan (reads UI-SPEC.md as context)
|
|
/msd-execute-phase N ← parallel execution
|
|
/msd-verify-work N ← manual UAT
|
|
/msd-ui-review N ← retroactive visual audit (optional but recommended)
|
|
```
|
|
|
|
`/msd-ui-phase` fica entre discussão e planejamento porque o planejador lê `UI-SPEC.md` como contexto de design — as tarefas em `PLAN.md` referenciam tokens de espaçamento, variáveis de cores e decisões de textos que a especificação bloqueou.
|
|
|
|
---
|
|
|
|
## Relacionados
|
|
|
|
- [Spike e sketch](spike-and-sketch.md)
|
|
- [Planejar uma fase](plan-a-phase.md)
|
|
- [Comandos](../COMMANDS.md)
|
|
- [Índice de documentação](../README.md)
|