@invisibleloop/pulse 0.1.21

package/docs/src/pages/components/timeline.js

@@ -0,0 +1,227 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { timeline, timelineItem, badge, card, stat, button } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/timeline')
+
+// Shared check SVG for reuse
+const checkIcon = `<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>`
+const starIcon  = `<svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/></svg>`
+const alertIcon = `<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><line x1="12" y1="8" x2="12" y2="12"/><line x1="12" y1="16" x2="12.01" y2="16"/></svg>`
+
+export default {
+  route: '/components/timeline',
+  meta: {
+    title: 'Timeline — Pulse Docs',
+    description: 'Timeline component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/timeline',
+    prev,
+    next,
+    name: 'timeline',
+    description: 'Ordered sequence of events or steps connected by a line. Supports vertical (default) and horizontal orientations. Each item accepts a raw HTML content slot — pass any text, component, or markup.',
+    content: `
+
+      <h2 class="doc-h2" id="vertical">Vertical (default)</h2>
+      <p>Steps flow downward. The connector line links each dot to the next.</p>
+      ${demo(
+        timeline({
+          items: [
+            { label: 'Jan 2023', content: '<strong style="color:var(--ui-text)">Project kicked off</strong><p style="color:var(--ui-muted);margin:.25rem 0 0">Initial scope agreed with stakeholders. Repository created.</p>' },
+            { label: 'Mar 2023', content: '<strong style="color:var(--ui-text)">Alpha release</strong><p style="color:var(--ui-muted);margin:.25rem 0 0">Internal testing with 12 pilot users. Core features stable.</p>' },
+            { label: 'Jun 2023', content: '<strong style="color:var(--ui-text)">Public beta</strong><p style="color:var(--ui-muted);margin:.25rem 0 0">Open sign-up enabled. 400 users in first week.</p>' },
+            { label: 'Sep 2023', content: '<strong style="color:var(--ui-text)">v1.0 launched</strong><p style="color:var(--ui-muted);margin:.25rem 0 0">Billing live, docs published, ProductHunt launch.</p>' },
+          ],
+        }),
+        `timeline({
+  items: [
+    { label: 'Jan 2023', content: '<strong>Project kicked off</strong><p>Initial scope agreed.</p>' },
+    { label: 'Mar 2023', content: '<strong>Alpha release</strong><p>Internal testing with 12 pilot users.</p>' },
+    { label: 'Jun 2023', content: '<strong>Public beta</strong><p>Open sign-up enabled. 400 users in first week.</p>' },
+    { label: 'Sep 2023', content: '<strong>v1.0 launched</strong><p>Billing live, docs published.</p>' },
+  ],
+})`
+      )}
+
+      <h2 class="doc-h2" id="horizontal">Horizontal</h2>
+      <p>Steps flow left to right — good for process flows or numbered stages.</p>
+      ${demo(
+        timeline({
+          direction: 'horizontal',
+          items: [
+            { label: 'Step 1', content: '<p style="color:var(--ui-muted);margin:0;font-size:.85rem">Sign up</p>' },
+            { label: 'Step 2', content: '<p style="color:var(--ui-muted);margin:0;font-size:.85rem">Connect data</p>' },
+            { label: 'Step 3', content: '<p style="color:var(--ui-muted);margin:0;font-size:.85rem">Invite team</p>' },
+            { label: 'Step 4', content: '<p style="color:var(--ui-muted);margin:0;font-size:.85rem">Go live</p>' },
+          ],
+        }),
+        `timeline({
+  direction: 'horizontal',
+  items: [
+    { label: 'Step 1', content: '<p>Sign up</p>'      },
+    { label: 'Step 2', content: '<p>Connect data</p>' },
+    { label: 'Step 3', content: '<p>Invite team</p>'  },
+    { label: 'Step 4', content: '<p>Go live</p>'      },
+  ],
+})`
+      )}
+
+      <h2 class="doc-h2" id="dot-colors">Dot colours</h2>
+      <p>Use <code>dotColor</code> to convey status: <code>'accent'</code> · <code>'success'</code> · <code>'warning'</code> · <code>'error'</code> · <code>'muted'</code>.</p>
+      ${demo(
+        timeline({
+          items: [
+            { dotColor: 'success', label: 'Deployed',  content: '<p style="color:var(--ui-muted);margin:0">Production deploy completed successfully.</p>' },
+            { dotColor: 'success', label: 'Tested',    content: '<p style="color:var(--ui-muted);margin:0">All 92 tests passed. Coverage 98%.</p>' },
+            { dotColor: 'warning', label: 'Review',    content: '<p style="color:var(--ui-muted);margin:0">Awaiting sign-off from design lead.</p>' },
+            { dotColor: 'error',   label: 'Blocked',   content: '<p style="color:var(--ui-muted);margin:0">Dependency on payment API not yet ready.</p>' },
+            { dotColor: 'muted',   label: 'Planned',   content: '<p style="color:var(--ui-muted);margin:0">Mobile app release — Q1 2025.</p>' },
+          ],
+        }),
+        `timeline({
+  items: [
+    { dotColor: 'success', label: 'Deployed', content: '...' },
+    { dotColor: 'success', label: 'Tested',   content: '...' },
+    { dotColor: 'warning', label: 'Review',   content: '...' },
+    { dotColor: 'error',   label: 'Blocked',  content: '...' },
+    { dotColor: 'muted',   label: 'Planned',  content: '...' },
+  ],
+})`
+      )}
+
+      <h2 class="doc-h2" id="icon-dots">Icon dots</h2>
+      <p>Pass any SVG or emoji as <code>dot</code>. The dot grows to accommodate the content and uses a tinted background matching its colour variant.</p>
+      ${demo(
+        timeline({
+          items: [
+            { dot: checkIcon, dotColor: 'success', label: 'Completed', content: '<strong style="color:var(--ui-text)">Onboarding</strong><p style="color:var(--ui-muted);margin:.2rem 0 0">Profile set up, preferences saved.</p>' },
+            { dot: starIcon,  dotColor: 'accent',  label: 'Milestone', content: '<strong style="color:var(--ui-text)">First 1,000 users</strong><p style="color:var(--ui-muted);margin:.2rem 0 0">Reached organically in 18 days.</p>' },
+            { dot: alertIcon, dotColor: 'warning', label: 'Incident',  content: '<strong style="color:var(--ui-text)">Partial outage</strong><p style="color:var(--ui-muted);margin:.2rem 0 0">CDN edge node failed — resolved in 4 minutes.</p>' },
+          ],
+        }),
+        `timeline({
+  items: [
+    {
+      dot:      checkSvg,
+      dotColor: 'success',
+      label:    'Completed',
+      content:  '<strong>Onboarding</strong><p>Profile set up, preferences saved.</p>',
+    },
+    {
+      dot:      starSvg,
+      dotColor: 'accent',
+      label:    'Milestone',
+      content:  '<strong>First 1,000 users</strong>',
+    },
+  ],
+})`
+      )}
+
+      <h2 class="doc-h2" id="rich-content">Rich content slot</h2>
+      <p>The <code>content</code> slot accepts any HTML — including other Pulse components like <code>card()</code>, <code>badge()</code>, or <code>stat()</code>.</p>
+      ${demo(
+        timeline({
+          items: [
+            {
+              dotColor: 'success',
+              label: 'Q1 2024',
+              content: card({
+                title: 'Series A closed',
+                content: `<div style="display:flex;gap:1.5rem;flex-wrap:wrap">` +
+                  stat({ label: 'Raised',    value: '$4.2M' }) +
+                  stat({ label: 'Valuation', value: '$18M'  }) +
+                  stat({ label: 'Investors', value: '6'     }) +
+                `</div>`,
+              }),
+            },
+            {
+              dotColor: 'accent',
+              label: 'Q3 2024',
+              content: card({
+                title: 'Product launch',
+                content: `<p style="color:var(--ui-muted);margin:0 0 .75rem">Shipped v1.0 to general availability. Three tiers, 14-day trial.</p>` +
+                  `<div style="display:flex;gap:.5rem;flex-wrap:wrap">` +
+                  badge({ label: 'Launch', variant: 'info'    }) +
+                  badge({ label: 'Billing live', variant: 'success' }) +
+                  `</div>`,
+              }),
+            },
+            {
+              dotColor: 'muted',
+              label: 'Q1 2025 (planned)',
+              content: card({
+                title: 'Mobile apps',
+                content: `<p style="color:var(--ui-muted);margin:0 0 .75rem">iOS and Android apps in development. Public beta planned.</p>` +
+                  button({ label: 'Join waitlist', size: 'sm', variant: 'secondary' }),
+              }),
+            },
+          ],
+        }),
+        `timeline({
+  items: [
+    {
+      dotColor: 'success',
+      label:    'Q1 2024',
+      content:  card({
+        title:   'Series A closed',
+        content: stat({ label: 'Raised', value: '$4.2M' }) + ...,
+      }),
+    },
+    {
+      dotColor: 'accent',
+      label:    'Q3 2024',
+      content:  card({
+        title:   'Product launch',
+        content: '<p>Shipped v1.0 to general availability.</p>' +
+                 badge({ label: 'Billing live', variant: 'success' }),
+      }),
+    },
+  ],
+})`
+      )}
+
+      <h2 class="doc-h2" id="item-fn">Using timelineItem()</h2>
+      <p>Build items individually with <code>timelineItem()</code> and pass the joined HTML as <code>content</code>. Useful for dynamic or conditional lists.</p>
+      ${demo(
+        timeline({
+          content:
+            timelineItem({ dotColor: 'success', label: 'Done',    content: '<p style="color:var(--ui-muted);margin:0">Design system tokens agreed</p>' }) +
+            timelineItem({ dotColor: 'success', label: 'Done',    content: '<p style="color:var(--ui-muted);margin:0">Component library built</p>' }) +
+            timelineItem({ dotColor: 'accent',  label: 'Current', content: '<p style="color:var(--ui-muted);margin:0">Documentation in progress</p>' }) +
+            timelineItem({ dotColor: 'muted',   label: 'Next',    content: '<p style="color:var(--ui-muted);margin:0">Public launch</p>' }),
+        }),
+        `timeline({
+  content:
+    timelineItem({ dotColor: 'success', label: 'Done',    content: '...' }) +
+    timelineItem({ dotColor: 'success', label: 'Done',    content: '...' }) +
+    timelineItem({ dotColor: 'accent',  label: 'Current', content: '...' }) +
+    timelineItem({ dotColor: 'muted',   label: 'Next',    content: '...' }),
+})`
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>direction</code>', 'string', "'vertical'", "'vertical' · 'horizontal'"],
+          ['<code>items</code>',     'array',  '[]',         'Array of <code>timelineItem</code> option objects'],
+          ['<code>content</code>',   'string (HTML)', '—',   'Raw HTML alternative to <code>items</code> — use with <code>timelineItem()</code>'],
+        ]
+      )}
+
+      <h3 class="doc-h3" style="margin-top:2rem">timelineItem() props</h3>
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>content</code>',  'string (HTML)', '—',        'Raw HTML body — accepts any component output'],
+          ['<code>label</code>',    'string',        '—',        'Timestamp or step label (escaped)'],
+          ['<code>dot</code>',      'string (HTML)', '—',        'Raw HTML inside the dot — SVG or emoji; grows the dot to 2rem'],
+          ['<code>dotColor</code>', 'string',        "'accent'", "'accent' · 'success' · 'warning' · 'error' · 'muted'"],
+        ]
+      )}
+    `,
+  }),
+}

