@invisibleloop/pulse 0.12.3 → 0.14.2

package/src/agent/guide-explore.md

@@ -0,0 +1,313 @@
+# Pulse Explore Guide — Blank-Canvas Layout Thinking
+
+This guide is for when you want a site that feels **distinct**, not just correct. It teaches structure-first thinking: start with layout zones and emotional intent, not with which template to adapt.
+
+> Read this when `pulse_sketch` suggests an unusual layout, when the user says "make it feel different", or when no template in `pulse://guide/templates` is a good fit.
+
+---
+
+## The Problem with Defaulting to Components
+
+Every Pulse component is well-built. That's also their risk: they pull strongly toward a recognisable vocabulary — centred hero, three-column features, testimonial cards. A dog groomer and a hedge fund built with default components will look like cousins.
+
+**The escape hatch is always available.** The `view` function is raw HTML. You can use:
+- Zero components — just utility classes and inline HTML
+- A mix of raw layout with components for specific elements (nav, footer, forms)
+- Component structure with overridden CSS via app.css class rules
+
+> **Note on inline styles:** The raw HTML patterns in this guide use `style=` attributes for clarity. In your own specs, move those rules into `app.css` as named classes — the `pulse_review` checklist will flag inline styles as a smell, and they can't be overridden cleanly. The pattern is: sketch with inline styles → extract to `app.css` classes → done.
+
+---
+
+## Start with Intent, Not Components
+
+Before opening `pulse://guide/components`, answer three questions:
+
+### 1. What is the emotional job?
+Not "what does the page contain" but "how should the user feel 30 seconds after landing?"
+
+| Feeling | Layout signal |
+|---|---|
+| Trust / authority | Wide margins, generous whitespace, restrained type, no decoration |
+| Energy / urgency | Full-bleed images, bold type, tight spacing, strong diagonals |
+| Warmth / handmade | Irregular layout, slight tilts, texture, serif body text |
+| Precision / technical | Monospace accents, grid-aligned everything, data tables, no fluff |
+| Playful / surprising | Breaking the grid, overlapping elements, unexpected colour pops |
+| Editorial / serious | Long reading width, pullquotes, photo captions, no eyebrow badges |
+
+### 2. What is the dominant structural gesture?
+One of these should describe the entire page:
+
+- **Full-bleed** — images or colour fills edge-to-edge, type floats over them
+- **Offset split** — persistent asymmetry: content always 60/40 or 70/30, never centered
+- **Vertical rhythm** — everything stacked, each section separated by whitespace not dividers
+- **Dense grid** — information-rich, small gutters, horizontal scannable
+- **Long-form** — single narrow column, essay-like, designed for reading not scanning
+- **Kinetic** — scrolling triggers layout shifts (parallax, sticky elements, revealed content)
+
+### 3. What should it NOT look like?
+Name something to avoid. "Not another SaaS dark card page." "Not a startup landing page." "Not like it was made with a template."
+
+This negative constraint is often more useful than the positive one.
+
+---
+
+## Layout Zones Approach
+
+Design the page as zones before deciding what fills them:
+
+```
+┌─────────────────────────────────────────┐
+│  IDENTITY ZONE                          │  ← Name, logo, hook. First impression.
+│  (full-bleed image? type only? split?)  │
+├─────────────────────────────────────────┤
+│  PROOF ZONE                             │  ← Why believe it? Numbers, names, photos.
+│  (stats? logos? photos? quote?)         │
+├─────────────────────────────────────────┤
+│  DETAIL ZONE                            │  ← What exactly do you offer?
+│  (features? services? work? prices?)    │
+├─────────────────────────────────────────┤
+│  TRUST ZONE                             │  ← Social proof, credentials, story.
+│  (testimonials? about? process?)        │
+├─────────────────────────────────────────┤
+│  ACTION ZONE                            │  ← The ask. Form, CTA, booking, purchase.
+└─────────────────────────────────────────┘
+```
+
+The *order* and *proportion* of these zones is a design decision. A personal trainer might lead with PROOF (transformation photos) before IDENTITY. A law firm might bury the ACTION ZONE beneath extensive TRUST ZONE content.
+
+**Reordering zones is one of the cheapest ways to feel distinctive.**
+
+---
+
+## Raw HTML Patterns (Zero Components)
+
+These are layouts that deliberately use no Pulse components except `nav` and `footer`. They demonstrate what's possible.
+
+### Full-Bleed Typography Hero
+```js
+const typographicHero = `
+<section style="
+  min-height: 100svh;
+  display: grid;
+  place-items: center;
+  background: var(--ui-bg);
+  padding: var(--ui-space-8);
+">
+  <div style="max-width: 900px; text-align: center;">
+    <p style="
+      font-size: clamp(0.75rem, 1.5vw, 0.875rem);
+      letter-spacing: 0.15em;
+      text-transform: uppercase;
+      color: var(--ui-muted);
+      margin-bottom: var(--ui-space-6);
+    ">Est. 2024 · London</p>
+    <h1 style="
+      font-size: clamp(3rem, 10vw, 8rem);
+      font-weight: 800;
+      line-height: 0.9;
+      letter-spacing: -0.04em;
+      color: var(--ui-text);
+    ">The Work<br>Speaks for<br>Itself.</h1>
+    <a href="#work" style="
+      display: inline-block;
+      margin-top: var(--ui-space-10);
+      padding: var(--ui-space-4) var(--ui-space-8);
+      border: 1px solid var(--ui-border);
+      color: var(--ui-text);
+      text-decoration: none;
+      font-size: 0.875rem;
+      letter-spacing: 0.05em;
+    ">View Work ↓</a>
+  </div>
+</section>
+`
+```
+
+### Asymmetric Split (Persistent Offset)
+```js
+const asymmetricHero = `
+<section style="
+  min-height: 100svh;
+  display: grid;
+  grid-template-columns: 1fr 1.6fr;
+">
+  <div style="
+    background: var(--ui-bg-alt);
+    padding: var(--ui-space-16) var(--ui-space-8);
+    display: flex;
+    flex-direction: column;
+    justify-content: flex-end;
+  ">
+    <p style="color:var(--ui-muted);font-size:0.75rem;letter-spacing:0.1em;text-transform:uppercase;margin-bottom:var(--ui-space-4)">Dog grooming · Maplewood</p>
+    <h1 style="font-size:clamp(2rem,4vw,3.5rem);font-weight:700;line-height:1.1;letter-spacing:-0.02em;color:var(--ui-text)">Your dog,<br>beautifully<br>groomed.</h1>
+    <a href="#book" style="display:inline-flex;align-items:center;gap:0.5rem;margin-top:var(--ui-space-8);color:var(--ui-text);text-decoration:none;font-weight:500">
+      Book now <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M5 12h14M12 5l7 7-7 7"/></svg>
+    </a>
+  </div>
+  <div style="overflow:hidden;">
+    <img src="${imageUrl}" alt="${imageAlt}" style="width:100%;height:100%;object-fit:cover;">
+  </div>
+</section>
+`
+```
+
+### Stacked Long-Form (Essay / Blog)
+```js
+const essayLayout = `
+<article style="
+  max-width: 680px;
+  margin: 0 auto;
+  padding: var(--ui-space-16) var(--ui-space-6);
+">
+  <header style="margin-bottom: var(--ui-space-12);">
+    <p style="font-size:0.75rem;letter-spacing:0.1em;text-transform:uppercase;color:var(--ui-muted);margin-bottom:var(--ui-space-3)">
+      ${category} · ${date} · ${readTime}
+    </p>
+    <h1 style="font-size:clamp(2rem,4vw,3rem);font-weight:700;line-height:1.15;letter-spacing:-0.02em;margin-bottom:var(--ui-space-4)">
+      ${title}
+    </h1>
+    <p style="font-size:1.125rem;color:var(--ui-muted);line-height:1.6;">${deck}</p>
+    <div style="display:flex;align-items:center;gap:1rem;margin-top:var(--ui-space-6);padding-top:var(--ui-space-6);border-top:1px solid var(--ui-border);">
+      <img src="${authorAvatar}" alt="${authorName}" style="width:40px;height:40px;border-radius:50%;object-fit:cover;">
+      <div>
+        <p style="font-weight:500;font-size:0.875rem;">${authorName}</p>
+        <p style="color:var(--ui-muted);font-size:0.75rem;">${authorRole}</p>
+      </div>
+    </div>
+  </header>
+  <img src="${heroImage}" alt="" style="width:100%;aspect-ratio:16/9;object-fit:cover;margin-bottom:var(--ui-space-10);">
+  <div style="font-size:1.0625rem;line-height:1.75;color:var(--ui-text);">
+    ${bodyHtml}
+  </div>
+</article>
+`
+```
+
+### Dense Grid (Portfolio / Gallery)
+```js
+const denseGrid = `
+<section style="
+  padding: var(--ui-space-4);
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
+  gap: var(--ui-space-3);
+">
+  ${items.map(item => `
+    <a href="${item.href}" style="
+      display: block;
+      overflow: hidden;
+      position: relative;
+      aspect-ratio: 4/3;
+      background: var(--ui-bg-alt);
+    ">
+      <img src="${item.img}" alt="${item.title}" style="width:100%;height:100%;object-fit:cover;transition:transform 0.4s ease;">
+      <div style="
+        position:absolute;inset:0;
+        background:linear-gradient(to top, rgba(0,0,0,0.6) 0%, transparent 50%);
+        display:flex;align-items:flex-end;padding:var(--ui-space-4);
+        opacity:0;transition:opacity 0.3s ease;
+      " class="grid-overlay">
+        <p style="color:#fff;font-weight:500;font-size:0.875rem;">${item.title}</p>
+      </div>
+    </a>
+  `).join('')}
+</section>
+`
+```
+
+---
+
+## Mixing Raw Layout with Pulse Components
+
+You don't have to choose all-or-nothing. Common hybrid pattern:
+
+```js
+view: () => `
+  ${uiNav({ ... })}                  ← Use nav — it handles mobile burger, sticky, a11y
+
+  <section style="...raw layout...">  ← Raw hero with your own structure
+    ...
+  </section>
+
+  ${section({                         ← Use section for padding + background variant
+    variant: 'alt',
+    content: grid({ ... })            ← Use grid for the responsive column system
+  })}
+
+  ${cta({ ... })}                     ← Use cta — saves 10 lines and is a11y correct
+
+  ${footer({ ... })}                 ← Use footer — handles all the footer layout
+`
+```
+
+**Rule of thumb:** Use Pulse components for global chrome (nav, footer), repeating patterns (cards, testimonials, features), and interactive elements (buttons, forms, modals). Use raw HTML for hero sections, custom layouts, and any zone where the default shape doesn't serve the design.
+
+---
+
+## CSS Custom Properties Available Everywhere
+
+Even in raw HTML, you have the full design token system:
+
+```css
+/* Colours */
+var(--ui-bg)           /* page background */
+var(--ui-bg-alt)       /* slightly offset background (cards, alternating sections) */
+var(--ui-surface)      /* elevated surface (modals, dropdowns) */
+var(--ui-text)         /* primary text */
+var(--ui-muted)        /* secondary / caption text */
+var(--ui-border)       /* divider / outline color */
+var(--ui-accent)       /* brand accent (buttons, links, highlights) */
+
+/* Spacing */
+var(--ui-space-1)      /* 0.25rem */
+var(--ui-space-2)      /* 0.5rem */
+var(--ui-space-3)      /* 0.75rem */
+var(--ui-space-4)      /* 1rem */
+var(--ui-space-6)      /* 1.5rem */
+var(--ui-space-8)      /* 2rem */
+var(--ui-space-10)     /* 2.5rem */
+var(--ui-space-12)     /* 3rem */
+var(--ui-space-16)     /* 4rem */
+
+/* Typography */
+var(--ui-font)         /* body font stack */
+var(--ui-radius)       /* base border-radius (affected by vibe) */
+var(--ui-radius-lg)    /* larger radius */
+
+/* Shadows */
+var(--ui-shadow-sm)    /* subtle card shadow */
+var(--ui-shadow)       /* standard shadow */
+var(--ui-shadow-lg)    /* large shadow */
+```
+
+Use `clamp()` for fluid type: `font-size: clamp(2rem, 5vw, 4rem)` — scales smoothly across breakpoints.
+
+---
+
+## The 3-Layout Rule
+
+Before writing any code, sketch 3 structurally different options for the hero / above-the-fold zone. Even one sentence each:
+
+> Option A: Full-bleed photo, title in bottom-left corner, text reversed out of image  
+> Option B: 60/40 split — headline left, product photo right, earthy cream background  
+> Option C: Typography-only, massive headline, minimal, no image — lets the copy breathe
+
+Then choose the one that matches the emotional intent. If you can't decide, pick the most unusual one.
+
+**The `pulse_sketch` tool automates this** — call it with a brief description and it returns 3 structured layout directions ready to choose from.
+
+---
+
+## Anti-Pattern Checklist
+
+These are the signs a design has defaulted to template mode rather than intent:
+
+- [ ] Hero is centred with eyebrow badge + large title + subtitle + two buttons
+- [ ] Three-column feature grid with icon + heading + body
+- [ ] Testimonials are all in cards with quote + author name
+- [ ] Every section alternates white/light-grey backgrounds
+- [ ] The nav has a logo on the left, links in the middle, CTA on the right
+- [ ] The footer has the same logo, same links, and a copyright line
+
+None of these are wrong. But if they're all there together, the page will look like every other Pulse page. Consider swapping at least 2 of the 6 for something more distinctive.

