@adia-ai/web-components 0.8.5 → 0.8.7

package/patterns/component-tokens/component-tokens.examples.html

@@ -0,0 +1,483 @@
+<header>
+    <div>
+      <h1>Component Token Pattern</h1>
+    </div>
+    <p>How AdiaUI components use <code>@scope</code>, CSS custom properties, and zero-specificity defaults to create a themeable, isolated styling system without Shadow DOM or BEM.</p>
+  </header>
+
+<section data-section data-property="overview">
+  <h2 variant="section">Overview</h2>
+  <p>
+    Every AdiaUI component follows a consistent CSS architecture built on three principles:
+  </p>
+  <ul>
+    <li><strong>Scoped isolation</strong> via <code>@scope(tag-ui)</code> — styles cannot leak in or out</li>
+    <li><strong>Token-driven theming</strong> via <code>--{component}-{prop}</code> custom properties — every visual property is configurable</li>
+    <li><strong>Zero-specificity defaults</strong> via <code>:where(:scope)</code> — tokens can be overridden from outside without specificity wars</li>
+  </ul>
+  <p data-note>
+    This pattern gives you the encapsulation benefits of Shadow DOM (no style leakage)
+    with the flexibility of light DOM (global styles, form participation, CSS inheritance).
+  </p>
+</section>
+
+<section data-section data-property="the-scope-pattern">
+  <h2 variant="section">The @scope Pattern</h2>
+  <p>
+    CSS <code>@scope</code> limits style rules to a specific subtree. AdiaUI scopes
+    each component to its custom element tag:
+  </p>
+  <code-ui language="css">@scope (button-ui) {
+  /* Everything in here only applies inside &lt;button-ui&gt; */
+  :scope { ... }        /* the button-ui element itself */
+  [slot="trailing"] { ... }  /* children of button-ui */
+}</code-ui>
+  <p>
+    Unlike Shadow DOM, <code>@scope</code> does not create a style boundary — it creates
+    a style <em>scope</em>. CSS custom properties still inherit through the scope boundary,
+    global resets still apply, and form elements participate in their parent form natively.
+  </p>
+</section>
+
+<section data-section data-property="wherescope-vs-scope">
+  <h2 variant="section">:where(:scope) vs :scope</h2>
+  <p>
+    This is the key mechanism that makes component tokens overridable. AdiaUI uses
+    two distinct selectors for two different purposes:
+  </p>
+
+  <h3><code>:where(:scope)</code> — Zero-specificity token defaults</h3>
+  <p>
+    Token declarations go in <code>:where(:scope)</code>, which has <strong>zero specificity</strong>.
+    This means any external rule — even a bare element selector — can override these values:
+  </p>
+  <code-ui language="css">@scope (button-ui) {
+  :where(:scope) {
+    --button-bg: var(--a-bg-muted);
+    --button-fg: var(--a-fg-muted);
+    --button-radius: var(--a-radius);
+    /* ... all component tokens declared here ... */
+  }
+}</code-ui>
+
+  <h3><code>:scope</code> — Base styles (normal specificity)</h3>
+  <p>
+    Structural styles that <em>consume</em> the tokens go in <code>:scope</code>,
+    which has normal specificity. These define the component's layout, transitions,
+    and visual properties by referencing the tokens:
+  </p>
+  <code-ui language="css">@scope (button-ui) {
+  :scope {
+    display: inline-flex;
+    align-items: center;
+    background: var(--button-bg);       /* consumes the token */
+    color: var(--button-fg);            /* consumes the token */
+    border-radius: var(--button-radius); /* consumes the token */
+    transition: background var(--a-duration-fast) var(--a-easing);
+  }
+}</code-ui>
+
+  <p data-note>
+    The separation is intentional: <code>:where(:scope)</code> sets <em>what the values are</em>,
+    <code>:scope</code> sets <em>how they are applied</em>. Because the defaults have zero
+    specificity, consumers can retheme without <code>!important</code> or deeply nested selectors.
+  </p>
+</section>
+
+<section data-section data-property="naming-convention">
+  <h2 variant="section">Naming Convention</h2>
+  <p>
+    Component tokens follow a strict <code>--{component}-{property}</code> naming scheme:
+  </p>
+  <table>
+    <thead>
+      <tr>
+        <th>Pattern</th>
+        <th>Example</th>
+        <th>Meaning</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td><code>--{comp}-bg</code></td>
+        <td><code>--button-bg</code></td>
+        <td>Background color</td>
+      </tr>
+      <tr>
+        <td><code>--{comp}-fg</code></td>
+        <td><code>--button-fg</code></td>
+        <td>Foreground / text color</td>
+      </tr>
+      <tr>
+        <td><code>--{comp}-border</code></td>
+        <td><code>--button-border</code></td>
+        <td>Border color</td>
+      </tr>
+      <tr>
+        <td><code>--{comp}-radius</code></td>
+        <td><code>--button-radius</code></td>
+        <td>Border radius</td>
+      </tr>
+      <tr>
+        <td><code>--{comp}-height</code></td>
+        <td><code>--button-height</code></td>
+        <td>Component height</td>
+      </tr>
+      <tr>
+        <td><code>--{comp}-px</code></td>
+        <td><code>--button-px</code></td>
+        <td>Horizontal padding</td>
+      </tr>
+      <tr>
+        <td><code>--{comp}-gap</code></td>
+        <td><code>--button-gap</code></td>
+        <td>Internal gap</td>
+      </tr>
+      <tr>
+        <td><code>--{comp}-font-size</code></td>
+        <td><code>--button-font-size</code></td>
+        <td>Font size</td>
+      </tr>
+      <tr>
+        <td><code>--{comp}-bg-{variant}</code></td>
+        <td><code>--button-bg-primary</code></td>
+        <td>Variant-specific background</td>
+      </tr>
+      <tr>
+        <td><code>--{comp}-{prop}-{state}</code></td>
+        <td><code>--button-bg-hover</code></td>
+        <td>State-specific value</td>
+      </tr>
+    </tbody>
+  </table>
+  <p data-note>
+    All variant and state tokens are pre-declared in <code>:where(:scope)</code>, even
+    if they are only used inside a variant selector. This makes every configurable value
+    discoverable at the top of the file.
+  </p>
+</section>
+
+<section data-section data-property="variant-overrides">
+  <h2 variant="section">Variant Overrides</h2>
+  <p>
+    Variants work by reassigning the base tokens to their variant-specific counterparts.
+    This keeps the <code>:scope</code> base styles unchanged — they always read from
+    <code>--button-bg</code>, <code>--button-fg</code>, etc. Variants just swap what
+    those tokens resolve to:
+  </p>
+  <code-ui language="css">/* Variant selectors reassign the base tokens */
+:scope[variant="primary"] {
+  --button-bg: var(--button-bg-primary);
+  --button-fg: var(--button-fg-primary);
+}
+
+:scope[variant="outline"] {
+  --button-bg: var(--button-bg-outline);
+  --button-fg: var(--button-fg-outline);
+  --button-border: var(--button-border-outline);
+}
+
+:scope[variant="ghost"] {
+  --button-bg: var(--button-bg-ghost);
+  --button-fg: var(--button-fg-ghost);
+  --button-border: var(--button-border-ghost);
+}</code-ui>
+  <p>
+    This "token indirection" approach means hover, focus, and disabled states only
+    need to be written once — they always target the base tokens. Variants just
+    redirect which values flow through.
+  </p>
+</section>
+
+<section data-section data-property="consumer-overrides">
+  <h2 variant="section">Consumer Overrides</h2>
+  <p>
+    Because tokens in <code>:where(:scope)</code> have zero specificity, consumers
+    can override any token from outside the component with a simple selector:
+  </p>
+  <code-ui language="css">/* Override from a parent context */
+.my-toolbar button-ui {
+  --button-bg: var(--md-sys-color-primary);
+  --button-fg: var(--md-sys-color-primary-on-primary);
+  --button-radius: var(--a-radius-full);
+}
+
+/* Override a specific instance */
+button-ui.big-cta {
+  --button-height: 3rem;
+  --button-px: var(--a-space-6);
+  --button-font-size: var(--a-ui-lg);
+}</code-ui>
+  <p data-note>
+    You never need <code>!important</code> to override component tokens. Even a type selector
+    like <code>button-ui { --button-bg: red; }</code> beats the zero-specificity defaults.
+    This is the entire point of the <code>:where()</code> wrapper.
+  </p>
+</section>
+
+<section data-section data-property="annotated-example-button-ui">
+  <h2 variant="section">Annotated Example: button-ui</h2>
+  <p>
+    Here is the complete <code>button-ui</code> CSS file, annotated to show how each
+    part of the pattern works together:
+  </p>
+  <code-ui language="css">@scope (button-ui) {
+
+  /* ── LAYER 1: Token defaults (zero specificity) ──
+     Every configurable value is declared here.
+     Consumers can override any of these from outside. */
+  :where(:scope) {
+    /* Base tokens — consumed by :scope styles */
+    --button-bg:               var(--a-bg-muted);
+    --button-fg:               var(--a-fg-muted);
+    --button-border:           transparent;
+    --button-height:           var(--a-size);
+    --button-px:               var(--a-ui-px);
+    --button-radius:           var(--a-radius);
+    --button-font-size:        var(--a-ui-size);
+    --button-font-weight:      var(--a-ui-weight);
+    --button-gap:              var(--a-space-1);
+
+    /* Hover state tokens */
+    --button-bg-hover:         var(--md-sys-color-neutral-background);
+    --button-fg-hover:         var(--md-sys-color-neutral-on-surface);
+    --button-border-hover:     var(--md-sys-color-neutral-on-surface);
+
+    /* Variant: primary */
+    --button-bg-primary:       var(--md-sys-color-primary);
+    --button-fg-primary:       var(--md-sys-color-primary-on-primary);
+
+    /* Variant: outline */
+    --button-bg-outline:       transparent;
+    --button-fg-outline:       var(--md-sys-color-neutral-on-surface);
+    --button-border-outline:   var(--a-ui-border);
+
+    /* Variant: ghost */
+    --button-bg-ghost:         transparent;
+    --button-fg-ghost:         var(--md-sys-color-neutral-on-surface-variant);
+    --button-fg-ghost-hover:   var(--md-sys-color-neutral-on-surface);
+    --button-bg-ghost-hover:   var(--a-bg-hover);
+    --button-border-ghost:     transparent;
+    --button-border-ghost-hover: var(--md-sys-color-neutral-outline);
+
+    /* Variant: danger */
+    --button-bg-danger:        var(--md-sys-color-danger);
+    --button-fg-danger:        var(--md-sys-color-danger-on-danger);
+
+    /* Size: sm */
+    --button-height-sm:        var(--a-ui-size-sm);
+    --button-px-sm:            var(--a-space-1);
+    --button-font-size-sm:     var(--a-ui-sm);
+
+    /* Size: lg */
+    --button-height-lg:        var(--a-ui-size-lg);
+    --button-px-lg:            var(--a-space-2);
+    --button-font-size-lg:     var(--a-ui-lg);
+
+    /* Disabled state */
+    --button-bg-disabled:      var(--a-ui-bg-disabled);
+    --button-fg-disabled:      var(--a-ui-text-disabled);
+    --button-border-disabled:  transparent;
+  }
+
+  /* ── LAYER 2: Base styles (normal specificity) ──
+     These consume the tokens above. They define layout
+     and visual properties that apply to ALL variants. */
+  :scope {
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--button-gap);
+    min-width: var(--button-height);
+    min-height: var(--button-height);
+    padding-inline: var(--button-px);
+    border: 1px solid var(--button-border);
+    border-radius: var(--button-radius);
+    background: var(--button-bg);
+    color: var(--button-fg);
+    font-size: var(--button-font-size);
+    font-weight: var(--button-font-weight);
+    cursor: pointer;
+    transition:
+      background var(--a-duration-fast) var(--a-easing),
+      border-color var(--a-duration-fast) var(--a-easing),
+      color var(--a-duration-fast) var(--a-easing);
+  }
+
+  :scope:focus-visible {
+    outline: none;
+    box-shadow: var(--a-focus-ring);
+  }
+
+  /* ── LAYER 3: Variants ──
+     Reassign base tokens to variant-specific values.
+     Base styles don't change — only the token values do. */
+  :scope[variant="primary"] {
+    --button-bg: var(--button-bg-primary);
+    --button-fg: var(--button-fg-primary);
+  }
+
+  :scope[variant="outline"] {
+    --button-bg: var(--button-bg-outline);
+    --button-fg: var(--button-fg-outline);
+    --button-border: var(--button-border-outline);
+  }
+
+  :scope[variant="ghost"] {
+    --button-bg: var(--button-bg-ghost);
+    --button-fg: var(--button-fg-ghost);
+    --button-border: var(--button-border-ghost);
+  }
+
+  /* ── LAYER 4: States ──
+     Hover, disabled, sizes. Written once, works for all variants. */
+  :scope:not([disabled]):hover {
+    --button-bg: var(--button-bg-hover);
+    --button-fg: var(--button-fg-hover);
+    --button-border: var(--button-border-hover);
+  }
+
+  :scope[disabled] {
+    --button-bg: var(--button-bg-disabled);
+    --button-fg: var(--button-fg-disabled);
+    --button-border: var(--button-border-disabled);
+    pointer-events: none;
+  }
+
+  :scope[size="sm"] {
+    --button-height: var(--button-height-sm);
+    --button-px: var(--button-px-sm);
+    --button-font-size: var(--button-font-size-sm);
+  }
+}</code-ui>
+</section>
+
+<section data-section data-property="why-not-shadow-dom">
+  <h2 variant="section">Why Not Shadow DOM?</h2>
+  <p>
+    Shadow DOM provides strong style encapsulation, but it comes with significant trade-offs
+    for a design system:
+  </p>
+  <table>
+    <thead>
+      <tr>
+        <th>Concern</th>
+        <th>Shadow DOM</th>
+        <th>@scope + Tokens</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>Style isolation</td>
+        <td>Hard boundary — no styles in or out</td>
+        <td>Soft boundary — scoped but inheritable</td>
+      </tr>
+      <tr>
+        <td>Theming</td>
+        <td>Requires <code>::part()</code> or CSS custom properties piercing the boundary</td>
+        <td>Standard CSS selectors work; tokens override naturally</td>
+      </tr>
+      <tr>
+        <td>Form participation</td>
+        <td>Requires <code>ElementInternals</code> + manual delegation</td>
+        <td>Native — inputs inside the element are in the form</td>
+      </tr>
+      <tr>
+        <td>Global styles</td>
+        <td>Blocked — resets, typography must be duplicated inside</td>
+        <td>Inherited — global resets and tokens flow through</td>
+      </tr>
+      <tr>
+        <td>Dev tools</td>
+        <td>Styles hidden in shadow tree</td>
+        <td>All styles visible in the regular cascade</td>
+      </tr>
+      <tr>
+        <td>SSR / progressive</td>
+        <td>Requires declarative shadow DOM or FOUC</td>
+        <td>Works with plain HTML — styles apply immediately</td>
+      </tr>
+    </tbody>
+  </table>
+</section>
+
+<section data-section data-property="why-not-bem">
+  <h2 variant="section">Why Not BEM?</h2>
+  <p>
+    BEM (<code>.block__element--modifier</code>) solves naming collisions through convention.
+    AdiaUI's approach solves it through the platform:
+  </p>
+  <table>
+    <thead>
+      <tr>
+        <th>Concern</th>
+        <th>BEM</th>
+        <th>@scope + Tokens</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>Isolation</td>
+        <td>Convention-based (easy to break)</td>
+        <td>Enforced by <code>@scope</code></td>
+      </tr>
+      <tr>
+        <td>Selector length</td>
+        <td><code>.button__icon--large</code></td>
+        <td><code>icon-ui</code> (inside <code>@scope(button-ui)</code>)</td>
+      </tr>
+      <tr>
+        <td>Theming</td>
+        <td>Override each BEM class individually</td>
+        <td>Set a token, all usages update</td>
+      </tr>
+      <tr>
+        <td>Variants</td>
+        <td>New class per variant per element</td>
+        <td>Attribute selector redirects tokens</td>
+      </tr>
+      <tr>
+        <td>Specificity</td>
+        <td>Flat but requires discipline</td>
+        <td>Structured: zero for defaults, normal for styles</td>
+      </tr>
+    </tbody>
+  </table>
+  <p data-note>
+    The component token pattern lets you write clean, minimal selectors inside each component
+    while maintaining full isolation. No naming conventions to memorize, no class-name
+    collisions to debug.
+  </p>
+</section>
+
+<section data-section data-property="writing-a-new-component">
+  <h2 variant="section">Writing a New Component</h2>
+  <p>Follow this checklist when creating a new component's CSS:</p>
+  <ol>
+    <li>Open with <code>@scope (my-component-ui) {</code></li>
+    <li>Declare all tokens in <code>:where(:scope) { }</code> — base values, variants, sizes, states</li>
+    <li>Write base styles in <code>:scope { }</code> that consume only your component tokens</li>
+    <li>Add <code>:scope:focus-visible</code> with <code>box-shadow: var(--a-focus-ring)</code></li>
+    <li>Write variants as <code>:scope[variant="..."]</code> that reassign base tokens</li>
+    <li>Write sizes as <code>:scope[size="..."]</code> that reassign height/padding/font tokens</li>
+    <li>Write disabled as <code>:scope[disabled]</code></li>
+    <li>Reference global tokens (<code>--a-*</code>) in your token defaults, never in base styles</li>
+  </ol>
+  <code-ui language="css">@scope (my-widget-ui) {
+  :where(:scope) {
+    --widget-bg: var(--a-bg-subtle);
+    --widget-fg: var(--md-sys-color-neutral-on-surface);
+    --widget-radius: var(--a-radius-md);
+    --widget-px: var(--a-space-3);
+  }
+
+  :scope {
+    display: flex;
+    padding-inline: var(--widget-px);
+    background: var(--widget-bg);
+    color: var(--widget-fg);
+    border-radius: var(--widget-radius);
+  }
+}</code-ui>
+</section>

package/patterns/component-tokens/component-tokens.html

@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Component Token Pattern (pattern) — AdiaUI</title>
+
+  <!-- Token base -->
+  <link rel="stylesheet" href="../../styles/resets.css">
+  <link rel="stylesheet" href="../../styles/tokens.css">
+
+  <!-- Component CSS — primitives this pattern composes -->
+  <link rel="stylesheet" href="../../components/code/code.css">
+
+  <!-- Component JS -->
+  <script type="module" src="../../components/code/code.js"></script>
+
+  <style>
+    :where(html, body) { margin: 0; min-height: 100vh; background: var(--md-sys-color-neutral-background); color: var(--md-sys-color-neutral-on-surface); font-family: var(--a-font-family); }
+    main { max-width: 960px; margin-inline: auto; padding: var(--a-space-6) var(--a-space-5); }
+  </style>
+</head>
+<body>
+
+  <main id="demo-root">
+    <p>Loading examples…</p>
+  </main>
+
+  <script type="module">
+    const root = document.getElementById('demo-root');
+    try {
+      const res = await fetch('./component-tokens.examples.html');
+      if (!res.ok) throw new Error(`fetch failed (${res.status})`);
+      root.innerHTML = await res.text();
+    } catch (err) {
+      root.innerHTML = `<p style="color:var(--a-danger-strong);">Failed to load component-tokens.examples.html — ${err.message}</p>`;
+      console.error('[component-tokens.html]', err);
+    }
+  </script>
+
+</body>
+</html>