@invisibleloop/pulse 0.10.2 → 0.12.0

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

@@ -1 +1 @@
-0.9.1
+0.10.2

package/docs/public/pulse-ui.css

@@ -759,7 +759,7 @@ hr.ui-divider {
 }
 
 /* ─── Hero ───────────────────────────────────────────────────────────────── */
-.ui-hero { padding: 5rem 0; text-align: center; }
+.ui-hero { padding: 5rem 1.5rem; text-align: center; }
 .ui-hero--left { text-align: left; }
 .ui-hero--sm   { padding-top: 2.5rem; padding-bottom: 0; }
 .ui-hero--gradient,
@@ -798,7 +798,7 @@ hr.ui-divider {
     #1e0e04;
 }
 
-.ui-hero-inner { max-width: 720px; margin: 0 auto; padding: 0 1.5rem; }
+.ui-hero-inner { max-width: 720px; margin: 0 auto; }
 .ui-hero--left .ui-hero-inner { margin: 0; }
 
 .ui-hero-eyebrow {
@@ -837,9 +837,8 @@ hr.ui-divider {
 /* Split (text + image) */
 .ui-hero--split { text-align: left; }
 .ui-hero--split .ui-hero-inner {
-  max-width: 1100px;
+  max-width: 1200px;
   margin: 0 auto;
-  padding: 0 1.5rem;
   display: grid;
   grid-template-columns: 1fr 1fr;
   gap: 3rem;
@@ -1462,8 +1461,7 @@ hr.ui-divider {
   .ui-media { grid-template-columns: 1fr; }
   .ui-media--reverse { direction: ltr; }
 
-  .ui-hero { padding: 3rem 0; }
-  .ui-hero-inner { padding: 0 1.25rem; }
+  .ui-hero { padding: 3rem 1.25rem; }
   .ui-hero-title { font-size: 2rem; }
   .ui-hero-subtitle { font-size: 1rem; }
   .ui-hero--split .ui-hero-inner { grid-template-columns: 1fr; }
@@ -1865,7 +1863,6 @@ hr.ui-divider {
 /* Screen */
 .ui-phone-screen {
   flex: 1;
-  min-height: 440px;
   overflow: hidden;
 }
 

package/docs/public/themes/observatory.css

@@ -0,0 +1,103 @@
+/*
+ * Observatory theme — dark astronomy palette
+ *
+ * Contrast notes (all checked against WCAG AA 4.5:1 for small text on --ui-bg):
+ *   --pacific-blue (#53a2be) on --prussian-blue (#0a2239) → 5.29:1  ✓
+ *   --ocean-blue   (#1d84b5) on --prussian-blue (#0a2239) → 3.68:1  (large text / UI only)
+ *   Default --ui-text (#e2e2ea) on --prussian-blue (#0a2239)         ✓ (very high)
+ *   --ui-muted rgba(180,215,230,0.85) on --prussian-blue (#0a2239)   → ~7.4:1  ✓
+ *   --ui-muted rgba(180,215,230,0.85) on --jet-black (#132e32)       → ~6.4:1  ✓
+ */
+
+/* Palette tokens */
+:root {
+  --prussian-blue: #0a2239;
+  --pacific-blue:  #53a2be;
+  --ocean-blue:    #1d84b5;
+  --jet-black:     #132e32;
+  --baltic-blue:   #176087;
+}
+
+/* Dark theme overrides — target :root (dark is the default pulse-ui theme) */
+:root {
+  --ui-bg:          var(--prussian-blue);
+  --ui-surface:     var(--jet-black);
+  --ui-surface-2:   #0d2b38;
+  --ui-border:      rgba(83, 162, 190, 0.18);
+  --ui-accent:      var(--pacific-blue);
+  --ui-accent-hover:#6bbcd4;
+  --ui-accent-dim:  rgba(83, 162, 190, 0.12);
+  --ui-accent-text: var(--prussian-blue);
+  --ui-muted:       rgba(180, 215, 230, 0.85);
+}
+
+/* Reading progress bar — CSS scroll-driven animation, no JS required */
+.obs-reading-progress {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 3px;
+  z-index: 10000;
+  pointer-events: none;
+}
+.obs-reading-progress-bar {
+  height: 100%;
+  width: 100%;
+  background: var(--ui-accent);
+  transform: scaleX(0);
+  transform-origin: left;
+  animation: obs-reading-progress linear both;
+  animation-timeline: scroll(root block);
+}
+@keyframes obs-reading-progress {
+  from { transform: scaleX(0); }
+  to   { transform: scaleX(1); }
+}
+
+/* Article hero — restore bottom padding (ui-hero--sm removes it) */
+.ui-hero--sm { padding-bottom: 3rem; }
+
+/* Article layout — prose + aside side by side */
+.obs-article {
+  display: grid;
+  grid-template-columns: 1fr 260px;
+  gap: 3rem;
+  align-items: start;
+}
+
+@media (max-width: 767px) {
+  .obs-article { grid-template-columns: 1fr; }
+}
+
+/* Aside sections */
+.obs-aside-section {
+  margin-bottom: 2rem;
+}
+.obs-aside-section:last-child {
+  margin-bottom: 0;
+}
+.obs-aside-nav-link {
+  display: block;
+  padding: 0.375rem 0;
+  font-size: 0.875rem;
+  color: var(--ui-muted);
+  text-decoration: none;
+  border-bottom: 1px solid var(--ui-border);
+  transition: color .15s;
+}
+.obs-aside-nav-link:hover { color: var(--ui-text); }
+.obs-aside-nav-link:last-child { border-bottom: none; }
+
+/* Nav — frosted glass effect */
+.ui-nav {
+  backdrop-filter: blur(14px);
+  -webkit-backdrop-filter: blur(14px);
+}
+
+/* Mobile nav — ensure readable text on the expanded panel */
+.ui-nav-mobile .ui-nav-link,
+.ui-nav-mobile .ui-nav-mega-item-label,
+.ui-nav-mobile-section {
+  color: var(--ui-text);
+}

package/docs/server.js

@@ -106,6 +106,7 @@ await createServer(
     // 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),
     // 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/nav.js

@@ -154,6 +154,7 @@ export const NAV = [
     items: [
       { label: 'All Templates',        href: '/templates'            },
       { label: 'Mobile App Landing',   href: '/templates/mobile-app' },
+      { label: 'Blog Post',            href: '/templates/blog-post'  },
     ],
   },
 ]

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

@@ -19,7 +19,7 @@ import {
   iconHandPointUp, iconHandPointDown, iconHandPointLeft, iconHandPointRight,
   iconGlobe, iconShield, iconZap, iconTrendingUp, iconTrendingDown, iconLoader, iconGrid, iconBug,
   iconMapPin, iconSun, iconMoon,
-  iconFeather, iconAi, iconSmile, iconBarChart,
+  iconFeather, iconTelescope, iconAi, iconSmile, iconBarChart,
   iconShoppingCart, iconShoppingBag, iconCreditCard, iconPackage, iconGift,
   iconWallet, iconTruck, iconReceipt, iconStore, iconPercent, iconTicket, iconBanknote,
   iconUtensils, iconCoffee, iconPizza, iconApple, iconCarrot,
@@ -59,6 +59,9 @@ const ICONS = [
     { name: 'iconAi',       fn: iconAi       },
     { name: 'iconBarChart', fn: iconBarChart },
   ]},
+  { group: 'Astronomy', icons: [
+    { name: 'iconTelescope', fn: iconTelescope },
+  ]},
   { group: 'Actions', icons: [
     { name: 'iconPlus',     fn: iconPlus     },
     { name: 'iconMinus',    fn: iconMinus    },

package/docs/src/pages/templates/blog-post.js

@@ -0,0 +1,226 @@
+/**
+ * Template: Blog Post — Observatory
+ *
+ * A full blog post page for an astronomy publication.
+ * Includes sticky nav, article hero, prose body, newsletter signup, and footer.
+ * Dark theme using the Observatory palette (prussian blue / pacific blue).
+ */
+
+import { asset } from '../../lib/layout.js'
+import {
+  nav        as uiNav,
+  hero,
+  section,
+  container,
+  prose,
+  heading,
+  card,
+  input,
+  button,
+  footer,
+  iconTelescope,
+  iconCheckCircle,
+  iconCalendar,
+  iconMapPin,
+} from '../../../../src/ui/index.js'
+
+// ── Navigation ───────────────────────────────────���────────────────────────────
+
+const pageNav = uiNav({
+  logo: `${iconTelescope({ size: 20 })}<span class="u-font-bold" style="letter-spacing:-0.02em">Observatory</span>`,
+  links: [
+    { label: 'Articles', href: '#' },
+    { label: 'Topics',   href: '#' },
+    { label: 'Archive',  href: '#' },
+  ],
+  sticky:     true,
+  background: 'rgba(10, 34, 57, 0.85)',
+})
+
+// ── Article hero ──────────────────────────────────────────────────────────────
+
+const articleHero = hero({
+  eyebrow:  'Deep Sky Objects',
+  title:    'The Pillars of Creation: Stellar Nurseries Caught in the Act',
+  subtitle: 'Six trillion miles tall and sculpted by the light of newborn stars — the Eagle Nebula\'s most famous feature is one of the most photographed objects in the cosmos. Here\'s what three decades of observation have revealed.',
+  actions:  `<p class="u-text-sm u-text-muted">By Dr. Elena Vasquez · 14 January 2026 · 9 min read</p>`,
+  align:    'center',
+  size:     'sm',
+  background: 'linear-gradient(160deg, #0a2239 0%, #132e32 60%, #0d2b38 100%)',
+})
+
+// ── Article body ──────────────────────────────────────────────────────────────
+
+const articleBody = `
+<p>In April 1995, astronomers pointed the Hubble Space Telescope at a seemingly unremarkable patch of sky in the constellation Serpens. What they captured would become one of the most iconic images in the history of science: three towering columns of gas and dust, backlit by the fierce radiation of newly-formed stars.</p>
+
+<p>These are the Pillars of Creation — a region of active star formation nestled inside the Eagle Nebula, some 6,500 light-years from Earth. The tallest pillar stretches four light-years from base to tip, roughly equivalent to the distance between our Sun and its nearest stellar neighbour, Proxima Centauri.</p>
+
+<figure>
+  <img
+    src="/img/heic1501a.jpg"
+    alt="Three towering columns of gas and dust, backlit by brilliant blue stars, rise from a field of glowing hydrogen in the Eagle Nebula — the Pillars of Creation as seen by Hubble."
+    loading="lazy">
+  <figcaption>The Pillars of Creation, Eagle Nebula (M16) — Hubble Space Telescope, 2015. Credit: NASA, ESA/Hubble and the Hubble Heritage Team</figcaption>
+</figure>
+
+<h2 id="what-are-the-pillars">What are the Pillars, exactly?</h2>
+
+<p>The Pillars are a type of structure known as an evaporating gaseous globule, or EGG. They form when intense ultraviolet radiation from hot, massive young stars bombards surrounding clouds of molecular hydrogen. The radiation ionises the outer layers of the cloud, causing them to evaporate and stream away. But denser knots of gas resist this erosion, acting as shields that protect the material behind them.</p>
+
+<p>The result is a column: a finger of denser gas pointing away from the radiation source, its tip rounded and hardened by the very light trying to destroy it. The pillars we see in the Eagle Nebula are essentially the remnants of a much larger cloud, sculpted over millions of years by the stars that formed within it.</p>
+
+<h2 id="nursery-in-destruction">A nursery in the act of destruction</h2>
+
+<p>Look closely at the tips of the pillars and you'll see small, dark bumps — protrusions that break away from the column like droplets from a slow-moving waterfall. Each of these is a potential solar system in the making. Inside every bump, gravity is pulling gas and dust into an ever-tighter knot. Given time — another hundred thousand years, perhaps — each one may collapse under its own weight and ignite as a new star.</p>
+
+<p>The irony is profound. The very stars that are destroying the pillars through photoevaporation were themselves born from the same cloud. The Pillars of Creation are, simultaneously, a stellar nursery and a funeral pyre.</p>
+
+<h2 id="how-spitzer-changed">How Spitzer changed the story</h2>
+
+<p>In 2007, the Spitzer Space Telescope — sensitive to infrared light invisible to human eyes — revealed something unexpected. The Eagle Nebula appeared to have already been hit by the shockwave from a supernova explosion. If correct, the pillars we see in visible light may already be gone. Light from their destruction would still be en route to us, not expected to arrive for another thousand years.</p>
+
+<p>When it does, the Eagle Nebula will briefly outshine everything in the night sky except the Moon. Then, as the light-years between us absorb the news, it will fade — and one of the most recognisable objects in the cosmos will exist only in our archives.</p>
+
+<h2 id="the-webb-revision">The Webb revision</h2>
+
+<p>In 2022, the James Webb Space Telescope turned its golden mirror on the Pillars and returned images that made 1995 look like a rough draft. Webb's near-infrared camera penetrated the dust to reveal thousands of previously hidden young stars, some still wrapped in their accretion discs. Orange jets of superheated material punch out from several of the protostars, signatures of the violent magnetic fields that accompany stellar birth.</p>
+
+<p>Webb also confirmed that the Pillars are not as serene as they appear. Turbulence ripples through the gas. Temperature gradients steepen where radiation meets denser material. The whole structure is in slow, continuous motion — a three-dimensional sculpture being revised in real time by forces we are only beginning to understand.</p>
+
+<h2 id="observing-from-earth">Observing from Earth</h2>
+
+<p>The Eagle Nebula is visible from Earth with modest equipment. From mid-northern latitudes, it rises in the southeast during summer evenings and reaches its highest point around midnight in July. A modest telescope at low magnification will reveal the nebulosity surrounding the cluster M16. The pillars themselves, however, require long-exposure imaging — they lie within the brighter core of the nebula and are impossible to resolve visually.</p>
+
+<p>If you point a camera at M16 on a dark night and stack several hours of exposures, the pillars will emerge from the noise — dim, dark columns against a field of glowing hydrogen. You'll be photographing light that left the nebula when the Western Roman Empire was still intact. Every image you take is a time machine.</p>
+`
+
+// ── Article aside ────────────────────────────────────────────────────────────
+
+const articleAside = `
+  <aside aria-label="Article sidebar">
+    <div class="obs-aside-section">
+      <p class="u-text-sm u-font-semibold u-mb-3">In this article</p>
+      <nav aria-label="Article sections">
+        <a class="obs-aside-nav-link" href="#what-are-the-pillars">What are the Pillars?</a>
+        <a class="obs-aside-nav-link" href="#nursery-in-destruction">A nursery in the act of destruction</a>
+        <a class="obs-aside-nav-link" href="#how-spitzer-changed">How Spitzer changed the story</a>
+        <a class="obs-aside-nav-link" href="#the-webb-revision">The Webb revision</a>
+        <a class="obs-aside-nav-link" href="#observing-from-earth">Observing from Earth</a>
+      </nav>
+    </div>
+    <div class="obs-aside-section">
+      ${card({
+        content: `
+          <p class="u-text-xs u-font-semibold u-text-accent u-mb-2">UPCOMING EVENT</p>
+          ${heading({ level: 3, text: 'Dark Sky Night 2026' })}
+          <p class="u-text-sm u-text-muted u-mt-2 u-mb-4">A guided tour of the summer sky with expert astronomers. Telescopes provided. Suitable for all ages.</p>
+          <div class="u-flex u-flex-col u-gap-1 u-mb-4">
+            <span class="u-flex u-items-center u-gap-2 u-text-sm u-text-muted">
+              ${iconCalendar({ size: 14 })} 19 July 2026
+            </span>
+            <span class="u-flex u-items-center u-gap-2 u-text-sm u-text-muted">
+              ${iconMapPin({ size: 14 })} Galloway Forest Park, Scotland
+            </span>
+          </div>
+          ${button({ label: 'Book a place', href: '#', size: 'sm', full: true })}
+        `,
+      })}
+    </div>
+  </aside>`
+
+// ── Newsletter ────────────────────────────────────────────────────────────────
+
+const newsletterSection = (state) => section({
+  id:      'newsletter',
+  variant: 'alt',
+  content: container({
+    size:    'sm',
+    content: `
+      <div class="u-text-center">
+        ${heading({ level: 2, text: 'Never miss a discovery' })}
+        <p class="u-text-muted u-mt-2 u-mb-6">Weekly dispatches from the cosmos — deep sky objects, new research, and what to observe this month.</p>
+        ${state.status === 'success'
+          ? `<div class="u-flex u-items-center u-justify-center u-gap-2">
+               ${iconCheckCircle({ size: 20 })}
+               <span>You're subscribed. Clear skies ahead.</span>
+             </div>`
+          : `<form data-action="subscribe" aria-label="Newsletter signup" novalidate>
+               <div class="u-flex u-gap-3 u-flex-wrap u-justify-center u-items-end">
+                 ${input({ label: 'Email address', name: 'email', type: 'email', placeholder: 'your@email.com', required: true })}
+                 ${button({
+                   label: state.status === 'loading' ? 'Subscribing\u2026' : 'Subscribe',
+                   type:  'submit',
+                   attrs: state.status === 'loading' ? { 'aria-busy': 'true', disabled: '' } : {},
+                 })}
+               </div>
+             </form>`
+        }
+      </div>
+    `,
+  }),
+})
+
+// ── Footer ────────────────────────────────────────────────────────────────────
+
+const pageFooter = footer({
+  logo:     `${iconTelescope({ size: 18 })}<span class="u-font-bold" style="letter-spacing:-0.02em">Observatory</span>`,
+  logoHref: '/',
+  links: [
+    { label: 'About',   href: '#' },
+    { label: 'Archive', href: '#' },
+    { label: 'Topics',  href: '#' },
+    { label: 'Privacy', href: '#' },
+    { label: 'RSS',     href: '#' },
+  ],
+  legal: `\u00a9 ${new Date().getFullYear()} Observatory. All rights reserved.`,
+})
+
+// ── Spec ─────────────────────────────────────────────────────────────────��────
+
+export default {
+  route: '/templates/blog-post',
+
+  meta: {
+    title:       'The Pillars of Creation \u2014 Observatory',
+    description: 'Six trillion miles tall and sculpted by the light of newborn stars \u2014 the Eagle Nebula\'s Pillars of Creation remain one of the most studied and photographed objects in the cosmos.',
+    styles:      ['/pulse-ui.css', '/themes/observatory.css'],
+  },
+
+  state: {
+    status: 'idle',
+  },
+
+  actions: {
+    subscribe: {
+      onStart: (state) => ({ status: 'loading' }),
+      run: async (state, serverState, formData) => {
+        const email = formData.get('email')
+        if (!email) throw new Error('Email address is required')
+        // Replace with your email API call
+        await new Promise(r => setTimeout(r, 600))
+        return { email }
+      },
+      onSuccess: (state) => ({
+        status: 'success',
+        _toast: { message: 'Welcome to Observatory! Clear skies ahead.', variant: 'success' },
+      }),
+      onError: (state, err) => ({
+        status: 'error',
+        _toast: { message: err.message || 'Something went wrong. Please try again.', variant: 'error' },
+      }),
+    },
+  },
+
+  view: (state) => `
+    <a href="#main-content" class="skip-link" style="position:absolute;left:-9999px;top:1rem;z-index:9999;padding:0.5rem 1rem;background:var(--ui-accent);color:var(--ui-accent-text);border-radius:0.25rem;text-decoration:none">Skip to main content</a>
+    <div class="obs-reading-progress" aria-hidden="true"><div class="obs-reading-progress-bar"></div></div>
+    ${pageNav}
+    <main id="main-content">
+      ${articleHero}
+      ${section({ content: container({ content: `<div class="obs-article">${prose({ content: articleBody })}${articleAside}</div>` }) })}
+      ${newsletterSection(state)}
+    </main>
+    ${pageFooter}
+    <script src="${asset('/pulse-ui.js')}" defer></script>`,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.10.2",
+  "version": "0.12.0",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.10.2
+0.12.0

package/src/agent/guide-templates.md

@@ -0,0 +1,246 @@
+# Pulse Templates — Scaffold Guide
+
+Templates are complete, production-ready page specs you can adapt for a new brand. Always start from a template when the user's request matches one — do not build from scratch.
+
+---
+
+## When to use a template
+
+Read the user's request and match against the triggers below. If it matches, use the template.
+
+| Template | Route | Triggers |
+|---|---|---|
+| Mobile App Landing | `docs/src/pages/templates/mobile-app.js` | "landing page for a mobile app", "app marketing site", "app homepage", "SaaS landing page" |
+| Blog Post          | `docs/src/pages/templates/blog-post.js`  | "blog post", "article page", "publication", "editorial site", "newsletter with blog" |
+
+---
+
+## Before writing any code — mandatory pre-build questions
+
+Ask these **before** presenting a plan. Do not skip them.
+
+1. **Colour palette** — "Do you have a colour palette, or should I choose one?"
+2. **Brand fonts** — "Any brand fonts, or system-ui is fine?"
+3. **Theme** — "Light or dark theme preference?"
+
+Record the answers. If the user provides palette colours, note which are light/mid/dark toned so you can plan contrast strategy before writing any CSS.
+
+**Why this matters:** Building with placeholder colours and retrofitting a palette requires rebuilding components, fixing WCAG contrast failures, and touching multiple files. Getting the palette upfront avoids that loop entirely.
+
+---
+
+## Mobile App Landing Page
+
+### What it includes
+
+| Section | Component(s) |
+|---|---|
+| Sticky nav | `nav` with logo, links, CTA button |
+| Hero | `hero` (split layout) with `phoneFrame` mockup |
+| Stats bar | `stat` × 4 in a `grid` |
+| Features | `feature` × 6 in a `grid` |
+| Testimonials | `testimonial` × 3 in a `grid` |
+| Pricing | `pricing` × 3 (Free / Pro / Family) in a `grid` |
+| FAQ | `accordion` |
+| Download CTA | `cta` with `appBadge` |
+| Footer | `footer` with logo, links, legal |
+
+### Files to create
+
+| File | Purpose |
+|---|---|
+| `src/pages/[name].js` | The page spec — copy and adapt the mobile-app template |
+| `public/themes/[name].css` | Brand theme — palette tokens + light-theme overrides |
+
+### Adapting the template
+
+1. **Brand name** — replace every instance of "Lumio" with the new app name.
+2. **Copy** — update eyebrows, titles, subtitles, feature descriptions, testimonials, pricing names/features, FAQ items, and footer links to match the new product.
+3. **Phone screen** — the `phoneScreen` HTML inside `phoneFrame` is a bespoke mockup. Update colours, labels, and data to match the new brand. Inline styles inside `phoneScreen` are intentional — the mockup uses sub-utility-scale sizes that utility classes cannot express.
+4. **Colour palette** — create `public/themes/[name].css` (see CSS rules below).
+5. **Icons** — the logo uses `iconFeather` for Lumio. Choose an appropriate icon from `src/ui/icons.js` or add a new one if nothing fits.
+6. **Route** — set `route: '/[name]'` or `route: '/'` as appropriate.
+7. **`pulse-ui.js`** — always load via `asset('/pulse-ui.js')` (import `asset` from the docs layout lib). Never hardcode `/pulse-ui.js` — the unhashed path gets a 1h cache header, not the immutable cache the hashed dist path gets.
+
+### Theme CSS rules
+
+Create `public/themes/[name].css`. Structure it like this:
+
+```css
+/* Token definitions — raw palette values */
+:root {
+  --color-primary:   #hex;
+  --color-secondary: #hex;
+  /* ... other palette colours */
+}
+
+/* Light theme overrides — must target [data-theme="light"], NOT :root */
+/* [data-theme="light"] has higher specificity than :root in pulse-ui.css */
+[data-theme="light"], .ui-theme-light {
+  --ui-bg:           #hex;   /* page background */
+  --ui-surface:      #hex;   /* card/panel surface */
+  --ui-surface-2:    #hex;   /* nested surface */
+  --ui-border:       #hex;   /* border colour */
+  --ui-accent:       #hex;   /* MUST pass WCAG AA (4.5:1) on --ui-bg for small text */
+  --ui-accent-hover: #hex;
+  --ui-accent-dim:   rgba(...); /* subtle tint for hover states */
+  --ui-accent-text:  #fff;   /* text on accent background */
+  --ui-muted:        #hex;   /* secondary text */
+}
+
+/* Primary button text fix for light theme (framework default uses var(--ui-bg)) */
+[data-theme="light"] .ui-btn--primary {
+  color: #fff;
+}
+
+/* Nav — frosted glass effect */
+[data-theme="light"] .ui-nav {
+  backdrop-filter: blur(14px);
+  -webkit-backdrop-filter: blur(14px);
+}
+
+/* Mobile nav — inherit dark text, not the white nav bar colour */
+[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 Pro card first on mobile */
+@media (max-width: 639px) {
+  #pricing .ui-grid > div:nth-child(2) { order: -1; }
+}
+```
+
+Load order in `meta.styles`: `['/pulse-ui.css', '/themes/[name].css']`
+
+**WCAG contrast rule for `--ui-accent`:** The palette's mid-tones are often too light to pass 4.5:1 on a near-white background. If none of the palette colours pass, derive a darker tonal variant (e.g. darken the primary colour) for `--ui-accent`. Keep the palette colours for large background areas where dark text is used — those only need 3:1 (large text / non-text).
+
+### Spec meta
+
+```js
+meta: {
+  title:       '[App name] — [tagline]',
+  description: '...',
+  theme:       'light',
+  styles:      ['/pulse-ui.css', '/themes/[name].css'],
+},
+```
+
+`theme: 'light'` sets `data-theme="light"` on `<body>`, which activates the light theme rules in `pulse-ui.css` and your theme file.
+
+### Utility classes — rule
+
+All HTML outside `phoneScreen` must use utility classes, not inline `style=""` attributes. The only legitimate inline styles are:
+- Inside `phoneScreen` (sub-utility-scale phone mockup)
+- `letter-spacing` values (no utility equivalent)
+- The skip-link off-screen positioning (`left: -9999px`)
+- `color:#fff` on the nav logo span (overrides the nav's cascaded colour)
+- `background` and `color` props on `hero()` and `nav()` — these are component props, not raw attributes
+
+### Accessibility checklist for this template
+
+- Nav and footer logo links must go to the same `href` (both `/`). Identical accessible name + different destination = WCAG failure.
+- Skip link: `<a href="#main-content" class="skip-link" style="position:absolute;left:-9999px;...">Skip to main content</a>` — always include it at the top of the view.
+- `phoneFrame` has `role="img" aria-label="Phone screen preview"` built in.
+
+---
+
+## Blog Post
+
+### What it includes
+
+| Section | Component(s) |
+|---|---|
+| Sticky nav | `nav` with logo, links |
+| Article header | `hero` (size `sm`, centered) — eyebrow category, title, subtitle/deck, byline in `actions` slot |
+| Article body | `section` + `container(size: 'sm')` + `prose` |
+| Newsletter signup | `section(variant: 'alt')` + `input` + `button` — subscribe action with loading/success states |
+| Footer | `footer` with logo, links, legal |
+
+### Files to create
+
+| File | Purpose |
+|---|---|
+| `src/pages/[name].js` | The page spec |
+| `public/themes/[name].css` | Brand theme |
+
+### State and action
+
+The page needs minimal state — only the newsletter form requires hydration:
+
+```js
+state: { status: 'idle' },
+
+actions: {
+  subscribe: {
+    onStart:   (state) => ({ status: 'loading' }),
+    run:       async (state, serverState, formData) => {
+                 const email = formData.get('email')
+                 if (!email) throw new Error('Email address is required')
+                 await yourEmailApi(email)
+                 return { email }
+               },
+    onSuccess: (state) => ({
+                 status: 'success',
+                 _toast: { message: 'Subscribed! Welcome aboard.', variant: 'success' },
+               }),
+    onError:   (state, err) => ({
+                 status: 'error',
+                 _toast: { message: err.message || 'Something went wrong.', variant: 'error' },
+               }),
+  },
+},
+```
+
+### Newsletter form — view pattern
+
+The form is state-driven. Show success confirmation once subscribed:
+
+```js
+state.status === 'success'
+  ? `<div class="u-flex u-items-center u-justify-center u-gap-2">
+       ${iconCheckCircle({ size: 20 })}
+       <span>You're subscribed. Clear skies ahead.</span>
+     </div>`
+  : `<form data-action="subscribe" novalidate>
+       <div class="u-flex u-gap-3 u-flex-wrap u-justify-center u-items-end">
+         ${input({ label: 'Email address', name: 'email', type: 'email', placeholder: 'your@email.com', required: true })}
+         ${button({
+           label: state.status === 'loading' ? 'Subscribing\u2026' : 'Subscribe',
+           type:  'submit',
+           attrs: state.status === 'loading' ? { 'aria-busy': 'true', disabled: '' } : {},
+         })}
+       </div>
+     </form>`
+```
+
+### Dark theme CSS pattern
+
+Dark theme overrides go in `:root` (not `[data-theme="light"]`):
+
+```css
+:root {
+  --ui-bg:          #hex;   /* darkest background */
+  --ui-surface:     #hex;   /* card / panel background */
+  --ui-surface-2:   #hex;   /* nested surface */
+  --ui-border:      rgba(..., 0.18);
+  --ui-accent:      #hex;   /* MUST pass 4.5:1 on --ui-bg */
+  --ui-accent-hover:#hex;
+  --ui-accent-dim:  rgba(..., 0.12);
+  --ui-accent-text: #hex;   /* text on accent-coloured backgrounds */
+  --ui-muted:       rgba(..., 0.7);
+}
+```
+
+Do NOT set `meta.theme: 'light'` on dark templates — the default pulse-ui theme is already dark.
+
+---
+
+## Adding a new template
+
+When you build a new template and want it available for future scaffolding:
+
+1. Add it to this guide under its own `##` section following the pattern above.
+2. Add a row to the "When to use a template" table.
+3. Update the MCP resource (`pulse://guide/templates`) — it is loaded from this file.

package/src/mcp/server.js

@@ -103,6 +103,13 @@ const GUIDE_RESOURCES = [
     description: 'Full working page examples including contact form with actions, validation, and error handling.',
     content:     () => GUIDE_EXAMPLES,
   },
+  {
+    name:        'guide-templates',
+    uri:         'pulse://guide/templates',
+    title:       'Pulse Guide — Templates & Scaffolding',
+    description: 'Ready-made page templates. Fetch this when the user asks to build a landing page, marketing site, or branded template — it lists triggers, pre-build questions, and adaptation rules for each template.',
+    content:     () => GUIDE_TEMPLATES,
+  },
 ]
 
 for (const { name, uri, title, description, content } of GUIDE_RESOURCES) {
@@ -887,7 +894,8 @@ const GUIDE_SERVER    = fs.readFileSync(new URL('../agent/guide-server.md',
 const GUIDE_STYLES    = fs.readFileSync(new URL('../agent/guide-styles.md',      import.meta.url), 'utf8')
 const GUIDE_ROUTING   = fs.readFileSync(new URL('../agent/guide-routing.md',     import.meta.url), 'utf8')
 const GUIDE_COMPONENTS = fs.readFileSync(new URL('../agent/guide-components.md', import.meta.url), 'utf8')
-const GUIDE_EXAMPLES  = fs.readFileSync(new URL('../agent/guide-examples.md',    import.meta.url), 'utf8')
+const GUIDE_EXAMPLES   = fs.readFileSync(new URL('../agent/guide-examples.md',   import.meta.url), 'utf8')
+const GUIDE_TEMPLATES  = fs.readFileSync(new URL('../agent/guide-templates.md', import.meta.url), 'utf8')
 
 // ---------------------------------------------------------------------------
 // The Persona — CLI-specific identity header + shared identity content
@@ -927,6 +935,7 @@ const PULSE_GUIDE_INDEX = `# Pulse Framework Guide
 | \`pulse://guide/routing\` | Navigation, page discovery, dynamic routes |
 | \`pulse://guide/components\` | All UI components, icons, charts, composition patterns |
 | \`pulse://guide/examples\` | Complete working page examples |
+| \`pulse://guide/templates\` | **Fetch when asked to build a landing page or branded template.** Pre-build questions, template inventory, adaptation rules, theme CSS patterns. |
 
 ## Tools available
 

package/src/ui/icons.js

@@ -181,7 +181,11 @@ export const iconBarChart = (o) => s('<line x1="18" y1="20" x2="18" y2="10"/><li
 
 // ─── Writing ─────────────────────────────────────────────────────────────────
 
-export const iconFeather      = (o) => s('<path d="M20.24 12.24a6 6 0 0 0-8.49-8.49L5 10.5V19h8.5z"/><line x1="16" y1="8" x2="2" y2="22"/><line x1="17.5" y1="15" x2="9" y2="15"/>', opts(o))
+export const iconFeather   = (o) => s('<path d="M20.24 12.24a6 6 0 0 0-8.49-8.49L5 10.5V19h8.5z"/><line x1="16" y1="8" x2="2" y2="22"/><line x1="17.5" y1="15" x2="9" y2="15"/>', opts(o))
+
+// ─── Astronomy ───────────────────────────────────────────────────────────────
+
+export const iconTelescope = (o) => s('<path d="M3 17L20 6 22 8 5 19z"/><line x1="13" y1="14" x2="13" y2="21"/><line x1="9" y1="21" x2="17" y2="21"/>', opts(o))
 
 // ─── Ecommerce ───────────────────────────────────────────────────────────────
 

package/src/ui/index.js

@@ -88,6 +88,7 @@ export {
   iconGlobe, iconShield, iconZap, iconTrendingUp, iconTrendingDown, iconLoader, iconGrid, iconBug, iconMapPin,
   iconSun, iconMoon,
   iconFeather,
+  iconTelescope,
   iconAi, iconSmile, iconBarChart,
   iconShoppingCart, iconShoppingBag, iconCreditCard, iconPackage, iconGift,
   iconWallet, iconTruck, iconReceipt, iconStore, iconPercent, iconTicket, iconBanknote,