# Guia de Referência: Plataforma Web — Referências MDN para IA Mapa mestre das **tecnologias Web** para orientar uma IA na escolha entre HTML, CSS, JavaScript, HTTP, Web APIs e Web Components. Use este arquivo para decidir a camada correta antes de anexar um guia especializado. --- ## 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. Mapa de responsabilidades ### HTML - **Conceito:** Estrutura e significado do conteúdo. - **Regra para IA:** Se o problema é semântico, conteúdo, formulário ou estrutura do documento, resolva primeiro em HTML. ### CSS - **Conceito:** Apresentação, layout, responsividade e estados visuais. - **Regra para IA:** Se o requisito é visual/layout, resolva em CSS antes de adicionar JavaScript. ### JavaScript - **Conceito:** Linguagem de programação e comportamento da aplicação. - **Regra para IA:** Use para regras, estado e coordenação; não reproduza funcionalidades nativas de HTML/CSS sem necessidade. ### Web APIs - **Conceito:** Capacidades expostas pelo ambiente Web ao código. - **Regra para IA:** Escolha a API pelo requisito e verifique permissões, segurança, suporte e contexto disponível. ### HTTP - **Conceito:** Protocolo de aplicação e semântica de comunicação cliente-servidor. - **Regra para IA:** Modele método/status/cache/headers com semântica correta; não esconda problemas de API em hacks de front-end. ### Web Components - **Conceito:** Custom Elements + Shadow DOM + templates/slots para componentes nativos reutilizáveis. - **Regra para IA:** Use quando interoperabilidade e encapsulamento nativos compensarem a complexidade adicional. --- ## 3. Referências para tecnologias Web ### WebAssembly - **Conceito:** Formato/VM para executar código compilado na Web. - **Regra para IA:** Use quando workload e ecossistema justificarem; não substitua JS para lógica comum sem evidência. ### Events - **Conceito:** Modelo de eventos do navegador. - **Regra para IA:** Prefira eventos nativos e contratos claros entre componentes. ### Media - **Conceito:** Áudio, vídeo, media streams e recursos relacionados. - **Regra para IA:** Use elementos nativos primeiro e APIs avançadas quando necessário. ### SVG e MathML - **Conceito:** Gráficos vetoriais e matemática semântica. - **Regra para IA:** Escolha SVG para gráficos/ícones vetoriais acessíveis e MathML para notação matemática quando suportado. ### WebDriver - **Conceito:** Automação padronizada de navegadores. - **Regra para IA:** Use em testes end-to-end/automação, não em runtime da aplicação. ### WebExtensions - **Conceito:** Extensões de navegador. - **Regra para IA:** Use apenas quando o produto é de fato uma extensão e respeite permissões mínimas. ### Web App Manifest e PWA - **Conceito:** Metadados instaláveis, service workers, offline e experiência de app. - **Regra para IA:** Adote somente recursos PWA que resolvem requisitos reais de instalação/offline/notificação. --- ## 4. Preocupações transversais ### Acessibilidade - **Conceito:** Semântica, teclado, foco, nomes, contraste e tecnologias assistivas. - **Regra para IA:** Acessibilidade é critério de aceite de toda camada. ### Performance - **Conceito:** Carga, renderização, rede, main thread e memória. - **Regra para IA:** Defina orçamento e meça com dados reais. ### Segurança - **Conceito:** Origem, CSP, XSS, CSRF, autenticação, transporte e permissões. - **Regra para IA:** Trate toda fronteira externa como não confiável e adote menor privilégio. ### Privacidade - **Conceito:** Coleta, storage, sensores, tracking e dados pessoais. - **Regra para IA:** Colete somente o necessário e peça permissões no contexto certo. --- ## 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 "Plataforma Web — Referências MDN para IA" 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: Aplicação web responsiva feita com HTML, CSS e JavaScript, destinada a Chrome, Edge e Firefox atuais. Objetivo: Criar upload de arquivo com validação, prévia e feedback de progresso escolhendo a camada Web mais adequada para cada parte. Restrições: Preferir recursos nativos; acessível por teclado; sem biblioteca adicional; funcionar em contexto HTTPS. ``` --- ## Fontes primárias - MDN Web: https://developer.mozilla.org/pt-BR/docs/Web - MDN Web APIs: https://developer.mozilla.org/pt-BR/docs/Web/API - MDN HTML: https://developer.mozilla.org/pt-BR/docs/Web/HTML - MDN CSS: https://developer.mozilla.org/pt-BR/docs/Web/CSS - MDN JavaScript: https://developer.mozilla.org/pt-BR/docs/Web/JavaScript - MDN HTTP: https://developer.mozilla.org/pt-BR/docs/Web/HTTP - MDN Web Components: https://developer.mozilla.org/pt-BR/docs/Web/API/Web_components