spirewise 1.7.1 → 1.9.0

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

@@ -0,0 +1,191 @@
+---
+name: motion-storytelling-design-system
+description: >-
+  A world-class, MOTION STORYTELLING design system for building scroll-driven narrative
+  websites — scrollytelling, pinned/sticky scenes, scrubbed sequences, choreographed
+  reveals, and parallax that tell a story as the visitor scrolls. Distilled from
+  motion-led references (Apple product pages, Stripe, Linear, Igloo Inc, Active Theory,
+  Cuberto, Awwwards winners) and modern AI sites (OpenAI, Anthropic, Perplexity, Cursor,
+  Runway). It gives coding/design/UI/branding/website-generation agents a complete,
+  reusable system: design philosophy, color/typography/spacing/grid/layout tokens, a
+  17+ -component library (Scroll Scene, Pinned Sequence, Reveal Timeline…), a deep motion
+  system (scroll-linked, IntersectionObserver, scrub), accessibility + responsive rules,
+  and a production website-generation framework. The framework builds a multipage site
+  (15+ pages, 10+ sections/page, NO borders/dividers between sections) in PURE HTML/CSS/
+  vanilla JS (no React/Vue/GSAP/Framer/Tailwind/Bootstrap/jQuery/any library), with clean
+  Vercel-ready URLs (no `.html`), navigation, and full SEO. Use when the user asks for a
+  "scrollytelling / motion / animated narrative website", "scroll-driven story", "pinned
+  sections", "make it like Apple/Stripe scroll", or "a motion design system / tokens". The
+  full system is baked into the companion files (live research optional). Outputs a
+  generated site/system into a `website/` folder.
+---
+
+# Motion Storytelling Design System
+
+A complete, agent-ready design system for **scroll-driven narrative websites** — where the
+page tells a story as you scroll: scenes **pin** while their content animates, sequences
+**scrub** frame-by-frame to scroll position, elements **reveal** in choreographed order,
+and gentle parallax adds depth. The craft of Apple product pages and award-winning
+"scrollytelling," built **performantly and accessibly** in pure vanilla. Distilled from
+Apple, Stripe, Linear, Igloo Inc, Active Theory, Cuberto, Awwwards winners, and modern AI
+sites (OpenAI, Anthropic, Perplexity, Cursor, Runway).
+
+This skill is the **single source of truth**. The detailed system lives in the companion
+files in this folder — read the ones relevant to the task, then generate.
+
+## The core idea — the scroll is the narrator
+
+- **Story beats, not just sections.** Each page is a sequence of **scenes** that advance a
+  narrative; scrolling is the timeline.
+- **Pin + animate.** Key scenes use `position: sticky` to **pin** while their content
+  transforms (text swaps, layers move, a product assembles, a number counts).
+- **Scrub sequences.** Hero/feature moments **scrub** an animation (image sequence, SVG
+  draw, transform) tied to scroll progress through a tall scroll track.
+- **Choreographed reveals.** Elements enter in a deliberate order/stagger as they cross the
+  viewport (via `IntersectionObserver`), guiding the eye through the story.
+- **Motion with meaning + restraint.** Every animation serves the narrative or clarifies
+  the product; it's smooth, performant, and **never** required to access content.
+
+## Hard structural requirements (MANDATORY — never skip)
+
+These are non-negotiable and override any conflicting guidance elsewhere:
+
+1. **Multipage — 15+ pages (≈20).** Always generate a **full multipage website with
+   more than 15 distinct pages** (not a single landing page) — a real site map.
+2. **10+ sections per page (≈12).** Every page contains **at least 10 full sections /
+   scenes**, composed from the layout + component library.
+3. **No borders/dividers between sections.** **Zero border widths, lines, rules, or
+   `<hr>` between sections.** Separate scenes with **whitespace, background transitions,
+   pinned-scene depth, and motion choreography** — never a section border.
+4. **Pure HTML + CSS + vanilla JS — no frameworks/libraries.** The generated site uses
+   **only HTML5, CSS3, and vanilla JavaScript** for all motion — `IntersectionObserver`,
+   scroll listeners (rAF-throttled), the CSS Scroll-Linked Animations API
+   (`animation-timeline: scroll()/view()`) where supported, `<canvas>`/SVG. **No GSAP,
+   ScrollMagic, Lenis, Framer, Locomotive, AOS**, no React/Vue/Angular/Svelte/Next, no
+   Bootstrap/Tailwind/any CSS framework, no jQuery/any library, no build step. (Exporting
+   `tokens.json` for other agents is fine — that's data, not a framework.)
+5. **Clean, Vercel-ready URLs.** All routes are **extensionless** (`/pricing`, not
+   `/pricing.html`); ship a `vercel.json` (`cleanUrls: true`) plus `sitemap.xml` /
+   `robots.txt` so production refresh and deep links work.
+6. **Full navigation + SEO.** Desktop nav (dropdown/mega-menu where useful) + mobile menu
+   + breadcrumbs; per-page SEO (unique title/description, Open Graph, Twitter card,
+   canonical, JSON-LD). Every component: responsive, accessible, reusable, production-ready.
+
+See `website-generation-rules.md` for the required page list, required sections/scenes, the
+`vercel.json`, navigation, and SEO specifics. Enforce in code: `.section { border: 0 }` and
+never place `<hr>`/divider elements between sections.
+
+## When to use
+
+Building or designing any landing page, marketing site, or product site that should be
+**scroll-driven / motion-led / cinematic** (Apple/Stripe/award-winning scrollytelling
+energy) — for a product, AI startup, developer platform, or launch — or producing **design
+tokens / a design system** for other agents.
+
+## The companion files (read what you need)
+
+| File | What it gives you |
+|---|---|
+| `design-principles.md` | The storytelling philosophy, motion hierarchy, restraint, do/don'ts |
+| `color-system.md` | Cinematic palette + scene-transition tokens (default dark) as CSS vars |
+| `typography-system.md` | Fonts, fluid type scale, kinetic-type roles |
+| `spacing-system.md` | 4/8-pt scale, container widths, scroll-track + scene rhythm |
+| `layout-system.md` | Grid + canonical scene layouts (pinned, scrub, reveal, horizontal) |
+| `component-library.md` | 17 components + Scroll Scene / Pinned Sequence / Reveal Timeline |
+| `motion-system.md` | The engine: IntersectionObserver, scroll-link, scrub, reduced-motion |
+| `accessibility-system.md` | Reduced motion (critical), focus, content-without-motion, vestibular safety |
+| `website-generation-rules.md` | Pure-vanilla build: pages, clean URLs + `vercel.json`, nav, SEO |
+| `example-page-structures.md` | Ready scroll-narrative page blueprints |
+
+All tokens use the same names across files, so they compose into one stylesheet.
+
+## Phase 1 — Research is baked in (live analysis OPTIONAL)
+
+The design intelligence extracted from the reference sites is **already encoded in the
+companion files** — patterns, palettes, type scales, spacing, the motion engine, scene
+components, choreography. **Do NOT re-scrape the references for the basics; use the baked-in
+system** (saves tokens). Only browse live when the user wants a *current* look from a
+specific site, a brand-new pattern not covered here, or to verify a font/feature.
+
+What the baked-in system already captures (the Phase-1 extraction): design patterns, visual
+hierarchy, typography/spacing/grid/layout systems, color + gradient systems, animation/
+motion (the focus here), navigation, CTA + hero patterns, trust/enterprise/social-proof
+components, footer/pricing/feature structures, interactive + micro-interactions, glassmorphism
+usage, accessibility, mobile responsiveness, developer-experience patterns, and AI-startup
+conversion patterns — all expressed as scroll-driven story.
+
+## Phase 2 — Generate (the workflow)
+
+1. **Clarify intent:** site type + the **story** to tell (problem → product → proof →
+   outcome), theme (default cinematic dark, or light), accent, and page set.
+2. **Lock the tokens:** start from `color-system.md` + `typography-system.md` +
+   `spacing-system.md`. Emit them once as `:root` CSS variables (and `tokens.json`).
+3. **Storyboard the scroll:** for each page, write the beat sheet — which scenes pin, which
+   scrub, which reveal — and the choreography order. Motion is designed, not sprinkled.
+4. **Compose layouts + components:** build scenes with Scroll Scene / Pinned Sequence /
+   Reveal Timeline + the standard components.
+5. **Engineer motion + a11y:** implement per `motion-system.md` (performant, rAF/IO based),
+   **fully gated by `prefers-reduced-motion`**; meet every rule in `accessibility-system.md`
+   (content readable with motion off).
+6. **Emit code:** follow `website-generation-rules.md` to produce clean, semantic, responsive
+   **pure HTML + CSS + vanilla JS** plus tokens, `vercel.json`, `sitemap.xml`, `robots.txt`.
+7. **Self-check** against the anti-patterns and the verification checklist below.
+
+## Output
+
+Unless the user specifies otherwise, write the generated **multipage site (15+ pages, ~20)**
+into a `website/` folder in the project root:
+- `website/index.html` **plus 15+ additional pages** (≥10 scenes each, scroll-driven, no
+  inter-section borders), linked with **extensionless URLs** (`/pricing`)
+- `website/css/tokens.css` + `website/css/styles.css`
+- `website/js/main.js` (vanilla nav + the motion engine: IO, scroll-link, scrub)
+- `website/vercel.json`, `website/sitemap.xml`, `website/robots.txt`
+- `website/assets/` (sequence frames, SVGs, media, og images)
+- `website/tokens.json` (machine-readable tokens for other agents)
+
+When the user only wants the **system** (not a site), emit the tokens + component specs.
+
+## Default look (baked-in identity)
+
+A cinematic dark canvas with deep, evolving gradients that **shift between scenes**, bold
+display type that moves with intent (kinetic headlines), one vivid accent that traces the
+story, layered depth (parallax), and product/SVG sequences that assemble on scroll. Smooth,
+premium, and purposeful — never a jittery, janky, motion-for-its-own-sake mess. (Default
+cinematic dark; a light theme is included. Siblings: `ai-dark-futuristic-design-system`,
+`apple-premium-minimal-design-system`, `product-demo-first-design-system`,
+`bento-grid-design-system`, `glassmorphism-design-system`, `editorial-luxury-design-system`.)
+
+## Anti-patterns (never ship these)
+
+Outdated startup designs · Bootstrap/template look · generic SaaS layouts · poor typography
+· weak visual hierarchy · overloaded gradients · excessive glassmorphism · poor accessibility
+· inconsistent spacing · **motion for its own sake · janky/janking scroll-jacking that fights
+the user · content trapped behind animation (unreadable until it plays) · no reduced-motion
+fallback · heavy animation libraries · layout-thrashing/janky scroll · borders or dividers
+between sections · single-page sites or thin pages with fewer than 10 sections · any
+framework/library in the shipped site · `.html` in URLs**. The result must feel like Apple/
+Stripe scroll storytelling — smooth, meaningful, accessible — never gimmicky.
+
+## Verification checklist (run before finishing)
+
+0. **Multipage scale met:** the site has **> 15 pages** (≈20), each page has **≥ 10
+   sections/scenes** (≈12), and there are **no borders/dividers between sections**.
+0b. **Storytelling met:** each page has a clear narrative arc; uses pinned/scrub/reveal
+   scenes with designed choreography (not random animation); motion serves the story.
+0c. **Reduced motion met (critical):** with `prefers-reduced-motion: reduce`, all content is
+   fully readable/usable in final state — no pinning that traps content, no scrub-gated text,
+   no essential info conveyed only by animation. No scroll-jacking that blocks normal scroll.
+0d. **Pure vanilla + clean URLs:** zero frameworks/animation libraries; routes extensionless
+   with a working `vercel.json` (`cleanUrls`), `sitemap.xml`, `robots.txt`.
+0e. **Nav + SEO:** desktop nav/dropdowns + mobile menu + breadcrumbs; per-page SEO + JSON-LD.
+1. Tokens emitted once (`:root`/`tokens.css`) and reused — no scattered one-off hex.
+2. Type uses the fluid scale; spacing uses the 4/8-pt scale; layout uses the grid +
+   container widths — all from the companion files.
+3. Every scene is a recognized layout; every component matches `component-library.md`.
+4. Body text ≥ 4.5:1 contrast, large text ≥ 3:1; visible focus; semantic landmarks + alt text.
+5. **Performance:** animations use `transform`/`opacity` (compositor-friendly), rAF-throttled
+   scroll, IO for reveals; no layout thrash; 60fps target; sequences lazy/decoded. Fully
+   responsive (360 → 1440+), no horizontal scroll (except intentional, keyboard-accessible
+   horizontal scenes), tap targets ≥ 44px.
+6. Trips **zero** anti-patterns; no scroll-jacking that fights the user; motion is smooth.
+7. Output feels like Apple/Stripe scroll storytelling — cinematic, meaningful, accessible.

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

@@ -0,0 +1,71 @@
+# Accessibility System — Motion Storytelling
+
+Scroll-driven motion is the **highest-risk** style for accessibility — animation can cause
+vestibular discomfort, trap content, hijack scrolling, and break keyboard use. This system
+bakes WCAG 2.1 AA (incl. 2.2.2 Pause/Stop/Hide and 2.3.3 Animation from Interactions) into
+the craft so the storytelling stays inclusive.
+
+## Reduced motion (the non-negotiable rule)
+- **Honor `prefers-reduced-motion: reduce` everywhere.** With it on: render every scene in
+  its **final state**, **unpin** scenes, disable scrub/parallax/horizontal/kinetic motion,
+  show final frames, set counters to final values. In JS, **don't attach** scroll/scrub/
+  parallax listeners when reduced motion is set (see motion-system).
+- **No essential content is gated behind animation.** All text/visuals are present in the DOM
+  and readable without motion; an animation only changes presentation.
+- Provide a **"Reduce motion" toggle** in the footer/settings for users who can't set the OS
+  preference; persist it (localStorage) and apply the same final-state path.
+
+## No scroll-jacking / safe scrolling
+- **Never hijack native scroll** (no `preventDefault` on wheel, no forced smooth-snap that
+  fights the user, no animation libraries that take over scrolling). Pinning uses CSS
+  `position: sticky` so normal scrolling and skimming always work.
+- The page must be **usable with keyboard, screen reader, and a mouse wheel** at any speed;
+  users can scroll past any scene to reach content quickly.
+- Horizontal scenes must be **keyboard-operable** (focus moves through items, advancing the
+  scene) and have a vertical-stack fallback.
+
+## Color & contrast (during motion)
+- **Body text ≥ 4.5:1**, large/UI ≥ 3:1, measured at the **brightest moment** of any moving
+  gradient/background the text passes over — verify mid-animation, not just at rest.
+- Keep gradients/atmospheres **calm behind text**; dim/scrim where copy sits.
+- **Non-text contrast ≥ 3:1** for controls, focus rings, progress indicators.
+- Don't encode meaning in color/motion alone; provide text/state.
+
+## Focus & keyboard
+- **Always-visible focus:** `:focus-visible { outline:2px solid var(--ring); outline-offset:2px }`.
+- Logical tab order matching reading order; **focusing an element inside a pinned/scrolled
+  scene scrolls it into view** and doesn't break the pin. No keyboard traps (except intended
+  modal focus-trap, ESC). **Skip link** to `#main` first in DOM.
+
+## Semantics & structure
+- One `<h1>` per page; ordered headings (size with CSS). Landmarks `<header><nav><main id=
+  "main"><section><footer>`. Numbered sequences `<ol>`; quotes `<blockquote><cite>`; code
+  `<pre><code>`. Native elements over ARIA; minimal correct ARIA.
+- A **scroll progress** indicator uses `role="progressbar"` (or is decorative + `aria-hidden`);
+  chapter dots are a labelled `<nav>` with in-page links.
+
+## Vestibular safety
+- Keep parallax/scale amplitudes small; avoid large, fast, or full-screen continuous motion.
+- Avoid spinning/zooming the whole viewport; no rapid flashing (> 3×/sec).
+- Auto-playing background motion (e.g., gradient drift) must be subtle and **pausable**
+  (reduced-motion freezes it).
+
+## Media & forms
+- Informative images/sequences have meaningful **`alt`** (and a final static frame);
+  decorative atmospheres/chrome are `aria-hidden`/`alt=""`. Captions for narrated video.
+- Labelled, error-accessible forms; inputs legible against any scene.
+
+## Touch & responsive
+- **Tap targets ≥ 44×44px**; **unpin/shorten scenes on mobile**; no unintended horizontal
+  scroll; intentional horizontal scenes are touch- and keyboard-operable; 200% zoom OK;
+  pinch-zoom not disabled.
+
+## Checklist (run before finishing)
+1. Reduced motion → all scenes final-state, unpinned, no scrub/parallax/kinetic; content complete.
+2. No scroll-jacking; native scroll + keyboard + screen reader all work; can skim past any scene.
+3. Text meets AA over the brightest moving background; gradients calm behind text.
+4. Visible focus; focusing inside a scene scrolls it in; skip link; logical order; no traps.
+5. Real semantics (ol/blockquote/landmarks); progress/chapter nav labelled or hidden.
+6. Parallax/scale subtle; nothing flashes; background motion pausable.
+7. Informative media has alt + static final frame; "Reduce motion" toggle present.
+8. 44px targets; scenes unpin on mobile; 200% zoom; zoom not disabled.

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

