Web Components Architecture

Core Principles

This skill enforces a strict architectural pattern for web components:

Zero DOM Selection: NEVER use

querySelector

querySelectorAll

, or

getElementById

Attribute-Driven State: All state flows through HTML attributes
Event Delegation on
this
: Use
```
this.addEventListener
```
and the
```
handleEvent
```
pattern
No External Dependencies: Use only standard Web Platform APIs
Declarative Shadow DOM: Use
```
<template shadowrootmode="open">
```
for instant rendering
Progressive Enhancement: Components work (degraded) even if JavaScript fails
Customized Built-ins Over Autonomous: Extend native elements when possible to preserve accessibility

Relationship with JavaScript Best Practices

This skill defines the architectural pattern for building web components. When implementing components, combine this skill with

javascript-pragmatic-rules

for production-quality code:

This skill provides the WHAT (component architecture):

Component structure (extends HTMLElement)
Lifecycle callbacks (connectedCallback, disconnectedCallback)
State management (attribute-driven)
Event patterns (handleEvent, CustomEvent)
Shadow DOM and encapsulation

javascript-pragmatic-rules
provides the HOW (implementation quality):

Async operation handling (timeouts, cancellation)
Resource cleanup patterns
Error handling strategies
Memory leak prevention
Performance optimization

Example: Building an

<async-button>

component:

javascript

// Architecture from web-components-architecture skill
class AsyncButton extends HTMLButtonElement {
  #controller = null; // Private field for cleanup

  connectedCallback() {
    this.addEventListener('click', this);
  }

