@invisibleloop/pulse 0.10.1 → 0.11.0

package/docs/src/pages/templates/mobile-app.js

@@ -304,7 +304,7 @@ const downloadCta = section({
 
 const pageFooter = footer({
   logo:     `${iconFeather({ size: 18 })}<span class="u-font-bold" style="letter-spacing:-0.02em">Lumio</span>`,
-  logoHref: '#',
+  logoHref: '/',
   links: [
     { label: 'Privacy',  href: '#' },
     { label: 'Terms',    href: '#' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.10.1",
+  "version": "0.11.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.1
+0.11.0

package/src/agent/guide-templates.md

@@ -0,0 +1,154 @@
+# 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" |
+
+---
+
+## 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.
+
+---
+
+## 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