spirewise 1.7.0 → 1.8.0

package/skills/motion-storytelling-design-system/example-page-structures.md

@@ -0,0 +1,91 @@
+# Example Page Structures — Motion Storytelling
+
+Ready-to-assemble, **scroll-narrative** page blueprints. Each section names a layout (see
+`layout-system.md`) and components (see `component-library.md`). Every page tells a story
+through scenes — pinned/scrub/reveal — with big beats alternating with calm passages. No
+borders between sections (separate by whitespace + animated background/scene transitions).
+
+Legend: `SH-* / ST-* / F-* / P-* / C-* / Q-* / FT-*` layouts · components by name.
+
+## MANDATORY: 15+ page site map (≈20), 10+ scenes/page, clean URLs
+
+Always ship a **full multipage website with 15+ pages (≈20)** — never a single landing page.
+Every page carries **at least 10 sections/scenes (≈12)**, **no borders/dividers between
+sections**, pure HTML/CSS/vanilla JS, **extensionless URLs**, and **reduced-motion + no
+scroll-jack** behavior. Required 20-page map:
+
+```
+/                Home              /customers      Customers
+/platform        Platform          /case-studies   Case Studies
+/solutions       Solutions         /developers     Developers
+/products        Products          /docs           Documentation  ← + DOC-A subpages
+/features        Features          /about          About
+/ai-agents       AI Agents         /careers        Careers
+/enterprise      Enterprise        /blog           Blog           ← + article pages
+/security        Security          /contact        Contact
+/pricing         Pricing           /partners       Partners
+                                   /resources      Resources   /faq  FAQ
+```
+
+Each blueprint below is a **10-scene** skeleton — extend toward 12, never fewer than 10.
+Every page must include: **Hero (kinetic/scrub) · Feature Scenes · Product Highlights ·
+Trust Signals · Testimonials · Use Cases · Statistics · Integrations · CTA (finale) ·
+Footer.** Mix big beats with calm passages.
+
+---
+
+## 1. Home (default) — the narrative arc
+1. **Navbar** + **Scroll Progress** — extensionless links
+2. **Hero** `SH-A/SH-B` — kinetic display H1 + scrub/atmosphere  ← big beat (opener)
+3. **Logos Section** — staggered reveal (calm)
+4. **Pinned narrative** `ST-A` — one product, 3 beats as copy swaps  ← big beat (setup)
+5. **Scrubbed demo** `ST-B` — product assembles on scroll  ← big beat (product)
+6. **Feature Grid** `F-A` — Reveal Timeline (calm)
+7. **Statistics** — count-up metrics (calm proof)
+8. **Testimonials** — quotes (reveal or pinned swap)
+9. **Pricing** `P-A` (or teaser) — light motion
+10. **CTA finale** `C-A` (parallax payoff) + **Footer** `FT-A`
+
+## 2. Platform / Product
+1. Navbar · 2. **Hero** scrub `SH-B` · 3. **Pinned narrative** `ST-A` · 4. **Dashboard
+Preview** (Pinned Sequence) · 5. **Parallax layers** `ST-E` feature · 6. Code Preview (type
+on reveal) · 7. Use Cases (reveal) · 8. **Statistics** · 9. Testimonials · 10. CTA finale + Footer
+
+## 3. Features
+1. Navbar · 2. Hero · 3.–8. alternating **feature scenes** (`ST-A` pinned / `ST-B` scrub /
+`ST-C` reveal / `ST-D` horizontal — used once, accessible) with calm sections between · 9.
+Integrations · 10. CTA finale + Footer
+
+## 4. Developers / Documentation
+- **Developers:** Navbar · **Hero** with **Terminal/Code** typing on scroll · Logos · Code
+  Preview (scrub/highlight) · Pinned "how it works" narrative · Use Cases · Statistics · CTA
+  ("Read docs"/"Get API key") · Footer (≥10).
+- **Docs:** `DOC-A` three-pane, **mostly static** (reading), light reveals only — **never
+  gate docs content behind motion**; breadcrumb; sticky nav.
+
+## 5. Enterprise / Security
+1. Navbar · 2. Hero (outcome-led) · 3. Logos · 4. Pinned narrative · 5. **Enterprise** scene ·
+6. **Security** scene · 7. **Statistics**/ROI · 8. Testimonials (exec) · 9. CTA finale (contact)
+· 10. Footer
+
+## 6. Pricing
+1. Navbar · 2. Hero (short + toggle) · 3. **Pricing** `P-A/P-B` (light motion) · 4. Feature
+comparison (reveal) · 5. Enterprise band · 6. Logos · 7. Statistics · 8. Testimonials · 9.
+**FAQ** `Q-A` · 10. CTA finale + Footer  (keep decision moments calm — don't over-animate)
+
+## 7. Content pages (About, Customers, Case Studies, Careers, Blog, Partners, Resources, Contact, FAQ)
+Reach **≥10 scenes** via story: Hero → narrative/story scenes (timeline of the company,
+customer story scrubs, case-study walkthroughs) → Trust Signals → Statistics → Testimonials →
+Integrations → CTA finale → Footer. **Blog articles stay reading-first** (light reveals only).
+
+---
+
+## Assembly notes
+- **Scale is mandatory:** 15+ pages, **≥10 scenes each**. Never a single/thin page.
+- **Storyboard first:** define the arc, then choose which scenes pin/scrub/reveal. **Alternate
+  big beats with calm passages** so the rhythm breathes — don't pin everything.
+- **No borders/dividers between sections** — whitespace + animated `--bg-scene-*` transitions
+  + pinned depth. One idea + one strong motion per scene.
+- **Reduced motion + no scroll-jack:** every scene degrades to a readable final state; native
+  scroll always works; provide a "Reduce motion" toggle.
+- **Reading-heavy pages (docs, blog, pricing) stay calm.** Use real content; mark guesses `[PLACEHOLDER]`.

package/skills/motion-storytelling-design-system/layout-system.md

@@ -0,0 +1,79 @@
+# Layout & Grid System — Motion Storytelling
+
+A 12-column fluid grid + canonical **scene layouts** for scroll-driven narrative: pinned
+scenes, scrubbed sequences, reveal timelines, horizontal scroll, and standard sections
+between the big beats. **No borders between sections.**
+
+## Grid
+
+```css
+:root { --grid-cols: 12; --grid-gap: clamp(16px, 2.2vw, 28px); }
+
+.grid { display: grid; gap: var(--grid-gap);
+        grid-template-columns: repeat(var(--grid-cols), 1fr); }
+.cols-1 { grid-template-columns: 1fr; }
+.cols-2 { grid-template-columns: repeat(2, 1fr); }
+.cols-3 { grid-template-columns: repeat(3, 1fr); }
+.cols-4 { grid-template-columns: repeat(4, 1fr); }
+.split  { grid-template-columns: 1fr 1fr; }
+@media (max-width: 900px){ .cols-3,.cols-4 { grid-template-columns: repeat(2,1fr); } }
+@media (max-width: 820px){ .split { grid-template-columns: 1fr; } }
+@media (max-width: 600px){ .cols-2,.cols-3,.cols-4 { grid-template-columns: 1fr; } }
+```
+
+Breakpoints: `sm 480` · `md 768` · `lg 1024` · `xl 1280` · `2xl 1440`. Mobile-first;
+collapse to single column by `md`, and **unpin/shorten scenes** on mobile (see spacing).
+
+## Scene scaffold (recap from spacing)
+A motion scene = a tall **`.scene`** track wrapping a **`.scene__stage`** (`position:
+sticky; height:100vh`). The stage holds the pinned content; the extra track height is the
+scroll distance the scene animates over. On mobile, scenes unpin and become normal sections.
+
+## Canonical scene layouts
+
+### Hero / opener
+- **SH-A Kinetic hero (default):** pinned stage — eyebrow → kinetic display H1 (line reveal)
+  → deck → CTA, with an animated gradient atmosphere; the headline/atmosphere respond to scroll.
+- **SH-B Scrub hero:** a tall scrub track drives a **sequence** (image frames / SVG draw /
+  product assembling) in the pinned stage as you scroll into the page.
+- **SH-C Reveal hero:** non-pinned, choreographed entrance of headline + media on load/scroll.
+
+### Story / feature scenes
+- **ST-A Pinned narrative:** stage pins; **copy swaps** (beat 1 → 2 → 3) while a visual
+  persists/transforms — one product, three points, told on scroll.
+- **ST-B Scrubbed demo:** a product/diagram assembles or animates step-by-step tied to scroll.
+- **ST-C Reveal timeline:** a normal section whose elements stagger in as it enters.
+- **ST-D Horizontal scene:** content scrolls **sideways** while you scroll down (translateX
+  of a track inside a pinned stage); used sparingly, **keyboard-accessible**, with a
+  vertical-stack fallback on mobile/reduced motion.
+- **ST-E Parallax layers:** background/mid/foreground move at different rates for depth.
+
+### Standard sections (between beats — calm)
+- **F-A Feature grid**, **F-C Bento**, logos, testimonials, metrics — lighter reveal motion,
+  letting the big scenes breathe.
+
+### Pricing / CTA / FAQ / Footer
+- **P-A 3-tier** (middle highlighted) + toggle; **P-B 2-tier + enterprise**. Light reveal.
+- **C-A CTA finale:** a closing pinned/parallax beat — big line + primary CTA, the story's
+  payoff. `--section-y-lg`, no border.
+- **Q-A Accordion FAQ**; **FT-A Mega footer** (calm, minimal motion).
+
+### Dashboard / Docs
+- **D-A Dashboard scene:** product shell revealed via scrub/pin.
+- **DOC-A Three-pane docs:** mostly static (reading), light reveals only; never gate docs
+  content behind motion.
+
+## Composition rules
+
+1. **Separate scenes by background transition + space + depth, NEVER borders.** Animate
+   `--bg-scene-*`/overlay between chapters; `.section{border:0}`; no `<hr>` between sections.
+2. **Storyboard the page.** Alternate **big beats** (pinned/scrub) with **calm passages**
+   (standard sections) so the rhythm breathes — don't pin every section.
+3. **One idea per scene; one strong motion per scene.** Don't stack competing animations.
+4. **At least 10 sections/scenes per page**, **15+ pages.** Never thin.
+5. **Arc:** opener (hero) → setup → product beats (pinned/scrub) → proof (metrics/quotes) →
+   pricing → FAQ → finale CTA → footer. Make the narrative legible even when skimming.
+6. **Performance + a11y:** pinned/scrub via sticky + rAF/IO (see motion-system); on mobile
+   and reduced motion, unpin and show final states; never block normal scrolling.
+7. **Reflow:** multi-column → single column by `md`; horizontal scenes → vertical stacks;
+   tracks shorten/disable on mobile.

package/skills/motion-storytelling-design-system/motion-system.md

@@ -0,0 +1,116 @@
+# Motion System — Motion Storytelling
+
+This is the heart of the skill: a **performant, accessible, library-free** motion engine for
+scroll-driven storytelling — reveals, pinned scenes, scrubbed sequences, parallax, and
+kinetic type — built only with `IntersectionObserver`, rAF-throttled scroll, the CSS
+Scroll-Linked Animations API where supported, `<canvas>`/SVG, and CSS transitions.
+
+## Tokens
+
+```css
+:root {
+  --dur-fast: 160ms;   --dur-base: 280ms;  --dur-slow: 520ms;  --dur-slower: 800ms;
+  --ease-out: cubic-bezier(0.2, 1, 0.3, 1);
+  --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
+  --ease-emph: cubic-bezier(0.16, 1, 0.3, 1);   /* emphasized decelerate */
+}
+```
+
+## Principles
+1. **Compositor-only.** Animate `transform` + `opacity` (and `clip-path` for masks). Never
+   animate layout properties (top/left/width/height/margin) on scroll — that thrashes.
+2. **rAF-throttle scroll.** Read scroll once per frame; write transforms in the rAF; cache
+   measurements; recompute on resize (debounced). Use `IntersectionObserver` for enter/exit.
+3. **Prefer CSS scroll-linked animations** (`animation-timeline: view()/scroll()`) where
+   supported for jank-free scrubbing; JS rAF fallback otherwise.
+4. **One strong motion per scene.** Calm passages between beats. Restraint = smoothness.
+5. **Never block the user.** No scroll-jacking/hijack of native scroll. Pinning uses CSS
+   `position: sticky` (the page still scrolls normally); the user can always skim past.
+6. **Final state is the content.** Animations only change presentation; everything is present
+   and readable with motion off.
+
+## Patterns
+
+### Reveal (IntersectionObserver) — the workhorse
+```js
+const io = new IntersectionObserver((es)=>es.forEach((e,i)=>{ if(e.isIntersecting){
+  e.target.style.transitionDelay = `${Math.min(i*70,360)}ms`;
+  e.target.classList.add('in'); io.unobserve(e.target);
+}}, {threshold:.15});
+document.querySelectorAll('[data-reveal]').forEach(el=>io.observe(el));
+```
+```css
+[data-reveal]{ opacity:0; transform: translateY(20px);
+  transition: opacity var(--dur-slow) var(--ease-out), transform var(--dur-slow) var(--ease-out); }
+[data-reveal].in{ opacity:1; transform:none; }
+```
+
+### Pinned scene (CSS sticky — no library, no scroll-jack)
+```css
+.scene { position: relative; height: var(--track); }     /* tall track */
+.scene__stage { position: sticky; top: 0; height: 100vh; overflow: clip; }
+```
+Within the sticky stage, progress = how far the `.scene` has scrolled; compute a 0→1 value
+and drive transforms/opacity (JS rAF) or use `animation-timeline: scroll()`.
+
+### Scrub progress (rAF, library-free)
+```js
+const scenes = [...document.querySelectorAll('[data-scene]')];
+let ticking = false;
+function update(){
+  for (const s of scenes){
+    const r = s.getBoundingClientRect(), h = s.offsetHeight - innerHeight;
+    const p = Math.min(1, Math.max(0, -r.top / (h||1)));   // 0→1 progress
+    s.style.setProperty('--p', p.toFixed(4));               // use in CSS calc()/JS
+    // e.g. drive a sequence frame: s.dataset.frame = Math.round(p*(FRAMES-1));
+  }
+  ticking = false;
+}
+addEventListener('scroll', ()=>{ if(!ticking){ requestAnimationFrame(update); ticking=true; }}, {passive:true});
+addEventListener('resize', ()=>requestAnimationFrame(update)); update();
+```
+Use `--p` in CSS: `transform: translateY(calc((1 - var(--p)) * 40px)); opacity: var(--p);`
+
+### Image-sequence / SVG scrub
+- **Frames:** preload + `decode()` a small set of frames; draw to `<canvas>` (or toggle
+  `<img>`) by index = `round(p * (FRAMES-1))`. Provide a static final frame + alt.
+- **SVG draw:** animate `stroke-dashoffset` from p; or `clip-path`/mask wipe for assembly.
+
+### Parallax (subtle)
+`transform: translate3d(0, calc(var(--p) * var(--depth)), 0)` per layer; small `--depth`
+(e.g. 20–80px). Foreground moves more than background. Off for reduced motion/touch.
+
+### Kinetic type (line reveal)
+Wrap heading lines in `.line > span`; reveal `translateY(110%) → 0` on `.in` (see typography).
+
+### Horizontal scene
+Pin a stage; translate an inner track on X by progress: `transform: translateX(calc(var(--p)
+* -1 * (var(--track-w) - 100vw)))`. Make it keyboard-operable (focus advances) and stack
+vertically on mobile/reduced motion.
+
+### Micro-interactions
+Hover lift, magnetic buttons (translate toward pointer, small), link underline grow, nav
+background morph on scroll, count-up, copy-check swap.
+
+## Reduced motion (CRITICAL)
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after { animation-duration:.001ms !important;
+    animation-iteration-count:1 !important; transition-duration:.001ms !important;
+    scroll-behavior:auto !important; }
+  .scene { height: auto !important; }                 /* untrack */
+  .scene__stage { position: static !important; height: auto !important; }
+}
+```
+And in JS: `const RM = matchMedia('(prefers-reduced-motion: reduce)').matches;` — if `RM`,
+**don't attach** scroll/scrub/parallax listeners, render every scene in its **final state**
+(final frame, headings shown, counters at final value), unpin scenes, and disable horizontal/
+parallax. The site must be fully usable and complete with zero motion.
+
+## Performance checklist
+- Only `transform`/`opacity`/`clip-path` animate; `will-change` used sparingly on active scenes.
+- Scroll handlers are `passive`, rAF-throttled, measurement-cached; resize debounced.
+- Sequence frames are few, sized for viewport, preloaded + `decode()`d; use `<canvas>` for many.
+- `content-visibility: auto` on offscreen heavy scenes; lazy-load media; target 60fps.
+- Disable/spin down observers for scenes scrolled past; never run all scenes at once.

package/skills/motion-storytelling-design-system/spacing-system.md

@@ -0,0 +1,83 @@
+# Spacing System — Motion Storytelling
+
+A strict **4-point base / 8-point rhythm**, plus **scroll-track** lengths that give pinned
+and scrubbed scenes room to animate. Whitespace, scene depth, and background transitions
+separate content — never borders.
+
+## Scale tokens
+
+```css
+:root {
+  /* 4-pt base, 8-pt rhythm */
+  --space-0: 0;        --space-1: 4px;   --space-2: 8px;   --space-3: 12px;
+  --space-4: 16px;     --space-5: 20px;  --space-6: 24px;  --space-8: 32px;
+  --space-10: 40px;    --space-12: 48px; --space-16: 64px; --space-20: 80px;
+  --space-24: 96px;    --space-28: 112px;--space-32: 128px;--space-40: 160px;
+
+  /* Radii */
+  --radius-sm: 8px;  --radius-md: 12px; --radius-lg: 16px;
+  --radius-xl: 22px; --radius-2xl: 28px; --radius-pill: 999px;
+
+  /* Containers */
+  --container-sm: 680px;   --container-md: 820px;  --container-lg: 1060px;
+  --container-xl: 1200px;  --container-2xl: 1360px;  /* wide cinematic scenes */
+  --gutter: clamp(20px, 5vw, 48px);
+
+  /* Section / scene rhythm (fluid) */
+  --section-y: clamp(72px, 9vw, 140px);
+  --section-y-lg: clamp(104px, 13vw, 200px);  /* hero / chapter openers */
+  --stack: clamp(16px, 2vw, 24px);
+
+  /* Scroll-track lengths (how long a scene "runs" while pinned/scrubbed) */
+  --track-short: 150vh;   /* a short pinned beat */
+  --track:       250vh;   /* standard pinned/scrub scene (1.5x extra scroll) */
+  --track-long:  400vh;   /* a long scrubbed sequence (more frames/steps) */
+}
+```
+
+## Usage map
+
+- **4-pt system** (`--space-1..6`): inside components — icon↔label, button/badge padding,
+  caption gaps, list-item gaps.
+- **8-pt system** (`--space-8..16`): between components — card gaps, copy↔media, form rows.
+- **Container widths:** standard scenes `--container-lg/xl`; wide cinematic scenes
+  `--container-2xl`; prose/docs `--container-md`.
+- **Section/scene spacing:** non-pinned sections use `padding-block: var(--section-y)`;
+  hero/chapter openers `--section-y-lg`.
+- **Scroll tracks (the motion-specific part):** a **pinned/scrub scene** is a tall wrapper
+  (`height: var(--track)`) containing a `position: sticky; height: 100vh` inner stage. The
+  extra track height = the scroll distance over which the scene animates. Use `--track-short/
+  track/track-long` per how much choreography a scene needs.
+- **Page spacing:** scenes stack with no extra margins and **no borders/dividers** —
+  `--section-y` whitespace + **background/scene transitions** + pinned depth separate them.
+
+## Rules
+
+1. **Only use scale values** for padding/gaps; tracks use the `--track-*` lengths.
+2. **Right-size the track.** More animation steps → longer track (`--track-long`); a quick
+   pin → `--track-short`. Avoid extremely long tracks (they feel slow/janky).
+3. **Pinned stage = 100vh sticky** inside a `--track`-tall wrapper. Keep the stage content
+   within safe padding so nothing clips during transforms.
+4. **Whitespace + scene transition > dividers.** Separate scenes this way, never lines.
+5. **Mobile:** shorten tracks (or disable pinning) so scenes aren't exhausting on small
+   screens; ensure normal scrolling always works.
+
+## Helpers
+
+```css
+.container { width:100%; max-width: var(--container-xl);
+             margin-inline:auto; padding-inline: var(--gutter); }
+.container--wide { max-width: var(--container-2xl); }
+.section   { padding-block: var(--section-y); border: 0; }   /* never a section border */
+.section--opener { padding-block: var(--section-y-lg); }
+
+/* Pinned / scrubbed scene scaffold (pure CSS sticky) */
+.scene        { position: relative; height: var(--track); }      /* the scroll track */
+.scene__stage { position: sticky; top: 0; height: 100vh;         /* the pinned viewport */
+                display: grid; place-items: center; overflow: clip; }
+@media (max-width: 768px){
+  .scene { height: auto; }                 /* unpin on mobile: */
+  .scene__stage { position: static; height: auto; padding-block: var(--section-y); }
+}
+.stack > * + * { margin-top: var(--stack); }
+```

package/skills/motion-storytelling-design-system/typography-system.md

@@ -0,0 +1,89 @@
+# Typography System — Motion Storytelling
+
+Bold, modern grotesk type that **moves with intent** — headlines assemble, mask-reveal, and
+track the scroll (kinetic type), while body stays clean and is never animated word-by-word.
+Legibility holds at every animation frame. Fluid scale across breakpoints.
+
+## Fonts
+
+```css
+:root {
+  --font-sans: "Inter", "Geist", "Satoshi", -apple-system, BlinkMacSystemFont, "Segoe UI",
+               Roboto, Helvetica, Arial, sans-serif;
+  --font-display: var(--font-sans);          /* or "Geist"/"Clash Display" for bolder kinetic headlines */
+  --font-mono: "Geist Mono", "JetBrains Mono", "SF Mono", ui-monospace, Menlo, monospace;
+}
+```
+A characterful display face (Geist, Clash Display, Satoshi) reads well in motion; keep body
+in a neutral, highly legible sans. Mono for code/terminal scenes.
+
+## Fluid type scale (clamp) — cinematic
+
+```css
+:root {
+  --fs-display: clamp(2.75rem, 1.4rem + 6.6vw, 6rem);    /* 44 → 96px kinetic hero */
+  --fs-h1:      clamp(2.25rem, 1.5rem + 3.4vw, 4rem);    /* 36 → 64px */
+  --fs-h2:      clamp(1.75rem, 1.3rem + 2.2vw, 2.875rem);/* 28 → 46px scene title */
+  --fs-h3:      clamp(1.375rem, 1.15rem + 1.1vw, 1.875rem);/* 22 → 30px */
+  --fs-h4:      clamp(1.125rem, 1.02rem + 0.5vw, 1.375rem);/* 18 → 22px */
+  --fs-lead:    clamp(1.125rem, 1.02rem + 0.55vw, 1.4375rem);/* 18 → 23px */
+  --fs-body:    1rem;          /* 16px base */
+  --fs-body-lg: 1.0625rem;     /* 17px */
+  --fs-small:   0.875rem;      /* 14px caption */
+  --fs-micro:   0.75rem;       /* 12px labels/eyebrow/scene-number */
+}
+```
+
+## Roles (each: size · weight · line-height · tracking)
+
+| Role | Size | Weight | Line-height | Tracking | Color |
+|---|---|---|---|---|---|
+| **Display** (hero) | `--fs-display` | 600–800 | 1.0–1.05 | -0.02em to -0.03em | `--text-primary` / `--grad-text` |
+| **H1** | `--fs-h1` | 600–700 | 1.06 | -0.02em | `--text-primary` |
+| **H2** (scene title) | `--fs-h2` | 600 | 1.1 | -0.015em | `--text-primary` |
+| **H3** | `--fs-h3` | 600 | 1.2 | -0.01em | `--text-primary` |
+| **H4 / overline** | `--fs-h4` | 600 | 1.3 | 0 | `--text-primary` |
+| **Eyebrow / scene number** | `--fs-micro` | 600 | 1.2 | 0.1em, UPPERCASE | `--accent`/`--text-muted` |
+| **Lead / deck** | `--fs-lead` | 400 | 1.5 | 0 | `--text-secondary` |
+| **Body** | `--fs-body`/`-lg` | 400 | 1.6 | 0 | `--text-secondary` |
+| **Caption / meta** | `--fs-small` | 400–500 | 1.45 | 0 | `--text-muted` |
+| **Kinetic word** | display sizes | 600–800 | — | — | `--text-primary`/accent (per beat) |
+| **Button** | `--fs-body` (`0.9375rem`) | 600 | 1 | -0.005em | `--text-on-accent`/`--text-primary` |
+| **Navigation** | `--fs-small`/`--fs-body` | 500 | 1 | 0 | `--text-secondary` → `--text-primary` |
+| **Pricing amount** | `clamp(2.5rem,2rem+2vw,3.5rem)` | 700 | 1 | -0.02em | `--text-primary` |
+| **Code / terminal** | `--fs-small` | 400–500 | 1.6 | 0 | mono, syntax-tinted |
+
+## Kinetic type rules (the craft)
+
+1. **Animate structure, keep legibility.** Reveal **headings line-by-line** (wrap lines in
+   `<span class="line">`) or with a **mask wipe** (`clip-path`/`background-clip`); never blur
+   text to illegibility or animate long paragraphs word-by-word.
+2. **Scroll-tracked headlines** (optional) can shift/scale slightly with scroll on a pinned
+   scene — keep amplitude small so text stays readable.
+3. **Final state is the real content.** Markup must contain the full text; animation only
+   affects presentation. With motion off, the heading is simply shown.
+4. **Gradient text** (`--grad-text`) on display/hero phrases only — verify contrast at the
+   lightest stop over its background; never on body/small text.
+5. **One display moment per scene** at most; calm passages between big kinetic beats.
+6. **Tighten as it grows;** body ~1.6, 0 tracking, measure ≤ 68ch. Numbers `tabular-nums`.
+
+## Base CSS
+
+```css
+body { font-family: var(--font-sans); font-size: var(--fs-body); line-height: 1.6;
+       color: var(--text-secondary); -webkit-font-smoothing: antialiased;
+       text-rendering: optimizeLegibility; }
+h1,h2,h3,h4 { color: var(--text-primary); font-family: var(--font-display);
+              font-weight: 700; text-wrap: balance; letter-spacing: -0.02em; }
+h1 { font-size: var(--fs-h1); line-height: 1.06; }
+.eyebrow { font-size: var(--fs-micro); font-weight:600; letter-spacing:.1em;
+           text-transform:uppercase; color: var(--accent); }
+.lead { font-size: var(--fs-lead); color: var(--text-secondary); max-width: 60ch; }
+/* kinetic line reveal — full text is in the DOM; only presentation animates */
+.kinetic .line { display:block; overflow:hidden; }
+.kinetic .line > span { display:block; transform: translateY(110%);
+  transition: transform var(--dur-slow) var(--ease-out); }
+.kinetic.in .line > span { transform: none; }
+p { max-width: 68ch; }
+code, pre { font-family: var(--font-mono); }
+```

package/skills/motion-storytelling-design-system/website-generation-rules.md

@@ -0,0 +1,200 @@
+# Website Generation Rules — Motion Storytelling
+
+How an agent turns this design system into a **production-ready, multi-page, scroll-driven
+narrative website**. Output clean, semantic **pure HTML + CSS + vanilla JavaScript** plus
+design tokens. The signature: each page tells a story through pinned/scrubbed/revealed
+scenes — built **performantly and accessibly**, with **no animation libraries**. (The token/
+spec system can be exported for other agents — see below — but the site itself is pure vanilla.)
+
+## Technology stack (MANDATORY — no frameworks, no libraries)
+
+Build everything — including all scroll motion — with **HTML5 + CSS3 + vanilla JavaScript
+only**. The generated site must contain **zero** of:
+
+> ❌ React · ❌ Vue · ❌ Angular · ❌ Svelte/Next/Nuxt · ❌ Bootstrap · ❌ Tailwind ·
+> ❌ jQuery · ❌ GSAP · ❌ ScrollMagic · ❌ Lenis/Locomotive · ❌ Framer · ❌ AOS ·
+> ❌ any UI/CSS framework · ❌ any JS animation/scroll library
+
+Motion is built only with `IntersectionObserver`, rAF-throttled passive scroll listeners,
+the CSS Scroll-Linked Animations API (`animation-timeline: scroll()/view()`) where supported,
+`<canvas>`/SVG, and CSS transitions. No build step, no npm, no CDN kits. Exporting
+`tokens.json` for other agents is allowed; shipping the site in a framework/animation library
+is not.
+
+## Mandatory scale & structure (read first)
+- **Multipage: build 15+ pages (recommended ~20)** — a full site map, not one page.
+- **Every page has at least 10 sections/scenes (recommend 12)** with a clear narrative arc.
+- **No borders or dividers between sections** — separate scenes with **whitespace, animated
+  background/scene transitions (`--bg-scene-*`), and pinned-scene depth**. In CSS: `.section
+  { border: 0 }`; never `<hr>`/divider or `border-top/bottom` between sections.
+- **Performant + accessible motion:** compositor-only (`transform`/`opacity`), rAF/IO,
+  **fully gated by `prefers-reduced-motion`** (final-state, unpinned), **no scroll-jacking**.
+- **Clean, extensionless, Vercel-ready URLs** (`/pricing`, not `/pricing.html`).
+
+## Required pages (build all — 15+; ~20 recommended)
+Home `/` · Platform `/platform` · Solutions `/solutions` · Products `/products` ·
+Features `/features` · AI Agents `/ai-agents` · Enterprise `/enterprise` · Security
+`/security` · Pricing `/pricing` · Customers `/customers` · Case Studies `/case-studies`
+· Developers `/developers` · Documentation `/docs` · About `/about` · Careers `/careers`
+· Blog `/blog` · Contact `/contact` · Partners `/partners` · Resources `/resources` ·
+FAQ `/faq`. Add product/solution/blog/doc subpages freely.
+
+## Required sections (every page — ≥10, recommend 12)
+Hero (kinetic/scrub) · Feature Scenes · Product Highlights · Trust Signals (logos) ·
+Testimonials · Use Cases · Statistics (count-up) · Integrations · CTA (finale) · Footer. Add
+more (Security, Enterprise, Pinned narrative, Bento, Code/Terminal) to reach 12. Mix **big
+beats** (pinned/scrub) with **calm passages** (standard sections).
+
+## Site types this must support
+Landing pages · startup websites · AI company websites · enterprise SaaS · developer
+platforms · agentic-AI startups · infrastructure startups · launches. (See `example-page-structures.md`.)
+
+## What to generate
+- **HTML** — semantic, accessible, one file per page; full content in DOM (motion = presentation).
+- **CSS** — `tokens.css` (`:root` vars) + `styles.css` (base + scene scaffold + components +
+  reduced-motion block).
+- **JavaScript** — vanilla **motion engine**: IO reveals, sticky-scene progress (rAF), scrub
+  (frames/SVG), parallax, kinetic type, nav, accordion, tabs, count-up — all reduced-motion-aware.
+- **`vercel.json`** + **`sitemap.xml`** + **`robots.txt`**.
+- **Design tokens** — `tokens.json` (token export only).
+- **Component specifications** — when asked for the *system*, emit component + scene markup.
+- **Accessibility + responsive guidance** inline (comments) and honored.
+
+## File/output layout (default — flat files + clean URLs)
+```
+website/
+├── index.html              # served at /
+├── platform.html  solutions.html  products.html  features.html  ai-agents.html
+├── enterprise.html  security.html  pricing.html  customers.html  case-studies.html
+├── developers.html  docs.html  about.html  careers.html  blog.html  contact.html
+├── partners.html  resources.html  faq.html
+├── css/  { tokens.css, styles.css }
+├── js/   { main.js }        # motion engine + nav + interactions
+├── assets/                  # sequence frames, SVGs, media, og images
+├── tokens.json
+├── sitemap.xml  robots.txt
+└── vercel.json
+```
+Alternative: folder-per-page `platform/index.html`. Either way **all internal links are
+extensionless** (`href="/pricing"`).
+
+## Clean URLs & Vercel (MANDATORY)
+- **No `.html` in any URL**, no `page.html` links, no ugly query params.
+- Emit **`vercel.json`** so `.html` is stripped, refresh works, and deep links resolve:
+```json
+{
+  "cleanUrls": true,
+  "trailingSlash": false,
+  "headers": [
+    { "source": "/assets/(.*)", "headers": [
+      { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" } ] }
+  ]
+}
+```
+  `cleanUrls: true` serves `platform.html` at `/platform` and 301-redirects `.html`.
+  Provide a `404.html`. Every nav/footer/internal link is extensionless.
+
+## Navigation system (vanilla JS)
+- **Desktop nav** with optional dropdown/mega-menu; may include **Scroll Progress** + chapter
+  dots. Keyboard + `aria-expanded`/`aria-haspopup`. **Never hijacks scroll.**
+- **Mobile nav**: full-screen overlay, accordion, focus-trap, ESC.
+- **Multi-level nav** + **breadcrumbs** on deep pages; `aria-current="page"`.
+
+## Hard rules
+1. **Vanilla only** — no animation/scroll libraries (see stack). Hand-build the motion engine.
+2. **Storyboard each page.** A clear arc; pinned/scrub/reveal scenes with designed
+   choreography; big beats alternate with calm passages; one strong motion per scene.
+3. **Reduced motion + no scroll-jack (non-negotiable).** Fully honor `prefers-reduced-motion`
+   (final-state, unpinned, no scrub/parallax); never hijack native scroll; content readable
+   without motion; provide a "Reduce motion" toggle.
+4. **Tokens first, once.** All colors/type/spacing as `:root` vars; no scattered hex/px.
+5. **No section borders.** Separate scenes with space + animated background transitions.
+   `.section{border:0}`.
+6. **Mobile-first + responsive**; **unpin/shorten scenes on mobile**; multi-column → single;
+   no unintended horizontal scroll.
+7. **Semantic + accessible** per `accessibility-system.md` (full content in DOM, contrast in
+   motion, focus, vestibular safety). Non-negotiable.
+8. **Components from the library** (incl. scene components). Every component responsive,
+   accessible, reusable, production-ready.
+9. **Performance:** compositor-only animation, rAF-throttled passive scroll, IO reveals,
+   `content-visibility` on offscreen scenes, decoded/lazy sequence frames; target 60fps; high
+   Lighthouse (90+). System/Inter fonts.
+10. **SEO on every page** (below). **Real content, not lorem** (mark guesses `[PLACEHOLDER]`).
+11. **Self-verify** against anti-patterns + every companion checklist before done.
+
+## SEO requirements (every page)
+Unique `<title>` + meta description (150–160); **Open Graph** + **Twitter card**
+(`summary_large_image`) + OG image; **canonical** (clean URL); **JSON-LD** (`Organization` +
+`WebSite` site-wide; `Product`, `FAQPage`, `BreadcrumbList`, `Article` where relevant);
+**`sitemap.xml`** + **`robots.txt`**. (Content lives in HTML, not only in JS-driven motion,
+so crawlers index it.)
+
+## Performance requirements
+60fps motion, compositor-only properties, rAF/IO, `content-visibility` offscreen, lazy/decoded
+media, one fixed background where possible, cached assets (via `vercel.json`), no libraries —
+high Lighthouse.
+
+## Boilerplate `<head>`
+```html
+<!doctype html><html lang="en"><head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="dark light">
+<title><!-- Page · Brand --></title>
+<meta name="description" content="<!-- 150–160 chars -->">
+<link rel="canonical" href="https://brand.com/path">
+<meta property="og:type" content="website">
+<meta property="og:title" content="<!-- Page · Brand -->">
+<meta property="og:description" content="<!-- … -->">
+<meta property="og:url" content="https://brand.com/path">
+<meta property="og:image" content="https://brand.com/assets/og.png">
+<meta name="twitter:card" content="summary_large_image">
+<link rel="stylesheet" href="/css/tokens.css">
+<link rel="stylesheet" href="/css/styles.css">
+<script type="application/ld+json"><!-- Organization / WebSite JSON-LD --></script>
+</head>
+<body>
+  <a class="skip-link" href="#main">Skip to content</a>
+  <header><!-- Navbar + scroll progress (links extensionless: /platform, /pricing) --></header>
+  <main id="main"><!-- hero scene + 10–12 scenes, animated bg transitions, no dividers --></main>
+  <footer><!-- Footer + "Reduce motion" toggle --></footer>
+  <script src="/js/main.js" defer></script>
+</body></html>
+```
+
+## Required base CSS (no section borders; scene scaffold; reduced motion)
+```css
+html, body { background: var(--bg-base); color: var(--text-secondary); }
+.section { padding-block: var(--section-y); border: 0; }   /* no borders/dividers between sections */
+.section + .section { border-top: 0; }
+.scene { position: relative; height: var(--track); }
+.scene__stage { position: sticky; top: 0; height: 100vh; overflow: clip; }
+@media (prefers-reduced-motion: reduce){
+  .scene { height: auto; } .scene__stage { position: static; height: auto; padding-block: var(--section-y); }
+  *,*::before,*::after { transition-duration:.001ms !important; animation-duration:.001ms !important; }
+}
+/* Separation = whitespace + animated --bg-scene-* transitions + pinned depth; never <hr>/dividers. */
+```
+
+## tokens.json shape (excerpt)
+```json
+{
+  "color": { "bgBase":"#05060a", "scene":["#070912","#0b0814","#060e12","#0e0a08"],
+             "text": {"primary":"#f5f6fb","secondary":"#c2c7d6","muted":"#939ab0"},
+             "accent": {"base":"#6366f1","2":"#06b6d4","3":"#ec4899"} },
+  "space": { "4":"16px","6":"24px","8":"32px","16":"64px" },
+  "track": { "short":"150vh","base":"250vh","long":"400vh" },
+  "radius": { "lg":"16px","xl":"22px","pill":"999px" },
+  "type": { "display":"clamp(2.75rem,1.4rem + 6.6vw,6rem)", "body":"1rem" }
+}
+```
+
+## Definition of done
+**15+ pages (≈20), each with ≥10 sections/scenes (≈12) and a clear narrative arc (pinned/
+scrub/reveal beats + calm passages), no borders/dividers between sections.** Pure HTML/CSS/
+vanilla JS (no frameworks/animation libraries); motion is compositor-only, rAF/IO, 60fps;
+**fully reduced-motion-aware (final-state, unpinned) with a toggle, and no scroll-jacking**;
+clean extensionless URLs with `vercel.json` (refresh + deep links work); desktop nav + mobile
++ breadcrumb + scroll progress; per-page SEO + sitemap; tokens centralized; fully responsive
+(scenes unpin on mobile); AA accessible (contrast in motion, focus, vestibular-safe); zero
+anti-patterns; could sit next to Apple/Stripe scroll storytelling — smooth, meaningful, accessible.