@@ -0,0 +1,101 @@
+# Color System — Motion Storytelling
+
+A cinematic palette built for **scenes that shift as you scroll**: a dark canvas, deep
+evolving gradients that transition between chapters, one vivid accent that traces the story,
+and accessible text at every animation state. Ships **cinematic dark by default**; a light
+theme is included. Scenes separate via background transitions + depth — **never borders**.
+Override `--accent-*` to rebrand. Contrast: body ≥ 4.5:1 at every motion state.
+
+## Tokens (`:root`) — cinematic dark (default)
+
+```css
+:root {
+  /* ---- Canvas + scene backgrounds (chapters transition between these) ---- */
+  --bg-base:    #05060a;   /* deepest canvas */
+  --bg-scene-1: #070912;   /* chapter 1 (cool) */
+  --bg-scene-2: #0b0814;   /* chapter 2 (violet) */
+  --bg-scene-3: #060e12;   /* chapter 3 (teal) */
+  --bg-scene-4: #0e0a08;   /* chapter 4 (warm) */
+  --bg-elevated:#12141d;   /* cards/panels over a scene */
+
+  /* ---- Cinematic gradients (used as scene atmospheres; animate position/opacity) ---- */
+  --grad-scene:  radial-gradient(60% 70% at 50% 30%, rgba(99,102,241,0.28), transparent 60%);
+  --grad-accent: linear-gradient(120deg, #6366f1 0%, #06b6d4 50%, #ec4899 100%);
+  --grad-aurora: radial-gradient(45% 55% at 20% 20%, rgba(99,102,241,0.30) 0%, transparent 60%),
+                 radial-gradient(50% 60% at 80% 30%, rgba(6,182,212,0.24) 0%, transparent 60%),
+                 radial-gradient(50% 60% at 60% 90%, rgba(236,72,153,0.18) 0%, transparent 62%);
+  --grad-text:   linear-gradient(90deg, #ffffff 0%, #c7d2fe 55%, #67e8f9 100%);
+
+  /* ---- Surfaces ---- */
+  --surface-1:  #12141d;
+  --surface-2:  #181b27;
+  --surface-glass: rgba(18,20,29,0.5);
+
+  /* ---- Text ramp (must hold AA over moving gradients) ---- */
+  --text-primary:   #f5f6fb;
+  --text-secondary: #c2c7d6;
+  --text-muted:     #939ab0;
+  --text-faint:     #636a80;   /* decorative/disabled — non-essential only */
+  --text-on-accent: #0a0712;
+
+  /* ---- Borders / hairlines (panels/inputs — NOT between scenes) ---- */
+  --border-subtle:  rgba(255,255,255,0.07);
+  --border-default: rgba(255,255,255,0.12);
+  --ring:           #a5b4fc;   /* focus ring (high-contrast) */
+
+  /* ---- Accent (the thread that traces the story) ---- */
+  --accent:        #6366f1;  /* indigo */
+  --accent-hover:  #7c80f7;
+  --accent-press:  #5457e6;
+  --accent-2:      #06b6d4;  /* cyan — secondary beat */
+  --accent-3:      #ec4899;  /* magenta — climactic beat (sparing) */
+  --accent-soft:   rgba(99,102,241,0.16);
+
+  /* ---- Semantic ---- */
+  --success: #34d399; --success-soft: rgba(52,211,153,0.16);
+  --warning: #fbbf24; --warning-soft: rgba(251,191,36,0.16);
+  --error:   #fb7185; --error-soft:   rgba(251,113,133,0.16);
+  --info:    #38bdf8; --info-soft:    rgba(56,189,248,0.16);
+
+  /* ---- Elevation ---- */
+  --shadow-sm: 0 1px 2px rgba(0,0,0,0.5);
+  --shadow-md: 0 14px 40px rgba(0,0,0,0.45);
+  --shadow-lg: 0 30px 80px rgba(0,0,0,0.55);
+  --glow:      0 0 40px var(--accent-soft);
+}
+```
+
+## Palette roles
+
+- **Canvas + scene backgrounds** (`--bg-*`): the page is one dark canvas; **scenes/chapters
+  transition between `--bg-scene-*`** as the story progresses (animate `background-color`/an
+  overlay opacity on scroll). These shifts replace section borders.
+- **Cinematic gradients** (`--grad-*`): scene atmospheres — animate their position/opacity
+  with scroll for living depth (`--grad-aurora` behind a hero; `--grad-scene` per chapter).
+  Keep low-contrast **behind text**.
+- **Surfaces** (`--surface-*`): cards/panels that ride within a scene.
+- **Text** (`--text-*`): must clear AA over the *brightest* gradient state a line can pass
+  through during animation — verify mid-transition, not just at rest. Never `--text-faint`
+  for content.
+- **Borders** (`--border-*`): panel/input hairlines only — not scene dividers.
+- **Accent** (`--accent`, `--accent-2/3`, `--grad-accent`): one thread tracing the story —
+  a line that draws, a highlight that moves; escalate to `--accent-2/3` at climactic beats.
+- **Semantic**: status/badges/validation only.
+
+## Usage rules
+
+1. **Scenes are chapters of color.** Move between `--bg-scene-*` to signal narrative
+   progress — this *is* how sections separate (with motion + space), **never borders**.
+2. **Keep gradients calm behind text.** Animate atmosphere where there's no copy; dim/scrim
+   behind headlines and body so contrast holds at every frame.
+3. **One accent thread.** Don't scatter all three accents; escalate deliberately at beats.
+4. **Verify contrast in motion.** Test text against the gradient's brightest moment.
+5. **Respect reduced motion:** with motion off, scenes settle to a clean static state with
+   the same colors/contrast (no mid-animation freeze).
+
+## Optional light theme
+
+`[data-theme="light"]`: `--bg-base:#f7f8fc; --bg-scene-1:#f3f5fb; --bg-scene-2:#f6f3fc;
+--bg-scene-3:#eef7f8; --surface-1:#ffffff; --text-primary:#0b0d14; --text-secondary:#3a4055;
+--text-muted:#5d6480; --accent:#4f46e5;` and re-verify contrast (incl. mid-transition).
+**Cinematic dark is the default identity.**

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