package/docs/src/pages/components/toggle.js

@@ -0,0 +1,84 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table, callout } from '../../lib/layout.js'
+import { toggle, stack } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/toggle')
+
+export default {
+  route: '/components/toggle',
+  meta: {
+    title: 'Toggle — Pulse Docs',
+    description: 'iOS-style switch toggle component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/toggle',
+    prev,
+    next,
+    name: 'toggle',
+    description: 'iOS-style switch that renders a visually hidden <code>&lt;input type="checkbox"&gt;</code> with a custom track and thumb. No JavaScript required — state is read from FormData on submission.',
+    content: `
+
+      <h2 class="doc-h2" id="default">Default</h2>
+      ${demo(
+        stack({ gap: 'md', content:
+          toggle({ name: 'notifications', label: 'Email notifications' }) +
+          toggle({ name: 'updates',       label: 'Product updates', checked: true }),
+        }),
+        `toggle({ name: 'notifications', label: 'Email notifications' })
+toggle({ name: 'updates',       label: 'Product updates', checked: true })`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="hint">With hint</h2>
+      <p>Use <code>hint</code> to add supporting text below the switch.</p>
+      ${demo(
+        stack({ gap: 'lg', content:
+          toggle({ name: 'marketing', label: 'Marketing emails', hint: 'Receive tips, product news, and special offers.' }) +
+          toggle({ name: 'digest',    label: 'Weekly digest',    hint: 'A summary of activity sent every Monday morning.', checked: true }),
+        }),
+        `toggle({
+  name:    'marketing',
+  label:   'Marketing emails',
+  hint:    'Receive tips, product news, and special offers.',
+})
+toggle({
+  name:    'digest',
+  label:   'Weekly digest',
+  hint:    'A summary of activity sent every Monday morning.',
+  checked: true,
+})`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="disabled">Disabled</h2>
+      ${demo(
+        stack({ gap: 'md', content:
+          toggle({ name: 'a', label: 'Off and disabled',  disabled: true }) +
+          toggle({ name: 'b', label: 'On and disabled',   disabled: true, checked: true }),
+        }),
+        `toggle({ name: 'a', label: 'Off and disabled', disabled: true })
+toggle({ name: 'b', label: 'On and disabled',  disabled: true, checked: true })`,
+        { col: true }
+      )}
+
+      <h2 class="doc-h2" id="in-forms">In forms</h2>
+      ${callout('note', 'The switch submits as <code>\'on\'</code> under its <code>name</code> when checked. When unchecked, the field is absent from FormData entirely — the same behaviour as a native checkbox. Read it with <code>formData.get(\'name\') === \'on\'</code>.')}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>name</code>',     'string',  '—',     'Field name — submitted in FormData'],
+          ['<code>label</code>',    'string',  '—',     'Visible label text'],
+          ['<code>checked</code>',  'boolean', 'false', 'Initial on/off state'],
+          ['<code>disabled</code>', 'boolean', 'false', ''],
+          ['<code>hint</code>',     'string',  '—',     'Helper text below the switch'],
+          ['<code>id</code>',       'string',  '—',     'Override the generated <code>id</code>'],
+          ['<code>class</code>',    'string',  '—',     ''],
+        ]
+      )}
+    `,
+  }),
+}

