@profpowell/vb-design-system 0.1.0

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@profpowell/vb-design-system",
+  "version": "0.1.0",
+  "description": "Design-system documentation components for Vanilla Breeze: color, type, spacing, token and motion specimens, palette generator, semantic palette, component sampler, theme export, accessibility specimen, breakpoint specimen, layout specimen, font pairer, and gradient builder.",
+  "license": "MIT",
+  "author": "Patrick Powell",
+  "type": "module",
+  "homepage": "https://github.com/ProfPowell/vb-design-system#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ProfPowell/vb-design-system.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ProfPowell/vb-design-system/issues"
+  },
+  "keywords": [
+    "vanilla-breeze",
+    "web-components",
+    "design-system",
+    "design-tokens",
+    "specimen",
+    "theme"
+  ],
+  "files": [
+    "src",
+    "dist"
+  ],
+  "main": "./dist/vb-design-system.js",
+  "module": "./src/index.js",
+  "style": "./dist/vb-design-system.css",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "default": "./dist/vb-design-system.js"
+    },
+    "./css": "./src/index.css",
+    "./dist/css": "./dist/vb-design-system.css",
+    "./color-palette": "./src/web-components/color-palette/logic.js",
+    "./palette-generator": "./src/web-components/palette-generator/logic.js",
+    "./type-specimen": "./src/web-components/type-specimen/logic.js",
+    "./spacing-specimen": "./src/web-components/spacing-specimen/logic.js",
+    "./token-specimen": "./src/web-components/token-specimen/logic.js",
+    "./component-sampler": "./src/web-components/component-sampler/logic.js",
+    "./semantic-palette": "./src/web-components/semantic-palette/logic.js",
+    "./motion-specimen": "./src/web-components/motion-specimen/logic.js",
+    "./theme-export": "./src/web-components/theme-export/logic.js",
+    "./accessibility-specimen": "./src/web-components/accessibility-specimen/logic.js",
+    "./breakpoint-specimen": "./src/web-components/breakpoint-specimen/logic.js",
+    "./layout-specimen": "./src/web-components/layout-specimen/logic.js",
+    "./font-pairer": "./src/web-components/font-pairer/logic.js",
+    "./gradient-builder": "./src/web-components/gradient-builder/logic.js",
+    "./theme-import": "./src/web-components/theme-import/logic.js",
+    "./theme-catalog": "./src/web-components/theme-catalog/logic.js",
+    "./brand-specimen": "./src/web-components/brand-specimen/logic.js",
+    "./icon-set": "./src/web-components/icon-set/logic.js",
+    "./icon-specimen": "./src/web-components/icon-specimen/logic.js",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "npm run build:js && npm run build:css",
+    "build:js": "esbuild src/index.js --bundle --format=esm --outfile=dist/vb-design-system.js && esbuild src/index.js --bundle --format=esm --minify --outfile=dist/vb-design-system.min.js",
+    "build:css": "esbuild src/index.css --bundle --outfile=dist/vb-design-system.css && esbuild src/index.css --bundle --minify --outfile=dist/vb-design-system.min.css",
+    "prepublishOnly": "npm run build",
+    "test:components": "playwright test"
+  },
+  "peerDependencies": {
+    "vanilla-breeze": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "vanilla-breeze": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.61.1",
+    "esbuild": "^0.27.0"
+  }
+}

package/src/index.css

@@ -0,0 +1,21 @@
+/* @profpowell/vb-design-system — component styles (light DOM). */
+@import "./web-components/color-palette/styles.css";
+@import "./web-components/palette-generator/styles.css";
+@import "./web-components/type-specimen/styles.css";
+@import "./web-components/spacing-specimen/styles.css";
+@import "./web-components/token-specimen/styles.css";
+@import "./web-components/component-sampler/styles.css";
+@import "./web-components/semantic-palette/styles.css";
+@import "./web-components/motion-specimen/styles.css";
+@import "./web-components/accessibility-specimen/styles.css";
+@import "./web-components/breakpoint-specimen/styles.css";
+@import "./web-components/layout-specimen/styles.css";
+@import "./web-components/font-pairer/styles.css";
+@import "./web-components/gradient-builder/styles.css";
+@import "./web-components/brand-specimen/styles.css";
+@import "./web-components/icon-set/styles.css";
+@import "./web-components/icon-specimen/styles.css";
+
+/* design-system authoring patterns */
+@import "./patterns/do-dont.css";
+@import "./patterns/token-table.css";

