specsfy-specialist-interface-experience

Experiência de interface

Quando usar

• Acionar ao criar ou alterar tela, dashboard, lista, formulário, jornada ou

CRUD usado por pessoas.

• Acionar antes de UX, UI e implementação para entender o sistema existente e

organizar a conversa sobre a interface.

• Não usar para endpoint, job ou mudança interna sem superfície para pessoas.

Fluxo

1. Carregar $specsfy-setup e ler .specsfy/STACK.md,

.specsfy/PACKAGES.md, manifests, instruções locais e documentação atual. Carregar $specsfy-specialist-design-system e ler DESIGNSYSTEM.MD antes de propor qualquer tela. Se o arquivo não existir, criar a fonte a partir de .specsfy/templates/DESIGNSYSTEM.MD. Executar node .agents/skills/specsfy-setup/scripts/inspect_interface.mjs --project <raiz> para localizar rotas, componentes e tecnologias antes da leitura detalhada.

1. Examinar as telas, fluxos, rotas, componentes, conteúdo, permissões, estados

e testes ligados à área afetada. Registrar o que a pessoa já consegue fazer, o que deve permanecer e o que a entrega muda.

1. Identificar framework, roteamento, primitives, estilos, formulários e runner

de testes usados pelo projeto. Seguir essas fontes e não trocar tecnologia ou biblioteca sem confirmação da pessoa.

1. Aplicar o contrato central de perguntas somente para lacunas reais:

perguntar uma lacuna por rodada sobre telas, fluxo de informação, formulário, formato de ação e composição. Quando a pessoa não informa direção visual, aplicar os defaults de DESIGNSYSTEM.MD e registrar a direção padrão. Só perguntar sobre composição quando o pedido contrariar uma regra existente. Oferecer opções textuais compatíveis com o sistema atual, Escrever outra resposta, Gere outras opções e Avançar.

1. Registrar na seção 10 da spec a stack observada, cada tela, o fluxo, os

formulários, a composição, os estados e a acessibilidade. Um CRUD não pode ficar restrito a API, banco ou serviço. Para CRUD, mapear sempre lista com PageHeader e DataGrid com detalhe clicável por linha, detalhe com PageHeader e DetailLists, e criar ou editar com PageHeader e seções de formulário em duas colunas responsivas. Toda tela também deve mapear Breadcrumb com equipe, módulo e tela atual; em Laravel, reaproveitar o componente já usado pelo layout. O PageHeader é um único componente reutilizável entre essas telas. A listagem ocupa a largura disponível, mostra o ID em coluna própria e oferece editar e apagar na linha, além do link para o detalhe.

1. Criar na seção 14 a Fase de interface, com uma tarefa por tela e testes

para navegação, formulário, validações, feedback e teclado.

1. Chamar $specsfy-specialist-ux-design para jornada e

$specsfy-specialist-ui-design para composição. Em projetos React, carregar $specsfy-specialist-react-ui-components para selecionar, reaproveitar e adaptar componentes antes de escrever JSX ou TSX, além de $specsfy-specialist-react para a implementação da stack. Para outra tecnologia, carregar o especialista equivalente detectado pelo setup.

Resultado esperado

Uma interface informativa, funcional e reconhecível para a tarefa, coerente com o sistema existente e com a personalidade do produto. O plano mostra telas, formulários, estados, regras de negócio, componentes e testes. A implementação preserva tudo fora do alcance registrado.

Padrões

• Mapear cada tela, ação, formulário, estado e retorno no plano.
• Preservar a stack, os componentes e os padrões de navegação já observados.
• Registrar teclado, foco, responsividade e mensagens junto da tela afetada.
• Renderizar Breadcrumb em todas as telas, mantendo o nome da equipe ativa

visível. Em Laravel, reutilizar Breadcrumb ou Breadcrumbs existente e sua tipagem de itens.

• Aplicar DESIGNSYSTEM.MD como fonte macro e INTERFACE.md como registro local.
• Usar DataGrid, DetailLists e PageHeader nas superfícies CRUD definidas;

a linha abre o detalhe e controles internos permanecem independentes.

• Reutilizar o mesmo PageHeader componentizado em todas as telas CRUD; manter

DataGrid em largura total com ID, editar e apagar visíveis na linha.

• Conferir bordas, espaçamentos, margens, padding e tipografia durante o

desenvolvimento, mesmo sem pedido da pessoa, e registrar o resultado no item VISUAL da tarefa.

• Organizar criar e editar em seções com coluna de contexto, painel em duas

colunas nos breakpoints largos e uma coluna no mobile.

• Mostrar erro de campo em vermelho, com mensagem abaixo do campo e foco útil.
• Projetar a hierarquia pelos dados, linguagem e estados do produto, sem cair em

uma composição visual genérica.

Antipadrões

• Propor uma tela sem ler as rotas e os componentes atuais.
• Tratar CRUD como endpoint sem descrever a interação da pessoa.
• Validar somente o estado feliz e ignorar vazio, erro ou permissão.

Validação

• Confirmar que a pessoa recebeu pergunta sobre as telas em toda entrega que

cria ou altera uma interface.

• Conferir que a seção 10 registra a stack e o sistema atual antes da proposta.
• Confirmar que DESIGNSYSTEM.MD foi lido ou criado e que a direção padrão ou

exceção está registrada com alcance.

• Executar validate_spec.mjs, validate_tasks.mjs e

validate_interface_tasks.mjs conforme a etapa.

• Verificar mobile e desktop, loading, vazio, erro, sucesso, permissão,

teclado e foco antes de concluir a interface.

Skills relacionadas

• $specsfy-specialist-ux-design para jornada, tarefas e conteúdo.
• $specsfy-specialist-ui-design para composição visual e estados.
• $specsfy-specialist-react-ui-components para selecionar e reaproveitar

componentes nas telas React.

• $specsfy-specialist-design-system para regras macro, defaults e cenários

CRUD.

Leia references/standards.md para fontes de acessibilidade e inspeção de interfaces.