feat(ux): incorporar diretrizes M3 de UX writing e organizacao de telas, modais e paineis

skills/auditar-ux-heuristicas/SKILL.md

@@ -52,23 +52,39 @@ Verificar conformidade com `rules/refactoring-ui-hierarquia-despoluicao`:
 - [ ] **Lei da Proximidade e Largura Ideal:** O espaço externo entre grupos/campos (`16px–32px`) é maior que o espaço interno (`4px–8px`), e formulários simples respeitam `max-width: 640px–800px`?
 - [ ] **Estados Vazios Despoluídos:** Quando não há registros criados na base, filtros secundários e paginação são ocultados em favor apenas do *Empty State* orientador com CTA?
 
-### 2.7. Auditoria Quantitativa de Ergonomia e Carga Cognitiva (`agent-browser`)
+### 2.7. Auditoria Quantitativa de Ergonomia, Telas, Modais e Painéis (`agent-browser` + Material Design 3)
 
-Toda auditoria de UX deve verificar se a tela não está visualmente sufocada por excesso de barras fixas, colisão de painéis laterais ou excesso de pílulas/badges por linha:
+Toda auditoria de UX deve verificar se a tela, modais e painéis seguem os limites espaciais e a Matriz de Superfícies do Material Design 3:
 - [ ] **Orçamento de Viewport (`>= 70%` Área Livre):** Em `1366x768` ou `1440x900`, o canvas principal de trabalho (lista, árvore, tabela, Gantt, Kanban) ocupa pelo menos 70% da janela sem ser esmagado por múltiplos painéis laterais abertos ao mesmo tempo?
-- [ ] **Teto de 2 Faixas no Cabeçalho Operacional:** A área de trabalho possui no máximo 2 faixas horizontais de cabeçalho/filtros acima do conteúdo, mantendo formulários de criação rápida (`+ Nova Tarefa`) recolhidos sob demanda?
-- [ ] **Exclusão Mútua de Painéis Laterais (*Auto-Collapse*):** Ao abrir uma gaveta inspetora de detalhes (`400px+`) ou entrar no Cronograma Gantt, o menu lateral de navegação recolhe automaticamente?
+- [ ] **Teto de 2 Faixas no Cabeçalho Operacional:** A área de trabalho possui no máximo 2 faixas horizontais de cabeçalho/filtros acima do conteúdo, mantendo formulários de criação rápida (`+ Nova tarefa`) recolhidos sob demanda?
+- [ ] **Exclusão Mútua de Painéis Laterais (*Auto-Collapse*):** Ao abrir uma gaveta inspetora de detalhes (`360px–420px`) ou entrar no Cronograma Gantt, o menu lateral de navegação recolhe automaticamente?
 - [ ] **Teto de 3 Indicadores por Linha em Repouso:** Linhas de árvore/lista e cards exibem no máximo 3 sinais visuais além do título (sem "Natal de Badges" de 5–7 pílulas coloridas por linha), revelando ações secundárias (`+ Sub`, `Editar`) em `:hover` / `:focus-within`?
 - [ ] **Inspetor em Acordeão e Sem Card de Resumo Redundante:** O painel de detalhes inicia apenas com *Identificação/Prazo* e *Entrega* abertos, agrupando *Pré-requisitos*, *Recursos* e *Responsáveis* em seções colapsáveis (Acordeão) com resumo no título?
