# Guia de Referência: HTML para IA — Referência MDN

Guia de HTML semântico para que a IA estruture documentos e aplicações com significado, acessibilidade nativa e bases corretas para CSS e JavaScript.

---

## 1. Contrato de execução para a IA

- Trate este arquivo como **referência de decisão e implementação**, não como licença para aplicar toda tecnologia disponível.
- Antes de codificar, declare o **ambiente** (browser, Node.js, worker, servidor, PWA etc.), os requisitos e as restrições de compatibilidade.
- Prefira a solução nativa e simples quando ela atende aos requisitos com boa acessibilidade, segurança e manutenção.
- Consulte compatibilidade antes de usar APIs experimentais ou de disponibilidade limitada.
- Não misture responsabilidades: estrutura/semântica em HTML, apresentação em CSS, comportamento em JavaScript e capacidades do navegador em Web APIs.
- Considere segurança, privacidade, performance e acessibilidade desde o design, não como correções finais.

---

## 2. Documento e metadados

### Documento base

- **Conceito:** doctype, html/lang, head, charset, viewport, title e metadata.
- **Regra para IA:** Sempre defina idioma e título; mantenha metadata relevante no head.

### Landmarks

- **Conceito:** header, nav, main, aside, footer.
- **Regra para IA:** Use landmarks de acordo com significado; normalmente há um `main` principal por documento.

### Conteúdo seccionado

- **Conceito:** article, section, headings.
- **Regra para IA:** Mantenha hierarquia de headings coerente e use section/article quando houver propósito semântico.

---

## 3. Texto e navegação

### Links

- **Conceito:** `a` com href para navegação.
- **Regra para IA:** Texto do link deve indicar destino; não use link vazio como botão.

### Buttons

- **Conceito:** `button` para ações.
- **Regra para IA:** Defina `type` em forms e nome acessível; não simule botão com div.

### Listas

- **Conceito:** ul/ol/dl.
- **Regra para IA:** Use lista quando os itens têm relação de lista, não apenas por layout.

---

## 4. Formulários

### Labels e controles

- **Conceito:** label, input, select, textarea, button, fieldset/legend.
- **Regra para IA:** Associe label/controle e agrupe conjuntos relacionados com fieldset/legend.

### Tipos de input

- **Conceito:** email, url, number, date, file, checkbox, radio etc.
- **Regra para IA:** Escolha tipo semântico para teclado mobile e validação nativa.

### Validação

- **Conceito:** required, min/max, minlength/maxlength, pattern e Constraint Validation.
- **Regra para IA:** Use validação nativa para UX, mas valide novamente no servidor.

---

## 5. Dados e mídia

### Tabelas

- **Conceito:** table, caption, thead/tbody/tfoot, th/scope.
- **Regra para IA:** Use apenas para dados tabulares e associe cabeçalhos.

### Imagens

- **Conceito:** img, picture, source, srcset/sizes.
- **Regra para IA:** Forneça alt adequado; use alt vazio apenas para imagem decorativa.

### Áudio e vídeo

- **Conceito:** audio/video/source/track.
- **Regra para IA:** Forneça controles e legendas/transcrições quando aplicável.

### Iframe

- **Conceito:** Incorporação de documento externo.
- **Regra para IA:** Defina title e avalie sandbox/allow pela menor permissão.

---

## 6. Elementos interativos e templates

### details/summary

- **Conceito:** Disclosure nativo.
- **Regra para IA:** Prefira quando atende ao requisito em vez de recriar accordion simples em JS.

### dialog

- **Conceito:** Diálogos nativos.
- **Regra para IA:** Use API apropriada, foco e fechamento previsíveis.

### template/slot

- **Conceito:** Conteúdo inerte reutilizável e composição.
- **Regra para IA:** Use como base declarativa de Web Components quando apropriado.

---

## Checklist de aceite

1. [ ] A tecnologia escolhida resolve um requisito real e foi aplicada no ambiente correto.
2. [ ] Semântica, acessibilidade e estados de teclado/foco foram revisados.
3. [ ] Entradas externas são tratadas como não confiáveis e saídas são renderizadas com segurança.
4. [ ] Erros, estados vazios, carregamento, offline/rede e cancelamento foram considerados quando aplicável.
5. [ ] Compatibilidade e fallback foram avaliados para recursos não Baseline/amplamente suportados.
6. [ ] O código não duplica APIs nativas ou responsabilidades de outra camada.
7. [ ] Performance foi medida quando a decisão tem impacto relevante.

---

## Prompt-base para IA

```text
Use o guia "HTML para IA — Referência MDN" anexado como contrato técnico.
Analise meu requisito e escolha somente os conceitos necessários.
Diga quais partes do guia serão aplicadas e por quê.
Implemente com semântica, acessibilidade, segurança e compatibilidade.
Não invente APIs.
Ao final, revise a solução pelo checklist do guia.


Contexto: [DESCREVA o sistema, stack/versões, ambiente e estado atual]
Objetivo: [DESCREVA o resultado observável esperado]
Restrições: [DESCREVA o que não pode mudar e os limites técnicos]
```


### Como preencher os campos

- **Contexto:** descreva sistema, stack/versões, arquitetura ou ambiente, estado atual e onde a mudança acontece.
- **Objetivo:** descreva o resultado observável esperado — o que o usuário ou o sistema deve conseguir fazer ao final.
- **Restrições:** descreva o que não pode mudar e os limites de compatibilidade, segurança, acessibilidade, performance, dependências e escopo.

### Exemplo preenchido

```text
Contexto: Página de cadastro usada com teclado e leitores de tela; o backend depende dos names e ids atuais dos campos.
Objetivo: Reestruturar o formulário com semântica correta, labels, fieldsets e mensagens de erro sem mudar o contrato enviado ao servidor.
Restrições: Preservar names/ids; links continuam navegação e buttons continuam ações; não depender apenas de placeholder para nomear campos.
```

---

## Fontes primárias

- MDN HTML: https://developer.mozilla.org/pt-BR/docs/Web/HTML