Pages é o inventário oficial de telas e páginas do projeto. Define o propósito de cada tela, quem acessa, quais ações são possíveis, quais informações são exibidas e quais estados precisam ser tratados.
Fase: 3 — Design de Produto
Pré-requisito: Docs/user-stories.md aprovado
Template: Templates/Full/pages.md ou Templates/Quick/pages.md
Artefato oficial: Docs/pages.md
Próximos artefatos: Docs/flow.md · Prototype/ · Docs/design-system.md
Quando criar ou revisar
- Após aprovação de
Docs/user-stories.md - Nova tela identificada em discovery ou refinamento
- Mudança de jornada que reorganiza a navegação
- Tela existente com escopo ou perfil alterado
Full vs Quick
| Situação | Template |
|---|---|
| Produto com múltiplas telas, áreas, perfis e estados | Templates/Full/pages.md |
| Feature com 1-3 telas em contexto já definido | Templates/Quick/pages.md |
| Ambiguidade surgiu durante o Quick | Migrar para Full na mesma task |
Tipos de tela reconhecidos pelo framework
página pública — acessível sem autenticação
página autenticada — requer login
tela administrativa — acesso restrito por papel admin
tela operacional — usada em campo ou operação rotineira
modal — sobreposição contextual
drawer — painel lateral deslizante
etapa de fluxo — parte de um processo multi-step
tela de detalhe — visualização de item específico
tela de listagem — lista paginada ou filtrada
tela de formulário — criação ou edição de dados
tela de confirmação — passo final antes de ação destrutiva ou irreversível
estado especial — erro 404, sem permissão, manutençãoEstrutura — Pages Full
O template Full tem 11 seções.
1. Identificação
Nome do projeto:
Versão do documento:
Status: [rascunho | revisando | aprovado]
Documento base: Docs/user-stories.md
Data de criação:
Última atualização:2. Objetivo do Documento
Cobre: páginas e telas, propósito funcional, perfis com acesso, histórias atendidas, estados esperados, dependências.
Não cobre: layout visual detalhado, fluxo de navegação completo, arquitetura técnica, contrato de API.
3. Regras de Definição das Páginas
Todo registro de página deve incluir: nome, tipo, objetivo funcional, perfis com acesso, histórias atendidas, estados obrigatórios, dependências.
4. Inventário de Páginas
Estrutura completa de cada página (PG-001, PG-002, ...):
### PG-001 — [nome da página]
Tipo: [página pública | autenticada | modal | listagem | detalhe | formulário | ...]
Objetivo da página:
[para que essa página existe]
Resumo funcional:
[o que o usuário faz ou obtém nessa página]
Perfis com acesso:
- [perfil 1]
- [perfil 2]
Histórias relacionadas:
- US-001
- US-002
Origem de navegação:
[de onde o usuário normalmente chega]
Destinos principais:
- [destino 1]
- [destino 2]
Ações principais disponíveis:
- [ação 1]
- [ação 2]
Informações exibidas:
- [informação 1]
- [informação 2]
Entradas esperadas do usuário:
- [campo ou input 1]
- [campo ou input 2]
Estados obrigatórios:
- loading
- vazio
- erro
- sucesso
- sem permissão
- sem dados
- indisponibilidade externa
- [estado específico da tela]
Regras ou restrições relevantes:
- [regra 1]
Dependências funcionais:
- [endpoint / módulo / integração / permissão]
Observações visuais ou de UX:
[preencher]
Observações adicionais:
[preencher]5. Agrupamento por Área / Módulo
Após listar páginas individuais, agrupá-las por área de produto:
### Área / módulo: [nome]
Objetivo da área: [descreva]
Páginas relacionadas:
- PG-001
- PG-002
Perfis impactados:
- [perfil 1]6. Estados Transversais Esperados
Estados que devem ser tratados de forma consistente em múltiplas páginas:
- loading
- vazio
- erro
- sucesso
- sem permissão
- sem conexão
- indisponibilidade externa
- sessão expirada
- conteúdo restritoDiretriz geral: como esses estados devem ser apresentados de forma consistente.
7. Convenções de Nomeação e Organização
Padrão de identificação: PG-001, PG-002...
Convenção de nome: [verbo + objeto | área + ação | entidade + operação]
Critério para separar página, modal e componente: [descreva]8. Dependências e Observações Funcionais
Dependências entre páginas:
- PG-002 depende de PG-001 (autenticação)
- PG-004 exige PG-003 finalizada primeiro
Restrições por perfil ou permissão: [preencher]
Páginas críticas do sistema: [preencher]
Páginas opcionais ou futuras: [preencher]9. Diretrizes para os Próximos Documentos
Docs/flow.md — quais relações de navegação precisam ser descritas
Prototype/ — quais páginas devem ser prototipadas primeiro
Docs/design-system.md — quais componentes são recorrentes entre páginas
Docs/tokens.json — necessidades de consistência visual entre telas
Docs/contract.yaml — páginas que sugerem endpoints ou integrações
Docs/plan.md — páginas prioritárias, fundacionais ou bloqueantes10. Síntese Operacional para Dev e AI
Páginas prioritárias: [PG-001, PG-002]
Páginas críticas para MVP: [preencher]
O que cada página precisa garantir: [preencher]
Estados que não podem ser esquecidos: [preencher]
O que ainda está indefinido: [preencher]11. Aprovação
Status: [pendente | aprovado | revisando]
Aprovado por:
Data de aprovação:
Observações finais:Exemplo preenchido — página completa
### PG-012 — Registro de Atendimento
Tipo: tela operacional (mobile)
Objetivo da página:
Permitir que o técnico de campo registre a execução do atendimento com
foto, assinatura e dados de encerramento vinculados ao chamado.
Resumo funcional:
O técnico abre a tela a partir do chamado em andamento, captura foto pelo app,
coleta assinatura digital do cliente e encerra o chamado.
Perfis com acesso:
- Técnico de campo
Histórias relacionadas:
- US-007 (registrar atendimento com foto e assinatura)
- US-008 (encerrar chamado com comprovação)
Origem de navegação:
PG-008 (detalhe do chamado) → botão "Registrar encerramento"
Destinos principais:
- PG-009 (lista de chamados) após sucesso
- Permanece na tela em caso de erro de upload
Ações principais disponíveis:
- Capturar foto pela câmera do app
- Coletar assinatura via canvas touch
- Adicionar observação textual (opcional)
- Submeter encerramento
Informações exibidas:
- Número e descrição do chamado
- Endereço e cliente
- Campos de foto, assinatura e observação
Entradas esperadas do usuário:
- Foto (câmera obrigatória — sem galeria)
- Assinatura (canvas touch)
- Observação (texto livre, opcional)
Estados obrigatórios:
- loading (enviando dados para o backend)
- erro de câmera (sem permissão → instrução de ativação)
- erro de upload (opção de reenvio)
- sucesso (chamado encerrado e navegação para lista)
- sem conectividade (dados salvos localmente)
Regras ou restrições relevantes:
- Foto deve ser tirada pela câmera — não da galeria
- Se cliente recusar assinar: campo opcional com justificativa obrigatória
- Submissão só avança se foto e assinatura (ou justificativa) estiverem presentes
Dependências funcionais:
- API: POST /atendimentos/{id}/encerramento
- Permissão: técnico_ativo
- PG-008 (chamado em status "em andamento")Estrutura — Pages Quick
Para features com poucas telas e contexto já definido:
## Páginas principais
### PG-001 — [nome]
Tipo: [pública | autenticada | modal | listagem | detalhe | formulário]
Objetivo: [para que essa página existe]
Perfis:
- [perfil 1]
Histórias relacionadas:
- US-001
Ações principais:
- [ação 1]
- [ação 2]
Estados obrigatórios:
- loading
- erro
- vazio
- sucesso
---
## Agrupamento por área / módulo
### [nome da área]
- PG-001
- PG-002
## Estados transversais
- loading
- erro
- vazio
- sucesso
- sem permissão
## Direção para os próximos documentos
Docs/flow.md: [orientação]
Prototype/: [orientação]
Docs/design-system.md:[orientação]
Docs/contract.yaml: [orientação]
## Síntese para Dev e AI
Páginas prioritárias: PG-001, PG-002
Páginas do MVP: [preencher]
Estados obrigatórios: [preencher]
O que está indefinido:[ponto]Prompt para gerar com agente
Atue como ProductAgent.
Objetivo: criar Docs/pages.md com base em Docs/user-stories.md
Carregue contexto base:
- GUIDE.md
- Skills/ui-ux.md
- Templates/Full/pages.md
- Docs/user-stories.md
- Docs/project.md
Preencha as 11 seções do template Full.
Seção 4: crie uma entrada para cada tela derivada das histórias — use os perfis da US como referência.
Para cada tela, preencha todos os campos incluindo estados obrigatórios.
Seção 6: defina estados transversais e diretriz de consistência.
Seção 9: preencha orientação por artefato para os próximos documentos.
Marque [indefinido] onde não houver clareza suficiente.Definição de pronto
O pages está pronto quando:
- Todas as histórias de alta prioridade têm pelo menos uma tela correspondente
- Cada tela tem objetivo claro, perfis de acesso e ações listadas
- Estados obrigatórios mapeados em toda tela (mínimo: loading, erro, vazio, sucesso)
- Seção 5 agrupa telas por área ou módulo
- Seção 6 define estados transversais e diretriz de consistência
- Seção 9 tem orientação por artefato seguinte
- Aprovação registrada na seção 11
Atenção
Documentar a página só pelo layout ("tem um card com foto e botão") não é pages — é protótipo. Pages define o que e para quem, não como visualmente. O "como" vai para Prototype/ e Docs/design-system.md.
Erros comuns
| Erro | Correção |
|---|---|
| Descrever a tela só pelo layout | Foco em objetivo, ações e estados — visual vai para Prototype |
| Esquecer estados de erro e vazio | Toda tela deve ter no mínimo: loading, erro, vazio, sucesso |
| Perfil ausente | Toda tela precisa de ao menos um perfil com acesso definido |
| Tela sem histórias relacionadas | Sem vínculo com US, a tela não tem base funcional justificada |
| Seção 9 em branco | flow.md, design-system e contract.yaml perdem a orientação de produto |
Documentos que nascem de Pages
Docs/pages.md (aprovado)
↓
Docs/flow.md — como o usuário navega entre as páginas definidas
Prototype/ — representação visual de cada tela (HTML)
Docs/design-system.md— componentes e padrões visuais recorrentes entre páginas
Docs/contract.yaml — endpoints inferidos pelas ações e dependências de cada tela