+- [ ] **Matriz de Superfícies e *Chunking* M3:** Formulários longos estão agrupados em seções de até 4–6 campos? Modais básicos (`v-dialog`, `400px–560px`) são usados apenas para confirmações ou 3–4 campos rápidos (usando *Side Sheet* para 5–8 campos/inspeção e `v-snackbar` para avisos passivos)?
+- [ ] **Regiões Fixas (*Pinned Header & Footer*):** Em modais e painéis laterais, o cabeçalho (com botão fechar `X` nos painéis) e o rodapé de ações permanecem sempre fixos caso o conteúdo central precise rolar?
+
+### 2.8. Auditoria de UX Writing e Microcopy (Material Design 3)
+
+Verificar conformidade com `rules/mensagens-usuario` e `https://m3.material.io/foundations/writing/best-practices`:
+- [ ] **Capitalização de Frase (*Sentence case*):** Títulos de telas/modais/painéis, cabeçalhos, labels, abas, menus e botões usam apenas a 1ª letra da 1ª palavra e siglas em maiúscula (ex.: `"Nova licença"` e não `"Nova Licença"`)?
+- [ ] **Começar pelo Objetivo (*Begin with the objective*):** Frases de instrução iniciam pelo objetivo antes da ação (`"Para emitir a licença, anexe o parecer técnico"`)?
+- [ ] **Anatomia M3 de Diálogos e Botões Específicos:** Modais de confirmação têm título com pergunta direta (`"Excluir condicionante?"`), explicam a consequência de forma neutra sem repetir o título e usam o verbo exato no botão (`[Cancelar]` / `[Excluir condicionante]`), sem botões ambíguos `[Sim]`, `[Não]` ou `[OK]`?
+- [ ] **Pontuação Enxuta de Escaneabilidade:** Rótulos, botões, títulos, tooltips de 1 frase, toasts de 1 frase e itens de lista curtos omitem ponto final (`.`), e nenhum `label` ou título termina com dois-pontos (`:`)?
+- [ ] **Tempo Presente, Voz Ativa, Algarismos e Zero Abreviações Truncadas:** Textos usam voz ativa no presente, números em algarismos (`3`, `10 MB`), zero pontos de exclamação (`!`) em erros/alertas e zero abreviações truncadas (`Qtd.`, `Obs.`, `Cad.`, `End.`, `Máx.`)?
 
 ```sh
 # Detectar excesso de divisores e possíveis cards aninhados
 rg "<v-divider" --include='*.vue' <modulo>-front/src/ -c | sort -t: -k2 -rn | head -10
 # Detectar botões destrutivos vermelhos sólidos fora de modais de confirmação
 rg 'color="error"|<v-btn[^>]*error' --include='*.vue' <modulo>-front/src/ -n
+# Detectar botões genéricos ambíguos (Sim, Não, OK), labels com dois-pontos e abreviações truncadas (M3 UX Writing)
+rg '>(Sim|Não|OK|Confirmar)</v-btn>|label="[^"]*(:|\bQtd\.|\bObs\.|\bCad\.|\bEnd\.|\bMáx\.)' --include='*.vue' <modulo>-front/src/ -n
 ```
 
-### 3. Acessibilidade Básica
+### 3. Acessibilidade Básica e Textual (M3)
+
+- `alt` conciso (até 125 caracteres) sem iniciar por `"Imagem de..."` (`alt=""` para imagens decorativas).
+- Textos truncados (`text-truncate` / `ellipsis`) oferecem tooltip ou expansão acessível.
 
 ```sh
 rg "<img" --include='*.vue' <modulo>-front/src/ -n | grep -v "alt="
@@ -88,9 +104,9 @@ rg "<v-btn\|<button" --include='*.vue' <modulo>-front/src/ -n | grep -v "aria-la
 | Componente | Loading | Vazio | Erro | Sucesso |
 |------------|---------|-------|------|---------|
 
-## Fluxo Funcional e Jornada (ux-fluxo-funcional)
-| Pilar | Status | Problema Identificado | Correção Proposta |
-|-------|--------|-----------------------|-------------------|
+## Fluxo Funcional, Superfícies e UX Writing (M3)
+| Pilar / Critério | Status | Problema Identificado | Correção Proposta |
+|------------------|--------|-----------------------|-------------------|
 
 ## Plano de Melhoria
 1. ...
@@ -98,6 +114,8 @@ rg "<v-btn\|<button" --include='*.vue' <modulo>-front/src/ -n | grep -v "aria-la
 
 ## Referências
 
+- Material Design 3 — Writing Best Practices: `https://m3.material.io/foundations/writing/best-practices`
+- Material Design 3 — Layout, Dialogs & Side Sheets: `https://m3.material.io/foundations/layout/understanding-layout/panes`, `https://m3.material.io/components/dialogs/guidelines`, `https://m3.material.io/components/side-sheets/guidelines`
 - Rule: `global/rules/refactoring-ui-hierarquia-despoluicao`
 - Livro *Refactoring UI* (Paiol): `https://adm.paiol.idz.one/estaticos/Refactoring-UI-Steve-Schoger-Adam-Wathan.pdf`
 - Skill: `skills/ux-fluxo-funcional/SKILL.md`

