web-components_skill

Overview

This skill defines a strict, production-ready architecture for building web components with the Custom Elements v1 API and Declarative Shadow DOM. It enforces attribute-driven state, the handleEvent pattern for events, zero DOM selection (no querySelector/getElementById), and no external libraries—pure web platform APIs only. Use it to create accessible, extendable, and progressively enhanced custom elements.

How this skill works

Components read input exclusively from attributes and expose changes via CustomEvent instances. Event handling is attached to the element itself with this.addEventListener and routed through a handleEvent method to avoid manual binding and simplify cleanup. Declarative Shadow DOM templates render immediately without JS, while lifecycle callbacks (connectedCallback, disconnectedCallback, attributeChangedCallback) manage setup, teardown, and reactive behavior. Customized built-in elements are preferred to preserve native semantics.

When to use it

• Building custom UI controls that must preserve native accessibility (extend built-ins).
• Creating composite or layout components that should render without JS using Declarative Shadow DOM.
• Implementing components that must avoid global DOM queries and operate by attributes only.
• Integrating custom elements with HTML forms using ElementInternals.
• Designing components for progressive enhancement and predictable lifecycle/resource cleanup.

Best practices

• Flow all input through attributes and observe changes via observedAttributes/attributeChangedCallback.
• Attach listeners on this and implement handleEvent to keep memory management simple.
• Never use querySelector, querySelectorAll, getElementById, or innerHTML inside components.
• Prefer customized built-in elements when native behavior and accessibility are required.
• Use Declarative Shadow DOM (<template shadowrootmode="open">) for instant render and slots/parts for styling hooks.
• Combine this architecture with solid async and cleanup patterns (timeouts, AbortController, disconnectedCallback).

Example use cases

• An accessible toggle button that extends HTMLButtonElement and manages pressed state via aria-pressed attribute.
• A product-card container using a declarative shadow template with slots and CSS parts for theming.
• A form-associated custom input leveraging ElementInternals to participate in form submission and validation.
• An async-action button that manages fetch timeouts with AbortController and sets aria-busy via attributes.
• A keyboard-navigable list component that updates state through attributes and emits activation events.