109 lines
3.9 KiB
Markdown
109 lines
3.9 KiB
Markdown
---
|
|
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?
|