---
type: workflow
name: adicionar-ajuda
description: Adicionar ou atualizar botão de ajuda e documentação em telas (Frontend)
scope: local
updatedAt: "2026-06-01"
---

# Workflow: Adicionar Ajuda em Telas

Este workflow automatiza a inserção do botão de ajuda e a criação do arquivo de documentação correspondente sempre que uma tela é criada ou modificada de forma significativa.

O objetivo da ajuda é **auxiliar o usuário final a compreender e utilizar corretamente a aplicação**, explicando o funcionamento da tela de forma clara e objetiva.

## Pré-requisitos

- O arquivo alvo deve ser um componente de interface (`.tsx` para React ou `.vue` para Vue).
- O projeto deve possuir um componente de ajuda (ex: `BotaoAjuda`, `HelpButton` ou equivalente) disponível para uso na interface.
- Caso não exista, criar um componente reutilizável que exiba o conteúdo do `.ajuda.md` em modal ou drawer.

## Passos

### 1. Identificar o Componente Alvo

Determine qual arquivo representa a tela principal ou modal que está sendo criado ou editado.

- React → `.tsx`
- Vue → `.vue`

### 2. Verificar Existência de Ajuda

Procure por um arquivo de ajuda com o mesmo nome do componente e sufixo indicativo de ajuda (ex.: `.ajuda.md`) localizado na mesma pasta.

Exemplo:

```

TelaCadastroUsuario.tsx
TelaCadastroUsuario.ajuda.md

```

ou

```

TelaCadastroUsuario.vue
TelaCadastroUsuario.ajuda.md

````

### 3. Criar ou Atualizar o Arquivo Markdown

Se o arquivo `.ajuda.md` não existir, crie-o utilizando o template básico abaixo.

O conteúdo deve ser escrito **pensando no usuário final**, explicando de forma simples como utilizar a tela.

A documentação deve incluir, quando aplicável:

- **Objetivo da tela**
- **Descrição dos botões**
- **Descrição dos campos de formulário**
- **Regras de preenchimento e validações**
- **Fluxo esperado de uso**
- **Contexto técnico ou legal**, quando relevante para o entendimento da funcionalidade

Template inicial:

```markdown
# Ajuda: [Nome da Tela]

## Objetivo da Tela

Explique de forma simples para que serve esta tela dentro do sistema.

## Botões

- **Salvar**: grava as informações preenchidas.
- **Cancelar**: descarta as alterações realizadas.
- **Excluir**: remove o registro atual do sistema.

## Campos do Formulário

- **Nome**: informe o nome completo do responsável.
- **Data de Vistoria**: data em que a vistoria foi realizada.
- **Observações**: campo livre para registrar informações adicionais.

## Fluxo de Uso

1. Preencha os campos obrigatórios.
2. Revise as informações inseridas.
3. Clique em **Salvar** para registrar os dados no sistema.

## Informações Técnicas ou Legais (quando aplicável)

Explique regras técnicas, normas ou exigências legais relacionadas à funcionalidade da tela.
````

### 4. Posicionamento do Botão de Ajuda

O botão deve ser inserido de forma consistente e não pode interferir na interface da aplicação.

#### Telas / Páginas

* O botão deve ficar na **parte inferior esquerda da página**.
* Deve respeitar espaçamento suficiente das bordas da interface.
* **Não pode sobrepor nenhum componente da tela.**
* **Não pode ficar oculto ou sobreposto pela barra de módulos da aplicação.**
* Ajustar `margin`, `padding` ou `z-index` quando necessário para garantir visibilidade adequada.

#### Modais e Diálogos

* O botão deve ficar na **parte inferior esquerda do modal**.
* Preferencialmente no rodapé do modal ou em um container equivalente.
* **Não pode sobrepor botões ou ações do modal.**
* Garantir espaçamento adequado para não interferir na usabilidade.


