GitHub v1.3.1
Lesson 05

Native CSS Scoping

How Coralite encapsulates component styles without the performance and accessibility costs of Shadow DOM.

The Shadow DOM Trade-off

Most Web Component frameworks rely on Shadow DOM for style encapsulation. While effective, Shadow DOM creates a hard boundary that breaks native form association and makes global theming difficult.

Coralite uses Light DOM. Your component's markup and styles live directly in the main document. To prevent style leakage, Coralite uses a build-time CSS Scoping engine.

Writing Scoped Styles

You write standard CSS inside your component's <style> block. You use :host to target the custom element itself, and standard class selectors for the inner elements.

css
Code copied!
  :host {
    display: block;
    padding: 16px;
    background: var(--bg-card);
  }
  
  .card-title {
    color: var(--text-primary);
    font-weight: bold;
  }

What Coralite Generates

During the build process, Coralite rewrites your CSS. It wraps your styles in a specific CSS Cascade Layer (@layer components) and scopes your class selectors using :where() to keep specificity low.

css
Code copied!
  @layer components {
    :where(my-card) {
      display: block;
      padding: 16px;
      background: var(--bg-card);
    }
    
    :where(my-card) .card-title {
      color: var(--text-primary);
      font-weight: bold;
    }
  }

Why this matters

Because the styles live in the Light DOM, you can easily inspect them in DevTools, override them with utility classes (since they are in a low-priority cascade layer), and ensure that native accessibility features work perfectly.