package/src/agent/guide-styles.md

@@ -16,8 +16,37 @@ Non-interactive components (nav, hero, button, card, etc.) only need '/pulse-ui.
 
 pulse-ui.css exposes CSS custom properties for every token. app.css MUST use these tokens — never hardcode colour hex values.
 
-Override tokens in :root inside app.css to retheme all components at once:
+### How theming works — two-layer token system
+
+Pulse uses a **two-layer token system**:
+
+1. **Input tokens** (unprefixed: `--bg`, `--text`, `--accent`, etc.) — you define these in `:root` or `[data-theme="light"]` to set your palette
+2. **Output tokens** (prefixed: `--ui-bg`, `--ui-text`, `--ui-accent`, etc.) — pulse-ui components read these; you reference them in app.css
+
+pulse-ui.css sets `--ui-*` tokens to `var(--your-input-token, fallback)`. When you override `--accent`, components automatically pick it up via `--ui-accent`.
+
+**Which token names to use where:**
+
+| File | Define input tokens | Reference output tokens |
+|---|---|---|
+| `public/theme.css` | ✓ `--accent: #e25;` | — |
+| `app.css` | — | ✓ `color: var(--ui-accent);` |
+| Pulse components | — | ✓ (already done internally) |
+
+**Common mistake:** defining `--color-accent` or `--brand-primary` expecting components to use them. Components only read the canonical unprefixed names: `--accent`, `--text`, `--bg`, `--surface`, `--border`, `--muted`, `--radius`. Define those, and everything updates.
+
+### Dark by default
+
+**The library is dark by default.** `pulse-ui.css` applies `background-color: var(--ui-bg)` and `color: var(--ui-text)` to `html, body` automatically using the dark palette defined in `:root` — you do NOT need to add these to app.css.
+
+For a **light theme**, set `meta.theme: 'light'` in the spec — this adds `data-theme="light"` to the `<body>` and activates the built-in light token set (accessible contrast for badges, alerts, and all semantic colours).
+
+### Overriding tokens in your theme
+
+Override input tokens to retheme all components at once. The pattern is the same for both dark and light themes — set the unprefixed input token in the appropriate selector:
+
 ```css
+/* Dark theme overrides — in :root */
 :root {
   --bg:           #0d0d10;   /* page background */
   --surface:      #111116;   /* card / panel background */
@@ -29,8 +58,17 @@ Override tokens in :root inside app.css to retheme all components at once:
   --accent-hover: #b5aaff;
   --radius:       8px;
 }
+
+/* Light theme overrides — in [data-theme="light"] */
+[data-theme="light"] {
+  --bg:           #ffffff;
+  --surface:      #f5f5fa;
+  --accent:       #e25;       /* overrides the light default #6b5ce7 */
+}
 ```
 
