@profpowell/vb-design-system 0.1.0

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

@@ -0,0 +1,67 @@
+/**
+ * icon-specimen: Curated icon-language specimen
+ *
+ * Presents a fixed, curated set of icon names across the project's sizing
+ * scale — a design specimen (not a searchable browser like <icon-set>).
+ * Each cell renders the icon with the `[data-icon]` primitive itself (a
+ * currentColor CSS mask sized in `em`), so the specimen documents the same
+ * terse authoring pattern it is teaching.
+ *
+ * @attr {string} set         - Icon set directory (default: "lucide")
+ * @attr {string} names       - Space/comma-separated list of icon names (required)
+ * @attr {string} data-sizes  - Space-separated size scale (default: "1rem 1.5rem 2rem")
+ *
+ * @example
+ * <icon-specimen names="check x star settings" data-sizes="1rem 1.5rem 2rem"></icon-specimen>
+ */
+
+import { registerComponent } from '../../lib/bundle-registry.js';
+import { VBElement } from '../../lib/vb-element.js';
+
+class IconSpecimen extends VBElement {
+  static observedAttributes = ['set', 'names', 'data-sizes'];
+
+  setup() {
+    this.#render();
+  }
+
+  attributeChangedCallback() {
+    if (this.isConnected) this.#render();
+  }
+
+  get set() {
+    return this.getAttribute('set') || 'lucide';
+  }
+
+  get names() {
+    return (this.getAttribute('names') || '').split(/[\s,]+/).filter(Boolean);
+  }
+
+  get sizes() {
+    return (this.getAttribute('data-sizes') || '1rem 1.5rem 2rem').trim().split(/\s+/);
+  }
+
+  #render() {
+    const { set, names, sizes } = this;
+    const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+    const cell = (n) => sizes.map((sz) => `
+        <td><i data-icon="${esc(n)}" data-icon-set="${set}" style="font-size:${sz}" aria-hidden="true"></i></td>`).join('');
+    this.innerHTML = `
+      <table class="icon-specimen">
+        <thead>
+          <tr>
+            <th scope="col">Icon</th>
+            ${sizes.map((sz) => `<th scope="col">${sz}</th>`).join('')}
+          </tr>
+        </thead>
+        <tbody>
+          ${names.map((n) => `<tr><th scope="row"><code>${n}</code></th>${cell(n)}</tr>`).join('')}
+        </tbody>
+      </table>`;
+  }
+}
+
+registerComponent('icon-specimen', IconSpecimen);
+
+export { IconSpecimen };

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