package/docs/src/pages/components/tooltip.js

@@ -0,0 +1,48 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { tooltip, button, cluster } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/tooltip')
+
+export default {
+  route: '/components/tooltip',
+  meta: {
+    title: 'Tooltip — Pulse Docs',
+    description: 'Tooltip component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/tooltip',
+    prev,
+    next,
+    name: 'tooltip',
+    description: 'CSS-powered tooltip that wraps any element. No JavaScript required — the bubble appears on hover and <code>:focus-within</code>. Supports four placements.',
+    content: `
+      ${demo(
+        cluster({ gap: 'lg', justify: 'center', content:
+          tooltip({ content: 'This appears on top',    position: 'top',    trigger: button({ label: 'Top',    variant: 'secondary' }) }) +
+          tooltip({ content: 'This appears below',     position: 'bottom', trigger: button({ label: 'Bottom', variant: 'secondary' }) }) +
+          tooltip({ content: 'This appears to the left',  position: 'left',   trigger: button({ label: 'Left',   variant: 'secondary' }) }) +
+          tooltip({ content: 'This appears to the right', position: 'right',  trigger: button({ label: 'Right',  variant: 'secondary' }) }),
+        }),
+        `tooltip({
+  content:  'This appears on top',
+  position: 'top',       // top | bottom | left | right
+  trigger:  button({ label: 'Hover me', variant: 'secondary' }),
+})`
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', ''],
+        [
+          ['<code>content</code>',  'string',                          '—',       'Tooltip text (plain text only)'],
+          ['<code>trigger</code>',  'string (HTML)',                   '—',       'Raw HTML slot — the element the tooltip wraps'],
+          ['<code>position</code>', '<code>top | bottom | left | right</code>', '<code>top</code>', ''],
+          ['<code>class</code>',    'string',                          '—',       ''],
+        ]
+      )}
+    `,
+  }),
+}

