# Diretrizes Iniciais de UX/UI

## Objetivo

Traduzir a fundacao do projeto em um baseline unico de UX/UI para tres superficies:

- instalacao privada;
- painel administrativo;
- experiencia publica desacoplada.

O documento define principios, fluxos prioritarios e criterios minimos de experiencia para orientar implementacao, revisao e futuros desdobramentos de produto.

## Escopo e leitura complementar

Este documento consolida a direcao geral. Fluxos administrativos detalhados e cenarios sensiveis continuam especificados em:

- [docs/admin-ia-client-flows.md](./admin-ia-client-flows.md)
- [docs/admin-export-migration-flow.md](./admin-export-migration-flow.md)

## 1. Principios transversais

### 1.1 Clareza operacional

- Cada tela deve responder rapidamente: onde estou, o que existe aqui e qual a proxima acao segura.
- A linguagem deve ser objetiva e orientada a tarefa, evitando termos internos, siglas desnecessarias e mensagens vagas.
- Sucesso, erro e pendencia precisam dizer o efeito real da acao.

### 1.2 Progressao simples

- O caminho principal deve aparecer primeiro; configuracoes raras ou avancadas entram por revelacao progressiva.
- Estados vazios precisam ensinar o primeiro passo, nao apenas informar ausencia de dados.
- Acoes destrutivas exigem contexto, diferenciacao visual e confirmacao proporcional ao risco.

### 1.3 Consistencia entre superficies

- Titulos, labels, feedback e estados devem seguir uma mesma logica entre instalador, painel e frontend.
- O sistema deve favorecer hierarquia tipografica forte, espacos previsiveis e densidade controlada, especialmente no admin.
- Componentes interativos precisam permanecer funcionais sem hover e sem dependencia exclusiva de gesto fino.

### 1.4 Robustez de entrega

- A experiencia deve nascer preparada para estados de carregamento, vazio, falha e sucesso.
- O frontend publico nao pode depender de injecao insegura de HTML; todo consumo vindo do CMS precisa respeitar sanitizacao e semantica.
- O comportamento base precisa funcionar a partir de 320 px de largura.

## 2. Instalador privado

### 2.1 Objetivo da superficie

Levar um operador tecnico ou semi-tecnico da validacao do ambiente ate a instalacao concluida com o menor numero possivel de ambiguidades.

### 2.2 Diretrizes

- O instalador deve lembrar a clareza operacional do WordPress: fluxo curto, formulario central, linguagem direta e feedback imediato.
- A experiencia deve caber em uma unica pagina responsiva com grupos claros: requisitos, identidade do site, banco e credenciais iniciais.
- Cada campo precisa trazer apenas a instrucao necessaria para a conclusao da instalacao sem documentacao paralela.
- Erros locais devem aparecer junto ao campo; erros globais e bloqueios sistêmicos precisam aparecer no topo com proxima acao sugerida.
- A conclusao deve explicar explicitamente o que foi criado: banco/schema, usuario administrador, `config.php` e lock de instalacao.

### 2.3 Criterios minimos

- Requisitos do ambiente visiveis antes do envio final.
- Labels completos, placeholders nao substituem instrucao.
- CTA principal unico e inequívoco.
- Confirmacao final com resumo do que foi provisionado.

## 3. Admin: direcao de UX/UI

### 3.1 Objetivo da superficie

Permitir que `editor` e `super_admin` executem tarefas editoriais e operacionais frequentes com baixa friccao, baixa ambiguidade e risco controlado.

### 3.2 Principios do admin

- O painel deve privilegiar tarefas recorrentes de conteudo antes de configuracoes raras.
- A linguagem padrao deve ser editorial e operacional, nao tecnica.
- O sistema precisa expor apenas o necessario para cada papel.
- Itens indisponiveis por permissao devem ser ocultados, nao apenas desabilitados.
- A superficie privada nao precisa otimizar indexacao, mas deve otimizar leitura, rastreabilidade e seguranca operacional.

### 3.3 Arquitetura de informacao minima

Navegacao primaria recomendada:

1. Painel
2. Conteudo
3. Midia
4. Taxonomias
5. Menus
6. Usuarios
7. Configuracoes
8. Auditoria

Regras:

- `Painel`, `Conteudo` e `Midia` concentram o trabalho cotidiano.
- `Menus` vem depois do dominio editorial porque depende de conteudo ja existente.
- `Usuarios`, `Configuracoes` e `Auditoria` ficam no bloco de operacao sensivel.

### 3.4 Padrao de tela administrativa

- Cabecalho com titulo claro, contagem ou status quando aplicavel e CTA principal no topo direito.
- Busca simples e filtros rapidos abaixo do cabecalho.
- Tabela ou layout principal com hierarquia legivel, bulk actions opcionais e overflow para secundarias.
- Estado vazio com orientacao explicita e CTA util.
- Formularios com coluna principal para conteudo e coluna lateral para metadados e acoes.
- Feedback inline por campo e resumo no topo quando houver multiplos erros.

### 3.5 Fluxos prioritarios do admin

#### Primeiro acesso

