Prévia Markdown
Guia de Referência: Web Components para IA — Referência MDN
Visualização renderizada do arquivo tecnologias/web-components-mdn.md. O conteúdo abaixo é o mesmo arquivo destinado a orientar a IA.
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
opensalvo 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/composedconscientemente.
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
- A tecnologia escolhida resolve um requisito real e foi aplicada no ambiente correto.
- Semântica, acessibilidade e estados de teclado/foco foram revisados.
- Entradas externas são tratadas como não confiáveis e saídas são renderizadas com segurança.
- Erros, estados vazios, carregamento, offline/rede e cancelamento foram considerados quando aplicável.
- Compatibilidade e fallback foram avaliados para recursos não Baseline/amplamente suportados.
- O código não duplica APIs nativas ou responsabilidades de outra camada.
- Performance foi medida quando a decisão tem impacto relevante.
Prompt-base para IA
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
Contexto: Biblioteca de UI deve funcionar em páginas sem framework e ser distribuída como ES Modules.
Objetivo: Criar um componente <status-badge> 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