# Guia de Referência: Web Components para IA — Referência MDN Guia especializado em Web Components para construir componentes nativos, reutilizáveis e interoperáveis usando Custom Elements, Shadow DOM e templates/slots. --- ## 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. Quando usar ### Interoperabilidade - **Conceito:** Componente utilizável por aplicações sem exigir um framework específico. - **Regra para IA:** Use quando a API web nativa e a independência de framework têm valor real. ### Encapsulamento - **Conceito:** Limite local para implementação e estilo. - **Regra para IA:** Use Shadow DOM quando isolamento ajuda mais do que atrapalha integração/theming. --- ## 3. Custom Elements ### Definição - **Conceito:** `customElements.define()` registra um elemento customizado; o nome contém hífen. - **Regra para IA:** Crie API pequena e estável; não faça trabalho pesado no constructor. ### Lifecycle - **Conceito:** connectedCallback, disconnectedCallback, adoptedCallback e attributeChangedCallback. - **Regra para IA:** Registre listeners/recursos ao conectar e limpe ao desconectar. ### Attributes vs properties - **Conceito:** Attributes são string/markup; properties podem conter valores ricos. - **Regra para IA:** Defina reflexão apenas quando útil e evite loops de sincronização. --- ## 4. Shadow DOM ### Shadow root - **Conceito:** Árvore encapsulada open/closed. - **Regra para IA:** Prefira `open` salvo requisito forte; encapsulamento não é barreira de segurança. ### Estilos - **Conceito:** CSS interno, :host, ::slotted, parts/custom properties. - **Regra para IA:** Exponha pontos de customização deliberados; não force consumidor a atravessar internals. --- ## 5. Templates e slots ### template - **Conceito:** Fragmento inerte clonável. - **Regra para IA:** Use para DOM repetível sem parsing de string inseguro. ### slot - **Conceito:** Ponto de projeção de conteúdo light DOM. - **Regra para IA:** Nomeie slots quando houver múltiplos papéis e defina fallback útil. --- ## 6. Eventos e integração ### CustomEvent - **Conceito:** Contrato de saída do componente. - **Regra para IA:** Use eventos para comunicar mudanças sem acoplar ao consumidor; configure `bubbles`/`composed` conscientemente. ### Forms - **Conceito:** Form-associated custom elements quando necessário. - **Regra para IA:** Antes de criar controle próprio, verifique se elemento HTML nativo resolve melhor acessibilidade. --- ## 7. Acessibilidade ### Semântica - **Conceito:** Nome, role, states e relações. - **Regra para IA:** Use elemento nativo internamente sempre que possível e teste com teclado/leitor de tela. ### Foco - **Conceito:** Delegação/ordem de foco e estados. - **Regra para IA:** Não crie armadilhas de foco; expose comportamento esperado ao consumidor. --- ## 8. Distribuição ### ES Modules - **Conceito:** Entrega do componente como módulo. - **Regra para IA:** Declare dependências, efeitos colaterais e versão; evite registrar globalmente múltiplas vezes. ### Design tokens - **Conceito:** Custom properties para theming. - **Regra para IA:** Exponha tokens semânticos em vez de seletores internos frágeis. --- ## 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 "Web Components 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: Biblioteca de UI deve funcionar em páginas sem framework e ser distribuída como ES Modules. Objetivo: Criar um componente reutilizável com tema, atributos/propriedades documentados e evento de mudança. Restrições: API pequena e estável; acessibilidade nativa; lifecycle com cleanup; Shadow DOM somente se o encapsulamento trouxer benefício real. ``` --- ## Fontes primárias - MDN Web Components: https://developer.mozilla.org/pt-BR/docs/Web/API/Web_components