Guide writing or changing Web Components so they fit the project and work for every consumer: learn its browser targets, consuming frameworks and versions, component library and conventions first, then design a stable public contract (tag, attributes, properties, events, slots, parts) and implement it with idempotent lifecycle and cleanup, shadow or light DOM as fits, accessibility across shadow boundaries, native form association, server-rendered roots reused, and a real-browser check. Use whenever you create or edit a custom element, a shadow root, a Lit, FAST or Stencil component, a form-associated control, or a component library's registration, types or docs, even when the user doesn't say Web Components. It adds no library, base class or TypeScript migration unless asked. Not for reviewing components already written (the knackpack:web-components-code-reviewer agent, started only on request), CSS layout and cascade (the css-engineering skill), or React's own semantics (the React reviewer).
90%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
Build elements the way the project already builds them, change as little as the requirement needs, and leave nothing that breaks when the element is moved, upgraded late, used from another framework, operated by keyboard or screen reader, or loaded in a browser the project supports. These rules hold for every edit: a one-line change to a lifecycle callback is where a leak or a lost value slips through.
HTMLElement, Lit, FAST, Stencil), base classes, naming, registration pattern, shadow or light DOM choice, styling approach and documentation format decide, even where you'd choose differently. Read them before writing; never introduce a library, a base class hierarchy, a reactive system, a global store or a TypeScript migration unless the user asks.detail, slots, CSS parts, custom properties and custom states are what consumers rely on. Add, don't rename; when a rename is required, find every consumer first (grep the tag, class, event and slot names), and for a published package treat it as a breaking change.ElementInternals and constructable stylesheets before custom machinery. Adopt a library only when its value is demonstrable for this project.npx (with no terminal attached it downloads and runs missing packages without asking), and never run a tool's fix or write mode over files you didn't change. Use the tools already in node_modules, by path.Read before writing, and keep the answers in mind for every step:
package.json (exports, files, sideEffects, peerDependencies, a customElements field), a custom-elements.json manifest, generated .d.ts files, the README or Storybook that documents components.browserslist or a Baseline target; with none, assume Baseline widely available and say so.define is called, whether definitions load eagerly or lazily, shadow or light DOM and why, how styles are shared, whether the server renders declarative shadow DOM.target, useDefineForClassFields), ESLint plugins (eslint-plugin-wc, eslint-plugin-lit), the test runner and whether it uses real browsers.Write down, before the class, what consumers will touch:
| Interface | Convention |
|---|---|
| Tag name | lowercase, with a hyphen, in the project's prefix |
| Class | PascalCase, matching the tag |
| Attribute | lowercase kebab-case, serializable configuration only |
| Property | camelCase; rich values (objects, arrays) as properties only |
| Event | lowercase kebab-case name, documented detail |
| Slot, part | lowercase kebab-case, named for the role |
| Custom property | the project's namespace (--prefix-name) |
| Private state | #private fields |
Decide each default, what an invalid value does, which attributes reflect, which events fire and when, and what the keyboard does. Keep internals private: expose only what a consumer needs.
Constructor: call super() first; attach the shadow root (or reuse a server-rendered one, step 6), create private state, add listeners on the element itself. Never read or add attributes or children there: an element created by createElement or the parser after definition fails if its constructor adds them, while an upgrade doesn't check, so the bug depends on loading order.
connectedCallback runs on every insertion, including every move. Make setup idempotent: one-time work in the constructor or behind a flag; connection-scoped work (listeners on window, document or other elements, observers, timers, subscriptions, fetches) created here and released in disconnectedCallback. Use a fresh AbortController per connection, pass its signal to addEventListener and fetch, and abort it on disconnect; a listener added with an already-aborted signal is never added, so don't reuse the old one. Disconnection isn't destruction: the element must set up again cleanly when reinserted. Check this.isConnected before async results touch the DOM.
Properties set before the element is defined become own properties that hide your accessors after the upgrade. In connectedCallback, for each public property: if Object.hasOwn(this, name), read it, delete this[name], assign it again.
Attributes and properties: list observed attributes in lowercase in static observedAttributes. Getters read the attribute (or private state for rich values); setters write it; attributeChangedCallback only performs side effects, so nothing loops. Booleans use presence: toggleAttribute(name, Boolean(value)), never setAttribute(name, value), which writes "false". Never overwrite a consumer's role, tabindex, aria-*, class or style; set defaults only when absent, or through ElementInternals.
Events: dispatch component events from the host (this.dispatchEvent(new CustomEvent('item-select', { bubbles: true, detail }))); an event dispatched from inside the shadow root without composed: true never reaches the page. change and submit aren't composed, so re-dispatch your own change when an inner input changes; click, input and keydown already escape, so don't re-dispatch those. Send copies in detail, never internal objects, since a listener that changes detail would otherwise change the element's state without its setters. Don't fire events in response to the consumer setting a property: native elements fire only for user actions, and a framework that sets the property when it hears the event would loop.
Inheritance: an override of a lifecycle callback calls super's; a subclass's observedAttributes includes the parent's.
Registration: follow the project's pattern. Remember that define throws if the name is taken, and that a customElements.get guard hides two different versions rather than fixing the conflict; prefer one shared copy (a peer dependency). A package whose modules register on import lists them in sideEffects, or bundlers drop them.
CSSStyleSheet per class in adoptedStyleSheets (or the library's equivalent), not a <style> per instance.part for elements consumers may restyle, exportparts through nested components, custom states (internals.states, :state()) for state styling. Document each. Avoid :host-context(): the CSS Working Group removed it from the specification, and only Chromium ships it.slot matches no slot isn't rendered; provide fallback content, and use slotchange to react to assignment changes.delegatesFocus: true instead of tabindex on the host, which creates two tab stops.Meet WCAG 2.2 at the project's level, AA by default:
<button>, <input>, <a href>); a <div> with a role needs keyboard handling, focusability and a name, and usually misses one.aria-labelledby, aria-describedby, aria-controls, <label for>) don't cross shadow boundaries. Put the label inside the shadow root, slot it, accept the text through an attribute, make the element form-associated so <label> names it, or use element reflection (ariaLabelledByElements) for references outward. Reference Target shipped first in Chrome and Edge 152 and isn't Baseline, so check it against the targets before relying on it.ElementInternals (internals.role, internals.ariaChecked, ...), which consumer attributes can override.<dialog> with showModal() for modals rather than a hand-built focus trap.prefers-reduced-motion and forced colors in component styles (see the css-engineering skill).Form controls set static formAssociated = true, call attachInternals() once in the constructor, and then:
setFormValue(value, state) on every change, at start and after reset (null means not submitted);setValidity(flags, message, anchor) with a message and an anchor inside the element, and setValidity({}) when valid;formResetCallback, formDisabledCallback (disable inner controls too) and formStateRestoreCallback;name, value, disabled and required like a native control.Don't fall back to a hidden input unless a target lacks form-associated custom elements, and then design and state the fallback.
Server-rendered roots: when the server sends <template shadowrootmode>, the root already exists. Calling attachShadow() again empties it. Reuse it:
this.#internals = this.attachInternals();
const root = this.#internals.shadowRoot ?? this.attachShadow({ mode: 'open' });Then hydrate the existing nodes instead of re-rendering. Add server rendering only where the application needs it.
onname to a listener for name with the case kept. So define the element before React renders it, and use lowercase or kebab-case event names. React 18 and earlier pass everything as attributes and ignore custom events: bridge with a ref and an effect, or a wrapper.compilerOptions.isCustomElement; Angular needs CUSTOM_ELEMENTS_SCHEMA; Svelte 5 sets properties only where the prototype has a setter, so expose accessors, not plain class fields.HTMLElementTagNameMap, event maps, JSX IntrinsicElements) in step with what the code dispatches and accepts. With Lit and useDefineForClassFields, declare reactive properties with accessor or declare so class fields don't shadow them. Validate untrusted runtime values; types don't.Build DOM from a static <template> and set textContent and attributes. Never pass attributes, properties, URL parameters or fetched data to innerHTML, insertAdjacentHTML or setHTMLUnsafe; a shadow root doesn't stop script. Allow only safe URL schemes in href and src, and never import() a URL from an attribute.
false, events received outside the host, slot assignment, form submission, reset and disabling, keyboard operation and accessible names, and server-rendered upgrade where used.bezmoradi/knackpack
a52ee20
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.