  // Using handleEvent pattern from web-components-architecture
  async handleEvent(e) {
    if (e.type === 'click') {
      // Rule 2 from javascript-pragmatic-rules: Timeout async operations
      this.#controller = new AbortController();
      const timeoutId = setTimeout(() => this.#controller.abort(), 5_000);

      try {
        const response = await fetch(this.getAttribute('data-url'), {
          signal: this.#controller.signal
        });
        clearTimeout(timeoutId);
        // Handle response...
      } catch (error) {
        // Rule 1 from javascript-pragmatic-rules: Handle rejections
        if (error.name === 'AbortError') {
          console.warn('Request timed out');
        } else {
          throw new Error('Request failed', { cause: error });
        }
      }
    }
  }

  // Rule 4 from javascript-pragmatic-rules: Clean up resources
  disconnectedCallback() {
    this.removeEventListener('click', this);
    if (this.#controller) this.#controller.abort();
  }
}

Key Integration Points:

Use this skill's

connectedCallback

with

javascript-pragmatic-rules

Rule 4 (cleanup)

Use this skill's
```
handleEvent
```
with
```
javascript-pragmatic-rules
```
Rules 1-2 (async safety)
Use this skill's attribute patterns with
```
javascript-pragmatic-rules
```
Rule 5 (immutability)

See

javascript-pragmatic-rules

skill for comprehensive JavaScript best practices.

Component Types

1. Customized Built-in Elements (PREFERRED)

Extend native HTML elements to preserve built-in accessibility and behavior.

javascript

class AsyncAction extends HTMLButtonElement {
  connectedCallback() {
    // Principle: Event Delegation on Self
    this.addEventListener('click', this);
  }

  // Principle: HandleEvent pattern avoids binding 'this'
  async handleEvent(e) {
    if (e.type === 'click') {
      // Principle: Attribute-Driven State (Input)
      this.setAttribute('aria-busy', 'true');
      this.disabled = true;

      // Simulate async work
      await new Promise((resolve) => setTimeout(resolve, 1_500));

      this.removeAttribute('aria-busy');
      this.disabled = false;

      // Principle: Events are the ONLY output
      this.dispatchEvent(new CustomEvent('action-complete', {
        bubbles: true,
        detail: { originalEvent: e }
      }));
    }
  }

  disconnectedCallback() {
    this.removeEventListener('click', this);
  }
}

// Register with { extends: 'button' }
customElements.define('async-action', AsyncAction, { extends: 'button' });

Usage in HTML:

html

<button is="async-action" aria-label="Add to cart">
  Add to Cart
</button>

2. Autonomous Custom Elements

Use for layout containers and composite components.

javascript

class ProductCard extends HTMLElement {
  // Purely declarative - no logic needed if using DSD
}

customElements.define('product-card', ProductCard);

Declarative Shadow DOM

Use

<template shadowrootmode="open">

for instant rendering without JavaScript.

html

<product-card>
  <template shadowrootmode="open">
    <style>
      :host {
        display: block;
        max-width: 300px;
      }

      /* Attribute-Driven Styling */
      button[aria-busy="true"] {
        opacity: 0.7;
        cursor: wait;
      }

      .card {
        background: var(--card-bg, white);
        border: 1px solid #e5e7eb;
        border-radius: 8px;
        padding: 1rem;
        display: flex;
        flex-direction: column;
        gap: 0.5rem;
      }

      .footer {
        margin-top: 1rem;
        display: flex;
        justify-content: space-between;
        align-items: center;
      }
    </style>

    <article class="card" part="container">
      <slot name="header"></slot>
      <slot></slot>

      <div class="footer">
        <slot name="price">Free</slot>

        <button is="async-action" part="action-btn">
          Add to Cart
        </button>
      </div>
    </article>
  </template>

  <h3 slot="header">Product Title</h3>
  <p>Product description goes here.</p>
  <strong slot="price">$450.00</strong>
</product-card>

Attribute-Driven State Pattern

State flows IN via attributes and OUT via events.

Input: Reading Attributes

javascript

class DataDisplay extends HTMLElement {
  connectedCallback() {
    // Read initial state from attributes
    const apiUrl = this.getAttribute('data-url');
    const refreshInterval = this.getAttribute('refresh-interval') || 5_000;

    this.setAttribute('status', 'loading');
    this.loadData(apiUrl);
  }

  async loadData(url) {
    try {
      const response = await fetch(url);
      const data = await response.json();

      // State change via attribute
      this.setAttribute('status', 'loaded');
      this.setAttribute('data-count', data.items.length);

      // Output via event
      this.dispatchEvent(new CustomEvent('data-loaded', {
        bubbles: true,
        detail: { data }
      }));
    } catch (error) {
      this.setAttribute('status', 'error');
      this.dispatchEvent(new CustomEvent('data-error', {
        bubbles: true,
        detail: { error: error.message }
      }));
    }
  }

  // Observe attribute changes
  static get observedAttributes() {
    return ['data-url', 'refresh-interval'];
  }

  attributeChangedCallback(name, oldValue, newValue) {
    if (oldValue === newValue) return;

    if (name === 'data-url' && newValue) {
      this.loadData(newValue);
    }
  }
}

Output: Events Only

javascript

// CORRECT: Dispatch events for output
this.dispatchEvent(new CustomEvent('value-changed', {
  bubbles: true,
  composed: true, // Cross shadow DOM boundaries
  detail: { value: newValue }
}));

// WRONG: Never modify external DOM
// document.querySelector('.result').textContent = value; // ❌ FORBIDDEN

HandleEvent Pattern

Use the

handleEvent

interface to avoid

.bind(this)

and maintain clean memory management.

javascript

class MultiEventHandler extends HTMLElement {
  connectedCallback() {
    // Single listener for multiple event types
    this.addEventListener('click', this);
    this.addEventListener('keydown', this);
    this.addEventListener('focus', this);
  }

  handleEvent(e) {
    // Route by event type
    switch(e.type) {
      case 'click':
        this.handleClick(e);
        break;
      case 'keydown':
        this.handleKeydown(e);
        break;
      case 'focus':
        this.handleFocus(e);
        break;
    }
  }

  handleClick(e) {
    this.setAttribute('last-interaction', 'click');
  }

  handleKeydown(e) {
    if (e.key === 'Enter' || e.key === ' ') {
      this.setAttribute('last-interaction', 'keyboard');
    }
  }

  handleFocus(e) {
    this.setAttribute('focused', 'true');
  }

  disconnectedCallback() {
    this.removeEventListener('click', this);
    this.removeEventListener('keydown', this);
    this.removeEventListener('focus', this);
  }
}

Styling API

CSS Custom Properties (Theming)

css

/* Consumer defines theme */
:root {
  --primary-color: #6200ea;
  --bg-color: #ffffff;
  --spacing: 1rem;
}

product-card {
  --card-bg: var(--bg-color);
  --card-padding: var(--spacing);
}

::part() Pseudo-element

html

<template shadowrootmode="open">
  <style>
    .internal-element {
      /* internal styles */
    }
  </style>

  <!-- Expose parts for external styling -->
  <div class="internal-element" part="container">
    <button part="action-btn">Click me</button>
  </div>
</template>

css

/* External styling via ::part() */
product-card::part(container) {
  box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
}

product-card::part(action-btn) {
  background-color: var(--primary-color);
  color: white;
}

:host and :host-context

css

<style>
  /* Style the host element */
  :host {
    display: block;
    font-family: system-ui, sans-serif;
  }

  /* State-based styling */
  :host([disabled]) {
    opacity: 0.5;
    pointer-events: none;
  }

  /* Context-based styling */
  :host-context(.dark-mode) {
    background: #1a1a1a;
    color: #ffffff;
  }
</style>

Lifecycle Callbacks

javascript

class LifecycleExample extends HTMLElement {
  constructor() {
    super();
    // ONLY: Initialize instance variables
    // DO NOT: Access attributes, children, or DOM
  }

  connectedCallback() {
    // Element added to DOM
    // DO: Set up event listeners, start timers, fetch data
    this.addEventListener('click', this);

    const initialValue = this.getAttribute('value');
    if (initialValue) {
      this.initialize(initialValue);
    }
  }

  disconnectedCallback() {
    // Element removed from DOM
    // DO: Clean up event listeners, timers, connections
    this.removeEventListener('click', this);

    if (this.intervalId) {
      clearInterval(this.intervalId);
    }
  }

  attributeChangedCallback(name, oldValue, newValue) {
    // Observed attribute changed
    if (oldValue === newValue) return;

    switch(name) {
      case 'value':
        this.updateValue(newValue);
        break;
      case 'disabled':
        this.updateDisabled(newValue !== null);
        break;
    }
  }

  adoptedCallback() {
    // Element moved to new document
    // Rarely needed - usually for iframes
  }

  static get observedAttributes() {
    return ['value', 'disabled', 'theme'];
  }
}

Form Integration with ElementInternals

Use ElementInternals API for form-associated custom elements.

javascript

class CustomInput extends HTMLElement {
  static formAssociated = true;

  constructor() {
    super();
    this.internals = this.attachInternals();
  }

  connectedCallback() {
    this.addEventListener('input', this);
    this.updateValue(this.getAttribute('value') || '');
  }

  handleEvent(e) {
    if (e.type === 'input') {
      const value = e.target.value;
      this.updateValue(value);
    }
  }

  updateValue(value) {
    // Update form value
    this.internals.setFormValue(value);

    // Validate
    if (!value) {
      this.internals.setValidity(
        { valueMissing: true },
        'This field is required'
      );
    } else {
      this.internals.setValidity({});
    }

    // Emit event
    this.dispatchEvent(new CustomEvent('value-changed', {
      bubbles: true,
      detail: { value }
    }));
  }

  // Form lifecycle callbacks
  formResetCallback() {
    this.updateValue('');
  }

  formDisabledCallback(disabled) {
    this.setAttribute('aria-disabled', disabled);
  }
}

customElements.define('custom-input', CustomInput);

Accessibility Patterns

ARIA Attributes

javascript

class AccessibleToggle extends HTMLButtonElement {
  connectedCallback() {
    this.addEventListener('click', this);

    // Set initial ARIA state
    if (!this.hasAttribute('aria-pressed')) {
      this.setAttribute('aria-pressed', 'false');
    }
  }

  handleEvent(e) {
    if (e.type === 'click') {
      const isPressed = this.getAttribute('aria-pressed') === 'true';
      this.setAttribute('aria-pressed', String(!isPressed));

      this.dispatchEvent(new CustomEvent('toggle', {
        bubbles: true,
        detail: { pressed: !isPressed }
      }));
    }
  }
}

customElements.define('accessible-toggle', AccessibleToggle, { extends: 'button' });

Keyboard Navigation

javascript

class KeyboardNav extends HTMLElement {
  connectedCallback() {
    if (!this.hasAttribute('tabindex')) {
      this.setAttribute('tabindex', '0');
    }

    this.addEventListener('keydown', this);
  }

  handleEvent(e) {
    if (e.type === 'keydown') {
      switch(e.key) {
        case 'Enter':
        case ' ':
          e.preventDefault();
          this.activate();
          break;
        case 'Escape':
          this.deactivate();
          break;
      }
    }
  }

  activate() {
    this.setAttribute('active', 'true');
    this.dispatchEvent(new CustomEvent('activated', { bubbles: true }));
  }

  deactivate() {
    this.removeAttribute('active');
    this.dispatchEvent(new CustomEvent('deactivated', { bubbles: true }));
  }
}

Complete Example: Async Action Button

javascript

/* async-action.js */
class AsyncAction extends HTMLButtonElement {
  connectedCallback() {
    this.addEventListener('click', this);
  }

  async handleEvent(e) {
    if (e.type === 'click') {
      // Prevent double-clicks
      if (this.getAttribute('aria-busy') === 'true') {
        return;
      }

      // Set loading state
      this.setAttribute('aria-busy', 'true');
      this.disabled = true;

      const originalText = this.textContent;
      const loadingText = this.getAttribute('loading-text') || 'Loading...';
      this.textContent = loadingText;

      try {
        // Dispatch event for external handler
        const actionEvent = new CustomEvent('async-action', {
          bubbles: true,
          cancelable: true,
          detail: {
            button: this,
            originalEvent: e
          }
        });

        const shouldContinue = this.dispatchEvent(actionEvent);

        if (shouldContinue) {
          // Simulate async work (in real usage, parent handles this)
          await new Promise((resolve) => setTimeout(resolve, 1_500));

          // Success state
          this.setAttribute('aria-busy', 'false');
          this.removeAttribute('aria-busy');

          this.dispatchEvent(new CustomEvent('action-complete', {
            bubbles: true,
            detail: { success: true }
          }));
        }
      } catch (error) {
        // Error state
        this.setAttribute('aria-busy', 'false');
        this.removeAttribute('aria-busy');

        this.dispatchEvent(new CustomEvent('action-error', {
          bubbles: true,
          detail: { error: error.message }
        }));
      } finally {
        // Reset state
        this.textContent = originalText;
        this.disabled = false;
      }
    }
  }

  disconnectedCallback() {
    this.removeEventListener('click', this);
  }
}

customElements.define('async-action', AsyncAction, { extends: 'button' });

HTML Usage:

html

<button
  is="async-action"
  loading-text="Saving..."
  aria-label="Save changes">
  Save
</button>

<script>
  document.addEventListener('async-action', async (e) => {
    // Handle the action
    const response = await fetch('/api/save', {
      method: 'POST',
      body: JSON.stringify({ data: 'example' })
    });

    if (!response.ok) {
      throw new Error('Save failed');
    }
  });
</script>

Anti-Patterns (NEVER DO THIS)

❌ DOM Selection

javascript

// WRONG
connectedCallback() {
  const button = this.querySelector('button'); // ❌
  button.addEventListener('click', ...);
}

❌ Direct DOM Manipulation of External Elements

javascript

// WRONG
handleClick() {
  document.getElementById('result').textContent = 'Done'; // ❌
}

❌ innerHTML for Dynamic Content

javascript

// WRONG
updateContent(data) {
  this.innerHTML = `<div>${data}</div>`; // ❌
}

❌ Imperative Shadow DOM Creation

javascript

// WRONG (use Declarative Shadow DOM instead)
constructor() {
  super();
  this.attachShadow({ mode: 'open' }); // ❌
  this.shadowRoot.innerHTML = '<div>...</div>'; // ❌
}

❌ Global State

javascript

// WRONG
let globalState = {}; // ❌

class MyComponent extends HTMLElement {
  connectedCallback() {
    globalState.value = 'bad'; // ❌
  }
}

Testing Pattern

javascript

// test.html
<!DOCTYPE html>
<html>
<head>
  <script type="module" src="./async-action.js"></script>
</head>
<body>
  <button is="async-action" id="test-btn">Test</button>

  <script type="module">
    const btn = document.getElementById('test-btn');

    // Test attribute-driven state
    btn.addEventListener('action-complete', (e) => {
      console.log('✓ Action completed', e.detail);
    });

    // Programmatically trigger
    btn.click();

    // Verify state
    console.assert(
      btn.getAttribute('aria-busy') === 'true',
      'Should be busy during action'
    );
  </script>
</body>
</html>

Progressive Enhancement

Components should degrade gracefully without JavaScript:

html

<!-- Works as regular button if JS fails -->
<button is="async-action" formaction="/submit" formmethod="post">
  Submit Form
</button>

<!-- Works as regular link if JS fails -->
<a is="spa-link" href="/page">
  Navigate
</a>

Integrating with Utopia Fluid Scales

When using this skill alongside Utopia skills (

utopia-fluid-scales

utopia-grid-layout

utopia-container-queries

), follow these patterns for CSS Custom Properties and shared styles.

CSS Custom Properties Pierce Shadow Boundaries

Utopia tokens defined on

:root

automatically work inside shadow DOM via

var()

css

/* Inside shadow DOM - these just work */
:host {
  display: block;
  container-type: inline-size; /* Required for cqi units */
}

.card {
  padding: var(--space-m);           /* Utopia spacing */
  font-size: var(--step-0);          /* Utopia typography */
  gap: var(--grid-gutter);           /* Utopia grid */
}

.title {
  font-size: var(--step-2);
  font-weight: 700;
}

.body {
  font-size: var(--step--1);
  color: var(--color-muted, #6b7280);
}

Sharing Utility Classes via Constructable Stylesheets

Shadow DOM encapsulates styles, so global utility classes (

.u-stack

.u-grid

.u-cluster

) don't penetrate. Use Constructable Stylesheets with

adoptedStyleSheets

to share utilities without duplication:

javascript

/* js/styles/shared-styles.js */

// Create stylesheets once - shared across all components
export const utopiaGridStyles = new CSSStyleSheet();
utopiaGridStyles.replaceSync(`
  .u-container {
    max-width: var(--grid-max-width, 77.5rem);
    margin-inline: auto;
    padding-inline: var(--grid-gutter, var(--space-s-l));
  }

  .u-grid {
    display: grid;
    gap: var(--grid-gutter, var(--space-s-l));
  }

  .u-grid-auto {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(min(280px, 100%), 1fr));
    gap: var(--grid-gutter, var(--space-s-l));
  }

  .u-stack {
    display: flex;
    flex-direction: column;
    gap: var(--space-s);
  }

  .u-cluster {
    display: flex;
    flex-wrap: wrap;
    gap: var(--space-s);
    align-items: center;
  }
`);

export const utopiaTypeStyles = new CSSStyleSheet();
utopiaTypeStyles.replaceSync(`
  .u-step-5 { font-size: var(--step-5); }
  .u-step-4 { font-size: var(--step-4); }
  .u-step-3 { font-size: var(--step-3); }
  .u-step-2 { font-size: var(--step-2); }
  .u-step-1 { font-size: var(--step-1); }
  .u-step-0 { font-size: var(--step-0); }
  .u-step--1 { font-size: var(--step--1); }
  .u-step--2 { font-size: var(--step--2); }
`);

// Helper to create component-specific stylesheets
export function createStyleSheet(css) {
  const sheet = new CSSStyleSheet();
  sheet.replaceSync(css);
  return sheet;
}

Component Using Shared Styles

Note: When using

adoptedStyleSheets

, imperative shadow DOM creation is acceptable. This is the exception to the "no imperative shadow DOM" rule.

javascript

import { utopiaGridStyles, utopiaTypeStyles, createStyleSheet } from '../styles/shared-styles.js';

const componentStyles = createStyleSheet(`
  :host {
    display: block;
    container-type: inline-size;
  }

  /* Use :host([attr]) for attribute-based styling */
  :host([variant="primary"]) {
    --card-accent: var(--color-primary, #6366f1);
  }

  :host([variant="secondary"]) {
    --card-accent: var(--color-secondary, #8b5cf6);
  }

  .card {
    background: var(--card-bg, white);
    border: 2px solid var(--card-accent, #e5e7eb);
    border-radius: var(--space-xs);
    padding: var(--space-m);
  }

  .title {
    font-size: var(--step-1);
    font-weight: 700;
  }
`);

class FeatureCard extends HTMLElement {
  static get observedAttributes() {
    return ['title', 'variant'];
  }

  constructor() {
    super();
    this.attachShadow({ mode: 'open' });

    // Adopt shared + component styles (no duplication!)
    this.shadowRoot.adoptedStyleSheets = [
      utopiaGridStyles,
      utopiaTypeStyles,
      componentStyles
    ];

    // Now utility classes work inside shadow DOM
    this.shadowRoot.innerHTML = `
      <article class="card u-stack" part="container">
        <h3 class="title u-step-1" part="title"></h3>
        <slot></slot>
      </article>
    `;

    this._titleEl = this.shadowRoot.querySelector('.title');
  }

  connectedCallback() {
    this.addEventListener('click', this);
    this.render();
  }

  disconnectedCallback() {
    this.removeEventListener('click', this);
  }

  attributeChangedCallback(name, oldVal, newVal) {
    if (oldVal === newVal) return;
    if (this.isConnected) this.render();
  }

  handleEvent(e) {
    if (e.type === 'click') {
      this.dispatchEvent(new CustomEvent('card-selected', {
        bubbles: true,
        composed: true,
        detail: { title: this.getAttribute('title') }
      }));
    }
  }

  render() {
    this._titleEl.textContent = this.getAttribute('title') || '';
  }
}

customElements.define('feature-card', FeatureCard);

Key Patterns for Utopia Integration

Always set
container-type: inline-size
on
:host
- Required for
```
cqi
```
units in Utopia fluid scales

Use
var()
for all Utopia tokens - They pierce shadow DOM automatically:

Typography:

var(--step-0)

var(--step-1)

var(--step--1)

Spacing:

var(--space-xs)

var(--space-m)

var(--space-l)

Grid:
```
var(--grid-gutter)
```
,
```
var(--grid-max-width)
```

Use
:host([attribute])
for variant styling - Attribute-driven state maps directly to CSS:

css

:host([size="small"]) { --internal-padding: var(--space-xs); }
:host([size="large"]) { --internal-padding: var(--space-l); }

Create component-scoped custom properties - Map Utopia tokens to semantic names:

css

:host {
  --card-padding: var(--space-m);
  --card-gap: var(--space-s);
  --title-size: var(--step-1);
}

Share CSSStyleSheet objects, not CSS strings -
```
adoptedStyleSheets
```
references the same object across all components

Container Query Checklist

When using Utopia's

cqi

-based fluid scales inside shadow DOM:

```
:host
```
has
```
container-type: inline-size
```
Parent elements in light DOM have
```
container-type: inline-size
```
where needed
Typography uses
```
var(--step-*)
```
tokens
Spacing uses
```
var(--space-*)
```
tokens
Component is tested at various container widths

FOUC Prevention (Flash of Unstyled Content)

Custom elements are "undefined" until JavaScript loads and registers them via

customElements.define()

. During this window, browsers render raw content without shadow DOM styles, causing a visible flash (FOUC) and layout shift (CLS).

The Problem

html

<!-- Before JavaScript loads, this shows raw slot content -->
<site-nav>
  <span slot="brand">My Site</span>
  <a slot="menu" href="/">Home</a>
</site-nav>

Without FOUC prevention:

HTML parses, custom element renders as inline element with raw slot content
JavaScript loads and defines the component
Shadow DOM attaches, styles apply, component "snaps" into place
Users see an ugly flash and layout shift

Solution 1: CSS

:not(:defined)

Selector (Required)

The

:defined

pseudo-class targets elements that have been registered via

customElements.define()

. Use

:not(:defined)

to hide or style elements before definition:

css

/* In global CSS (e.g., accessibility.css) */

/* Hide custom elements until JavaScript defines them */
site-nav:not(:defined),
nav-link-item:not(:defined) {
  opacity: 0;
}

/* Reserve layout space to prevent CLS */
site-nav:not(:defined) {
  display: block;
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  z-index: var(--z-sticky, 100);
  min-height: calc(var(--nav-height, 56px) + var(--space-s) * 2);
  background: var(--theme-surface);
  border-block-end: 1px solid var(--theme-outline);
}

/* Instant visibility once defined */
site-nav:defined {
  opacity: 1;
}

Why
opacity: 0
instead of
display: none
?

```
opacity: 0
```
preserves layout space, preventing CLS
```
display: none
```
causes layout shift when element appears
```
visibility: hidden
```
also works but can cause focus issues

Solution 2: Module Preload (Recommended)

Preload critical above-the-fold components to reduce time-to-definition:

html

<head>
  <!-- Styles first -->
  <link rel="stylesheet" href="/css/styles/index.css">

  <!-- Preload critical component scripts -->
  <link rel="modulepreload" href="/js/components/site-nav.js">
  <link rel="modulepreload" href="/js/components/nav-link-item.js">
  <link rel="modulepreload" href="/js/components/page-transition.js">

  <!-- Import maps -->
  <script type="importmap">...</script>
</head>

Benefits:

Browser starts downloading modules in parallel with HTML parsing
Reduces time between HTML render and component definition
Works with ES modules (
```
type="module"
```
scripts)

Solution 3: Declarative Shadow DOM (Best)

For server-rendered or static sites, use Declarative Shadow DOM for instant styling:

html

<site-nav>
  <template shadowrootmode="open">
    <style>
      :host {
        display: block;
        position: fixed;
        top: 0;
        /* ... all component styles inline ... */
      }
    </style>
    <nav>
      <slot name="brand"></slot>
      <slot name="menu"></slot>
    </nav>
  </template>

  <!-- Light DOM content -->
  <span slot="brand">My Site</span>
  <a slot="menu" href="/">Home</a>
</site-nav>

Benefits:

Styles apply immediately during HTML parsing
No JavaScript required for initial render
Best possible CLS score
JavaScript enhances (adds interactivity) but doesn't enable styling

Implementation Checklist

For every custom element in your application:

Add
```
:not(:defined)
```
CSS rule in global stylesheet
Reserve layout space for fixed/positioned elements
Add
```
modulepreload
```
for above-the-fold components
Consider Declarative Shadow DOM for critical-path components
Test with network throttling to verify no FOUC
Measure CLS in Lighthouse/PageSpeed Insights

Project Pattern

This project handles FOUC in

css/styles/accessibility.css

css

/* Navigation - reserve space and hide content */
site-nav:not(:defined) {
  display: block;
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  z-index: var(--z-sticky, 100);
  min-height: calc(var(--nav-height, 56px) + var(--space-s, 0.75rem) * 2);
  background: var(--theme-surface, #1f1b15);
  border-block-end: 1px solid var(--theme-outline, #5c4d3d);
  opacity: 0;
}

/* Cards and grids - hide until ready */
filterable-grid:not(:defined),
word-card:not(:defined) {
  opacity: 0;
}

And in HTML

<head>

html

<!-- Modulepreload critical components to prevent FOUC -->
<link rel="modulepreload" href="/js/components/site-nav.js">
<link rel="modulepreload" href="/js/components/nav-link-item.js">
<link rel="modulepreload" href="/js/components/page-transition.js">

Anti-Pattern: Generic Wildcard

Avoid hiding all undefined elements with a wildcard:

css

/* DON'T DO THIS - breaks progressive enhancement */
*:not(:defined) {
  display: none;
}

This breaks elements that should be visible during progressive enhancement (forms, links, etc.). Instead, explicitly list the components that need FOUC prevention.

When to Use This Pattern

Building reusable UI components
Creating design systems
Server-side rendering (SSR) with hydration
Progressive web apps (PWAs)
Micro-frontends
Accessibility-first applications

When NOT to Use

Simple static websites (use plain HTML)
Heavy data visualization (consider Canvas/WebGL)
Applications requiring IE11 support (no polyfills allowed)

Instructions for Implementation

When implementing web components:

Choose Element Type: Prefer customized built-ins over autonomous elements
Define State Contract: Document all attributes and events
Use HandleEvent: Implement
```
handleEvent()
```
for event delegation
Avoid DOM Selection: NEVER use
```
querySelector
```
or similar methods
Use DSD: Implement Declarative Shadow DOM for instant rendering
Expose Styling API: Use CSS custom properties and
```
::part()
```
Implement Accessibility: Add ARIA attributes and keyboard support
Test Progressive Enhancement: Verify behavior with JavaScript disabled
Document Usage: Provide clear HTML examples

File Organization

components/
├── async-action/
│   ├── async-action.js
│   ├── async-action.test.html
│   └── README.md
├── product-card/
│   ├── product-card.js
│   ├── product-card.test.html
│   └── README.md
└── index.js (exports all components)

web-components-architecture

NPX Install

Tags

SKILL.md Content

Web Components Architecture

Core Principles

Relationship with JavaScript Best Practices

Component Types

1. Customized Built-in Elements (PREFERRED)

2. Autonomous Custom Elements

Declarative Shadow DOM

Attribute-Driven State Pattern

Input: Reading Attributes

Output: Events Only

HandleEvent Pattern

Styling API

CSS Custom Properties (Theming)

::part() Pseudo-element

:host and :host-context

Lifecycle Callbacks

Form Integration with ElementInternals

Accessibility Patterns

ARIA Attributes

Keyboard Navigation

Complete Example: Async Action Button

Anti-Patterns (NEVER DO THIS)

❌ DOM Selection

❌ Direct DOM Manipulation of External Elements

❌ innerHTML for Dynamic Content

❌ Imperative Shadow DOM Creation

❌ Global State

Testing Pattern

Progressive Enhancement

Integrating with Utopia Fluid Scales

CSS Custom Properties Pierce Shadow Boundaries

Sharing Utility Classes via Constructable Stylesheets

Component Using Shared Styles

Key Patterns for Utopia Integration

Container Query Checklist

FOUC Prevention (Flash of Unstyled Content)

The Problem

Solution 1: CSS :not(:defined) Selector (Required)

Solution 2: Module Preload (Recommended)

Solution 3: Declarative Shadow DOM (Best)

Implementation Checklist

Project Pattern

Anti-Pattern: Generic Wildcard

When to Use This Pattern

When NOT to Use

Instructions for Implementation

File Organization

References

Solution 1: CSS
`:not(:defined)`
Selector (Required)