.

global/skills/adicionar-ajuda/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: adicionar-ajuda
+description: Adicionar ou atualizar botão de ajuda e documentação contextual em telas e modais (Frontend)
+scope: global
+updatedAt: "2026-09-01"
+---
+
+# Skill / Workflow: Adicionar Ajuda Contextual em Telas e Modais
+
+Este guia estabelece o padrão para criação e manutenção de arquivos de **ajuda contextual ao usuário** exibidos diretamente na interface da aplicação.
+
+O objetivo da ajuda em tela é **auxiliar o usuário final a compreender e operar a interface de forma autônoma**, explicando o funcionamento da tela/modal de forma clara, amigável e objetiva.
+
+---
+
+## 1. Padrão Canônico de Nomenclatura e Co-Localização
+
+Sempre que uma tela ou modal possuir ajuda contextual, o arquivo Markdown de documentação **DEVE** ser co-localizado com o componente na mesma pasta, adotando o sufixo `.ajuda.md`:
+
+```
+modalExportarPdf.vue       → modalExportarPdf.ajuda.md
+modalParametros.vue        → modalParametros.ajuda.md
+telaCadastroPonto.vue      → telaCadastroPonto.ajuda.md
+```
+
+> ⚠️ **Regra Estrita**: Para qualquer componente `modalX.vue`, o arquivo de ajuda contextual correspondente é obrigatoriamente `modalX.ajuda.md`.
+
+---
+
+## 2. Conteúdo Obrigatório do `.ajuda.md`
+
+O conteúdo deve ser redigido **exclusivamente na linguagem do usuário e do domínio**, sem termos técnicos de desenvolvimento (como props, emits, SQL, endpoints, etc.).
+
+Estrutura recomendada:
+
+```markdown
+# Ajuda: [Nome da Tela / Modal]
+
+## Objetivo
+Explique resumidamente para que serve esta tela ou modal dentro do fluxo de trabalho do usuário.
+
+## Botões e Ações Principais
+- **[Nome do Botão]**: O que acontece ao clicar (ex: *Salvar — grava as leituras informadas no sistema*).
+- **[Nome do Botão]**: Ação de cancelamento ou descarte.
+
+## Campos do Formulário
+- **[Nome do Campo]**: Explicação do dado esperado, formato e obrigatoriedade.
+- **[Nome do Campo]**: Regra de preenchimento ou limites aplicáveis.
+
+## Fluxo de Uso Passo a Passo
+1. Passo inicial do usuário.
+2. Preenchimento e conferência.
+3. Conclusão da ação.
+
+## Regras de Validação e Normas (quando aplicável)
+Explique prazos, limites legais ou critérios ambientais relevantes para a operação.
+```
+
+---
+
+## 3. Posicionamento do Botão de Ajuda na UI
+
+O botão de ajuda (ex: `BotaoAjuda`, ícone `HelpCircle` ou `v-icon`) deve ser posicionado de maneira consistente:
+
+### Em Modais (`modalX.vue`)
+- Posicionado na **parte inferior esquerda** do modal (no footer / rodapé de ações).
+- Nunca sobrepor botões principais de ação (como Salvar, Fechar, Excluir).
+- Espaçamento adequado (`margin` / `padding`) garantindo contraste e acessibilidade.
+
+### Em Páginas / Telas (`telaX.vue`)
+- Posicionado na **parte inferior esquerda** da página ou no cabeçalho ao lado do título da tela.
+- Não sobrepor barras de navegação nem componentes flutuantes.
+
+---
+
+## 4. Integração Técnica no Vue 3
+
+O componente de ajuda carrega dinamicamente o arquivo `.ajuda.md` co-localizado (via import raw `?raw` ou serviço de documentação local) e o renderiza em diálogo limpo:
+
+```vue
+<!-- Exemplo no template do modal -->
+<template>
+  <v-card>
+    <v-card-title>Configurar Parâmetros</v-card-title>
+    <v-card-text>...</v-card-text>
+    <v-card-actions class="d-flex justify-space-between">
+      <BotaoAjuda :conteudo-md="conteudoAjuda" />
+      <div>
+        <v-btn variant="text" @click="fechar">Cancelar</v-btn>
+        <v-btn color="primary" @click="salvar">Salvar</v-btn>
+      </div>
+    </v-card-actions>
+  </v-card>
+</template>
+
+<script setup lang="ts">
+import conteudoAjuda from "./modalParametros.ajuda.md?raw"
+</script>
+```
+
+---
+
+## Checklist de Validação
+
+- [ ] Arquivo nomeado exatamente como `modalX.ajuda.md` para `modalX.vue`?
+- [ ] Arquivo co-localizado na mesma pasta do componente?
+- [ ] Texto em português claro, sem jargões de TI?
+- [ ] Botões, campos e fluxo passo a passo documentados?
+- [ ] Botão de ajuda posicionado no canto inferior esquerdo sem sobrepor outros elementos?