package/src/index.js

@@ -0,0 +1,24 @@
+/**
+ * @profpowell/vb-design-system — barrel.
+ * Side-effect imports register every design-system component.
+ * Consumes Vanilla Breeze design tokens/themes via CSS custom properties.
+ */
+import './web-components/color-palette/logic.js';
+import './web-components/palette-generator/logic.js';
+import './web-components/type-specimen/logic.js';
+import './web-components/spacing-specimen/logic.js';
+import './web-components/token-specimen/logic.js';
+import './web-components/component-sampler/logic.js';
+import './web-components/semantic-palette/logic.js';
+import './web-components/motion-specimen/logic.js';
+import './web-components/theme-export/logic.js';
+import './web-components/accessibility-specimen/logic.js';
+import './web-components/breakpoint-specimen/logic.js';
+import './web-components/layout-specimen/logic.js';
+import './web-components/font-pairer/logic.js';
+import './web-components/gradient-builder/logic.js';
+import './web-components/theme-import/logic.js';
+import './web-components/theme-catalog/logic.js';
+import './web-components/brand-specimen/logic.js';
+import './web-components/icon-set/logic.js';
+import './web-components/icon-specimen/logic.js';

package/src/lib/bundle-registry.js

@@ -0,0 +1,156 @@
+/**
+ * Bundle Registry — Vanilla Breeze
+ *
+ * Provides infrastructure for modular bundles to register effects,
+ * components, and activate full bundles at runtime.
+ */
+
+// ─── Effect registry ─────────────────────────────────────────────────────────
+
+const effects = new Map()
+let observer = null
+const reducedMotionMq = window.matchMedia('(prefers-reduced-motion: reduce)')
+
+function startObserver() {
+  if (observer) return
+  observer = new MutationObserver(mutations => {
+    for (const mutation of mutations) {
+      for (const node of mutation.addedNodes) {
+        if (node.nodeType !== Node.ELEMENT_NODE) continue
+        const el = /** @type {Element} */ (node)
+        matchEffects(el)
+        el.querySelectorAll('*').forEach(matchEffects)
+      }
+      for (const node of mutation.removedNodes) {
+        if (node.nodeType !== Node.ELEMENT_NODE) continue
+        const el = /** @type {Element} */ (node)
+        unmatchEffects(el)
+        el.querySelectorAll('*').forEach(unmatchEffects)
+      }
+    }
+  })
+  observer.observe(document.body, { childList: true, subtree: true })
+}
+
+function matchEffects(el) {
+  for (const [, def] of effects) {
+    if (el.matches?.(def.selector)) {
+      if (reducedMotionMq.matches && def.reducedMotionFallback) {
+        def.reducedMotionFallback(el)
+      } else {
+        def.init(el)
+      }
+    }
+  }
+}
+
+function unmatchEffects(el) {
+  for (const [, def] of effects) {
+    if (el.matches?.(def.selector) && def.destroy) {
+      def.destroy(el)
+    }
+  }
+}
+
+/**
+ * Register a DOM effect that auto-initializes on matching elements.
+ *
+ * @param {string} name - Unique effect name
+ * @param {{ selector: string, init: (el: Element) => void, destroy?: (el: Element) => void, reducedMotionFallback?: (el: Element) => void }} def
+ */
+export function registerEffect(name, def) {
+  effects.set(name, def)
+
+  // Initialize on existing matching elements
+  document.querySelectorAll(def.selector).forEach(el => {
+    if (reducedMotionMq.matches && def.reducedMotionFallback) {
+      def.reducedMotionFallback(el)
+    } else {
+      def.init(el)
+    }
+  })
+
+  // Start shared observer lazily
+  if (document.body) {
+    startObserver()
+  } else {
+    document.addEventListener('DOMContentLoaded', startObserver, { once: true })
+  }
+}
+
+// ─── Component registry ──────────────────────────────────────────────────────
+
+const components = new Map()
+
+/**
+ * Register a custom element with priority-based conflict resolution.
+ * First-wins at equal priority. Higher priority wins over lower.
+ *
+ * @param {string} tag - Custom element tag name
+ * @param {typeof HTMLElement} impl - The element class
+ * @param {{ bundle?: string, contract?: string, priority?: number }} [opts]
+ */
+export function registerComponent(tag, impl, opts = {}) {
+  const priority = opts.priority ?? 10
+  const meta = { impl, bundle: opts.bundle, contract: opts.contract, priority }
+
+  const existing = components.get(tag)
+
+  if (customElements.get(tag)) {
+    // Already defined in the browser — cannot redefine
+    if (!existing || existing.priority >= priority) {
+      if (existing && existing.priority === priority && existing.impl !== impl) {
+        console.warn(
+          `[VB Bundle] Tag <${tag}> already registered by "${existing.bundle}" (priority ${existing.priority}). Skipping "${opts.bundle}".`
+        )
+      }
+      return
+    }
+    // Higher priority but can't redefine — warn
+    console.warn(
+      `[VB Bundle] Tag <${tag}> defined by "${existing.bundle}" cannot be replaced (customElements.define is permanent). "${opts.bundle}" has higher priority but arrived late.`
+    )
+    return
+  }
+
+  if (existing && existing.priority >= priority) {
+    if (existing.priority === priority) {
+      console.warn(
+        `[VB Bundle] Tag <${tag}> already registered by "${existing.bundle}". Skipping "${opts.bundle}" (first wins at equal priority).`
+      )
+    }
+    return
+  }
+
+  components.set(tag, meta)
+  customElements.define(tag, impl)
+}
+
+/**
+ * Activate a full pack by loading its CSS and JS from the CDN path.
+ * Convention: cdn/packs/{name}.full.css and cdn/packs/{name}.full.js
+ *
+ * @param {string} bundleName
+ * @param {{ basePath?: string }} [opts]
+ * @returns {Promise<void>}
+ */
+export async function activateBundle(bundleName, opts = {}) {
+  const base = opts.basePath ?? '/cdn/packs'
+
+  // Load CSS
+  const cssHref = `${base}/${bundleName}.full.css`
+  if (!document.querySelector(`link[href="${cssHref}"]`)) {
+    const link = document.createElement('link')
+    link.rel = 'stylesheet'
+    link.href = cssHref
+    await new Promise((resolve, reject) => {
+      link.onload = resolve
+      link.onerror = () => reject(new Error(`Failed to load bundle CSS: ${cssHref}`))
+      document.head.appendChild(link)
+    })
+  }
+
+  // Load JS
+  const jsSrc = `${base}/${bundleName}.full.js`
+  await import(jsSrc)
+}

