@invisibleloop/pulse 0.12.3 → 0.14.2

package/docs/public/swish.css

@@ -0,0 +1,394 @@
+/*
+ * swish.css — Swish editorial fashion example
+ *
+ * Palette: warm off-white paper, deep ink, oxblood accent.
+ * Font:    Playfair Display (display headings), system-ui (body)
+ *
+ * Split into two logical sections:
+ *   1. Token overrides — hex values, palette definitions ([data-theme="light"])
+ *   2. Component styles — layout, typography, custom elements (var() only)
+ */
+
+/* ==========================================================================
+   1. Token overrides (hex values live here)
+   ========================================================================== */
+
+/* Override --font-display so --ui-font-display cascades to Playfair Display */
+:root {
+  --font-display: 'Playfair Display', Georgia, 'Times New Roman', serif;
+}
+
+[data-theme="light"] {
+  --ui-bg:           #f5f1ea;
+  --ui-surface:      #faf7f1;
+  --ui-surface-2:    #ede7dc;
+  --ui-border:       #d8cfc0;
+  --ui-text:         #14110d;
+  --ui-muted:        #6b6357;
+  --ui-accent:       #6b1d1d;
+  --ui-accent-hover: #4a1212;
+  --ui-accent-dim:   rgba(107, 29, 29, 0.10);
+  --ui-accent-text:  #faf7f1;
+
+  /* Swish-specific tokens */
+  --swish-paper:         #faf7f1;
+  --swish-ink:           #14110d;
+  --swish-hero-veil:     rgba(20, 17, 13, 0.55);
+  --swish-hero-veil-top: rgba(20, 17, 13, 0.05);
+  --swish-label-bg:      rgba(20, 17, 13, 0.55);
+}
+
+/* Primary button on light theme — needs paper text, not default */
+[data-theme="light"] .ui-btn--primary {
+  color: var(--swish-paper);
+}
+
+/* Frosted nav over editorial imagery */
+[data-theme="light"] .ui-nav {
+  backdrop-filter: blur(14px);
+  -webkit-backdrop-filter: blur(14px);
+  background: rgba(245, 241, 234, 0.78);
+}
+
+[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);
+}
+
+/* ==========================================================================
+   2. Component styles (var() only — no hex values below this line)
+   ========================================================================== */
+
+/* --------------------------------------------------------------------------
+   Skip link
+   -------------------------------------------------------------------------- */
+.skip-link {
+  position: absolute;
+  left: -9999px;
+  top: 0;
+  background: var(--ui-text);
+  color: var(--ui-bg);
+  padding: var(--ui-space-2) var(--ui-space-4);
+  z-index: 100;
+}
+
+.skip-link:focus {
+  left: var(--ui-space-4);
+  top: var(--ui-space-4);
+}
+
+/* --------------------------------------------------------------------------
+   Brand wordmark
+   -------------------------------------------------------------------------- */
+.swish-mark {
+  font-family: var(--ui-font-display);
+  font-weight: 400;
+  font-size: var(--ui-text-2xl);
+  letter-spacing: 0.32em;
+  text-transform: uppercase;
+}
+
+/* --------------------------------------------------------------------------
+   Full-bleed hero
+   -------------------------------------------------------------------------- */
+.swish-hero {
+  position: relative;
+  min-height: 88vh;
+  display: flex;
+  align-items: center;
+  background-image:
+    linear-gradient(180deg, var(--swish-hero-veil-top) 0%, var(--swish-hero-veil) 100%),
+    url('/images/swish/1490481651871-ab68de25d43d.jpg');
+  background-size: cover;
+  background-position: center;
+  color: var(--swish-paper);
+  padding: var(--ui-space-12) var(--ui-space-6) var(--ui-space-16);
+}
+
+.swish-hero__inner {
+  max-width: 880px;
+  margin: 0 auto;
+  width: 100%;
+}
+
+.swish-hero__eyebrow {
+  display: inline-block;
+  font-size: var(--ui-text-xs);
+  letter-spacing: 0.24em;
+  text-transform: uppercase;
+  color: var(--swish-ink);
+  background: var(--swish-paper);
+  padding: var(--ui-space-1) var(--ui-space-3);
+  margin-bottom: var(--ui-space-5);
+}
+
+.swish-hero__title {
+  font-family: var(--ui-font-display);
+  font-weight: 400;
+  font-size: clamp(3rem, 9vw, 7rem);
+  line-height: 0.95;
+  letter-spacing: -0.02em;
+  margin-bottom: var(--ui-space-6);
+}
+
+.swish-hero__deck {
+  font-size: var(--ui-text-lg);
+  line-height: 1.6;
+  max-width: 36rem;
+  margin-bottom: var(--ui-space-8);
+  opacity: 0.92;
+}
+
+/* Ghost button inside the hero — force white so it's visible over the dark veil */
+.swish-hero .ui-btn--ghost {
+  color: #fff;
+  border-color: rgba(255,255,255,0.6);
+}
+.swish-hero .ui-btn--ghost:hover {
+  background: rgba(255,255,255,0.12);
+  border-color: #fff;
+}
+
+/* Quote section — equal top and bottom padding */
+.swish-quote-section { padding-bottom: var(--ui-space-16); }
+
+/* --------------------------------------------------------------------------
+   Section eyebrow / issue marker
+   -------------------------------------------------------------------------- */
+.swish-issue {
+  display: flex;
+  align-items: center;
+  gap: var(--ui-space-4);
+  font-size: var(--ui-text-xs);
+  letter-spacing: 0.24em;
+  text-transform: uppercase;
+  color: var(--ui-muted);
+  margin-bottom: var(--ui-space-6);
+}
+
+.swish-issue::before,
+.swish-issue::after {
+  content: '';
+  flex: 1;
+  height: 1px;
+  background: var(--ui-border);
+}
+
+.swish-issue--left::after {
+  display: none;
+}
+
+/* --------------------------------------------------------------------------
+   Featured looks (product cards)
+   -------------------------------------------------------------------------- */
+.swish-look {
+  display: block;
+  text-decoration: none;
+  color: var(--ui-text);
+}
+
+.swish-look__frame {
+  aspect-ratio: 3 / 4;
+  overflow: hidden;
+  background: var(--ui-surface-2);
+  margin-bottom: var(--ui-space-4);
+}
+
+.swish-look__frame img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  display: block;
+  transition: transform 600ms ease;
+}
+
+.swish-look:hover .swish-look__frame img {
+  transform: scale(1.04);
+}
+
+.swish-look__name {
+  font-family: var(--ui-font-display);
+  font-size: var(--ui-text-lg);
+  font-weight: 400;
+  margin-bottom: var(--ui-space-1);
+}
+
+.swish-look__meta {
+  font-size: var(--ui-text-sm);
+  color: var(--ui-muted);
+  letter-spacing: 0.04em;
+}
+
+/* --------------------------------------------------------------------------
+   Atelier split layout
+   -------------------------------------------------------------------------- */
+.swish-split {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: var(--ui-space-12);
+  align-items: center;
+}
+
+.swish-split__media {
+  aspect-ratio: 4 / 5;
+  overflow: hidden;
+  background: var(--ui-surface-2);
+}
+
+.swish-split__media img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  display: block;
+}
+
+.swish-split__title {
+  font-family: var(--ui-font-display);
+  font-size: clamp(2rem, 4vw, 3rem);
+  font-weight: 400;
+  line-height: 1.05;
+  letter-spacing: -0.015em;
+  margin-bottom: var(--ui-space-5);
+}
+
+.swish-split__body p {
+  font-size: var(--ui-text-lg);
+  line-height: 1.75;
+  color: var(--ui-text);
+  margin-bottom: var(--ui-space-4);
+}
+
+@media (max-width: 720px) {
+  .swish-split {
+    grid-template-columns: 1fr;
+    gap: var(--ui-space-8);
+  }
+}
+
+/* --------------------------------------------------------------------------
+   Lookbook strip
+   -------------------------------------------------------------------------- */
+.swish-strip {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: var(--ui-space-4);
+}
+
+.swish-strip__cell {
+  position: relative;
+  aspect-ratio: 4 / 5;
+  overflow: hidden;
+  background: var(--ui-surface-2);
+}
+
+.swish-strip__cell img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  display: block;
+}
+
+.swish-strip__label {
+  position: absolute;
+  left: var(--ui-space-4);
+  bottom: var(--ui-space-4);
+  font-size: var(--ui-text-xs);
+  letter-spacing: 0.24em;
+  text-transform: uppercase;
+  color: var(--swish-paper);
+  background: var(--swish-label-bg);
+  padding: var(--ui-space-2) var(--ui-space-3);
+}
+
+@media (max-width: 720px) {
+  .swish-strip {
+    grid-template-columns: 1fr;
+  }
+}
+
+/* --------------------------------------------------------------------------
+   Journal cards
+   -------------------------------------------------------------------------- */
+.swish-journal-card {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ui-space-3);
+}
+
+.swish-journal-card__frame {
+  aspect-ratio: 16 / 10;
+  overflow: hidden;
+  background: var(--ui-surface-2);
+}
+
+.swish-journal-card__frame img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  display: block;
+}
+
+.swish-journal-card__category {
+  font-size: var(--ui-text-xs);
+  letter-spacing: 0.24em;
+  text-transform: uppercase;
+  color: var(--ui-accent);
+}
+
+.swish-journal-card__title {
+  font-family: var(--ui-font-display);
+  font-size: var(--ui-text-xl);
+  font-weight: 400;
+  line-height: 1.25;
+}
+
+.swish-journal-card__deck {
+  font-size: var(--ui-text-base);
+  color: var(--ui-muted);
+  line-height: 1.6;
+}
+
+.swish-journal-card__byline {
+  font-size: var(--ui-text-xs);
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--ui-muted);
+}
+
+/* --------------------------------------------------------------------------
+   Newsletter section
+   -------------------------------------------------------------------------- */
+.swish-newsletter {
+  text-align: center;
+}
+
+.swish-newsletter__title {
+  font-family: var(--ui-font-display);
+  font-size: clamp(2rem, 4vw, 2.75rem);
+  font-weight: 400;
+  letter-spacing: -0.01em;
+  margin-bottom: var(--ui-space-4);
+}
+
+.swish-newsletter__deck {
+  max-width: 32rem;
+  margin: 0 auto var(--ui-space-8);
+  color: var(--ui-muted);
+  line-height: 1.6;
+}
+
+.swish-newsletter__form {
+  max-width: 32rem;
+  margin: 0 auto;
+  display: flex;
+  gap: var(--ui-space-3);
+  align-items: flex-end;
+  flex-wrap: wrap;
+  justify-content: center;
+}
+
+/* Safe area padding for mobile devices (home indicator bar) */
+@supports (padding-bottom: env(safe-area-inset-bottom)) {
+  footer { padding-bottom: max(var(--ui-space-6), env(safe-area-inset-bottom)); }
+}