+pulse-ui.css maps input → output via `var()` in **both** the dark (`:root`) and light (`[data-theme="light"]`) blocks, so the same two-layer pattern works in both themes.
+
 Then use the computed --ui-* tokens everywhere in app.css:
 ```css
 /* pulse-ui.css already sets background-color and color on html/body — do not repeat them */
@@ -40,28 +78,64 @@ a    { color: var(--ui-accent); }
 code { background: var(--ui-surface-2); color: var(--ui-accent); border: 1px solid var(--ui-border); }
 ```
 
-**The library is dark by default.** `pulse-ui.css` applies `background-color: var(--ui-bg)` and `color: var(--ui-text)` to `html, body` automatically — you do NOT need to add these to app.css.
+> **Light theme escape hatch:** if you need to override a specific output token that has no input equivalent, you can set `--ui-accent` directly inside `[data-theme="light"]` — but prefer input tokens wherever possible.
+
+```js
+meta: {
+  theme: 'light',
+  styles: ['/pulse-ui.css', '/app.css'],
+}
+```
+
+**Colour tokens:** `--ui-bg`, `--ui-surface`, `--ui-surface-2`, `--ui-border`, `--ui-text`, `--ui-muted`, `--ui-accent`, `--ui-accent-hover`, `--ui-accent-dim`, `--ui-accent-text`, `--ui-green`, `--ui-red`, `--ui-yellow`, `--ui-blue`, `--ui-radius`, `--ui-radius-sm`, `--ui-font`, `--ui-font-display`, `--ui-mono`. Never hardcode hex values — override the tokens.
+
+> **⚠ `--ui-muted` contrast on warm/light palettes** — The default `--ui-muted` value (`#60607a` in light theme) achieves 4.5:1 on the default white `--ui-bg`. When you set a warm or coloured background (`--bg: #f5e6d3` etc.) the luminance difference shrinks and `--ui-muted` can drop below the WCAG AA threshold of 4.5:1. **Always override `--muted` when changing `--bg`**, and run `pulse_check_contrast` immediately after writing your `theme.css`. A common failure mode: stat labels, nav links, and feature descriptions all use `--ui-muted` and will fail contrast silently if this token is not rechecked against your actual background colour.
 