package/src/lib/vb-element.js

@@ -0,0 +1,96 @@
+/**
+ * VBElement — Minimal base class for Vanilla Breeze web components
+ *
+ * Provides:
+ * - data-upgraded guard (prevents double initialization on reconnect)
+ * - listen() method with automatic cleanup on disconnect
+ * - setup()/teardown() lifecycle hooks
+ *
+ * Does NOT provide: props reflection, template rendering, reactivity.
+ * Components that need observedAttributes/attributeChangedCallback
+ * declare them normally alongside setup()/teardown().
+ */
+class VBElement extends HTMLElement {
+  #cleanups = [];
+  /** @type {ElementInternals | undefined} */
+  #internals;
+
+  connectedCallback() {
+    if (this.hasAttribute('data-upgraded')) return;
+    if (this.setup() === false) return;
+    this.setAttribute('data-upgraded', '');
+    // Dispatch :upgraded in a microtask so any sibling component definitions
+    // queued in the same synchronous script (e.g. a pack's registerComponent
+    // calls) complete before consumers react. Without this, listeners that
+    // immediately assign .items can hit a race where downstream components
+    // (work-item, etc.) aren't defined yet and the default renderer falls
+    // back to a plain element.
+    queueMicrotask(() => {
+      this.dispatchEvent(new CustomEvent(`${this.localName}:upgraded`, { bubbles: true }));
+    });
+  }
+
+  disconnectedCallback() {
+    for (const fn of this.#cleanups) fn();
+    this.#cleanups = [];
+    this.removeAttribute('data-upgraded');
+    this.teardown();
+  }
+
+  /**
+   * Track an event listener for automatic cleanup on disconnect.
+   * @param {EventTarget} target
+   * @param {string} event
+   * @param {EventListenerOrEventListenerObject} handler
+   * @param {AddEventListenerOptions} [opts]
+   */
+  listen(target, event, handler, opts) {
+    target.addEventListener(event, handler, opts);
+    this.#cleanups.push(() => target.removeEventListener(event, handler, opts));
+  }
+
+  /**
+   * Override in subclass. Return false to abort upgrade.
+   * @returns {boolean | void}
+   */
+  setup() {}
+
+  /** Override in subclass for cleanup beyond event listeners. */
+  teardown() {}
+
+  /**
+   * Toggle a CustomStateSet entry targetable via the `:state(name)` CSS selector.
+   * Use for component-private flags. For author-facing state, keep using
+   * data-* / aria-* attributes — see admin/specs/custom-state-set-research.md.
+   *
+   * Lazily attaches ElementInternals on first call; subclasses that already
+   * attached internals (form-associated components) must hand them over via
+   * `_adoptInternals(this.attachInternals())` in their constructor to avoid
+   * the double-attach throw.
+   *
+   * @param {string} name
+   * @param {boolean} on
+   */
+  setState(name, on) {
+    if (!this.#internals) this.#internals = this.attachInternals();
+    const states = this.#internals.states;
+    try {
+      if (on) states.add(name); else states.delete(name);
+    } catch {
+      // Legacy --name syntax for older Chromium/WebKit releases
+      const legacy = `--${name}`;
+      if (on) states.add(legacy); else states.delete(legacy);
+    }
+  }
+
+  /**
+   * Hand pre-attached ElementInternals to the base class. Form-associated
+   * subclasses call this in their constructor right after attachInternals().
+   * @param {ElementInternals} internals
+   */
+  _adoptInternals(internals) {
+    if (!this.#internals) this.#internals = internals;
+  }
+}
+
+export { VBElement };

package/src/patterns/do-dont.css

@@ -0,0 +1,86 @@
+/**
+ * Do/Don't and Pro/Con list patterns
+ *
+ * Usage:
+ *   <ul data-list="do-dont">
+ *     <li data-do>Use the full logo on light backgrounds.</li>
+ *     <li data-dont>Don't stretch or rotate the logo.</li>
+ *   </ul>
+ *
+ *   <ul data-list="pro-con">
+ *     <li data-pro>Fast initial load time.</li>
+ *     <li data-con>Requires JavaScript for interactivity.</li>
+ *   </ul>
+ */
+
+[data-list="do-dont"],
+[data-list="pro-con"] {
+  list-style: none;
+  padding-inline-start: 0;
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(14rem, 1fr));
+  gap: var(--size-s, 0.5rem);
+}
+
+/* Do / Pro items */
+[data-list] > [data-do],
+[data-list] > [data-pro] {
+  padding: var(--size-s, 0.5rem) var(--size-m, 1rem);
+  border-inline-start: 4px solid var(--color-success, oklch(55% 0.2 145));
+  background: var(--color-success-subtle, oklch(95% 0.03 145));
+  border-radius: var(--radius-s, 0.25rem);
+}
+
+/* Don't / Con items */
+[data-list] > [data-dont],
+[data-list] > [data-con] {
+  padding: var(--size-s, 0.5rem) var(--size-m, 1rem);
+  border-inline-start: 4px solid var(--color-error, oklch(55% 0.22 25));
+  background: var(--color-error-subtle, oklch(95% 0.03 25));
+  border-radius: var(--radius-s, 0.25rem);
+}
+
+/* Labels via ::before */
+[data-list="do-dont"] > [data-do]::before {
+  content: "Do";
+  display: block;
+  font-weight: 700;
+  font-size: var(--font-size-xs, 0.75rem);
+  color: var(--color-success, oklch(45% 0.2 145));
+  margin-block-end: var(--size-2xs, 0.25rem);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+[data-list="do-dont"] > [data-dont]::before {
+  content: "Don\2019t";
+  display: block;
+  font-weight: 700;
+  font-size: var(--font-size-xs, 0.75rem);
+  color: var(--color-error, oklch(45% 0.22 25));
+  margin-block-end: var(--size-2xs, 0.25rem);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+[data-list="pro-con"] > [data-pro]::before {
+  content: "Pro";
+  display: block;
+  font-weight: 700;
+  font-size: var(--font-size-xs, 0.75rem);
+  color: var(--color-success, oklch(45% 0.2 145));
+  margin-block-end: var(--size-2xs, 0.25rem);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+[data-list="pro-con"] > [data-con]::before {
+  content: "Con";
+  display: block;
+  font-weight: 700;
+  font-size: var(--font-size-xs, 0.75rem);
+  color: var(--color-error, oklch(45% 0.22 25));
+  margin-block-end: var(--size-2xs, 0.25rem);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}

package/src/patterns/token-table.css

@@ -0,0 +1,67 @@
+/**
+ * Design System Token Table
+ *
+ * Usage:
+ *   <table class="ds-token-table">
+ *     <thead><tr><th>Token</th><th>Preview</th><th>Value</th></tr></thead>
+ *     <tbody>
+ *       <tr>
+ *         <td><code>--color-primary</code></td>
+ *         <td><token-swatch data-preview="var(--color-primary)"></token-swatch></td>
+ *         <td>oklch(50% 0.2 260)</td>
+ *       </tr>
+ *     </tbody>
+ *   </table>
+ */
+
+.ds-token-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: var(--font-size-s, 0.875rem);
+}
+
+.ds-token-table thead {
+  border-block-end: 2px solid var(--color-border, #ddd);
+}
+
+.ds-token-table th {
+  text-align: start;
+  padding: var(--size-xs, 0.25rem) var(--size-s, 0.5rem);
+  font-size: var(--font-size-xs, 0.75rem);
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--color-text-muted, #666);
+}
+
+.ds-token-table td {
+  padding: var(--size-xs, 0.25rem) var(--size-s, 0.5rem);
+  border-block-end: 1px solid var(--color-border, #eee);
+  vertical-align: middle;
+}
+
+.ds-token-table code {
+  font-family: var(--font-mono, monospace);
+  font-size: var(--font-size-xs, 0.75rem);
+}
+
+/* Inline swatch preview in table cells */
+.ds-token-table .ds-swatch {
+  display: inline-block;
+  width: 2.5rem;
+  height: 1.5rem;
+  border-radius: var(--radius-s, 0.25rem);
+  border: 1px solid var(--color-border, #ddd);
+  vertical-align: middle;
+}
+
+/* Also support token-swatch with proper child markup */
+.ds-token-table token-swatch {
+  display: inline-flex;
+}
+.ds-token-table token-swatch > [data-preview] {
+  width: 2.5rem;
+  height: 1.5rem;
+  border-radius: var(--radius-s, 0.25rem);
+  border: 1px solid var(--color-border, #ddd);
+}