@invisibleloop/pulse 0.9.0 → 0.10.0

package/docs/.claude/pulse-checklist.md

@@ -130,3 +130,14 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 - Interactive elements without visible text have an `aria-label`.
 - Disabled state is reflected with the `disabled` attribute, not just CSS.
 - The page has a `<main id="main-content">` landmark.
+- **Every element with `data-event`, `data-store-event`, `data-dialog-open`, or `data-dialog-close` is natively interactive (`button`, `a`, `input`, `select`, `textarea`, `summary`) or has `tabindex="0"`.** Non-interactive tags (`div`, `span`, `li`, `td`, etc.) with these attributes are not keyboard reachable. Prefer `<button>` — it is focusable, fires on Enter/Space, and carries the correct ARIA role for free. Only use `tabindex="0"` on a non-interactive element when a `<button>` genuinely cannot be used.
+- **Every interactive element communicates its purpose and state:**
+  - Buttons have visible text or `aria-label`. Links use descriptive text — "click here", "here", "read more" are failures.
+  - Form inputs have an associated `<label for="id">` or `aria-label`. `placeholder` alone is not a label.
+  - Toggle controls (open/close, show/hide, expand/collapse) carry `aria-expanded="true|false"` or `aria-pressed="true|false"`.
+  - While an action is in flight, the trigger button has `aria-busy="true"` or its label changes (e.g. "Saving…"). A spinner alone is not enough.
+  - Active nav items have `aria-current="page"`. Selected items in a list, tab set, or option group have `aria-selected="true"`.
+- **The page has a logical tab order:**
+  - No `tabindex` value greater than 0. Positive tabindex values override the natural DOM order and create a broken tab sequence. Remove them and reorder the DOM instead.
+  - Visually hidden interactive content (off-canvas menus, collapsed panels, `opacity:0` elements) is removed from the tab order with `tabindex="-1"` or the `inert` attribute — CSS alone does not remove an element from tab order.
+  - DOM order matches the visual reading order. When flexbox `order` or CSS grid placement visually reposition elements, the tab sequence still follows the DOM — author the DOM in the order a user would read and interact with the page.

package/docs/public/.pulse-ui-version

@@ -1 +1 @@
-0.8.1
+0.9.1

package/docs/public/docs.css

@@ -1160,6 +1160,18 @@ a:hover {
   width: 100%;
 }
 
+.demo-preview--bleed {
+  padding-inline: 0;
+}
+
+.demo-preview--bleed .demo-preview-inner {
+  gap: 0;
+}
+
+.demo-preview--bleed .demo-preview-inner > * {
+  width: 100%;
+}
+
 .demo-preview--col .demo-preview-inner {
   display: block;
 }

package/docs/public/menu.js

@@ -67,20 +67,30 @@
     input.style.setProperty('--slider-fill', pct)
   }
 
-  document.querySelectorAll('.ui-slider').forEach(function (input) {
-    input.addEventListener('input', function () { updateSliderFill(this) })
-  })
-
-  // ── Demo theme toggles ────────────────────────────────────────────────────
-  document.querySelectorAll('.demo-theme-toggle').forEach(function (toggle) {
-    var preview = toggle.closest('.demo-preview')
-    if (!preview) return
-    toggle.addEventListener('click', function () {
-      var isLight = preview.classList.toggle('is-light')
-      var inner   = preview.querySelector('.demo-preview-inner')
-      if (inner) {
-        inner.classList.toggle('ui-theme-light', isLight)
-      }
+  function bindDemoControls() {
+    document.querySelectorAll('.ui-slider').forEach(function (input) {
+      input.addEventListener('input', function () { updateSliderFill(this) })
     })
-  })
+
+    // ── Demo theme toggles ──────────────────────────────────────────────────
+    document.querySelectorAll('.demo-theme-toggle').forEach(function (toggle) {
+      var preview = toggle.closest('.demo-preview')
+      if (!preview) return
+      toggle.addEventListener('click', function () {
+        var isLight = preview.classList.toggle('is-light')
+        var inner   = preview.querySelector('.demo-preview-inner')
+        if (inner) {
+          inner.classList.toggle('ui-theme-light', isLight)
+        }
+      })
+    })
+  }
+
+  document.addEventListener('pulse:navigate', bindDemoControls)
+
+  if (document.readyState === 'complete') {
+    setTimeout(bindDemoControls, 50)
+  } else {
+    window.addEventListener('load', bindDemoControls)
+  }
 })()

