---
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?