package/docs/src/pages/components.js

@@ -0,0 +1,204 @@
+import { renderLayout, h1, lead, section, codeBlock, callout, table } from '../lib/layout.js'
+import { prevNext } from '../lib/nav.js'
+import { highlight } from '../lib/highlight.js'
+
+const { prev, next } = prevNext('/components')
+
+export default {
+  route: '/components',
+  meta: {
+    title: 'Component Library — Pulse Docs',
+    description: 'Server-rendered UI components for Pulse — button, card, input, alert, stat, avatar, table and more. Fully accessible, mobile-ready, zero client JS.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderLayout({
+    currentHref: '/components',
+    prev,
+    next,
+    content: `
+      ${h1('Component Library')}
+      ${lead('Server-rendered building blocks. Each component is a pure function that returns an HTML string — no client-side JS, no build step, accessible and mobile-ready by default. The output is the same every time the same props are passed.')}
+
+      ${section('setup', 'Setup')}
+      <p>Components are imported directly into the spec file alongside the stylesheet reference in <code>meta.styles</code>. No build step, no registration.</p>
+      ${codeBlock(highlight(`import { button, card, input } from '@invisibleloop/pulse/ui'
+import { escHtml }          from '@invisibleloop/pulse/html'
+
+export default {
+  route: '/example',
+  meta: {
+    title:  'Example',
+    styles: ['/pulse-ui.css', '/app.css'],
+  },
+  view: () => \`
+    <main id="main-content">
+      \${card({
+        title:   'Welcome',
+        content: button({ label: 'Get started', href: '/start' }),
+      })}
+    </main>
+  \`,
+}`, 'js'))}
+
+      ${section('theming', 'Theming')}
+      <p>All visual values flow through CSS custom properties. Override any <code>--ui-*</code> token in <code>:root</code> in your <code>app.css</code> to retheme the entire library at once.</p>
+      ${codeBlock(highlight(`/* app.css */
+:root {
+  --ui-accent:       #6366f1;
+  --ui-accent-hover: #818cf8;
+  --ui-accent-dim:   rgba(99, 102, 241, .12);
+  --ui-radius:       6px;
+  --ui-bg:           #ffffff;
+  --ui-surface:      #f9fafb;
+  --ui-text:         #111827;
+  --ui-muted:        #6b7280;
+  --ui-border:       #e5e7eb;
+}`, 'css'))}
+      <p>New variants follow the <code>ui-btn--{name}</code> CSS modifier pattern. A brand-coloured button, for example, is just a new class in <code>app.css</code> — the component itself stays untouched.</p>
+      ${codeBlock(highlight(`.ui-btn--brand {
+  background: var(--brand);
+  color:      #fff;
+  border:     none;
+}
+.ui-btn--brand:hover:not(.ui-btn--disabled) {
+  background: var(--brand-hover);
+}`, 'css'))}
+
+      ${section('components', 'Components')}
+      <p>Each component has its own page with full demos, code examples, and a props reference.</p>
+
+      <h3 class="doc-h3">UI</h3>
+      ${table(
+        ['Component', 'Description'],
+        [
+          ['<a href="/components/button">button</a>',   'Renders as <code>&lt;button&gt;</code> or <code>&lt;a&gt;</code>. Four variants, three sizes.'],
+          ['<a href="/components/badge">badge</a>',     'Inline status label. Five semantic colour variants.'],
+          ['<a href="/components/card">card</a>',       'Content surface with title, body, and optional footer.'],
+          ['<a href="/components/input">input</a>',       'Labelled text input with hint and error support.'],
+          ['<a href="/components/fieldset">fieldset</a>', 'Semantic grouping of related fields with an accessible legend.'],
+          ['<a href="/components/select">select</a>',     'Styled select with option groups and current-value support.'],
+          ['<a href="/components/textarea">textarea</a>', 'Multi-line input with label, hint, and error.'],
+          ['<a href="/components/alert">alert</a>',     'Inline feedback banner. ARIA roles wired by variant.'],
+          ['<a href="/components/stat">stat</a>',       'Numeric metric with optional trend arrow.'],
+          ['<a href="/components/avatar">avatar</a>',   'User avatar — image with fallback to initials.'],
+          ['<a href="/components/empty">empty</a>',     'Empty state with title, description, and optional CTA.'],
+          ['<a href="/components/table">table</a>',     'Accessible data table with scroll wrapper.'],
+        ]
+      )}
+
+      <h3 class="doc-h3">Landing page</h3>
+      ${table(
+        ['Component', 'Description'],
+        [
+          ['<a href="/components/nav">nav</a>',               'Site header with logo, links, and optional CTA.'],
+          ['<a href="/components/hero">hero</a>',             'Full-width hero section with eyebrow, title, and actions.'],
+          ['<a href="/components/app-badge">appBadge</a>',    'App Store / Google Play download badge.'],
+          ['<a href="/components/feature">feature</a>',       'Icon + title + description block for feature grids.'],
+          ['<a href="/components/testimonial">testimonial</a>', 'Customer quote with avatar and star rating.'],
+          ['<a href="/components/pricing">pricing</a>',       'Plan card with feature list and CTA. Supports highlighted state.'],
+          ['<a href="/components/accordion">accordion</a>',   'Collapsible FAQ items — no JS, native <code>&lt;details&gt;</code>.'],
+          ['<a href="/components/cta">cta</a>',               'Call-to-action block with eyebrow, heading, body, and actions slot.'],
+        ]
+      )}
+
+      <h3 class="doc-h3">Layout</h3>
+      ${table(
+        ['Component', 'Description'],
+        [
+          ['<a href="/components/container">container</a>', 'Max-width wrapper with horizontal padding.'],
+          ['<a href="/components/section">section</a>',     'Vertical padding block with background variant.'],
+          ['<a href="/components/grid">grid</a>',           'Responsive CSS grid. Collapses to one column on mobile.'],
+          ['<a href="/components/stack">stack</a>',         'Flex column with consistent vertical gap.'],
+          ['<a href="/components/cluster">cluster</a>',     'Flex row with wrapping — for badges, buttons, etc.'],
+          ['<a href="/components/divider">divider</a>',     'Horizontal rule, optionally with centred label.'],
+          ['<a href="/components/banner">banner</a>',       'Full-width announcement bar above the nav.'],
+          ['<a href="/components/media">media</a>',             'Two-column image + text layout, stacks on mobile.'],
+          ['<a href="/components/code-window">codeWindow</a>', 'macOS window chrome around a code block. Accepts pre-highlighted HTML.'],
+          ['<a href="/components/footer">footer</a>',          'Site footer with logo, nav links, and legal text. Stacks on mobile.'],
+        ]
+      )}
+
+      ${section('utilities', 'Utility classes')}
+      <p><code>pulse-ui.css</code> ships a utility layer (prefix <code>u-</code>) for common spacing, typography, and layout needs. Reach for these before writing custom CSS — they use the same <code>--ui-*</code> tokens as components so theme overrides apply everywhere.</p>
+
+      <h3 class="doc-h3">Spacing</h3>
+      <p>Scale: 1=4px 2=8px 3=12px 4=16px 5=20px 6=24px 8=32px 10=40px 12=48px 16=64px</p>
+      ${table(
+        ['Class', 'Property'],
+        [
+          ['<code>u-mt-{0–16}</code>', 'margin-top'],
+          ['<code>u-mb-{0–16}</code>', 'margin-bottom'],
+          ['<code>u-mx-auto</code>', 'margin-left + right: auto'],
+          ['<code>u-p-{0–8}</code>', 'padding (all sides)'],
+          ['<code>u-px-{0–8}</code>', 'padding-left + right'],
+          ['<code>u-py-{0–8}</code>', 'padding-top + bottom'],
+        ]
+      )}
+
+      <h3 class="doc-h3">Typography</h3>
+      ${table(
+        ['Class', 'Effect'],
+        [
+          ['<code>u-text-{xs,sm,base,lg,xl,2xl,3xl,4xl}</code>', 'Font size + matching line-height'],
+          ['<code>u-font-{normal,medium,semibold,bold}</code>', 'Font weight'],
+          ['<code>u-text-{left,center,right}</code>', 'Text alignment'],
+          ['<code>u-text-{default,muted,accent,green,red,yellow,blue}</code>', 'Token colour'],
+          ['<code>u-leading-{tight,snug,normal,relaxed,loose}</code>', 'Line height'],
+        ]
+      )}
+
+      <h3 class="doc-h3">Layout</h3>
+      ${table(
+        ['Class', 'Effect'],
+        [
+          ['<code>u-flex</code> / <code>u-flex-col</code>', 'Flex row or column'],
+          ['<code>u-items-{start,center,end,stretch}</code>', 'align-items'],
+          ['<code>u-justify-{start,center,end,between}</code>', 'justify-content'],
+          ['<code>u-gap-{1–8}</code>', 'gap'],
+          ['<code>u-w-full</code>', 'width: 100%'],
+          ['<code>u-max-w-{xs,sm,md,lg,xl,prose}</code>', 'max-width (320px–1024px, 65ch)'],
+          ['<code>u-hidden</code> / <code>u-block</code> / <code>u-inline-block</code>', 'display'],
+        ]
+      )}
+
+      <h3 class="doc-h3">Visual</h3>
+      ${table(
+        ['Class', 'Effect'],
+        [
+          ['<code>u-rounded</code> / <code>u-rounded-md</code> / <code>u-rounded-lg</code> / <code>u-rounded-full</code>', 'border-radius'],
+          ['<code>u-border</code> / <code>u-border-t</code> / <code>u-border-b</code>', '1px solid --ui-border'],
+          ['<code>u-bg-surface</code> / <code>u-bg-surface2</code> / <code>u-bg-accent</code>', 'background token'],
+          ['<code>u-overflow-hidden</code> / <code>u-overflow-auto</code>', 'overflow'],
+          ['<code>u-opacity-50</code> / <code>u-opacity-75</code>', 'opacity'],
+        ]
+      )}
+
+      <p>Utilities compose naturally with components and with each other:</p>
+      ${codeBlock(highlight(`<!-- centred hero block — no custom CSS needed -->
+<div class="u-flex u-flex-col u-items-center u-text-center u-py-16 u-gap-4">
+  <h1 class="u-text-4xl u-font-bold">Hello</h1>
+  <p class="u-text-lg u-text-muted u-max-w-prose">Subtitle goes here.</p>
+  \${button({ label: 'Get started', href: '/start' })}
+</div>`, 'html'))}
+
+      ${callout('note', 'Never use inline <code>style=""</code> attributes. Reach for utility classes first, and only add to <code>app.css</code> when you need something utilities cannot provide — a unique animation, a custom grid, or a one-off component variant.')}
+
+      ${section('composing', 'Composing components')}
+      <p>Components compose naturally — pass the output of one as the <code>content</code> or <code>footer</code> of another. Here's a stat dashboard card:</p>
+      ${codeBlock(highlight(`import { card, stat, button } from '@invisibleloop/pulse/ui'
+
+card({
+  title:   'This week',
+  content: \`
+    \${stat({ label: 'Page views', value: '48,291', change: '+12%', trend: 'up' })}
+    \${stat({ label: 'New users',  value: '1,042',  change: '+4%',  trend: 'up' })}
+    \${stat({ label: 'Bounced',    value: '22%',    change: '+1%',  trend: 'down' })}
+  \`,
+  footer: button({ label: 'View full report', href: '/analytics', variant: 'ghost', size: 'sm' }),
+})`, 'js'))}
+
+      ${callout('note', 'Text props like <code>label</code>, <code>title</code>, <code>value</code>, and <code>error</code> are escaped automatically. <code>content</code>, <code>footer</code>, <code>rows</code>, <code>actions</code>, <code>icon</code>, <code>action</code>, and <code>logo</code> are raw HTML slots — they pass through as-is, so any user-supplied data going into those slots should go through <code>escHtml()</code> first.')}
+    `,
+  }),
+}