Web Components Architecture

Core Principles

This skill enforces a strict architectural pattern for web components:

1. Zero DOM Selection: NEVER use querySelector, querySelectorAll, or getElementById
2. Attribute-Driven State: All state flows through HTML attributes
3. Event Delegation on this: Use this.addEventListener and the handleEvent pattern
4. No External Dependencies: Use only standard Web Platform APIs
5. Declarative Shadow DOM: Use <template shadowrootmode="open"> for instant rendering
6. Progressive Enhancement: Components work (degraded) even if JavaScript fails
7. 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:

// 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.

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:

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

2. Autonomous Custom Elements

Use for layout containers and composite components.

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.

<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

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

// 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.

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)

/* 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

<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>

/* 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

<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

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.

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

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

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

/* 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:

<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

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

❌ Direct DOM Manipulation of External Elements

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

❌ innerHTML for Dynamic Content

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

❌ Imperative Shadow DOM Creation

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

❌ Global State

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

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

Testing Pattern

// 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:

<!-- 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():

/* 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:

/* 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.

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

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

2. 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)

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

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

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

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

5. 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

<!-- 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:

1. HTML parses, custom element renders as inline element with raw slot content
2. JavaScript loads and defines the component
3. Shadow DOM attaches, styles apply, component "snaps" into place
4. 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:

/* 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:

<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:

<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:

/* 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>:

<!-- 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:

/* 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:

1. Choose Element Type: Prefer customized built-ins over autonomous elements
2. Define State Contract: Document all attributes and events
3. Use HandleEvent: Implement handleEvent() for event delegation
4. Avoid DOM Selection: NEVER use querySelector or similar methods
5. Use DSD: Implement Declarative Shadow DOM for instant rendering
6. Expose Styling API: Use CSS custom properties and ::part()
7. Implement Accessibility: Add ARIA attributes and keyboard support
8. Test Progressive Enhancement: Verify behavior with JavaScript disabled
9. 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)

References

• Custom Elements Spec
• Declarative Shadow DOM
• ElementInternals API
• ARIA Authoring Practices