-To apply a **light theme**, set `meta.theme: 'light'` in the spec — this adds `data-theme="light"` to the `<body>` and activates the built-in light token set (accessible contrast for badges, alerts, and all semantic colours). Do NOT manually copy token values into `:root`.
+> **⚠ `section--dark` in light theme** — `section({ variant: 'dark' })` uses `--ui-surface-2` as its background, which in the default light theme resolves to `#f0f0f8` — a light grey, not a dark background. The framework now auto-corrects this via a `[data-theme="light"] .ui-section--dark` override (navy `#1a1a2e`), and ghost buttons inside it get automatic light-text treatment. If you use a custom `--surface-2` override in your theme, set `--ui-dark-bg` and `--ui-dark-text` to pin the dark section to specific values:
+> ```css
+> [data-theme="light"] { --ui-dark-bg: #1a1a2e; --ui-dark-text: #e8e0d0; }
+> ```
 
-**Overriding tokens on a light-theme page:** `pulse-ui.css` defines light theme values under `[data-theme="light"]`, which has higher specificity than `:root`. Overrides written only to `:root` will be silently beaten. Always target `[data-theme="light"]` when overriding tokens for a light-theme page:
+> **Ghost buttons on dark backgrounds** — use `variant: 'ghost-light'` instead of `variant: 'ghost'` whenever the button sits on a dark background (custom hero div, `section--dark`, navy sections). `ghost-light` renders white text with a subtle white border, maintaining 4.5:1 contrast regardless of the surrounding theme. `ghost` uses `--ui-muted` text which fails on dark backgrounds in light theme.
 
