2026-09-28 22:18:39 -03:00

3.9 KiB

Raw Blame History

name	description	scope	updatedAt
adicionar-ajuda	Adicionar ou atualizar botão de ajuda e documentação contextual em telas e modais (Frontend)	global	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:

# 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:

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

3.9 KiB Raw Blame History