skills/ux-fluxo-funcional/SKILL.md

@@ -16,7 +16,7 @@ Garantir que qualquer aplicação `<modulo>-front` do ecossistema (identificada
 
 ---
 
-## Os 6 Pilares da Usabilidade Funcional
+## Os 7 Pilares da Usabilidade Funcional
 
 ### Pilar 1 — Navegação no Menu Lateral Ordenada pela Jornada Operacional
 
@@ -96,22 +96,49 @@ No Vuetify 3 em tema claro (`dark: false`), componentes com `variant="tonal"` e
 ### Pilar 6 — Ergonomia de Quadros Operacionais e Navegação Cruzada
 
 1. **Quadros Kanban Sempre Horizontais Lado a Lado:**
-   - Colunas de estágios (ex.: *A Fazer*, *Em Andamento*, *Em Revisão*, *Concluído*) devem ser exibidas **lado a lado horizontalmente** em desktop utilizando container flexível (`d-flex flex-nowrap overflow-x-auto ga-4 pb-2`) com largura mínima por coluna (`min-width: 280px` a `320px`).
+   - Colunas de estágios (ex.: *A fazer*, *Em andamento*, *Em revisão*, *Concluído*) devem ser exibidas **lado a lado horizontalmente** em desktop utilizando container flexível (`d-flex flex-nowrap overflow-x-auto ga-4 pb-2`) com largura mínima por coluna (`min-width: 280px` a `320px`).
    - **Proibido** usar `v-row`/`v-col` que empilhe colunas de `min-height: 420px` verticalmente em resoluções intermediárias, gerando enormes caixas vazias que escondem os cartões abaixo da dobra.
 2. **Navegação Cruzada (*Drill-down* Contextual):**
    - Cards de resumo em Dashboards e tabelas de acompanhamento devem oferecer ação direta (clique ou botão) para abrir o registro correspondente no painel de detalhamento ou no quadro operacional já filtrado pelo item selecionado (`query` ou `params` de rota).
 
 ---
 
+### Pilar 7 — Organização de Telas, Modais (`Dialogs`) e Painéis Laterais (`Side Sheets`) — Material Design 3
+
+Conforme as diretrizes de **Layout (`Panes` e `Canonical Layouts`), `Dialogs` e `Side Sheets` do Material Design 3** (`https://m3.material.io/foundations/layout/understanding-layout/panes`, `https://m3.material.io/components/dialogs/guidelines` e `https://m3.material.io/components/side-sheets/guidelines`):
+
+1. **Matriz de Escolha de Superfície (Quando usar cada container):**
+   - **Tela Principal / *Single-Pane* (`12 colunas`):** Fluxos primários densos (tabelas amplas, múltiplas abas, cronogramas, formulários estruturantes).
+   - **Painel Lateral Coplanar (*Standard Side Sheet*, `360px–420px`, sem *scrim*):** Inspeção contextual de item selecionado na lista/árvore (*Supporting Pane* / *Master-Detail* leve) ou filtros avançados ao vivo, onde o usuário precisa comparar ou alternar itens na área principal simultaneamente. Recolhe automaticamente o menu lateral esquerdo.
+   - **Painel Lateral Modal (*Modal Side Sheet*, `v-navigation-drawer temporary location="right"`, `400px–560px`, com *scrim*):** Formulários secundários de média complexidade (5 a 8 campos), histórico detalhado ou fluxos auxiliares que exigem foco exclusivo sem perder o contexto espacial da página ao fundo.
+   - **Modal Básico (*Basic Dialog*, `v-dialog`, `max-width: 400px–560px`):** Modais são **interruptivos** por natureza e devem ser usados **com parcimônia**, exclusivamente para:
+     1. **Confirmações críticas ou destrutivas** que exigem decisão imediata;
+     2. **Decisões rápidas ou criação enxuta** (até **3 a 4 campos simples** que não dependem de leitura da tela de fundo).
+   - **Modal de Tela Cheia (*Full-Screen Dialog*, `v-dialog fullscreen`):** Tarefas modais complexas ou multi-etapas com barra superior fixa contendo `Fechar (X)` à esquerda, título em *Sentence case* e ação primária (`Salvar`) à direita.
+   - **Snackbar / Toast (`v-snackbar`):** Feedback passivo de sucesso ou aviso curto de 1 frase. **Proibido** abrir um `v-dialog` apenas para exibir `"Salvo com sucesso"`.
+2. **Organização de Telas e *Chunking* Escaneável (*Make Content Scannable*):**
+   - Dividir telas e formulários longos em **seções temáticas curtas** (máximo de **4 a 6 campos** relacionados por bloco) encabeçadas por título em *Sentence case* (`16px–20px`, peso `600`, sem dois-pontos `:` e sem ponto final `.`).
+   - Posicionar a informação mais importante no início do título/parágrafo (*front-loading*) e ocultar configurações raras ou detalhes técnicos sob demanda (*Reveal details as needed*).
+3. **Anatomia e Regiões Fixas em Modais (*M3 Dialog Anatomy & Pinned Regions*):**
+   - **Cabeçalho e Rodapé Fixos (*Pinned Header & Footer*):** Evitar rolagem em *Basic Dialogs*; quando o conteúdo precisar rolar (ex.: lista de seleção), o **Cabeçalho (`v-card-title`) no topo** e a **Barra de Ações (`v-card-actions`) no rodapé** devem permanecer **fixos e visíveis**, rolando apenas o corpo central (`v-card-text`) com divisor sutil.
+   - **Título Específico + Consequência + Botão com Verbo:** Título com pergunta direta (`"Excluir condicionante?"`), corpo explicando a consequência sem repetir o título, e botões alinhados à direita (`[Cancelar]` + `[Excluir condicionante]`), proibindo `[Sim]`, `[Não]` ou `[OK]`.
+4. **Anatomia de Painéis Laterais (*M3 Side Sheet Anatomy*):**
+   - **Header Fixo no Topo:** Título conciso em *Sentence case*, botão explícito de fechar (`X` com `aria-label="Fechar painel"`) à direita e, quando houver navegação multi-nível dentro do painel, botão de voltar (`←`) à esquerda do título.
+   - **Corpo em Seções e Acordeões:** Até 2 seções primárias abertas; seções relacionais (`1:N`) em acordeões colapsáveis com resumo numérico no título.
+   - **Footer Fixo de Ações:** Quando o painel exigir submissão manual, manter `[Cancelar]` e `[Salvar alterações]` fixos no rodapé do painel com divisor superior.
+
+---
+
 ## Protocolo Passo a Passo de Aplicação
 
 1. **Ler Identidade do Módulo:** Consultar `memorias-ia/modulo.yml` para identificar `modulo-id`, `modulo-caminho`, `modulo-descricao` e `modulo-tipo`.
-2. **Auditar a Jornada Completa:** Inspecionar `App.vue`, `router/index.ts`, `plugins/vuetify.ts` e as views de `<modulo>-front/src/` verificando os 6 Pilares acima.
+2. **Auditar a Jornada Completa:** Inspecionar `App.vue`, `router/index.ts`, `plugins/vuetify.ts` e as views de `<modulo>-front/src/` verificando os 7 Pilares acima.
 3. **Corrigir Tokens e Navegação Global:**
    - Ajustar `secondary` em `vuetify.ts` caso esteja usando cor clara sem contraste.
    - Concentrar a navegação principal exclusivamente em `MenuLateral.vue` (sem duplicar links na `CabecalhoPrincipal.vue`) e ordenada pela jornada operacional.
-4. **Desafogar Layouts e Conectar Fluxos:**
+4. **Desafogar Layouts, Organizar Modais/Painéis e Conectar Fluxos:**
    - Substituir *split-screens* apertados (`4+8`) por seleção de contexto + área principal de `12 colunas`.
+   - Adequar modais e painéis à Matriz de Superfícies M3 (convertendo modais longos de 6+ campos em *Side Sheets* ou páginas, garantindo *Pinned Header/Footer* e botões com verbo específico).
    - Inserir links de navegação cruzada e *empty states* guiados entre telas dependentes.
    - Garantir que quadros Kanban sejam horizontais e responsivos.
 5. **Validar Visualmente com `agent-browser`:**
@@ -126,7 +153,9 @@ No Vuetify 3 em tema claro (`dark: false`), componentes com `variant="tonal"` e
 - [ ] Telas com abas densas ou tabelas largas usam `12 colunas` em vez de *split-screen* `4+8` espremido?
 - [ ] O cabeçalho operacional respeita o teto de 2 faixas horizontais (com criadores rápidos sob demanda) e recolhe o menu lateral automaticamente ao abrir o Inspetor de Detalhes?
 - [ ] Linhas de árvore/lista exibem no máximo 3 indicadores em repouso (sem "Natal de Badges") e o Inspetor usa seções colapsáveis (Acordeão) sem card de resumo duplicado?
-- [ ] Todos os rótulos técnicos de banco/código (`(info)`, `JSONB`, `Instanciar`, enums crus) foram substituídos por linguagem natural do domínio?
+- [ ] A Matriz de Superfícies M3 é respeitada (*Basic Dialog* restrito a confirmações ou 3–4 campos com Header/Footer fixos; *Side Sheet* com botão fechar `X` e Footer fixo para formulários médios/inspeção; `v-snackbar` para avisos passivos)?
+- [ ] Formulários longos estão divididos em blocos temáticos de até 4–6 campos com títulos em *Sentence case* (sem `:` e sem `.`)?
+- [ ] Todos os rótulos técnicos de banco/código (`(info)`, `JSONB`, `Instanciar`, enums crus) foram substituídos por linguagem natural do domínio em *Sentence case*?
 - [ ] O token `secondary` do tema Vuetify possui contraste escuro (≥ 4.5:1) em botões e chips `variant="tonal"` e `variant="outlined"`?
 - [ ] Quadros Kanban renderizam colunas lado a lado (`overflow-x-auto`) sem empilhar caixas vazias gigantes?
 - [ ] Existe navegação direta (*drill-down*) entre o Dashboard, a Visão de Detalhes e o Quadro Operacional?
@@ -135,6 +164,9 @@ No Vuetify 3 em tema claro (`dark: false`), componentes com `variant="tonal"` e
 
 ## Referências
 
+- Material Design 3 — Writing Best Practices: `https://m3.material.io/foundations/writing/best-practices`
+- Material Design 3 — Layout, Dialogs & Side Sheets: `https://m3.material.io/foundations/layout/understanding-layout/panes`, `https://m3.material.io/components/dialogs/guidelines`, `https://m3.material.io/components/side-sheets/guidelines`
+- Rule: `rules/mensagens-usuario.md` (UX Writing M3 e linguagem do domínio)
 - Rule: `rules/refactoring-ui-hierarquia-despoluicao.md` (Hierarquia visual, pirâmide de ações, menos bordas e consolidação de tabelas — *Refactoring UI*)
 - Livro *Refactoring UI* (consulta online no Paiol): `https://adm.paiol.idz.one/estaticos/Refactoring-UI-Steve-Schoger-Adam-Wathan.pdf`
 - Skill: `skills/ux/SKILL.md` (Paleta de cores, Lucide icons e padrões Vuetify)

skills/ux/SKILL.md

@@ -112,12 +112,17 @@ Antes de alterar, entender o que já existe:
 
 Para cada elemento da interface, avaliar:
 
-#### Clareza
+#### Clareza e UX Writing (Material Design 3)
 
 - [ ] O propósito de cada elemento é óbvio sem instrução?
-- [ ] Labels e placeholders são descritivos? (ex: "Buscar por nome ou CPF" vs "Buscar")
+- [ ] Títulos, cabeçalhos, labels, abas, menus e botões usam **Capitalização de frase (*Sentence case*)** (apenas a 1ª letra da 1ª palavra e siglas em maiúscula, ex.: `"Nova licença"`, `"Salvar alterações"`, sem *Title Case* artificial)?
+- [ ] Textos orientativos começam pelo **objetivo antes da ação** (`"Para emitir a licença, anexe o parecer técnico"`)?
+- [ ] Rótulos (`label`), botões, títulos, tooltips de 1 frase e toasts de 1 frase **omitem ponto final (`.`)** e nenhum `label` ou título termina com dois-pontos (`:`)?
+- [ ] Modais de confirmação seguem a **Anatomia M3**: Título com pergunta direta (`"Excluir condicionante?"`), corpo com a consequência neutra sem repetir o título, e botões `[Cancelar]` + `[Verbo + objeto]` (sem botões genéricos `[Sim]`, `[Não]` ou `[OK]`)?
+- [ ] Quantidades e limites usam **algarismos** (`"3 condicionantes"`, `"Até 10 MB"`) e a tela está livre de abreviações truncadas (`"Qtd."`, `"Obs."`, `"Cad."`, `"End."`) e pontos de exclamação (`!`) em erros/alertas?
+- [ ] Labels e placeholders são descritivos (ex.: `"Buscar por razão social ou CNPJ"` vs `"Buscar"`)?
 - [ ] Ícones acompanham texto quando a ação não é universalmente reconhecível?
-- [ ] O estado vazio (empty state) orienta o usuário sobre o próximo passo?
+- [ ] O estado vazio (*empty state*) orienta o usuário sobre o próximo passo com botão de ação?
 
 #### Hierarquia visual e Pirâmide de Ações (*Refactoring UI*)
 
@@ -140,6 +145,8 @@ Para cada elemento da interface, avaliar:
 - [ ] Ao abrir uma gaveta inspetora de detalhes (`400px+`), o menu lateral de navegação recolhe automaticamente (*Sidebar Mutual Exclusion*) para preservar >= 70% de largura útil?
 - [ ] Linhas de árvore/lista exibem no máximo 3 indicadores em repouso (sem "Natal de Badges"), revelando ações secundárias (`+ Sub`, `Editar`) em `:hover` / `:focus-within`?
 - [ ] Painéis de detalhe usam seções colapsáveis (Acordeão) com resumo no título para itens secundários (*Pré-requisitos*, *Recursos*, *Responsáveis*), sem card de resumo duplicado no topo?
+- [ ] A **Matriz de Superfícies M3** é respeitada (*Basic Dialog* restrito a confirmações críticas ou 3–4 campos rápidos; *Side Sheet* para formulários de 5–8 campos ou inspeção; `v-snackbar` para avisos passivos; formulários longos agrupados em blocos de até 4–6 campos)?
+- [ ] Em modais (`v-dialog`) e painéis laterais (`Side Sheets`), o **Cabeçalho no topo** (com botão fechar `X` nos painéis) e o **Rodapé de ações** permanecem **fixos (*pinned*)** caso o conteúdo central role?
 
 #### Feedback e estados
 
@@ -262,7 +269,10 @@ Após implementar:
 | Múltiplos botões sólidos (`primary`, `success`, `warning`) lado a lado | Pirâmide de ações: 1 primário `flat`, secundários `outlined`/`tonal` e terciários `text` |
 | *Card-ception* (`v-card` com borda dentro de `v-card` + `v-divider`) | Separar seções por contraste de superfície (`#FFFFFF` sobre `#F2F3EE`) ou espaçamento (`24px–32px`) |
 | Pilha de `Rótulo: Valor` com mesmo peso visual | Omitir rótulos óbvios pelo formato ou combinar em frase; destacar o dado e suavizar o rótulo |
-| Modal com scroll extenso | Dividir em etapas ou usar drawer lateral |
+| Modal com scroll extenso ou 6+ campos espremidos | Converter em *Side Sheet* (5–8 campos), página dedicada ou *Full-Screen Dialog*, mantendo Cabeçalho e Rodapé fixos (*pinned*) |
+| Modal de confirmação com botões `[Sim] / [Não]` ou `[OK]` | Título com pergunta (`"Excluir condicionante?"`), consequência no corpo e botões `[Cancelar]` + `[Excluir condicionante]` |
+| *Title Case* anglófono (`"Nova Licença"`, `"Salvar Alterações"`) ou labels com `:` | Capitalização de frase (*Sentence case*: `"Nova licença"`, `"Salvar alterações"`) e zero dois-pontos (`:`) em labels/títulos |
+| Abreviações truncadas (`"Qtd."`, `"Obs."`, `"Cad."`, `"Máx."`) | Escrever por extenso (`"Quantidade"`, `"Observações"`, `"Cadastro"`, `"Máximo"`) e usar algarismos (`3`, `10 MB`) |
 | Tabela com 10–15+ colunas estreitas | Consolidar colunas correlatas em célula de 2 linhas (Título + metadado secundário) |
 | Ícone inflado a seco (`48px–64px`) | Ícone `20px–24px` dentro de badge arredondado (`40px–48px`) com fundo pastel |
 | Estilos inline em template | Usar `<style scoped>` com tokens CSS e fallback |