Referências Visuais

Quando uma feature tem tela, você quer que o código saia parecido com o que foi desenhado. Arraste um print no chat, passe o caminho de um arquivo, cole um link do Figma, ou descreva a tela em texto.

Na v3 a referência não fica solta: ela é matéria-prima para o contrato duplo de UX (DESIGN.md + EXPERIENCE.md) que a skill makuco-ux produz, e é esse contrato que as tasks de frontend perseguem.

O que você pode mandar

Você tem…	Como mandar	Observação
Print ou mockup (imagem)	Arrasta/cola no chat, ou passa o caminho do arquivo
Protótipo em HTML	Passa o caminho do arquivo `.html`
Link do Figma	Cola o link	Requer integração MCP do Figma ativa e créditos disponíveis
Outro link (protótipo, site no ar…)	Cola o link
Design system / UI kit já adotado	Diz o nome (shadcn, MUI, UIKit, Compose, um DS interno)	Os dois contratos herdam dele; o `EXPERIENCE.md` especifica só o delta
Só uma ideia na cabeça	Descreve a tela em texto

O print e o HTML ficam salvos junto da feature. A referência continua valendo mesmo que um link externo quebre depois.

Quando entrar com a referência

Entre no makuco-analisar. É o momento mais cedo e mais útil: a referência vale para a feature inteira e para todas as PBIs, e chega ao makuco-ux no passo step-05b, antes de qualquer código.

Você também pode entrar com uma referência nova depois, durante o makuco-desenvolver. Uma task de frontend numa PBI sem o par DESIGN.md/EXPERIENCE.md é um gap de UI: o makuco-ux é acionado antes de a task ser emitida, e é aí que a referência nova entra.

Como as referências fluem pelo fluxo

Referências visuais no fluxo das skills

O contrato prevalece sobre o mock

DESIGN.md e EXPERIENCE.md prevalecem sobre qualquer mock, wireframe ou import em caso de conflito. A referência é o insumo; o contrato é a decisão.

Exemplos de como mandar

Print arrastado no chat durante a análise:

Aqui o mockup da tela de login:
[imagem colada]
Os estados são: normal, senha errada, carregando.

Caminho de arquivo no projeto:

A referência está em design/telas/login.png.
O botão "Entrar" usa a cor primária. Sem link "esqueci a senha" por enquanto.

Link do Figma (requer MCP ativo e créditos):

Mockup: https://figma.com/file/abc/login?node-id=12-34
Foca no card central. O resto é placeholder.

Só descrição, sem imagem:

Tela de login centralizada: campo e-mail, campo senha, botão "Entrar".
Erro aparece em vermelho abaixo do campo.

Vale sempre dizer o que a referência NÃO cobre. Assim a skill não inventa o que falta.

O que fica salvo

O contrato de UX, por PBI

.makuco/docs/modules/module_NNN_nome/feature_NNN_nome/pbis/pbi-NNN-slug/
├── DESIGN.md       # identidade visual: tokens (cores, tipografia, espaçamento, componentes)
└── EXPERIENCE.md   # arquitetura de informação, estados, interações, acessibilidade, fluxos-chave

DESIGN.md segue a especificação design.md do Google Labs: tokens no frontmatter YAML + corpo markdown na ordem canônica (Brand & Style · Colors · Typography · Layout & Spacing · Elevation & Depth · Shapes · Components · Do's and Don'ts).

EXPERIENCE.md referencia os tokens do DESIGN.md pela sintaxe {path.to.token} e sempre traz: Foundation · Information Architecture · Voice and Tone · Component Patterns · State Patterns · Interaction Primitives · Accessibility Floor · Key Flows.

O índice de referências da feature

Quando arquivos ou links são registrados, eles ficam indexados em {feature_dir}/references/references.md, com os arquivos locais copiados para {feature_dir}/references/assets/:

# References
 
| ID      | Title             | Type       | File / URL                 | Coverage               |
| ------- | ----------------- | ---------- | -------------------------- | ---------------------- |
| REF-001 | Tela de Login     | png        | assets/login.png           | Login, estados de erro |
| REF-002 | Fluxo de Checkout | html       | assets/checkout-flow.html  | Checkout completo      |
| REF-003 | Design System     | figma-link | https://figma.com/file/abc | Tokens globais         |

Você não precisa criar nem editar esses arquivos — a skill makuco-artifact-reference cuida deles.

Na revisão

O makuco-code-review lê o contrato de UX (e o references/references.md, quando existe) no step-02, e no pass 1 compara a tela implementada com o que foi combinado. Uma tela que divergir do contrato é um achado de conformidade, não uma questão de gosto.