package/docs/server.js

@@ -73,9 +73,12 @@ await createServer(
     new URL('./src/pages/components/heading.js',     import.meta.url),
     new URL('./src/pages/components/icons.js',       import.meta.url),
     new URL('./src/pages/components/image.js',       import.meta.url),
+    new URL('./src/pages/components/gallery.js',     import.meta.url),
     new URL('./src/pages/components/input.js',       import.meta.url),
     new URL('./src/pages/components/list.js',        import.meta.url),
+    new URL('./src/pages/components/marquee.js',     import.meta.url),
     new URL('./src/pages/components/modal.js',       import.meta.url),
+    new URL('./src/pages/components/photo-card.js',  import.meta.url),
     new URL('./src/pages/components/progress.js',    import.meta.url),
     new URL('./src/pages/components/prose.js',       import.meta.url),
     new URL('./src/pages/components/pullquote.js',   import.meta.url),
@@ -104,14 +107,24 @@ await createServer(
     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),
-    new URL('./src/pages/templates/blog-post.js',    import.meta.url),
+    new URL('./src/pages/templates.js',                     import.meta.url),
+    new URL('./src/pages/templates/mobile-app.js',          import.meta.url),
+    new URL('./src/pages/templates/blog-post.js',           import.meta.url),
+    new URL('./src/pages/templates/coutumes.js',            import.meta.url),
+    new URL('./src/pages/templates/sparkys.js',             import.meta.url),
+    new URL('./src/pages/templates/swish.js',               import.meta.url),
+    new URL('./src/pages/templates/bookworms.js',           import.meta.url),
+    new URL('./src/pages/templates/retrowheels.js',         import.meta.url),
+    new URL('./src/pages/templates/suzukibento.js',         import.meta.url),
+    new URL('./src/pages/templates/andypixel.js',           import.meta.url),
+    new URL('./src/pages/templates/journey.js',             import.meta.url),
+    new URL('./src/pages/templates/shop.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),
     new URL('./src/pages/components/code-window.js', import.meta.url),
     new URL('./src/pages/components/container.js',   import.meta.url),
+    new URL('./src/pages/components/decorate.js',    import.meta.url),
     new URL('./src/pages/components/divider.js',     import.meta.url),
     new URL('./src/pages/components/footer.js',      import.meta.url),
     new URL('./src/pages/components/grid.js',        import.meta.url),
@@ -125,7 +138,9 @@ await createServer(
     root:         new URL('.', import.meta.url),
     defaultCache: true,
     csp: {
-      'img-src': ['https://picsum.photos', 'https://images.unsplash.com'],
+      'img-src':   ['https://picsum.photos', 'https://fastly.picsum.photos', 'https://images.unsplash.com'],
+      'style-src': ['https://fonts.googleapis.com'],
+      'font-src':  ['https://fonts.gstatic.com'],
     },
   }
 )

package/docs/src/lib/nav.js

@@ -90,9 +90,12 @@ export const NAV = [
       { label: 'Heading',     href: '/components/heading'     },
       { label: 'Icons',       href: '/components/icons'       },
       { label: 'Image',       href: '/components/image'       },
+      { label: 'Gallery',     href: '/components/gallery'     },
       { label: 'Input',       href: '/components/input'       },
       { label: 'List',        href: '/components/list'        },
+      { label: 'Marquee',     href: '/components/marquee'     },
       { label: 'Modal',       href: '/components/modal'       },
+      { label: 'Photo Card',  href: '/components/photo-card'  },
       { label: 'Progress',    href: '/components/progress'    },
       { label: 'Prose',       href: '/components/prose'       },
       { label: 'Pullquote',   href: '/components/pullquote'   },
@@ -133,6 +136,7 @@ export const NAV = [
       { label: 'Cluster',     href: '/components/cluster'     },
       { label: 'Code Window', href: '/components/code-window' },
       { label: 'Container',   href: '/components/container'   },
+      { label: 'Decorate',    href: '/components/decorate'    },
       { label: 'Divider',     href: '/components/divider'     },
       { label: 'Footer',      href: '/components/footer'      },
       { label: 'Grid',        href: '/components/grid'        },
@@ -152,9 +156,16 @@ export const NAV = [
   {
     section: 'Templates',
     items: [
-      { label: 'All Templates',        href: '/templates'            },
-      { label: 'Mobile App Landing',   href: '/templates/mobile-app' },
-      { label: 'Blog Post',            href: '/templates/blog-post'  },
+      { label: 'All Templates',        href: '/templates'                   },
+      { label: 'Mobile App Landing',   href: '/templates/mobile-app'        },
+      { label: 'Blog Post',            href: '/templates/blog-post'         },
+      { label: 'Swish — Fashion',      href: '/templates/swish'             },
+      { label: 'BookWorms',            href: '/templates/bookworms'         },
+      { label: 'Retro Wheels Co.',     href: '/templates/retrowheels'       },
+      { label: 'Susuki Bento',         href: '/templates/suzukibento'       },
+      { label: 'Andy Pixel — Blog',    href: '/templates/andypixel'         },
+      { label: 'Journey — App',        href: '/templates/journey'           },
+      { label: 'Shop — Product Page',  href: '/templates/shop'              },
     ],
   },
 ]

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

@@ -0,0 +1,74 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table, callout } from '../../lib/layout.js'
+import { decorate } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/decorate')
+
+const swatch = (pattern, label) => `
+  <div style="position:relative;width:200px;height:120px;border-radius:var(--ui-radius);border:1px solid var(--ui-border);overflow:hidden;display:flex;align-items:center;justify-content:center">
+    ${decorate({ pattern })}
+    <span style="position:relative;z-index:1;font-weight:600;font-size:.875rem">${label}</span>
+  </div>`
+
+export default {
+  route: '/components/decorate',
+  meta: {
+    title: 'Decorate — Pulse Docs',
+    description: 'Inline SVG background pattern overlay for adding subtle texture to sections in Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  view: () => renderComponentPage({
+    currentHref: '/components/decorate',
+    prev,
+    next,
+    name: 'decorate',
+    description: 'Inline SVG background pattern. Drop it inside any container with <code>position: relative</code> to add subtle texture without external assets. Five patterns: dots, grid, lines, zigzag, cross. Zero JavaScript — pure inline SVG.',
+    content: `
+      <h2 class="doc-h2" id="patterns">Patterns</h2>
+      <p>Five built-in patterns. The SVG fills the parent completely with <code>position: absolute; inset: 0</code>.</p>
+      ${demo(
+        `<div style="display:flex;flex-wrap:wrap;gap:1rem">` +
+          swatch('dots',   'dots') +
+          swatch('grid',   'grid') +
+          swatch('lines',  'lines') +
+          swatch('zigzag', 'zigzag') +
+          swatch('cross',  'cross') +
+        `</div>`,
+        `// Parent must have position: relative
+<div style="position:relative">
+  ${`${decorate({ pattern: 'dots' })}`}
+  <p>Your content sits on top</p>
+</div>`
+      )}
+
+      <h2 class="doc-h2" id="color">Color and opacity</h2>
+      <p>The default color is <code>var(--ui-border)</code> — it fits both light and dark themes. Override with any CSS value. Control density with <code>opacity</code>.</p>
+      ${demo(
+        `<div style="display:flex;flex-wrap:wrap;gap:1rem">` +
+          `<div style="position:relative;width:200px;height:120px;border-radius:var(--ui-radius);overflow:hidden;background:var(--ui-accent);display:flex;align-items:center;justify-content:center">` +
+            decorate({ pattern: 'dots', color: '#fff', opacity: 0.3 }) +
+            `<span style="position:relative;z-index:1;color:#fff;font-weight:600">opacity: 0.3</span>` +
+          `</div>` +
+          `<div style="position:relative;width:200px;height:120px;border-radius:var(--ui-radius);overflow:hidden;background:var(--ui-surface-raised);display:flex;align-items:center;justify-content:center">` +
+            decorate({ pattern: 'grid', opacity: 0.6 }) +
+            `<span style="position:relative;z-index:1;font-weight:600">opacity: 0.6</span>` +
+          `</div>` +
+        `</div>`,
+        `decorate({ pattern: 'dots', color: '#fff', opacity: 0.3 })`
+      )}
+
+      ${callout('note', 'The <code>decorate</code> element is <code>aria-hidden="true"</code> — it is purely decorative. Make sure surrounding content has sufficient contrast without relying on the pattern.')}
+
+      ${table(
+        ['Prop', 'Type', 'Default', 'Description'],
+        [
+          ['<code>pattern</code>', 'string', "'dots'",              "'dots' · 'grid' · 'lines' · 'zigzag' · 'cross'"],
+          ['<code>color</code>',   'string', "'var(--ui-border)'",  'Any CSS color value — <code>var()</code> tokens and hex are both accepted'],
+          ['<code>opacity</code>', 'number', '0.4',                 'SVG opacity — 0 (invisible) to 1 (solid)'],
+          ['<code>size</code>',    'number', '20',                  'Pattern tile size in pixels — smaller values = denser pattern'],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -0,0 +1,102 @@
+import { renderComponentPage, demo } from '../../lib/component-page.js'
+import { prevNext } from '../../lib/nav.js'
+import { table } from '../../lib/layout.js'
+import { gallery } from '../../../../src/ui/index.js'
+
+const { prev, next } = prevNext('/components/gallery')
+
+const PHOTOS = [
+  { src: '/img/placeholder-landscape.svg', alt: 'Mountain landscape' },
+  { src: '/img/placeholder-square.svg',    alt: 'Portrait photo' },
+  { src: '/img/placeholder-tall.svg',      alt: 'Urban street' },
+  { src: '/img/placeholder-landscape.svg', alt: 'Coastal path' },
+  { src: '/img/placeholder-square.svg',    alt: 'Dog in the park' },
+  { src: '/img/placeholder-tall.svg',      alt: 'City skyline' },
+]
+
+const CAPTIONED = [
+  { src: '/img/placeholder-landscape.svg', alt: 'Mountain landscape', caption: 'Glen Coe, Scotland' },
+  { src: '/img/placeholder-square.svg',    alt: 'Portrait',           caption: 'Lisbon, Portugal' },
+  { src: '/img/placeholder-tall.svg',      alt: 'Urban',              caption: 'Tokyo, Japan' },
+]
+
+export default {
+  route: '/components/gallery',
+  meta: {
+    title: 'Gallery — Pulse Docs',
+    description: 'Responsive image gallery with grid, strip, and masonry layouts for Pulse UI.',
+    styles: ['/pulse-ui.css', '/docs.css'],
+  },
+  view: () => renderComponentPage({
+    currentHref: '/components/gallery',
+    prev,
+    next,
+    name: 'gallery',
+    description: 'Responsive image gallery. Three layout modes: <code>grid</code> (equal aspect-ratio cells), <code>strip</code> (single horizontally scrollable row), and <code>masonry</code> (Pinterest-style varying heights). All images are lazy-loaded.',
+    content: `
+      <h2 class="doc-h2" id="grid">Grid layout</h2>
+      <p>Equal-sized cells with a consistent aspect ratio. Good for portfolios and photo libraries.</p>
+      ${demo(
+        gallery({ images: PHOTOS, layout: 'grid', cols: 3, ratio: '4/3' }),
+        `gallery({
+  images: photos.map(p => ({ src: p.url, alt: p.alt })),
+  layout: 'grid',
+  cols:   3,
+  ratio:  '4/3',
+})`
+      )}
+
+      <h2 class="doc-h2" id="strip">Strip layout</h2>
+      <p>A single horizontally scrollable row — ideal for a quick photo preview or a scrolling carousel of product shots.</p>
+      ${demo(
+        gallery({ images: PHOTOS, layout: 'strip', ratio: '4/3' }),
+        `gallery({
+  images: photos.map(p => ({ src: p.url, alt: p.alt })),
+  layout: 'strip',
+  ratio:  '4/3',
+})`
+      )}
+
+      <h2 class="doc-h2" id="masonry">Masonry layout</h2>
+      <p>Varying heights — images render at their natural ratio. Best for editorial photography where portrait and landscape images are mixed.</p>
+      ${demo(
+        gallery({ images: PHOTOS, layout: 'masonry', cols: 3 }),
+        `gallery({
+  images: photos.map(p => ({ src: p.url, alt: p.alt })),
+  layout: 'masonry',
+  cols:   3,
+})`
+      )}
+
+      <h2 class="doc-h2" id="captions">Captions</h2>
+      <p>Add a <code>caption</code> to any image in the array — rendered as a <code>&lt;figcaption&gt;</code>.</p>
+      ${demo(
+        gallery({ images: CAPTIONED, layout: 'grid', cols: 3, ratio: '4/3' }),
+        `gallery({
+  images: [
+    { src: '/img/landscape.jpg', alt: 'Mountain', caption: 'Glen Coe, Scotland' },
+    { src: '/img/portrait.jpg',  alt: 'Street',   caption: 'Lisbon, Portugal' },
+  ],
+  layout: 'grid',
+  cols:   3,
+  ratio:  '4/3',
+})`
+      )}
+
+      <h2 class="doc-h2" id="linked">Linked images</h2>
+      <p>Add an <code>href</code> to any image to wrap it in a link.</p>
+
+      ${table(
+        ['Prop', 'Type', 'Default', 'Description'],
+        [
+          ['<code>images</code>',  'object[]',      '[]',       'Array of image objects: <code>{ src, alt, caption?, href? }</code>'],
+          ['<code>layout</code>',  'string',        "'grid'",   "'grid' · 'strip' · 'masonry'"],
+          ['<code>cols</code>',    'number',        '3',        'Columns in grid/masonry (1–4)'],
+          ['<code>ratio</code>',   'string',        "'4/3'",    "CSS aspect-ratio for grid/strip cells — e.g. <code>'16/9'</code>, <code>'1/1'</code>. Ignored in masonry."],
+          ['<code>gap</code>',     'string',        "'md'",     "'sm' · 'md' · 'lg'"],
+          ['<code>rounded</code>', 'boolean',       'false',    'Adds border-radius to each image'],
+        ]
+      )}
+    `,
+  }),
+}

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

@@ -137,6 +137,7 @@ hero({ title: 'Headline', background: 'linear-gradient(135deg, #1e1b4b, #312e81)
           ['<code>subtitle</code>',    'string',        '—',          ''],
           ['<code>actions</code>',     'string (HTML)', '—',          'Raw HTML slot — buttons, badges, etc.'],
           ['<code>image</code>',       'string (HTML)', '—',          'Raw HTML slot — activates split layout when set'],
+          ['<code>layout</code>',      'string',        "'split'",    "When <code>image</code> is set: <code>'split'</code> (even columns) · <code>'asymmetric'</code> (wider text, narrower image) · <code>'overlap'</code> (image overlaps below text)"],
           ['<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"],