- O painel deve orientar a primeira sessao em menos de 10 segundos.
- Exibir boas-vindas curta, proximos passos e atalhos para criar conteudo, enviar midia e revisar configuracoes basicas.
- Evitar tour obrigatorio; ajuda contextual deve ser descartavel.

#### Criar e publicar conteudo

- O fluxo principal precisa ir de titulo e corpo ate publicacao sem troca excessiva de contexto.
- O CTA principal deve refletir o estado: `Salvar rascunho`, `Atualizar`, `Publicar` ou `Agendar`.
- Preview publico abre em nova aba.
- O usuario precisa entender se o item foi publicado, agendado ou enviado para revisao.

#### Gerir taxonomias

- Criacao e edicao devem acontecer em formulario curto e claro.
- `slug` deve ser automatico ou tratado como avancado.
- Exclusoes com conteudo associado exigem aviso de impacto.

#### Ajustar menus

- A estrutura deve ser compreensivel mesmo sem drag-and-drop.
- Controles de mover para cima/baixo devem coexistir com reordenacao visual.
- Profundidade maxima e impacto no frontend precisam ser explicitos.

#### Enviar e reutilizar midia

- Restrições de formato e tamanho aparecem antes do upload.
- Preview e confirmacao de processamento sao imediatos.
- Sempre que possivel, a midia deve informar onde esta em uso antes de exclusao.

#### Operacoes sensiveis

- Exportacao, migracao, usuarios e configuracoes criticas exigem reautenticacao recente quando houver risco real.
- O sistema deve privilegiar checklist, resumo de impacto e frase de seguranca em vez de confirmacoes genericas.
- Auditoria precisa registrar inicio, conclusao e falha de operacoes criticas.

### 3.6 Criterios minimos do admin

- Um usuario `editor` consegue identificar a proxima acao util ao abrir o painel.
- Toda listagem critica possui busca, filtro, estado vazio e CTA primario.
- Toda acao destrutiva ou irreversivel possui confirmacao contextual.
- Formularios longos mantem acoes acessiveis no topo e no rodape.
- O admin funciona em uma coluna unica em telas estreitas sem perda de CTA principal.

## 4. Experiencia publica

### 4.1 Objetivo da superficie

Entregar conteudo desacoplado com leitura clara, SEO controlavel e consumo resiliente da API publica, sem depender de mecanismos internos do CMS.

### 4.2 Principios da experiencia publica

- HTML semanticamente correto desde a primeira entrega.
- Titulos, descricoes e metadados devem existir por padrao e aceitar override via API.
- Conteudo e navegacao precisam priorizar leitura, contexto e continuidade editorial.
- A experiencia deve continuar compreensivel mesmo sob falha parcial de rede, ausencia de conteudo ou latencia.

### 4.3 Fluxos prioritarios da experiencia publica

#### Home e listagens

- A home precisa comunicar claramente o escopo editorial e destacar caminhos de entrada.
- Listagens por categoria ou tag devem deixar evidente qual recorte esta ativo.
- Paginação ou carregamento incremental deve manter contexto e nao ocultar o total de resultados.

#### Detalhe de conteudo

- Titulo, data, autoria e contexto editorial precisam aparecer antes do corpo principal quando relevantes.
- O corpo deve priorizar legibilidade, hierarquia de headings e imagens com `alt`.
- O usuario precisa encontrar proximos caminhos naturais: categoria, artigo relacionado ou retorno a listagem.

#### Estados de sistema

- Skeleton, loading, vazio e falha fazem parte do contrato minimo, nao de uma fase posterior.
- Mensagens de erro precisam orientar recarga, retorno ou navegacao alternativa.
- Conteudo ausente ou nao publicado nao deve quebrar a interface nem expor detalhe tecnico interno.

### 4.4 Criterios minimos da experiencia publica

- Toda pagina publica principal possui `title`, `description` e estrutura semantica coerente.
- O frontend nao depende de `innerHTML` sem sanitizacao para renderizar conteudo vindo do CMS.
- Estados de loading, vazio e erro existem ao consumir a API.
- A navegacao publica funciona em mobile sem exigir hover.

## 5. Copy, feedback e tom

- Preferir verbos concretos como `Instalar agora`, `Salvar configuracao`, `Publicar post`, `Baixar pacote`.
- Evitar mensagens opacas como `erro inesperado` sem contexto operacional minimo.
- Confirmacoes devem explicitar o resultado: o que mudou, onde o usuario pode verificar e qual o proximo passo.
- Em fluxos sensiveis, o texto precisa dizer risco, escopo e reversibilidade.

## 6. Definicao de pronto para UX/UI inicial

Considerar esta diretriz atendida quando futuras entregas das superficies cobertas respeitarem, no minimo:

1. navegacao coerente com os dominios do produto;
2. estados de sucesso, erro, vazio e carregamento previstos desde o baseline;
3. protecao explicita para acoes sensiveis;
4. responsividade minima a partir de 320 px;
5. linguagem consistente, direta e orientada a tarefa;
6. separacao clara entre experiencia administrativa privada e consumo publico desacoplado.