Search the docs, videos, blog, apps, teams, skills and release notes.
At a glance
What it is
Expert guidance for building custom elements with shadow DOM, lifecycle callbacks, slots, form participation, and framework interoperability patterns.
A skill is a written procedure a bot loads when a job calls for it. This one is a single file, SKILL.md, and the whole file is on this page.
The whole file, exactly as it downloads. Read it before you rely on it.
SKILL.md
429 lines · 1,742 words
You are an expert in web components and the custom elements API. You guide developers through building reusable, framework-agnostic UI components using native browser standards: custom elements, shadow DOM, HTML templates, slots, and the CSS parts API. You emphasize progressive enhancement, accessibility, form participation, and interoperability with any framework.
Expert guidance for building custom elements with shadow DOM, lifecycle callbacks, slots, form participation, and framework interoperability patterns.
Nothing. It ships with Murage, which is open source. Your bots run on the AI plan you already have.
Yes. Open it in Settings → Skills to read, edit or duplicate it. Skill Guard scans it again after every edit.
Download the app, connect the AI you already pay for, and tell your Chief of Staff what needs doing. Plan on about ten minutes from install to a working team.
No account needed · Runs on the AI plan you already pay for
Paste it into your agent's instructions (CLAUDE.md, AGENTS.md or a custom GPT), or add it to a bot in Murage.
Ask Ember for the bot, then switch the skill on in its settings.
Step 1
Send your Chief of Staff this message. It proposes the bot and its role first, and creates it when you say go.
Send this to Ember
“Create a bot that uses the Web Components skill, and show me the plan first.”
You're done when your Chief proposes the bot and its role, and the bot appears in your sidebar once you say go.
Step 2
You're done when you see the bot’s skills and the library.
Step 3
You're done when the skill shows as on for that bot.
Step 4
You're done when the bot takes the job and opens the skill when it needs it.
Prefer to do it yourself? Choose + in the sidebar, then New Bot.Read the full guide to skills and Skill Guard
What it teaches a bot, what it covers, and the whole file to read.
The principle
You are an expert in web components and the custom elements API. You guide developers through building reusable, framework-agnostic UI components using native browser standards: custom elements, shadow DOM, HTML templates, slots, and the CSS parts API. You emphasize progressive enhancement, accessibility, form participation, and interoperability with any framework.
What it covers
Custom Element Fundamentals
Shadow DOM Deep Dive
Slots and Composition
Form-Associated Custom Elements
Lifecycle Callback Reference
Framework Interoperability
Performance Patterns
Accessibility Checklist
Performance Checklist
Decision Matrix: Component Approach
When to Use
Output Format
Example
Edge Cases
class AppAlert extends HTMLElement {
static observedAttributes = ['type', 'dismissible'];
#type = 'info';
#dismissible = false;
#shadow;
constructor() {
super();
this.#shadow = this.attachShadow({ mode: 'open' });
}
connectedCallback() {
this.#render();
this.#setupListeners();
}
disconnectedCallback() {
this.#controller?.abort();
}
attributeChangedCallback(name, oldValue, newValue) {
if (oldValue === newValue) return;
switch (name) {
case 'type':
this.#type = newValue || 'info';
break;
case 'dismissible':
this.#dismissible = newValue !== null;
break;
}
if (this.isConnected) this.#render();
}
get type() { return this.#type; }
set type(val) { this.setAttribute('type', val); }
get dismissible() { return this.#dismissible; }
set dismissible(val) { this.toggleAttribute('dismissible', Boolean(val)); }
#controller;
#setupListeners() {
this.#controller = new AbortController();
const { signal } = this.#controller;
this.#shadow.querySelector('.dismiss')?.addEventListener('click', () => {
this.dispatchEvent(new CustomEvent('dismiss', { bubbles: true, composed: true }));
this.remove();
}, { signal });
}
// NOTE: For production use, prefer template cloning (see Performance
// Patterns below) or a DOM-building helper over setting shadow root
// content directly. Always sanitize any user-provided data before
// inserting it into the DOM.
#render() {
const typeStyles = {
info: { bg: '#e8f4fd', border: '#2196F3' },
success: { bg: '#e8f5e9', border: '#4CAF50' },
warning: { bg: '#fff8e1', border: '#FF9800' },
error: { bg: '#fde8e8', border: '#f44336' },
};
const colors = typeStyles[this.#type] || typeStyles.info;
// Clear and rebuild using safe DOM methods
const root = this.#shadow;
root.replaceChildren();
const style = document.createElement('style');
style.textContent = `
:host { display: block; margin: 0.5rem 0; }
:host([hidden]) { display: none; }
.alert {
display: flex; align-items: flex-start; gap: 0.75rem;
padding: 0.75rem 1rem; border-radius: 6px;
border-left: 4px solid ${colors.border};
background: ${colors.bg};
font-family: inherit; font-size: 0.95rem;
}
.content { flex: 1; }
.dismiss {
background: none; border: none; cursor: pointer;
font-size: 1.2rem; padding: 0; line-height: 1; opacity: 0.6;
}
.dismiss:hover { opacity: 1; }
`;
root.appendChild(style);
const alert = document.createElement('div');
alert.className = 'alert';
alert.setAttribute('role', 'alert');
const content = document.createElement('div');
content.className = 'content';
content.appendChild(document.createElement('slot'));
alert.appendChild(content);
if (this.#dismissible) {
const btn = document.createElement('button');
btn.className = 'dismiss';
btn.setAttribute('aria-label', 'Dismiss');
btn.textContent = '\u00D7';
alert.appendChild(btn);
}
root.appendChild(alert);
}
}
customElements.define('app-alert', AppAlert);<app-alert type="success" dismissible>
Your changes have been saved.
</app-alert>
<script>
document.querySelector('app-alert').addEventListener('dismiss', (e) => {
console.log('Alert dismissed');
});
</script>// Open shadow DOM - shadowRoot accessible from outside
this.attachShadow({ mode: 'open' });
// el.shadowRoot returns the shadow root
// Closed shadow DOM - shadowRoot not accessible
this.attachShadow({ mode: 'closed' });
// el.shadowRoot returns null
// Store reference privately: this.#shadow = this.attachShadow({ mode: 'closed' });class AppCard extends HTMLElement {
constructor() {
super();
const shadow = this.attachShadow({ mode: 'open' });
const style = document.createElement('style');
style.textContent = `
:host {
display: block;
--card-padding: 1.5rem;
--card-radius: 8px;
--card-bg: #ffffff;
--card-shadow: 0 2px 8px rgba(0,0,0,0.1);
}
:host([variant="outlined"]) {
--card-shadow: none;
--card-border: 1px solid #ddd;
}
.card {
padding: var(--card-padding);
border-radius: var(--card-radius);
background: var(--card-bg);
box-shadow: var(--card-shadow);
border: var(--card-border, none);
}
.header { margin-bottom: 1rem; }
[part="title"] { font-size: 1.25rem; font-weight: 600; margin: 0; }
[part="body"] { line-height: 1.6; }
`;
shadow.appendChild(style);
// Build DOM structure programmatically
const card = document.createElement('div');
card.className = 'card';
const header = document.createElement('div');
header.className = 'header';
const title = document.createElement('h3');
title.setAttribute('part', 'title');
const titleSlot = document.createElement('slot');
titleSlot.name = 'title';
titleSlot.textContent = 'Card Title';
title.appendChild(titleSlot);
header.appendChild(title);
const body = document.createElement('div');
body.setAttribute('part', 'body');
body.appendChild(document.createElement('slot'));
const footer = document.createElement('div');
footer.setAttribute('part', 'footer');
const footerSlot = document.createElement('slot');
footerSlot.name = 'footer';
footer.appendChild(footerSlot);
card.append(header, body, footer);
shadow.appendChild(card);
}
}
customElements.define('app-card', AppCard);/* External styling via custom properties */
app-card {
--card-padding: 2rem;
--card-bg: #f9fafb;
}
/* External styling via ::part() */
app-card::part(title) {
color: navy;
font-size: 1.5rem;
}
app-card::part(footer) {
border-top: 1px solid #eee;
padding-top: 1rem;
margin-top: 1rem;
}connectedCallback() {
const slot = this.shadowRoot.querySelector('slot:not([name])');
slot.addEventListener('slotchange', () => {
const assigned = slot.assignedElements();
console.log(`${assigned.length} elements slotted`);
this.#updateLayout(assigned);
});
}To make a custom element participate in <form> natively (works with FormData, validation, reset):
class AppRating extends HTMLElement {
static formAssociated = true;
static observedAttributes = ['value', 'max', 'required', 'disabled'];
#internals;
#value = 0;
constructor() {
super();
this.#internals = this.attachInternals();
this.attachShadow({ mode: 'open', delegatesFocus: true });
}
// Key form integration points:
get value() { return this.#value; }
set value(val) {
this.#value = Number(val);
this.#internals.setFormValue(String(this.#value)); // Submit value
this.#validate();
this.#render();
}
get form() { return this.#internals.form; }
get validity() { return this.#internals.validity; }
#validate() {
if (this.hasAttribute('required') && this.#value === 0) {
this.#internals.setValidity({ valueMissing: true }, 'Required');
} else {
this.#internals.setValidity({});
}
}
formResetCallback() { this.value = 0; } // Called on form.reset()
formDisabledCallback(disabled) { this.#render(); } // Called when disabled changes
// formStateRestoreCallback(state, mode) // Called on browser back/forward
#render() { /* build star rating UI */ }
}
customElements.define('app-rating', AppRating);Usage: <form><app-rating name="rating" required></app-rating></form> -- the value appears in new FormData(form).get('rating').
| Callback | When It Fires | Common Uses |
|---|---|---|
constructor() | Element created | Attach shadow DOM, init state |
connectedCallback() | Added to document | Render, add listeners, get data |
disconnectedCallback() | Removed from document | Cleanup listeners, timers, observers |
attributeChangedCallback(name, old, new) | Observed attribute changes | Update state, re-render |
adoptedCallback() | Moved to new document | Re-initialize document-dependent code |
formAssociatedCallback(form) | Associated with a form | Store form reference |
formResetCallback() | Form is reset | Reset to default value |
formDisabledCallback(disabled) | Disabled state changes | Update UI disabled state |
formStateRestoreCallback(state, mode) | Browser restores form state | Restore saved value |
React: Use a useRef + useEffect wrapper to set properties (not just attributes) and attach event listeners on custom elements. React 19+ has improved custom element support natively.
Vue: Add compilerOptions.isCustomElement in vite config: tag => tag.startsWith('app-'). Vue handles attributes, properties, and @event bindings on custom elements.
Angular: Custom elements work natively. Add CUSTOM_ELEMENTS_SCHEMA to your module or component schemas.
Svelte: Bind to custom element properties with bind:property and listen to events with on:eventname.
Template cloning: Create a <template> element once, then use template.content.cloneNode(true) in the constructor. Significantly faster than rebuilding DOM each render.
adoptedStyleSheets: Create CSSStyleSheet objects and assign to shadow.adoptedStyleSheets. Shares memory across instances and enables dynamic style updates via replaceSync().
Set appropriate ARIA role for non-standard semantics (slider, tablist, dialog, etc.)
Manage tabindex for focusable shadow DOM elements
Use delegatesFocus: true when shadow root should delegate focus
Dispatch composed events (composed: true) when events must cross shadow boundaries
Provide keyboard navigation matching the expected ARIA pattern
Use :host(:focus-visible) for visible focus indicators
Ensure aria-label or aria-labelledby for non-text content
Test with screen readers (VoiceOver, NVDA) since shadow DOM can behave differently
Implement formAssociated for form controls so they participate in validation
Use template cloning (cloneNode) instead of rebuilding DOM per render
Use adoptedStyleSheets for shared stylesheets across instances to reduce memory
Debounce attributeChangedCallback when multiple attributes change together
Use requestAnimationFrame for visual updates triggered by events
Lazy-load heavy shadow DOM content until the element is visible
| Factor | Web Components | Framework Component |
|---|---|---|
| Cross-framework reuse needed | Preferred | Not possible |
| Design system / shared library | Preferred | Only if single framework |
| Requires complex state management | Consider carefully | Preferred |
| Form integration needed | Use formAssociated | Native framework forms |
| SSR required | Needs declarative shadow DOM | Better framework support |
| Team expertise | Standards knowledge | Framework knowledge |
| Style encapsulation critical | Shadow DOM enforces it | CSS modules / scoped styles |
Use this skill when:
Designing or implementing web components solutions
Reviewing or improving existing web components approaches
Making architectural or implementation decisions about web components
Learning web components patterns and best practices
Troubleshooting web components-related issues
Do NOT use this skill when:
The question is about a fundamentally different technology domain
A more specific sibling skill covers the exact topic needed
The user needs a complete hands-on tutorial rather than expert guidance
# Web Components Analysis
## Context Assessment
[Situation summary and constraints]
## Recommended Approach
[Primary recommendation with rationale]
## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]
## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]
## Next Steps
- [Immediate action item]
- [Follow-up action item]Input: "Help me implement web components for a medium-scale production application"
Output: A structured analysis covering current state assessment, recommended web components approach with specific patterns, implementation roadmap with milestones, and risk mitigation strategies tailored to the application scale and constraints.
Legacy system integration: When web components must coexist with legacy approaches, provide a gradual migration path rather than a complete rewrite
Scale mismatch: When the solution complexity exceeds the project scale, recommend a simpler approach and note when to revisit
Team skill gaps: When the team lacks experience with the recommended approach, include learning resources and simpler alternatives
Conflicting requirements: When constraints conflict (e.g., performance vs. maintainability), explicitly state the trade-off and recommend based on stated priorities
SKILL.md
429 lines · 1,742 words
The text of SKILL.md is shown as it downloads, under the Apache-2.0 license, by Ferrox Labs. The license is the one in the file's own frontmatter.
Your new bot
Web Components bot
Waiting in your sidebar once you say go.
No account needed · Runs on the AI plan you already pay for