+**Display font token:** `--ui-font-display` is used for hero titles and section headings. By default it inherits `--ui-font`. Override it separately to get a display/heading face that differs from body text:
 ```css
-/* WRONG — loses to pulse-ui.css */
-:root { --ui-accent: #e25; }
+/* app.css */
+:root { --font-display: 'Playfair Display', Georgia, serif; }
+```
 
-/* CORRECT */
-[data-theme="light"] { --ui-accent: #e25; }
+**Letter-spacing token:** `--ui-letter-spacing-display` (default `-0.025em`) controls heading tightness. Override in `:root` to match your typeface:
+```css
+:root { --letter-spacing-display: -0.04em; }  /* tighter for heavy condensed fonts */
 ```
 
+## Visual personality — meta.vibe
+
+`meta.vibe` sets `data-vibe` on `<body>` and adjusts geometry + type tokens as a preset. It doesn't touch colour — pair it with a `theme.css` for full personality.
+
 ```js
 meta: {
-  theme: 'light',
-  styles: ['/pulse-ui.css', '/app.css'],
+  vibe:   'warm',   // warm | editorial | playful | minimal | bold
+  theme:  'light',
+  styles: ['/pulse-ui.css', '/theme.css', '/app.css'],
 }
 ```
 
-**Colour tokens:** `--ui-bg`, `--ui-surface`, `--ui-surface-2`, `--ui-border`, `--ui-text`, `--ui-muted`, `--ui-accent`, `--ui-accent-hover`, `--ui-accent-dim`, `--ui-accent-text`, `--ui-green`, `--ui-red`, `--ui-yellow`, `--ui-blue`, `--ui-radius`, `--ui-radius-sm`, `--ui-font`, `--ui-mono`. Never hardcode hex values — override the tokens.
+| Vibe | Effect | Pairs well with |
+|---|---|---|
+| `warm` | radius 14px, softer letter-spacing | rounded photo cards, `section: paper`, warm palette |
+| `editorial` | radius 0, serif display font, tight letter-spacing | `hero layout: overlap`, `section: diagonal`, `pullquote` |
+| `playful` | radius 22px, neutral letter-spacing | `gallery` with rounded images, `marquee`, bright accent |
+| `minimal` | radius 2px, open letter-spacing, no shadows | left-aligned hero, `section: spotlight`, monochrome |
+| `bold` | radius 6px, very tight letter-spacing | `section: dark`, large `stat` components, gradient hero |
+
+Vibes affect `--ui-radius`, `--ui-font-display`, and `--ui-letter-spacing-display`. All component shapes, borders, and heading appearance change automatically.
+
+**Custom override:** Set vibe first, then fine-tune with CSS variable overrides in `public/theme.css`:
+```css
+/* Fine-tune the warm vibe */
+[data-vibe="warm"] { --ui-radius: 18px; }
+```
 
 **Spacing tokens** (`--ui-space-N`): `--ui-space-1` (4px), `--ui-space-2` (8px), `--ui-space-3` (12px), `--ui-space-4` (16px), `--ui-space-5` (20px), `--ui-space-6` (24px), `--ui-space-8` (32px), `--ui-space-10` (40px), `--ui-space-12` (48px), `--ui-space-16` (64px), `--ui-space-20` (80px), `--ui-space-24` (96px). Use these for `padding`, `margin`, and `gap`.
 
@@ -119,6 +193,49 @@ Then in app.css:
 
 If you cannot modify `createServer` (e.g. the project uses auto-discovery), use a self-hosted font in `public/fonts/` with `@font-face` in `app.css` — no CSP changes needed.
 
+### External images (img-src)
+
+The default CSP does **not** restrict `img-src` — it inherits `default-src 'self'`, which means images served from the same origin load fine. But if you load images from an external host (e.g. `https://images.unsplash.com`, `https://picsum.photos`, a CDN), you must add the host to `img-src`.
+
+**Do this at build time, before writing any image tags.** If you know you'll use external images, add the CSP entry to `pulse.config.js` first — discovering the block at Lighthouse time costs an extra round-trip.
+
+```js
+// pulse.config.js
+export default {
+  csp: {
+    'img-src': ['https://picsum.photos', 'https://fastly.picsum.photos'],
+  },
+}
+```
+
+Or via `createServer`:
+
+```js
+createServer(specs, {
+  csp: {
+    'img-src': ['https://images.unsplash.com', 'https://picsum.photos'],
+  },
+})
+```
+
+**Common hosts to add:**
+| Source | `img-src` entry |
+|---|---|
+| picsum.photos | `https://picsum.photos https://fastly.picsum.photos` |
+| Unsplash | `https://images.unsplash.com` |
+| Cloudinary | `https://res.cloudinary.com` |
+| Imgix | your subdomain, e.g. `https://mysite.imgix.net` |
+
+> **picsum CDN note:** `picsum.photos` redirects image requests through `fastly.picsum.photos`. You must whitelist **both** domains — whitelisting only `https://picsum.photos` will still block the actual image bytes and the browser error will point to the `fastly.picsum.photos` URL, which is confusing to debug.
+
+> **⚠ Unsplash and third-party cookies — Lighthouse Best Practices failure:** `images.unsplash.com` sets tracking cookies (`azk`, `azk-ss`) on every image request. These are classified as third-party cookies and cause Lighthouse Best Practices to drop to ~77, failing the 100 pass bar. **For production builds, download images locally instead of referencing Unsplash URLs directly.** Use `curl` to save images to `public/images/`:
+> ```bash
+> curl -sL "https://images.unsplash.com/photo-ID?w=900&q=85" -o public/images/hero.jpg
+> ```
+> Then reference `/images/hero.jpg` in your spec. This also improves performance (no external DNS lookup) and avoids rate limiting. `picsum.photos` does **not** set tracking cookies and is safe to use via CDN for prototypes.
+
+Without this, external images will be blocked in production and Lighthouse will flag a Best Practices failure. Use the same pattern for other external resource types (`media-src` for video, `connect-src` for fetch/XHR to external APIs).
+
 For multiple weights or italic variants, separate them with a semicolon in the URL:
 ```
 ?family=Inter:ital,wght@0,400;0,700;1,400&display=swap
@@ -171,6 +288,33 @@ For multi-brand sites, keep `@font-face` declarations (or the font service URL)
 
 ## CSS rules — where to put styles and when to use utilities
 
+### The hex colour rule — know this upfront
+
+There are three places you write colour values. The rules are different for each:
+
+| Where | Hex/raw values | `var(--ui-*)` tokens | Inline `style=""` |
+|---|---|---|---|
+| `public/theme.css` or `public/themes/*.css` | **✓ allowed** — this is where palette values live | ✓ allowed | — |
+| `app.css` or any `.css` file in `public/` | **✗ blocked by lint** | **✓ required** | — |
+| JS spec files (the `view` function) | **✓ allowed** (e.g. `color: '#fff'` on component props) | ✓ allowed | **✗ avoid** |
+
+The rule in plain English: **CSS files reference tokens; theme files define them.** JS spec files are exempt because component props like `hero({ background: '#1a1a2e' })` are intentional design overrides, not CSS authoring.
+
+**Common mistake:** Writing `--ui-accent: #e25;` directly in `app.css`. This trips the lint. Move it to `public/theme.css` (dark theme in `:root`) or `public/themes/brand.css` (light theme in `[data-theme="light"]`).
+
+```css
+/* public/theme.css — hex values live here ✓ */
+[data-theme="light"] { --ui-accent: #e25; }
+
+/* app.css — var() only ✓ */
+.hero { color: var(--ui-accent); }
+
+/* app.css — this will be blocked ✗ */
+.hero { color: #e25; }
+```
+
+Load order in `meta.styles` matters: `pulse-ui.css` → `theme.css` → `app.css`. Theme tokens must exist before `app.css` references them.
+
 RULE: Never use inline style attributes (style="...") in HTML. Always use classes.
 
 RULE: For spacing, typography, layout, and colour, always prefer pulse-ui utility classes first. Only add to app.css if you need something the utilities cannot provide (e.g. a unique component style, a keyframe animation, a custom grid).
@@ -218,3 +362,60 @@ Example — a centred hero block using only utilities, no custom CSS:
 ```
 
 When you DO need to write CSS, add it to public/app.css — never inline.
+
+
+## Placeholder images for prototypes
+
+**Use `picsum.photos` with numeric IDs for anything Lighthouse-audited.** Unsplash direct IDs rotate and 404 without warning. Picsum seeds are convenient for development but can return `ERR_CONNECTION_CLOSED` under Lighthouse's burst-load pattern — use numeric IDs for pages you'll audit:
+
+```html
+<!-- Best for Lighthouse: numeric IDs — stable under burst load -->
+<img src="https://picsum.photos/id/10/1200/600" alt="..." width="1200" height="600">
+<img src="https://picsum.photos/id/64/80/80" alt="..." width="80" height="80">
+
+<!-- OK for dev / visual work only: seeds can fail under Lighthouse burst -->
+<img src="https://picsum.photos/seed/hero/1200/600" alt="..." width="1200" height="600">
+```
+
+The numeric ID is sequential (1–1000+). Browse options at `https://picsum.photos/images`. Use numeric IDs whenever you're running Lighthouse — seeds are fine for screenshots and dev iteration.
+
+**Avoid:** `https://images.unsplash.com/photo-LONGID?...` — these are unstable for prototypes. If you use Unsplash, add `https://images.unsplash.com` to `csp.img-src` in `pulse.config.js`, and expect some IDs to rot.
+
+> **Unsplash photo IDs must be the full hash.** The format is `photo-` followed by an 11-character alphanumeric hash, e.g. `photo-1506905925346-21bda4d32df4`. A truncated or partial ID (e.g. `photo-1506905925346`) returns a 404 silently — the image is missing with no obvious error. Always copy the full ID from the Unsplash URL.
+
+
+## CSS gotchas
+
+### calc() with + and − requires whitespace
+
+The CSS specification **requires** whitespace around `+` and `−` inside `calc()` when either operand is a value that starts with a sign (including CSS custom properties, since their resolved value may start with `−`):
+
+```css
+/* ✓ CORRECT — spaces around + */
+padding-top: calc(64px + var(--ui-space-16));
+
+/* ✗ WRONG — will silently fail in browsers, padding becomes 0 */
+padding-top: calc(64px+var(--ui-space-16));
+```
+
+The Pulse production CSS minifier preserves these spaces. Never manually collapse `calc()` expressions.
+
+### Padding shorthand vs. longhand ordering
+
+CSS processes declarations top-to-bottom. A shorthand that appears **after** a longhand will silently override it:
+
+```css
+/* ✗ WRONG — padding-top: 0 because shorthand resets it */
+.block {
+  padding-top: var(--ui-space-8);  /* set */
+  padding: 0 var(--ui-space-6);   /* shorthand resets padding-top to 0 */
+}
+
+/* ✓ CORRECT — shorthand first, longhand overrides */
+.block {
+  padding: 0 var(--ui-space-6);
+  padding-top: var(--ui-space-8);
+}
+```
+
+This produces no browser error and is invisible at a glance — the expected spacing just doesn't appear. Always write shorthand before longhand in the same declaration block.