package/docs/public/pulse-ui.css

@@ -24,7 +24,7 @@
   --ui-accent:       var(--accent,        #9b8dff);
   --ui-accent-hover: var(--accent-hover,  #b5aaff);
   --ui-accent-dim:   var(--accent-dim,    rgba(155,141,255,.12));
-  --ui-accent-text:  var(--accent-text,   #ffffff);
+  --ui-accent-text:  var(--accent-text,   #0d0a20);
   --ui-green:        var(--green,         #3dd68c);
   --ui-green-dim:    rgba(61, 214, 140, .12);
   --ui-red:          var(--red,           #ff6b6b);
@@ -525,6 +525,7 @@ html, body {
 .ui-stat-change--neutral { color: var(--ui-muted);  }
 
 .ui-stat--center { align-items: center; text-align: center; }
+.ui-stat--center .ui-stat-change { margin-inline: auto; }
 
 /* ─── Avatar ─────────────────────────────────────────────────────────────── */
 .ui-avatar {
@@ -758,11 +759,46 @@ hr.ui-divider {
 }
 
 /* ─── Hero ───────────────────────────────────────────────────────────────── */
-.ui-hero { padding: 5rem 1.5rem; text-align: center; }
+.ui-hero { padding: 5rem 0; text-align: center; }
 .ui-hero--left { text-align: left; }
 .ui-hero--sm   { padding-top: 2.5rem; padding-bottom: 0; }
+.ui-hero--gradient,
+.ui-hero--gradient--purple {
+  background:
+    radial-gradient(ellipse 70% 80% at 75% 50%, #2d1b6e 0%, #1a0f45 45%, transparent 75%),
+    radial-gradient(ellipse 60% 60% at 20% 80%, #1c1060 0%, transparent 65%),
+    #0d0a1e;
+}
+
+.ui-hero--gradient--blue {
+  background:
+    radial-gradient(ellipse 70% 80% at 75% 50%, #0e2d6b 0%, #071840 45%, transparent 75%),
+    radial-gradient(ellipse 60% 60% at 20% 80%, #0a1f5c 0%, transparent 65%),
+    #060d1e;
+}
+
+.ui-hero--gradient--green {
+  background:
+    radial-gradient(ellipse 70% 80% at 75% 50%, #0d3d28 0%, #052218 45%, transparent 75%),
+    radial-gradient(ellipse 60% 60% at 20% 80%, #083020 0%, transparent 65%),
+    #020e09;
+}
+
+.ui-hero--gradient--rose {
+  background:
+    radial-gradient(ellipse 70% 80% at 75% 50%, #6b0e35 0%, #400720 45%, transparent 75%),
+    radial-gradient(ellipse 60% 60% at 20% 80%, #5c0a2a 0%, transparent 65%),
+    #1e0610;
+}
+
+.ui-hero--gradient--orange {
+  background:
+    radial-gradient(ellipse 70% 80% at 75% 50%, #6b2e0e 0%, #401807 45%, transparent 75%),
+    radial-gradient(ellipse 60% 60% at 20% 80%, #5c2208 0%, transparent 65%),
+    #1e0e04;
+}
 
-.ui-hero-inner { max-width: 720px; margin: 0 auto; }
+.ui-hero-inner { max-width: 720px; margin: 0 auto; padding: 0 1.5rem; }
 .ui-hero--left .ui-hero-inner { margin: 0; }
 
 .ui-hero-eyebrow {
@@ -801,8 +837,9 @@ hr.ui-divider {
 /* Split (text + image) */
 .ui-hero--split { text-align: left; }
 .ui-hero--split .ui-hero-inner {
-  max-width: 1200px;
+  max-width: 1100px;
   margin: 0 auto;
+  padding: 0 1.5rem;
   display: grid;
   grid-template-columns: 1fr 1fr;
   gap: 3rem;
@@ -1425,7 +1462,8 @@ hr.ui-divider {
   .ui-media { grid-template-columns: 1fr; }
   .ui-media--reverse { direction: ltr; }
 
-  .ui-hero { padding: 3rem 1.25rem; }
+  .ui-hero { padding: 3rem 0; }
+  .ui-hero-inner { padding: 0 1.25rem; }
   .ui-hero-title { font-size: 2rem; }
   .ui-hero-subtitle { font-size: 1rem; }
   .ui-hero--split .ui-hero-inner { grid-template-columns: 1fr; }
@@ -1767,6 +1805,88 @@ hr.ui-divider {
 
 .ui-code-window-code { font-family: inherit; }
 
+/* ─── Phone Frame ────────────────────────────────────────────────────────────
+   Realistic CSS mobile phone frame — body, dynamic island, side buttons,
+   home indicator. Drop any HTML into the content slot.                       */
+.ui-phone {
+  position: relative;
+  display: inline-flex;
+  width: 260px;
+  background: linear-gradient(160deg, #1e1e28 0%, #141418 100%);
+  border-radius: 3rem;
+  border: 1.5px solid rgba(255, 255, 255, 0.1);
+  box-shadow:
+    0 0 0 1px rgba(0, 0, 0, 0.8),
+    0 2px 0 1px rgba(255, 255, 255, 0.05) inset,
+    0 48px 96px rgba(0, 0, 0, 0.55),
+    0 12px 32px rgba(0, 0, 0, 0.4);
+  padding: 12px;
+}
+
+/* Side buttons */
+.ui-phone-btn {
+  position: absolute;
+  background: linear-gradient(90deg, #1a1a22 0%, #26262e 100%);
+  border-radius: 2px;
+}
+.ui-phone-btn--mute     { left: -3px; top: 88px;  width: 3px; height: 28px; }
+.ui-phone-btn--vol-up   { left: -3px; top: 128px; width: 3px; height: 48px; }
+.ui-phone-btn--vol-down { left: -3px; top: 186px; width: 3px; height: 48px; }
+.ui-phone-btn--power    { right: -3px; top: 140px; width: 3px; height: 64px; }
+
+/* Phone inner — holds screen + chrome */
+.ui-phone-inner {
+  width: 100%;
+  background: #000;
+  border-radius: 2.5rem;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+}
+
+/* Dynamic island */
+.ui-phone-island {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 32px;
+  background: #000;
+}
+.ui-phone-camera {
+  display: block;
+  width: 10px;
+  height: 10px;
+  background: radial-gradient(circle at 35% 35%, #2a2a3a, #0a0a0a);
+  border-radius: 50%;
+  box-shadow: 0 0 0 1px rgba(255,255,255,0.06);
+}
+
+/* Screen */
+.ui-phone-screen {
+  flex: 1;
+  min-height: 440px;
+  overflow: hidden;
+}
+
+/* Home indicator */
+.ui-phone-home {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 24px;
+  background: #000;
+}
+.ui-phone-home::after {
+  content: '';
+  display: block;
+  width: 80px;
+  height: 4px;
+  background: rgba(255, 255, 255, 0.25);
+  border-radius: 2px;
+}
+
 /* ─── Footer ─────────────────────────────────────────────────────────────────
    Site footer — logo, nav links, legal text. Stacks on mobile.              */
 .ui-footer {
@@ -1789,6 +1909,9 @@ hr.ui-divider {
   color:           var(--ui-text);
   text-decoration: none;
   flex-shrink:     0;
+  display:         flex;
+  align-items:     center;
+  gap:             .5rem;
   transition:      color .15s;
 }
 

package/docs/public/themes/lumio.css

@@ -0,0 +1,50 @@
+/* ─── Lumio brand theme ───────────────────────────────────────────────────────
+   Palette tokens + light-theme overrides for the Lumio mobile-app template.
+   Load after pulse-ui.css so these override the framework defaults.          */
+
+/* Palette tokens — available in any rule */
+:root {
+  --cotton-rose: #e5c1bd;
+  --bone:        #d2d0ba;
+  --dry-sage:    #b6be9c;
+  --muted-teal:  #7b9e87;
+  --blue-slate:  #5e747f;
+}
+
+/* Override light-theme semantic tokens */
+[data-theme="light"],
+.ui-theme-light {
+  --ui-bg:           #f7f4ed;
+  --ui-surface:      #edeae0;
+  --ui-surface-2:    #e4e1d6;
+  --ui-border:       #cbc8b8;
+  /* Deep teal — darker than --muted-teal so it passes WCAG AA on both bg surfaces */
+  --ui-accent:       #3d6650;
+  --ui-accent-hover: #2e5040;
+  --ui-accent-dim:   rgba(61, 102, 80, 0.14);
+  --ui-accent-text:  #ffffff;
+  --ui-muted:        #5a574e;
+}
+
+/* Nav: frosted glass effect */
+[data-theme="light"] .ui-nav {
+  backdrop-filter: blur(14px);
+  -webkit-backdrop-filter: blur(14px);
+}
+
+/* Mobile menu: dark text on light dropdown background */
+[data-theme="light"] .ui-nav-mobile .ui-nav-link,
+[data-theme="light"] .ui-nav-mobile .ui-nav-mega-item-label,
+[data-theme="light"] .ui-nav-mobile-section {
+  color: var(--ui-text);
+}
+
+/* Pricing: show the Pro (highlighted) card first on mobile */
+@media (max-width: 639px) {
+  #pricing .ui-grid > div:nth-child(2) { order: -1; }
+}
+
+/* Primary buttons: white text on the deep teal accent background (6.5:1) */
+[data-theme="light"] .ui-btn--primary {
+  color: #fff;
+}

package/docs/server.js

@@ -100,8 +100,12 @@ await createServer(
     new URL('./src/pages/components/feature.js',     import.meta.url),
     new URL('./src/pages/components/hero.js',        import.meta.url),
     new URL('./src/pages/components/nav.js',         import.meta.url),
+    new URL('./src/pages/components/phone-frame.js', import.meta.url),
     new URL('./src/pages/components/pricing.js',     import.meta.url),
     new URL('./src/pages/components/testimonial.js', import.meta.url),
+    // Templates
+    new URL('./src/pages/templates.js',              import.meta.url),
+    new URL('./src/pages/templates/mobile-app.js',   import.meta.url),
     // Layout Components
     new URL('./src/pages/components/banner.js',      import.meta.url),
     new URL('./src/pages/components/cluster.js',     import.meta.url),

package/docs/src/lib/component-page.js

@@ -8,11 +8,12 @@
 import { renderLayout, h1, lead, codeBlock } from './layout.js'
 import { highlight } from './highlight.js'
 
-export function demo(previewHtml, codeStr, { col = false, scroll = false } = {}) {
+export function demo(previewHtml, codeStr, { col = false, scroll = false, bleed = false } = {}) {
   const previewClass = [
     'demo-preview',
     col    ? 'demo-preview--col'    : '',
     scroll ? 'demo-preview--scroll' : '',
+    bleed  ? 'demo-preview--bleed'  : '',
   ].filter(Boolean).join(' ')
   const toggle = `<button class="demo-theme-toggle" aria-label="Toggle light/dark theme" title="Toggle theme">
     <svg class="demo-theme-toggle__dark" width="14" height="14" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M21 12.79A9 9 0 1111.21 3a7 7 0 109.79 9.79z"/></svg>

package/docs/src/lib/nav.js

@@ -121,6 +121,7 @@ export const NAV = [
       { label: 'Feature',     href: '/components/feature'     },
       { label: 'Hero',        href: '/components/hero'        },
       { label: 'Nav',         href: '/components/nav'         },
+      { label: 'Phone Frame', href: '/components/phone-frame' },
       { label: 'Pricing',     href: '/components/pricing'     },
       { label: 'Testimonial', href: '/components/testimonial' },
     ],
@@ -148,6 +149,13 @@ export const NAV = [
       { label: 'Payments (Stripe)', href: '/stripe'   },
     ],
   },
+  {
+    section: 'Templates',
+    items: [
+      { label: 'All Templates',        href: '/templates'            },
+      { label: 'Mobile App Landing',   href: '/templates/mobile-app' },
+    ],
+  },
 ]
 
 export function prevNext(currentHref) {

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

@@ -51,7 +51,8 @@ export default {
   subtitle: 'Beautifully simple. Ridiculously fast.',
   actions:  appBadge({ store: 'apple',  href: appStoreUrl }) +
             appBadge({ store: 'google', href: playStoreUrl }),
-})`
+})`,
+        { bleed: true }
       )}
 
       ${demo(
@@ -69,7 +70,8 @@ export default {
   actions:  appBadge({ store: 'apple',  href: appStoreUrl }) +
             appBadge({ store: 'google', href: playStoreUrl }),
   image:    \`<img src="\${screenshotUrl}" alt="Product screenshot">\`,
-})`
+})`,
+        { bleed: true }
       )}
 
       ${demo(
@@ -86,7 +88,31 @@ export default {
   subtitle:   'Set imageAlign to swap sides.',
   image:      \`<img src="\${screenshotUrl}" alt="Product screenshot">\`,
   imageAlign: 'left',
-})`
+})`,
+        { bleed: true }
+      )}
+
+      ${demo(
+        `<div style="display:flex;flex-direction:column;gap:0">` +
+          hero({ eyebrow: 'Purple (default)', title: 'gradient: true', gradient: 'purple', size: 'sm' }) +
+          hero({ eyebrow: 'Blue',             title: "gradient: 'blue'",   gradient: 'blue',   size: 'sm' }) +
+          hero({ eyebrow: 'Green',            title: "gradient: 'green'",  gradient: 'green',  size: 'sm' }) +
+          hero({ eyebrow: 'Rose',             title: "gradient: 'rose'",   gradient: 'rose',   size: 'sm' }) +
+          hero({ eyebrow: 'Orange',           title: "gradient: 'orange'", gradient: 'orange', size: 'sm' }) +
+        `</div>`,
+        `hero({ title: 'Headline', gradient: 'purple' })  // or 'blue' | 'green' | 'rose' | 'orange'`,
+        { bleed: true }
+      )}
+
+      ${demo(
+        `<div style="display:flex;flex-direction:column;gap:0">` +
+          hero({ eyebrow: 'Solid colour', title: 'background: color', background: '#0f172a', size: 'sm' }) +
+          hero({ eyebrow: 'Custom gradient', title: 'background: CSS gradient', background: 'linear-gradient(135deg, #1e1b4b 0%, #312e81 50%, #1e1b4b 100%)', size: 'sm' }) +
+        `</div>`,
+        `// Any valid CSS background value
+hero({ title: 'Headline', background: '#0f172a' })
+hero({ title: 'Headline', background: 'linear-gradient(135deg, #1e1b4b, #312e81)' })`,
+        { bleed: true }
       )}
 
       ${demo(
@@ -99,7 +125,8 @@ export default {
   title:    'Blog',
   subtitle: 'Thoughts on building for the web.',
   size:     'sm',
-})`
+})`,
+        { bleed: true }
       )}
 
       ${table(
@@ -113,6 +140,8 @@ export default {
           ['<code>imageAlign</code>',  'string',        "'right'",    "'right' (text left) or 'left' (text right) — only applies when image is set"],
           ['<code>align</code>',       'string',        "'center'",   "'center' or 'left' — text alignment when no image"],
           ['<code>size</code>',        'string',        "'md'",       "'md' (5rem padding) or 'sm' (2.5rem top, no bottom) — use sm for inner-page headers"],
+          ['<code>gradient</code>',    "boolean | 'purple' | 'blue' | 'green' | 'rose' | 'orange'", 'false', 'Named gradient preset. true and \'purple\' are identical.'],
+          ['<code>background</code>', 'string',        '—',          'Any CSS background value — solid colour or custom gradient. Overrides gradient preset.'],
         ]
       )}
     `,

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

@@ -19,6 +19,7 @@ import {
   iconHandPointUp, iconHandPointDown, iconHandPointLeft, iconHandPointRight,
   iconGlobe, iconShield, iconZap, iconTrendingUp, iconTrendingDown, iconLoader, iconGrid, iconBug,
   iconMapPin, iconSun, iconMoon,
+  iconFeather, iconAi, iconSmile, iconBarChart,
   iconShoppingCart, iconShoppingBag, iconCreditCard, iconPackage, iconGift,
   iconWallet, iconTruck, iconReceipt, iconStore, iconPercent, iconTicket, iconBanknote,
   iconUtensils, iconCoffee, iconPizza, iconApple, iconCarrot,
@@ -52,6 +53,11 @@ const ICONS = [
     { name: 'iconAlertCircle',   fn: iconAlertCircle   },
     { name: 'iconAlertTriangle', fn: iconAlertTriangle },
     { name: 'iconInfo',          fn: iconInfo          },
+    { name: 'iconSmile',         fn: iconSmile         },
+  ]},
+  { group: 'AI & Data', icons: [
+    { name: 'iconAi',       fn: iconAi       },
+    { name: 'iconBarChart', fn: iconBarChart },
   ]},
   { group: 'Actions', icons: [
     { name: 'iconPlus',     fn: iconPlus     },
@@ -87,6 +93,7 @@ const ICONS = [
     { name: 'iconLogIn',  fn: iconLogIn  },
   ]},
   { group: 'Content & Files', icons: [
+    { name: 'iconFeather',  fn: iconFeather  },
     { name: 'iconFile',     fn: iconFile     },
     { name: 'iconImage',    fn: iconImage    },
     { name: 'iconLink',     fn: iconLink     },
@@ -238,21 +245,7 @@ function iconModals_() {
   return ICONS.flatMap(({ icons }) => icons).map(iconPreviewModal).join('')
 }
 
-export default {
-  route: '/components/icons',
-  meta: {
-    title: 'Icons — Pulse Docs',
-    description: 'Built-in icon set for Pulse UI.',
-    styles: ['/pulse-ui.css', '/docs.css'],
-  },
-  view: () => renderComponentPage({
-    currentHref: '/components/icons',
-    prev,
-    next,
-    name: 'icons',
-    description: '100 curated icons. All are pure functions returning an SVG string — no external library, no DOM dependency, tree-shakeable. Style: 24×24 viewBox, <code>stroke="currentColor"</code>, compatible with any colour token.',
-    content: `
-
+const pageContent = `
       <h2 class="doc-h2" id="usage">Usage</h2>
       <p>Import the icon functions you need alongside other components. Call each as a function — optionally pass <code>size</code> and <code>class</code>.</p>
       ${demo(
@@ -370,8 +363,6 @@ feature({ icon: iconCode({   size: 22, bg: 'square', bgColor: 'muted'   }), titl
 
       ${iconGrid_()}
 
-      ${iconModals_()}
-
       ${table(
         ['Prop', 'Type', 'Default', 'Description'],
         [
@@ -383,6 +374,33 @@ feature({ icon: iconCode({   size: 22, bg: 'square', bgColor: 'muted'   }), titl
       )}
 
       <p style="margin-top:2rem;font-size:.8rem;color:var(--muted)">SVG paths derived from <a href="https://lucide.dev" target="_blank" rel="noopener noreferrer">Lucide</a> (ISC License, Copyright © 2022 Lucide Contributors) and <a href="https://feathericons.com" target="_blank" rel="noopener noreferrer">Feather Icons</a> (MIT License, Copyright © 2013–2017 Cole Bemis). Phosphor hand-pointer icons MIT License, Copyright © 2020 Phosphor Icons.</p>
-    `,
-  }),
+    `
+
+export default {
+  route: '/components/icons',
+  meta: {
+    title: 'Icons — Pulse Docs',
+    description: 'Built-in icon set for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+
+  // Shell: all visible content (nav, examples, icon grid) — sends immediately.
+  // Modals: 100 hidden <dialog> elements — streamed after. Users never see them
+  // arrive since dialogs are display:none until opened.
+  stream: {
+    shell:    ['page'],
+    deferred: ['modals'],
+  },
+
+  view: {
+    page: () => renderComponentPage({
+      currentHref: '/components/icons',
+      prev,
+      next,
+      name: 'icons',
+      description: '100 curated icons. All are pure functions returning an SVG string — no external library, no DOM dependency, tree-shakeable. Style: 24×24 viewBox, <code>stroke="currentColor"</code>, compatible with any colour token.',
+      content: pageContent,
+    }),
+    modals: () => iconModals_(),
+  },
 }

package/docs/src/pages/components/phone-frame.js

@@ -0,0 +1,54 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { phoneFrame } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/phone-frame')
+
+const sampleScreen = `
+  <div style="background:#1a2c24;height:100%;padding:0.75rem;display:flex;flex-direction:column;gap:0.625rem;font-family:system-ui,sans-serif;">
+    <div style="display:flex;justify-content:space-between;align-items:center;padding:0 0.25rem;font-size:0.6rem;color:rgba(255,255,255,0.5)">
+      <span>9:41</span>
+      <svg width="20" height="8" viewBox="0 0 20 8" fill="none" aria-hidden="true"><rect x="0.5" y="0.5" width="16" height="7" rx="2" stroke="rgba(255,255,255,0.35)" stroke-width="1"/><rect x="1.5" y="1.5" width="12" height="5" rx="1" fill="rgba(255,255,255,0.7)"/><path d="M18 3v2c.8-.3.8-1.7 0-2z" fill="rgba(255,255,255,0.6)"/></svg>
+    </div>
+    <div style="font-size:0.85rem;font-weight:700;color:#fff">Good morning, Sarah</div>
+    <div style="background:rgba(255,255,255,0.06);border-radius:0.625rem;padding:0.625rem;flex:1">
+      <div style="font-size:0.6rem;color:rgba(255,255,255,0.5);margin-bottom:0.3rem">TODAY'S ENTRY</div>
+      <div style="font-size:0.72rem;color:rgba(255,255,255,0.85);line-height:1.5">Feeling grateful today. The early morning light…</div>
+    </div>
+  </div>`
+
+export default {
+  route: '/components/phone-frame',
+  meta: {
+    title: 'Phone Frame — Pulse Docs',
+    description: 'Phone Frame component for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  state: {},
+  view: () => renderComponentPage({
+    currentHref: '/components/phone-frame',
+    prev,
+    next,
+    name: 'phoneFrame',
+    description: 'A realistic CSS mobile phone frame — device chrome, dynamic island, side buttons, and home indicator. Pass arbitrary HTML into the <code>content</code> slot to fill the screen area. No images, pure CSS/HTML.',
+    content: `
+      ${demo(
+        phoneFrame({ content: sampleScreen }),
+        `phoneFrame({
+  content: \`<div style="background:#1a2c24;height:100%;padding:0.75rem;">
+    <!-- your app screen UI -->
+  </div>\`,
+})`,
+      )}
+
+      ${table(
+        ['Prop', 'Type', 'Default', 'Description'],
+        [
+          ['<code>content</code>', 'string (HTML)', "''",  'HTML rendered inside the screen area'],
+          ['<code>class</code>',   'string',        "''",  'Extra CSS classes on the root element'],
+        ]
+      )}
+    `,
+  }),
+}