@@ -0,0 +1,39 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Icon Specimen — Static Fallback</title>
+  <style>
+    body { font-family: system-ui, sans-serif; padding: 2rem; }
+    table { border-collapse: collapse; }
+    th, td { text-align: left; padding: 0.5rem 1rem; border-bottom: 1px solid #d4d4d8; }
+  </style>
+</head>
+<body>
+  <!--
+    Static fallback for <icon-specimen>.
+
+    Upgrade relationship:
+    - Without JS: a plain table listing each curated icon name across the
+      size scale remains readable, so the specimen's contents are never
+      hidden from no-JS readers.
+    - With JS: the component re-renders each cell with the real icon via
+      <icon-wc>, sized per the `data-sizes` scale.
+  -->
+
+  <icon-specimen names="check x star settings" data-sizes="1rem 1.5rem 2rem">
+    <table>
+      <thead>
+        <tr><th>Icon</th><th>1rem</th><th>1.5rem</th><th>2rem</th></tr>
+      </thead>
+      <tbody>
+        <tr><th scope="row"><code>check</code></th><td>check</td><td>check</td><td>check</td></tr>
+        <tr><th scope="row"><code>x</code></th><td>x</td><td>x</td><td>x</td></tr>
+        <tr><th scope="row"><code>star</code></th><td>star</td><td>star</td><td>star</td></tr>
+        <tr><th scope="row"><code>settings</code></th><td>settings</td><td>settings</td><td>settings</td></tr>
+      </tbody>
+    </table>
+  </icon-specimen>
+</body>
+</html>

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

@@ -0,0 +1,38 @@
+/* icon-specimen: curated icon-language specimen across the sizing scale */
+
+icon-specimen:not(:defined) {
+  display: block;
+}
+
+icon-specimen {
+  display: block;
+  font-family: var(--font-sans, system-ui);
+  color: var(--color-text, #1a1a1a);
+}
+
+@scope (icon-specimen) {
+  .icon-specimen {
+    inline-size: 100%;
+    border-collapse: collapse;
+  }
+
+  .icon-specimen th,
+  .icon-specimen td {
+    text-align: start;
+    padding: var(--size-s, 0.75rem);
+    border-block-end: 1px solid var(--color-border, #d4d4d8);
+  }
+
+  .icon-specimen thead th {
+    font-size: var(--font-size-xs, 0.75rem);
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    color: var(--color-text-muted, #71717a);
+  }
+
+  .icon-specimen td [data-icon] {
+    color: inherit;
+    vertical-align: middle;
+  }
+}

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

@@ -0,0 +1,12 @@
+{
+  "$schema": "../../../schemas/api.schema.json",
+  "element": "layout-specimen",
+  "type": "web-component",
+  "description": "Visual specimen of VB layout primitives for design-system docs. Renders each primitive with a labeled mini-example and the canonical HTML snippet.",
+  "attributes": [
+    { "name": "data-only", "kind": "data", "purpose": "config", "type": "string", "description": "Comma-separated subset of primitive names to render (e.g. \"cluster,grid,stack\"; with or without the \"layout-\" prefix). Default: all 14 primitives." }
+  ],
+  "events": [],
+  "childAttributes": [],
+  "structure": []
+}

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

@@ -0,0 +1,219 @@
+/**
+ * layout-specimen: Visual specimen of VB layout primitives for design-system docs.
+ *
+ * Renders each layout custom element with a labeled mini-example and the
+ * canonical HTML snippet. Lets docs readers see the pattern + copy it.
+ *
+ * @attr {string} data-only - Comma-separated subset (e.g. "cluster,grid,stack").
+ *                            Defaults to all primitives below.
+ *
+ * Adjacent: spacing-specimen, type-specimen, motion-specimen, breakpoint-specimen,
+ *           token-specimen — each visualizes a different design-system axis.
+ */
+
+import { registerComponent } from '../../lib/bundle-registry.js';
+import { VBElement } from '../../lib/vb-element.js';
+
+/**
+ * Each entry: { name, desc, snippet, render(box) }
+ *  - snippet is the source HTML to display in the code block
+ *  - render() returns a DOM tree for the live mini-example
+ */
+const PRIMITIVES = [
+  {
+    name: 'layout-stack',
+    desc: 'Vertical stack with consistent gap between children.',
+    snippet: `<layout-stack data-layout-gap="m">
+  <p>One</p>
+  <p>Two</p>
+  <p>Three</p>
+</layout-stack>`,
+    render: () => el('layout-stack', { 'data-layout-gap': 's' }, [box('One'), box('Two'), box('Three')]),
+  },
+  {
+    name: 'layout-cluster',
+    desc: 'Horizontal cluster that wraps; for tag rows, button groups.',
+    snippet: `<layout-cluster data-layout-gap="s">
+  <button>One</button> <button>Two</button> <button>Three</button>
+</layout-cluster>`,
+    render: () => el('layout-cluster', { 'data-layout-gap': 's' }, [chip('One'), chip('Two'), chip('Three'), chip('Four')]),
+  },
+  {
+    name: 'layout-grid',
+    desc: 'Auto-fit responsive grid; columns flow based on min-item-size.',
+    snippet: `<layout-grid data-layout-min="12rem">
+  <div>1</div> <div>2</div> <div>3</div> <div>4</div>
+</layout-grid>`,
+    render: () => el('layout-grid', { 'data-layout-min': '6rem', 'data-layout-gap': 's' }, [box('1'), box('2'), box('3'), box('4'), box('5'), box('6')]),
+  },
+  {
+    name: 'layout-center',
+    desc: 'Center a block horizontally with optional max-width.',
+    snippet: `<layout-center data-layout-max="readable">
+  <p>Centered prose.</p>
+</layout-center>`,
+    render: () => el('layout-center', { 'data-layout-max': 'narrow', style: 'border: 1px dashed var(--color-border); padding: var(--size-2xs)' }, [box('Centered')]),
+  },
+  {
+    name: 'layout-cover',
+    desc: 'Vertical cover layout: optional header + main area + optional footer, with main filling available space.',
+    snippet: `<layout-cover style="block-size: 12rem">
+  <header>Top</header>
+  <main>Center</main>
+  <footer>Bottom</footer>
+</layout-cover>`,
+    render: () => el('layout-cover', { style: 'block-size: 9rem; border: 1px dashed var(--color-border); padding: var(--size-2xs)' }, [
+      el('header', {}, [box('Top')]),
+      el('main', {}, [box('Center', 'main')]),
+      el('footer', {}, [box('Bottom')]),
+    ]),
+  },
+  {
+    name: 'layout-imposter',
+    desc: 'Absolute centering — child sits in the dead center of the parent.',
+    snippet: `<div style="position:relative; block-size:8rem">
+  <layout-imposter><span>Centered</span></layout-imposter>
+</div>`,
+    render: () => el('div', { style: 'position:relative; block-size: 6rem; border: 1px dashed var(--color-border)' }, [
+      el('layout-imposter', {}, [box('Imposter')]),
+    ]),
+  },
+  {
+    name: 'layout-columns',
+    desc: 'Multi-column text layout (CSS columns); good for newspapery prose.',
+    snippet: `<layout-columns data-layout-columns="3">
+  <p>Long prose flows across columns…</p>
+</layout-columns>`,
+    render: () => el('layout-columns', { 'data-layout-columns': '3' }, [
+      el('p', { style: 'margin: 0; font-size: 0.85em' }, ['One two three four five six seven eight nine ten eleven twelve thirteen fourteen fifteen.']),
+    ]),
+  },
+  {
+    name: 'layout-card',
+    desc: 'Stack of header + body + actions with card chrome (border + padding).',
+    snippet: `<layout-card>
+  <h3>Title</h3>
+  <p>Body text.</p>
+  <div data-layout-card-actions><button>OK</button></div>
+</layout-card>`,
+    render: () => el('layout-card', {}, [
+      el('h3', { style: 'margin: 0; font-size: 0.9em' }, ['Card title']),
+      el('p', { style: 'margin: 0; font-size: 0.85em' }, ['Card body content.']),
+    ]),
+  },
+  {
+    name: 'layout-canvas',
+    desc: 'Full-bleed canvas section that breaks the centered max-width.',
+    snippet: `<layout-canvas>
+  <p>Edge-to-edge content.</p>
+</layout-canvas>`,
+    render: () => el('layout-canvas', { style: 'background: var(--color-surface-sunken, oklch(94% 0 0)); padding: var(--size-2xs)' }, [box('Full-bleed')]),
+  },
+  {
+    name: 'layout-badge',
+    desc: 'Tiny inline badge / pill for inline labels.',
+    snippet: `<layout-badge>NEW</layout-badge>`,
+    render: () => el('layout-cluster', { 'data-layout-gap': 'xs' }, [
+      el('layout-badge', {}, ['NEW']),
+      el('layout-badge', {}, ['BETA']),
+      el('layout-badge', {}, ['v2.0']),
+    ]),
+  },
+  {
+    name: 'layout-reel',
+    desc: 'Horizontal scrollable reel with snap points.',
+    snippet: `<layout-reel>
+  <article>1</article> <article>2</article> <article>3</article>
+</layout-reel>`,
+    render: () => el('layout-reel', {}, [box('1', 'reel'), box('2', 'reel'), box('3', 'reel'), box('4', 'reel'), box('5', 'reel'), box('6', 'reel')]),
+  },
+  {
+    name: 'layout-sidebar',
+    desc: 'Sidebar + main split that collapses to a stack on narrow viewports.',
+    snippet: `<layout-sidebar>
+  <aside>Side</aside>
+  <main>Main</main>
+</layout-sidebar>`,
+    render: () => el('layout-sidebar', {}, [
+      el('aside', { style: 'background: var(--color-surface-sunken, oklch(94% 0 0)); padding: var(--size-2xs)' }, ['Side']),
+      el('main', {}, [box('Main')]),
+    ]),
+  },
+  {
+    name: 'layout-switcher',
+    desc: 'Container that switches from a row to a stack at a configurable threshold.',
+    snippet: `<layout-switcher data-layout-threshold="30rem">
+  <div>One</div> <div>Two</div>
+</layout-switcher>`,
+    render: () => el('layout-switcher', { 'data-layout-threshold': '20rem' }, [box('One'), box('Two')]),
+  },
+  {
+    name: 'layout-text',
+    desc: 'Constrains line length to a readable measure (~60ch).',
+    snippet: `<layout-text>
+  <p>Constrained-measure prose for comfortable reading.</p>
+</layout-text>`,
+    render: () => el('layout-text', {}, [
+      el('p', { style: 'margin: 0; font-size: 0.85em' }, ['This paragraph is constrained to a comfortable reading measure (~60ch) regardless of the parent width.']),
+    ]),
+  },
+];
+
+// ── Tiny element-builder helper (no JSX, no template literal HTML parsing) ────
+
+function el(tag, attrs = {}, children = []) {
+  const node = document.createElement(tag);
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v == null) continue;
+    if (k === 'style') node.setAttribute('style', v);
+    else node.setAttribute(k, v === true ? '' : String(v));
+  }
+  for (const c of children) {
+    if (typeof c === 'string') node.appendChild(document.createTextNode(c));
+    else if (c) node.appendChild(c);
+  }
+  return node;
+}
+
+function box(label, variant) {
+  const b = el('div', { class: `ls-box${variant ? ` ls-box-${variant}` : ''}` }, [label]);
+  return b;
+}
+
+function chip(label) {
+  return el('span', { class: 'ls-chip' }, [label]);
+}
+
+class LayoutSpecimen extends VBElement {
+  setup() {
+    const only = this.getAttribute('data-only');
+    const allowed = only ? new Set(only.split(',').map((s) => s.trim())) : null;
+    const list = PRIMITIVES.filter((p) => !allowed || allowed.has(p.name) || allowed.has(p.name.replace(/^layout-/, '')));
+
+    this.replaceChildren();
+    for (const prim of list) {
+      this.appendChild(this.#renderEntry(prim));
+    }
+  }
+
+  #renderEntry(prim) {
+    const section = el('section', { class: 'ls-entry' });
+
+    const head = el('header', { class: 'ls-entry-head' }, [
+      el('h3', { class: 'ls-entry-name' }, [prim.name]),
+      el('p', { class: 'ls-entry-desc' }, [prim.desc]),
+    ]);
+
+    const live = el('div', { class: 'ls-live' });
+    live.appendChild(prim.render());
+
+    const code = el('pre', { class: 'ls-snippet' }, [el('code', {}, [prim.snippet])]);
+
+    section.append(head, live, code);
+    return section;
+  }
+}
+
+registerComponent('layout-specimen', LayoutSpecimen);
+
+export { LayoutSpecimen };

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

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>layout-specimen demo</title>
+  <link rel="stylesheet" href="/src/main.css">
+  <style>
+    body { font-family: system-ui, sans-serif; max-inline-size: 56rem; margin-inline: auto; padding: 2rem 1rem; line-height: 1.5; }
+  </style>
+</head>
+<body>
+  <h1>layout-specimen</h1>
+  <p>All 14 VB layout primitives at a glance.</p>
+  <layout-specimen></layout-specimen>
+
+  <h2>Subset (cluster + grid + stack only)</h2>
+  <layout-specimen data-only="cluster,grid,stack"></layout-specimen>
+
+  <script type="module" src="/src/main.js"></script>
+</body>
+</html>

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

@@ -0,0 +1,95 @@
+/* --------------------------------------------------------------------------
+   layout-specimen: visual showcase of VB layout primitives for docs.
+   -------------------------------------------------------------------------- */
+
+layout-specimen {
+  display: flex;
+  flex-direction: column;
+  gap: var(--size-l, 1.5rem);
+  font: inherit;
+}
+
+layout-specimen .ls-entry {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: var(--size-s, 0.75rem);
+  padding: var(--size-s, 0.75rem);
+  border: var(--border-width-thin, 1px) solid var(--color-border, #ddd);
+  border-radius: var(--radius-m, 0.5rem);
+  background: var(--color-surface, #fff);
+}
+
+layout-specimen .ls-entry-head {
+  display: flex;
+  flex-direction: column;
+  gap: var(--size-3xs, 0.125rem);
+}
+
+layout-specimen .ls-entry-name {
+  margin: 0;
+  font-size: 1em;
+  font-family: var(--font-mono, ui-monospace, monospace);
+  color: var(--color-text, #1a1a1a);
+}
+
+layout-specimen .ls-entry-desc {
+  margin: 0;
+  font-size: 0.875em;
+  color: var(--color-text-muted, currentColor);
+}
+
+layout-specimen .ls-live {
+  padding: var(--size-s, 0.75rem);
+  background: var(--color-surface-sunken, oklch(94% 0 0));
+  border-radius: var(--radius-s, 0.25rem);
+  min-block-size: 4rem;
+}
+
+layout-specimen .ls-snippet {
+  margin: 0;
+  padding: var(--size-2xs, 0.375rem) var(--size-s, 0.5rem);
+  background: var(--color-surface-sunken, oklch(94% 0 0));
+  border-radius: var(--radius-s, 0.25rem);
+  font-size: 0.8em;
+  line-height: 1.4;
+  font-family: var(--font-mono, ui-monospace, monospace);
+  color: var(--color-text, #1a1a1a);
+  overflow-x: auto;
+  white-space: pre;
+}
+
+/* -------- Mini-example placeholder boxes -------- */
+
+layout-specimen .ls-box {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--size-xs, 0.5rem);
+  background: var(--color-action-subtle, color-mix(in oklch, var(--color-interactive, oklch(55% 0.2 260)) 15%, transparent));
+  color: var(--color-text, #1a1a1a);
+  border: var(--border-width-thin, 1px) solid var(--color-interactive, currentColor);
+  border-radius: var(--radius-s, 0.25rem);
+  font-size: 0.85em;
+  font-weight: 500;
+  min-block-size: 2rem;
+}
+
+layout-specimen .ls-box-main {
+  background: var(--color-surface, #fff);
+  border-style: dashed;
+}
+
+layout-specimen .ls-box-reel {
+  inline-size: 5rem;
+  flex-shrink: 0;
+}
+
+layout-specimen .ls-chip {
+  display: inline-flex;
+  align-items: center;
+  padding: var(--size-3xs, 0.125rem) var(--size-2xs, 0.375rem);
+  background: var(--color-surface-raised, var(--color-surface, #fff));
+  border: var(--border-width-thin, 1px) solid var(--color-border, #ddd);
+  border-radius: var(--radius-full, 999px);
+  font-size: 0.85em;
+}

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

@@ -0,0 +1,54 @@
+{
+  "$schema": "../../../schemas/api.schema.json",
+  "element": "motion-specimen",
+  "type": "web-component",
+  "description": "Design token motion scale display. Shows easing curves with animated preview dots and/or durations as bars.",
+  "attributes": [
+    {
+      "name": "type",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "enum",
+      "values": ["easing", "duration", "both"],
+      "default": "easing",
+      "description": "Which motion tokens to display."
+    },
+    {
+      "name": "tokens",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Comma-separated token names (defaults vary by type)."
+    },
+    {
+      "name": "prefix",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "CSS variable prefix. Auto-set to --ease- or --duration- from type."
+    },
+    {
+      "name": "duration",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "default": "1.2s",
+      "description": "Animation duration for easing previews (only applies to easing rows)."
+    },
+    {
+      "name": "show-values",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "boolean",
+      "default": "true",
+      "description": "Show computed token values."
+    },
+    {
+      "name": "label",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Optional heading label."
+    }
+  ]
+}