@@ -0,0 +1,122 @@
+# Component Library — Motion Storytelling
+
+Specs for the 17 required components **plus the storytelling components** (Scroll Scene,
+Pinned Sequence, Reveal Timeline, Horizontal Scene, Scroll Progress). Each: purpose, anatomy,
+tokens, states, responsive + a11y. Semantic HTML; shared tokens; **no borders between
+sections**; full text in the DOM (animation only affects presentation).
+
+Shared primitives:
+
+```css
+.btn { display:inline-flex; align-items:center; gap: var(--space-2);
+  font-weight:600; font-size:.9375rem; padding: var(--space-3) var(--space-6);
+  border-radius: var(--radius-pill); border:1px solid transparent; cursor:pointer;
+  transition: transform .15s ease, background .2s ease, box-shadow .2s ease; }
+.btn:active { transform: translateY(1px); }
+.btn-primary { background: var(--accent); color: var(--text-on-accent); box-shadow: var(--glow); }
+.btn-primary:hover { background: var(--accent-hover); }
+.btn-ghost { background: transparent; color: var(--text-primary); border-color: var(--border-default); }
+.card { background: var(--surface-1); border:1px solid var(--border-subtle);
+  border-radius: var(--radius-xl); padding: var(--space-8); }
+:where(a,button,input,[tabindex]):focus-visible { outline:2px solid var(--ring);
+  outline-offset:2px; border-radius: var(--radius-sm); }
+```
+
+## ★ Storytelling components (the signature)
+- **Scroll Scene** (`.scene` + `.scene__stage`) — a pinned stage over a tall scroll track;
+  the base for pinned/scrub beats. Unpins on mobile/reduced motion (final state shown).
+- **Pinned Sequence** — a Scroll Scene whose stage **scrubs** a sequence to scroll progress:
+  image frames (`<canvas>`/swapped `<img>`), an SVG draw (`stroke-dashoffset`), or transforms.
+  Full meaning available statically (final frame + alt/text). Performant (rAF, decoded frames).
+- **Reveal Timeline** — a section whose children enter in an ordered stagger via
+  `IntersectionObserver` (`.in`); the workhorse for non-pinned scenes.
+- **Horizontal Scene** — a pinned stage translating a track on the X axis as you scroll Y;
+  **keyboard-accessible** (focus advances it) with a vertical-stack fallback (mobile/reduced motion).
+- **Scroll Progress** — a slim top progress bar and/or chapter dots for orientation;
+  `role="progressbar"`/nav; updates via scroll (rAF).
+
+All motion: see `motion-system.md`. All gated by `prefers-reduced-motion`.
+
+---
+
+## 1. Navbar
+Sticky bar; transparent over the hero, gains background/blur on scroll. Logo · nav links ·
+primary CTA + "Sign in" · mobile hamburger. **Extensionless hrefs**. Optional dropdown/
+mega-menu (vanilla). May host **Scroll Progress** + chapter dots. Mobile: full-screen
+overlay, focus-trap, ESC. a11y: `aria-current`, `aria-expanded`; nav never hijacks scroll.
+
+## 2. Hero
+Layout SH-A/SH-B/SH-C. Kinetic display H1 (line reveal) · deck · CTA pair · animated gradient
+atmosphere or a scrub sequence. One H1, one primary CTA. Full headline text in DOM; motion
+is presentation. Decorative atmosphere `aria-hidden`. Reduced motion → static hero.
+
+## 3. Feature Grid
+`.grid.cols-3` of `.card`s revealed via **Reveal Timeline** (stagger). Icon · H3 · body ·
+optional link. Calm passage between big beats. Hover lift.
+
+## 4. Bento Grid
+Asymmetric tiles revealed in sequence; one tile may contain a mini scrub/clip. Single column
+on mobile.
+
+## 5. Testimonials
+Quotes revealed in sequence, or a pinned scene where quotes swap on scroll. `<blockquote>` +
+`<cite>`. Carousel optional (buttons + `aria`).
+
+## 6. Logos Section
+"Trusted by" + logo row; gentle staggered reveal or slow pausable marquee. `<img alt>`.
+
+## 7. Pricing
+Layout P-A/P-B. Tier cards reveal in sequence; highlighted tier accent + "Most popular";
+monthly/annual toggle. Light motion (don't over-animate a decision moment). a11y: real switch/radio.
+
+## 8. FAQ
+Accordion; items reveal on enter. `<button>` + collapsible answer (height/opacity). a11y:
+`aria-expanded`/`aria-controls`. Content readable without motion.
+
+## 9. CTA → **Finale**
+Layout C-A: the story's payoff — a closing pinned/parallax beat with a big line + **primary
+CTA**. `--section-y-lg`, no border. Reduced motion → static band.
+
+## 10. Footer
+Mega footer; minimal motion (a subtle reveal at most). Brand · columns · legal · social.
+`<footer>`, `<nav>` lists.
+
+## 11. Dashboard Preview
+Product app shell revealed via **Pinned Sequence** (assembles/scrubs) or a clean reveal.
+Real-looking data; final state is a complete static screenshot with alt. Decorative chrome `aria-hidden`.
+
+## 12. Agent Workflow Section
+A **pinned narrative** (ST-A) or **reveal timeline**: steps (Plan → Retrieve → Act → Verify)
+advance with scroll, a traveling accent connector tracing the flow. a11y: ordered `<ol>` text
+equivalent; readable statically.
+
+## 13. Code Preview
+Code in a window-framed card; lines can **type/highlight on reveal** (reduced motion → full
+code shown). `<pre><code>`; copy `aria-label`. Never gate the code behind animation.
+
+## 14. Terminal Preview
+Terminal card; command **types on scroll-in** (reduced motion → final output shown). Real text.
+
+## 15. Trust Section
+Big metrics that **count up** on reveal (final value in DOM); accent on numbers. Often a calm
+beat after a big scene. tabular-nums.
+
+## 16. Security Section
+Compliance badges + assurances; gentle staggered reveal. Calm, factual. Badges alt text.
+
+## 17. Enterprise Section
+"Built for enterprise" beat: value props reveal in sequence + "Talk to sales" CTA. No border.
+
+---
+
+## Component rules
+- **Full content in the DOM; motion is presentation.** Every component is complete and
+  readable with motion disabled (reduced motion → final state).
+- **Storytelling components gate on `prefers-reduced-motion`** and **unpin on mobile**; never
+  trap content or block normal scrolling.
+- Compose from shared `.btn`/`.card`/`.scene`/tokens — no animation libraries.
+- Every interactive element has hover **and** `:focus-visible`; horizontal scenes are
+  keyboard-operable; components reflow to single column by `md`/`sm`.
+- Decorative visuals/atmospheres `aria-hidden`; informative media has meaningful `alt`.
+- Restraint: one strong motion per scene; alternate big beats with calm sections; performant
+  (transform/opacity, rAF/IO) — **never** layout-thrashing or scroll-jacking.

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

@@ -0,0 +1,81 @@
+# Design Principles — Motion Storytelling
+
+The philosophy distilled from motion-led references (Apple product pages, Stripe, Linear,
+Igloo Inc, Active Theory, Cuberto, Awwwards winners) and modern AI sites (OpenAI, Anthropic,
+Perplexity, Cursor, Runway). The guiding tension: scroll-driven motion is captivating but
+easy to ruin — this system makes it **purposeful, performant, and accessible**.
+
+## The one-sentence philosophy
+
+**The scroll is the narrator.** Design each page as a story told through scroll — scenes
+pin, sequences scrub, elements reveal in order — where every motion advances the narrative
+or clarifies the product, and the content is always readable even with motion off.
+
+## Core principles
+
+1. **Story first, motion second.** Write the narrative (problem → product → proof → outcome)
+   before choreographing anything. Motion expresses the story; it isn't the story.
+2. **Every animation earns its place.** It advances a beat, reveals structure, demonstrates
+   the product, or directs attention. If it does none of these, cut it.
+3. **Pin to focus.** Use sticky **pinned scenes** to hold a moment while its content
+   transforms — the viewer dwells on one idea as it unfolds.
+4. **Scrub to demonstrate.** Tie a sequence (assembly, SVG draw, count, layer move) to
+   scroll progress so the viewer *controls* the reveal — satisfying and clear.
+5. **Choreograph reveals.** Elements enter in a deliberate order and stagger as they cross
+   the viewport, leading the eye along the narrative.
+6. **Depth through parallax — gently.** Layers move at different rates for cinematic depth;
+   keep it subtle to avoid disorientation.
+7. **Smooth, never janky.** 60fps via compositor-only properties (`transform`/`opacity`),
+   rAF-throttled scroll, `IntersectionObserver`. Performance *is* the aesthetic.
+8. **Never hijack the user.** No scroll-jacking that fights native scrolling, traps the
+   user, or makes content unreachable. The page must scroll normally and be skimmable.
+9. **Accessible by construction.** Content is fully readable with motion off; honor
+   `prefers-reduced-motion`; nothing essential is gated behind an animation.
+10. **Restraint within drama.** A few strong, well-built moments beat dozens of twitchy
+    effects. Calm passages let the big beats land.
+
+## Motion hierarchy (how much movement, where)
+
+- **Hero / chapter beats:** the boldest motion — a scrub sequence or pinned kinetic headline.
+- **Feature scenes:** medium — pinned product demos, layered reveals, transforms.
+- **Supporting content:** light — staggered fade/rise reveals as sections enter.
+- **Body/reading:** minimal — text appears cleanly; never animate long paragraphs in.
+- **Micro:** hover/press feedback, magnetic buttons, link underlines, nav morphs.
+
+## Storytelling devices
+
+- **Pinned scene:** a tall section whose inner content sticks and animates through scroll.
+- **Scrubbed sequence:** scroll progress drives a timeline (frames/SVG/transform).
+- **Reveal timeline:** ordered, staggered entrance of a scene's elements.
+- **Scene transition:** background/gradient shifts between scenes (the "chapter change").
+- **Horizontal scene:** a section that scrolls sideways as you scroll down (used sparingly,
+  keyboard-accessible, with a normal-scroll fallback).
+- **Kinetic type:** headlines that assemble line-by-line, mask-reveal, or track the scroll.
+- **Progress cue:** a slim scroll progress indicator / chapter dots for orientation.
+
+## Visual-hierarchy laws
+
+- **One H1 per page**, the anchor of the opening scene.
+- **Motion = importance.** The most important idea gets the strongest, most dwelt-on motion.
+- **Contrast ladder** holds at every animation state — text stays AA mid-transition.
+- **One primary CTA per viewport.**
+- **Group by scene + space + background**, not borders between sections.
+- **Accent traces the story** — one vivid accent threads through the narrative (a line that
+  draws, a highlight that moves), not scattered everywhere.
+
+## Reference cues (what each does well)
+
+- **Apple:** scrubbed product sequences, pinned scenes, immaculate performance + restraint.
+- **Stripe / Linear:** purposeful scroll reveals, gradient scene transitions, polish.
+- **Igloo Inc / Active Theory / Cuberto / Awwwards:** cinematic, inventive scroll narratives
+  (borrow the craft; keep it accessible and performant).
+
+## Do / Don't
+
+**Do:** storyboard first · pin to focus · scrub to demonstrate · choreograph reveals ·
+subtle parallax · compositor-only 60fps motion · one accent tracing the story · readable
+with motion off · scroll progress cues.
+
+**Don't:** motion for its own sake · scroll-jacking that fights the user · content trapped
+until an animation plays · janky/layout-thrashing effects · animation libraries · animating
+long body text · disorienting parallax · no reduced-motion fallback · borders between scenes.