@profpowell/vb-design-system 0.1.0

package/src/web-components/accessibility-specimen/styles.css

@@ -0,0 +1,156 @@
+/* --------------------------------------------------------------------------
+   accessibility-specimen: WCAG contrast-ratio table + a11y checklist
+   for design-system docs.
+   -------------------------------------------------------------------------- */
+
+accessibility-specimen {
+  display: block;
+  font: inherit;
+}
+
+/* -------- Contrast table -------- */
+
+accessibility-specimen .as-contrast-table {
+  inline-size: 100%;
+  border-collapse: collapse;
+  border: var(--border-width-thin, 1px) solid var(--color-border, #ddd);
+  border-radius: var(--radius-m, 0.5rem);
+  overflow: hidden;
+  font-size: 0.95em;
+}
+
+accessibility-specimen .as-contrast-table th,
+accessibility-specimen .as-contrast-table td {
+  padding-block: var(--size-2xs, 0.375rem);
+  padding-inline: var(--size-s, 0.5rem);
+  text-align: start;
+  border-block-end: var(--border-width-thin, 1px) solid var(--color-border, #ddd);
+}
+
+accessibility-specimen .as-contrast-table tr:last-child th,
+accessibility-specimen .as-contrast-table tr:last-child td {
+  border-block-end: none;
+}
+
+accessibility-specimen .as-contrast-table thead {
+  background: var(--color-surface-raised, var(--color-surface, #fff));
+  font-size: 0.85em;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--color-text-muted, currentColor);
+}
+
+accessibility-specimen .as-pair-label {
+  font-weight: 500;
+  display: flex;
+  align-items: center;
+  gap: var(--size-2xs, 0.375rem);
+  font-variant-numeric: tabular-nums;
+}
+
+accessibility-specimen .as-swatch {
+  display: inline-block;
+  inline-size: 1.25rem;
+  block-size: 1.25rem;
+  border-radius: var(--radius-s, 0.25rem);
+  border: var(--border-width-thin, 1px) solid currentColor;
+  flex-shrink: 0;
+}
+
+accessibility-specimen .as-pair-sample {
+  font-weight: 500;
+  font-size: 1em;
+  white-space: nowrap;
+  text-align: center;
+}
+
+accessibility-specimen .as-pair-ratio {
+  font-variant-numeric: tabular-nums;
+  font-weight: 600;
+}
+
+accessibility-specimen .as-badge {
+  text-align: center;
+  font-weight: 600;
+  font-size: 1.1em;
+  inline-size: 3em;
+}
+
+accessibility-specimen .as-pass {
+  color: var(--color-success, #2e7d32);
+}
+
+accessibility-specimen .as-fail {
+  color: var(--color-error, #c62828);
+}
+
+accessibility-specimen .as-empty {
+  text-align: center;
+  font-style: italic;
+  color: var(--color-text-muted, currentColor);
+  padding-block: var(--size-l, 1.5rem) !important;
+}
+
+/* -------- Checklist -------- */
+
+accessibility-specimen .as-checklist {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--size-2xs, 0.375rem);
+}
+
+accessibility-specimen .as-checklist > li {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--size-xs, 0.5rem);
+  padding-block: var(--size-2xs, 0.375rem);
+  padding-inline: var(--size-s, 0.5rem);
+  border: var(--border-width-thin, 1px) solid var(--color-border, #ddd);
+  border-radius: var(--radius-s, 0.25rem);
+}
+
+accessibility-specimen .as-checklist-icon {
+  flex-shrink: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  inline-size: 1.5rem;
+  block-size: 1.5rem;
+  border-radius: var(--radius-full, 999px);
+  font-weight: 700;
+  line-height: 1;
+}
+
+accessibility-specimen .as-status-pass { border-color: var(--color-success, #2e7d32); }
+accessibility-specimen .as-status-pass .as-checklist-icon {
+  background: var(--color-success, #2e7d32); color: var(--color-text-on-success, white);
+}
+
+accessibility-specimen .as-status-fail { border-color: var(--color-error, #c62828); }
+accessibility-specimen .as-status-fail .as-checklist-icon {
+  background: var(--color-error, #c62828); color: var(--color-text-on-error, white);
+}
+
+accessibility-specimen .as-status-warn { border-color: var(--color-warning, #b8860b); }
+accessibility-specimen .as-status-warn .as-checklist-icon {
+  background: var(--color-warning, #b8860b); color: var(--color-text-on-warning, white);
+}
+
+accessibility-specimen .as-status-na .as-checklist-icon {
+  background: var(--color-text-muted, oklch(60% 0 0)); color: var(--color-surface, white);
+}
+
+accessibility-specimen .as-sr-only {
+  position: absolute;
+  inline-size: 1px;
+  block-size: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+  border: 0;
+}

package/src/web-components/brand-specimen/api.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "../../../schemas/api.schema.json",
+  "element": "brand-specimen",
+  "type": "web-component",
+  "description": "Brand mark specimen: shows a <brand-mark> on light/dark surfaces, a size scale, and a clear-space box",
+  "htmlvalidate": {
+    "flow": true,
+    "permittedContent": [
+      "@flow"
+    ]
+  },
+  "attributes": [
+    {
+      "name": "src",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Logo image URL, passed through to each <brand-mark src>"
+    },
+    {
+      "name": "name",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Brand name, passed through to each <brand-mark wordmark> (default: \"Brand\")"
+    },
+    {
+      "name": "data-sizes",
+      "kind": "data",
+      "purpose": "config",
+      "type": "string",
+      "description": "Space-separated <brand-mark data-size> values for the scale row (default: \"s m l xl\")"
+    }
+  ],
+  "childAttributes": [],
+  "structure": []
+}

package/src/web-components/brand-specimen/logic.js

@@ -0,0 +1,61 @@
+/**
+ * brand-specimen: DS specimen documenting a brand mark
+ *
+ * Shows a `<brand-mark>` on light and dark surfaces, at a size scale, and
+ * inside a clear-space box. Pairs with the other identity/token specimens
+ * (color-palette, semantic-palette) for brand-guideline pages.
+ *
+ * `<brand-mark>` itself is a VB-core component (runtime peer) — this
+ * specimen only arranges instances of it; it does not re-implement its
+ * theme-aware light/dark logo swap.
+ *
+ * @attr {string} src        - Logo image URL, passed through to `<brand-mark src>`
+ * @attr {string} name       - Brand name, passed through as `<brand-mark>` child text content
+ * @attr {string} data-sizes - Space-separated `<brand-mark data-size>` values
+ *                             for the scale row (default: "s m l xl")
+ *
+ * @example
+ * <brand-specimen src="/logo.svg" name="Acme"></brand-specimen>
+ * <brand-specimen src="/logo.svg" name="Acme" data-sizes="xs s m l xl 2xl"></brand-specimen>
+ */
+
+import { registerComponent } from '../../lib/bundle-registry.js';
+import { VBElement } from '../../lib/vb-element.js';
+
+class BrandSpecimen extends VBElement {
+  static observedAttributes = ['src', 'name', 'data-sizes'];
+
+  setup() {
+    this.#render();
+  }
+
+  attributeChangedCallback() {
+    if (this.isConnected) this.#render();
+  }
+
+  #render() {
+    const src = this.getAttribute('src') || '';
+    const name = this.getAttribute('name') || 'Brand';
+    const sizes = (this.getAttribute('data-sizes') || 's m l xl').trim().split(/\s+/);
+    // `<brand-mark>` treats `wordmark` as a boolean presence attribute and
+    // reads the displayed brand name from its light-DOM text content — the
+    // name must be the element's child text, not the value of `wordmark=`.
+    const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+    const mark = (size) =>
+      `<brand-mark${src ? ` src="${esc(src)}"` : ''} wordmark${size ? ` data-size="${size}"` : ''}>${esc(name)}</brand-mark>`;
+    this.innerHTML = `
+      <section class="brand-specimen">
+        <div class="bs-surfaces">
+          <figure data-surface="light">${mark('l')}<figcaption>On light</figcaption></figure>
+          <figure data-surface="dark">${mark('l')}<figcaption>On dark</figcaption></figure>
+        </div>
+        <div class="bs-scale" data-scale>
+          ${sizes.map(s => `<span>${mark(s)}<small>${s}</small></span>`).join('')}
+        </div>
+        <div class="bs-clearspace"><span class="bs-clear-box">${mark('l')}</span>
+          <figcaption>Clear space</figcaption></div>
+      </section>`;
+  }
+}
+
+registerComponent('brand-specimen', BrandSpecimen);

package/src/web-components/brand-specimen/static.html

@@ -0,0 +1,77 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Brand Specimen (Static Fallback)</title>
+  <style>
+    /*
+     * Static fallback for <brand-specimen>.
+     *
+     * Upgrade relationship:
+     * When JavaScript loads and the <brand-specimen> custom element is
+     * defined, it renders a <brand-mark> on light and dark surface
+     * panels, a size scale, and a clear-space box.
+     *
+     * Without JS, this static page presents the same information as
+     * plain semantic HTML: a labeled logo image and a list of the
+     * size-scale names, providing equivalent content through markup
+     * alone.
+     */
+
+    *, *::before, *::after { box-sizing: border-box; }
+
+    body {
+      font-family: system-ui, sans-serif;
+      line-height: 1.6;
+      margin: 0;
+      padding: 2rem;
+      color: #1a1a1a;
+      background: #f8f8f8;
+    }
+
+    h1 { margin-block-end: 1rem; }
+
+    .surfaces {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+      gap: 1rem;
+      max-width: 30rem;
+      margin-block-end: 1.5rem;
+    }
+
+    figure {
+      margin: 0;
+      padding: 1.5rem;
+      border-radius: 0.5rem;
+      text-align: center;
+    }
+
+    figure img { max-height: 3rem; }
+
+    .surfaces figure:first-child { background: #fff; color: #111; }
+    .surfaces figure:last-child { background: #111; color: #fff; }
+
+    figcaption { font-size: 0.875rem; margin-block-start: 0.5rem; }
+
+    ul { font-family: ui-monospace, monospace; font-size: 0.875rem; color: #666; }
+  </style>
+</head>
+<body>
+  <h1>Brand Mark</h1>
+  <p>These panels show the brand mark on light and dark surfaces. With JavaScript enabled, this becomes an interactive specimen with a size scale and clear-space guide.</p>
+
+  <div class="surfaces">
+    <figure><img src="" alt="" width="0" height="0"><figcaption>On light</figcaption></figure>
+    <figure><img src="" alt="" width="0" height="0"><figcaption>On dark</figcaption></figure>
+  </div>
+
+  <p>Size scale:</p>
+  <ul>
+    <li>s</li>
+    <li>m</li>
+    <li>l</li>
+    <li>xl</li>
+  </ul>
+</body>
+</html>

package/src/web-components/brand-specimen/styles.css

@@ -0,0 +1,10 @@
+.brand-specimen { display: grid; gap: var(--size-l, 1.5rem); }
+.bs-surfaces { display: grid; grid-template-columns: 1fr 1fr; gap: var(--size-m, 1rem); }
+.bs-surfaces figure { margin: 0; padding: var(--size-l, 1.5rem); border-radius: var(--radius-m, 0.5rem);
+  display: grid; place-items: center; gap: var(--size-s, 0.75rem); }
+.bs-surfaces [data-surface="light"] { background: #fff; color: #111; }
+.bs-surfaces [data-surface="dark"]  { background: #111; color: #fff; }
+.bs-scale { display: flex; align-items: end; gap: var(--size-l, 1.5rem); flex-wrap: wrap; }
+.bs-scale span { display: grid; justify-items: center; gap: var(--size-2xs, 0.25rem); }
+.bs-clear-box { display: inline-block; padding: 1em; outline: 1px dashed var(--color-border, #d4d4d8);
+  outline-offset: 0.25em; }

package/src/web-components/breakpoint-specimen/api.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "../../../schemas/api.schema.json",
+  "element": "breakpoint-specimen",
+  "type": "web-component",
+  "description": "Responsive breakpoint visualization with live width readout",
+  "htmlvalidate": {
+    "flow": true,
+    "permittedContent": [
+      "@flow"
+    ]
+  },
+  "attributes": [
+    {
+      "name": "tokens",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Comma-separated breakpoint names (default: \"sm,md,lg,xl\")"
+    },
+    {
+      "name": "prefix",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "CSS variable prefix (default: \"--bp-\")"
+    },
+    {
+      "name": "label",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Optional heading label"
+    },
+    {
+      "name": "data-observe",
+      "kind": "data",
+      "purpose": "config",
+      "type": "string",
+      "description": "CSS selector of a container to track instead of the viewport. Container-query mode (JS-only)."
+    }
+  ],
+  "childAttributes": [],
+  "structure": []
+}

package/src/web-components/breakpoint-specimen/logic.js

@@ -0,0 +1,186 @@
+/**
+ * breakpoint-specimen: Responsive breakpoint visualization
+ *
+ * Joins the specimen family (spacing, type, motion, token). Renders a
+ * ruler of viewport breakpoints with a live cursor at the current
+ * width and the active breakpoint label called out.
+ *
+ * Reads --bp-* tokens from :root by default; can be given an explicit
+ * tokens list. Tracks the viewport (window) by default; data-observe
+ * accepts a CSS selector to track an arbitrary container instead.
+ *
+ * Progressive enhancement:
+ *   1. HTML — a semantic <dl> of breakpoint name → value remains
+ *      readable without JS or CSS.
+ *   2. CSS  — pure-CSS active-row highlighting via @media rules pulls
+ *      the matching token into a callout, no JS required for the
+ *      "which breakpoint is active" cue (viewport mode only).
+ *   3. JS   — adds the live numeric width readout and the moving
+ *      cursor on the ruler, plus container-query mode (data-observe).
+ *
+ * @attr {string} tokens   - Comma-separated breakpoint names
+ *                           (default: "sm,md,lg,xl")
+ * @attr {string} prefix   - CSS variable prefix (default: "--bp-")
+ * @attr {string} label    - Optional heading label
+ * @attr {string} data-observe - CSS selector of a container to track
+ *                               instead of the viewport. JS-only.
+ *
+ * @example
+ * <breakpoint-specimen></breakpoint-specimen>
+ * <breakpoint-specimen tokens="sm,md,lg" label="Core breakpoints"></breakpoint-specimen>
+ * <breakpoint-specimen data-observe="#preview-frame"></breakpoint-specimen>
+ */
+
+import { registerComponent } from '../../lib/bundle-registry.js';
+import { VBElement } from '../../lib/vb-element.js';
+
+class BreakpointSpecimen extends VBElement {
+  static observedAttributes = ['tokens', 'prefix', 'label', 'data-observe'];
+
+  setup() {
+    this.#render();
+    this.#start();
+  }
+
+  attributeChangedCallback() {
+    if (this.isConnected) {
+      this.#stop();
+      this.#render();
+      this.#start();
+    }
+  }
+
+  teardown() {
+    this.#stop();
+  }
+
+  #render() {
+    const tokensAttr = this.getAttribute('tokens') || 'sm,md,lg,xl';
+    const prefix = this.getAttribute('prefix') || '--bp-';
+    const label = this.getAttribute('label') || '';
+    const names = tokensAttr.split(',').map((t) => t.trim()).filter(Boolean);
+
+    const cs = getComputedStyle(document.documentElement);
+    const stops = names
+      .map((name) => {
+        const raw = cs.getPropertyValue(`${prefix}${name}`).trim();
+        const px = this.#toPx(raw);
+        return { name, raw, px };
+      })
+      .filter((s) => s.px > 0)
+      .sort((a, b) => a.px - b.px);
+
+    this.#stops = stops;
+    this.#max = stops.length ? stops[stops.length - 1].px * 1.15 : 1;
+
+    const labelHTML = label ? `<header class="bps-label">${label}</header>` : '';
+
+    const readoutHTML = `
+      <output class="bps-readout" aria-live="polite">
+        <span class="bps-width">—</span>
+        <span class="bps-active" data-active="">—</span>
+      </output>
+    `;
+
+    const rulerHTML = `
+      <figure class="bps-ruler" aria-hidden="true">
+        <span class="bps-cursor" data-cursor></span>
+        ${stops.map((s) => `
+          <span class="bps-stop" style="--bps-pos:${(s.px / this.#max) * 100}%" data-bp="${s.name}">
+            <span class="bps-tick"></span>
+            <span class="bps-stop-label">${s.name}<br><small>${Math.round(s.px)}px</small></span>
+          </span>
+        `).join('')}
+      </figure>
+    `;
+
+    const tableHTML = `
+      <dl class="bps-list">
+        ${stops.map((s) => `
+          <div class="bps-row" data-bp="${s.name}">
+            <dt>${s.name}</dt>
+            <dd><code>${s.raw}</code> — ${Math.round(s.px)}px and up</dd>
+          </div>
+        `).join('')}
+      </dl>
+    `;
+
+    this.innerHTML = `${labelHTML}${readoutHTML}${rulerHTML}${tableHTML}`;
+    this.#widthEl = /** @type {HTMLElement | null} */ (this.querySelector('.bps-width'));
+    this.#activeEl = /** @type {HTMLElement | null} */ (this.querySelector('.bps-active'));
+    this.#cursorEl = /** @type {HTMLElement | null} */ (this.querySelector('[data-cursor]'));
+  }
+
+  #start() {
+    const sel = this.getAttribute('data-observe');
+    if (sel) {
+      const target = document.querySelector(sel);
+      if (!target) return;
+      this.#ro = new ResizeObserver(() => this.#update(target.clientWidth));
+      this.#ro.observe(target);
+      this.#update(target.clientWidth);
+      return;
+    }
+    const update = () => this.#update(window.innerWidth);
+    update();
+    this.listen(window, 'resize', update, { passive: true });
+  }
+
+  #stop() {
+    if (this.#ro) {
+      this.#ro.disconnect();
+      this.#ro = null;
+    }
+  }
+
+  #update(width) {
+    if (!this.#widthEl || !this.#activeEl) return;
+    this.#widthEl.textContent = `${Math.round(width)}px`;
+    const active = this.#activeFor(width);
+    this.#activeEl.textContent = active ? active.name : 'base';
+    this.#activeEl.dataset.active = active ? active.name : '';
+    if (this.#cursorEl) {
+      const pct = Math.min(100, (width / this.#max) * 100);
+      this.#cursorEl.style.setProperty('--bps-pos', `${pct}%`);
+    }
+    this.querySelectorAll('[data-bp]').forEach((el) => {
+      const matches = active && el.getAttribute('data-bp') === active.name;
+      el.toggleAttribute('data-current', !!matches);
+    });
+  }
+
+  #activeFor(width) {
+    let match = null;
+    for (const stop of this.#stops) {
+      if (width >= stop.px) match = stop;
+    }
+    return match;
+  }
+
+  #toPx(value) {
+    if (!value) return 0;
+    const n = parseFloat(value);
+    if (Number.isNaN(n)) return 0;
+    if (value.endsWith('rem') || value.endsWith('em')) {
+      const root = parseFloat(getComputedStyle(document.documentElement).fontSize) || 16;
+      return n * root;
+    }
+    return n;
+  }
+
+  /** @type {Array<{name: string, raw: string, px: number}>} */
+  #stops = [];
+  #max = 1;
+  /** @type {ResizeObserver | null} */
+  #ro = null;
+  /** @type {HTMLElement | null} */
+  #widthEl = null;
+  /** @type {HTMLElement | null} */
+  #activeEl = null;
+  /** @type {HTMLElement | null} */
+  #cursorEl = null;
+}
+
+registerComponent('breakpoint-specimen', BreakpointSpecimen);
+
+export { BreakpointSpecimen };

package/src/web-components/breakpoint-specimen/static.html

@@ -0,0 +1,38 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Breakpoint Specimen — Static Fallback</title>
+  <style>
+    body { font-family: system-ui, sans-serif; padding: 2rem; }
+    dl { display: grid; grid-template-columns: max-content 1fr; gap: 0.25rem 1rem; max-width: 30rem; }
+    dt { font-family: ui-monospace, monospace; font-weight: 600; }
+    dd { margin: 0; color: #666; }
+  </style>
+</head>
+<body>
+  <!--
+    Static fallback for <breakpoint-specimen>.
+
+    Upgrade relationship:
+    - Without JS, modern browsers: the @media-driven highlight in the
+      component's stylesheet calls out the active row, so even no-JS
+      readers see which breakpoint is in effect.
+    - Without JS or CSS: the <dl> below remains a readable list of
+      breakpoint names and their token values.
+    - With JS: the component adds a live numeric width readout and a
+      moving cursor on a visual ruler, plus container-query tracking
+      via data-observe.
+  -->
+
+  <breakpoint-specimen>
+    <dl>
+      <dt>sm</dt><dd>37.5rem (600px) and up — compact mobile</dd>
+      <dt>md</dt><dd>48rem (768px) and up — tablet / mobile split</dd>
+      <dt>lg</dt><dd>64rem (1024px) and up — desktop layouts</dd>
+      <dt>xl</dt><dd>87.5rem (1400px) and up — ultra-wide enhancements</dd>
+    </dl>
+  </breakpoint-specimen>
+</body>
+</html>