spirewise 1.7.0 → 1.8.0

package/skills/product-demo-first-design-system/README.md

@@ -0,0 +1,96 @@
+# product-demo-first-design-system
+
+A world-class, **product-demo-first design system** for building websites where the
+**product itself is the hero of every page** — framed screenshots, interactive demos,
+video, code/terminal, and live previews. Distilled from product-led leaders (**Linear,
+Vercel, Stripe, Retool, Framer, Loom, Arc**) and modern AI sites (**OpenAI, Anthropic,
+Perplexity, Cursor, Replit**). It gives coding/design/UI/branding/website-generation
+agents a complete, reusable system so they can ship product-led sites that convert.
+
+It also ships a **production website-generation framework**: a multipage site (15+
+pages, 10+ sections/page, **≥3 demo moments per page**, **no borders/dividers between
+sections**) in **pure HTML/CSS/vanilla JS** (no React/Vue/Tailwind/Bootstrap/jQuery/any
+library — demos included), with **clean Vercel-ready URLs** (no `.html`), navigation, and
+full SEO.
+
+> The full design intelligence is **baked into the companion files** (live research
+> optional, to save tokens). Outputs a generated site/system into a `website/` folder.
+> Sibling design skills: `ai-dark-futuristic-design-system` (dark), `apple-premium-minimal-design-system` (light minimal).
+
+## Install
+
+```bash
+npx spirewise install -s product-demo-first-design-system          # pick agents + scope
+npx spirewise install -s product-demo-first-design-system -a claude,cursor -sc workspace
+```
+
+## Remove
+
+```bash
+npx spirewise remove -s product-demo-first-design-system           # pick agents + scope
+npx spirewise remove -s product-demo-first-design-system -a claude,cursor -sc both
+```
+
+(No Node? `./install.sh -s product-demo-first-design-system` and `./install.sh remove -s product-demo-first-design-system`.)
+
+## Use
+
+After installing, ask your agent:
+
+> "Build a product-led, demo-first website for our product"
+> "Make it like Linear/Vercel/Retool — show the product working"
+
+It reads the companion files, locks the tokens, plans the demos per page, composes
+demo-first layouts + the Product Frame / Interactive Demo / Video Demo components, applies
+motion + accessibility, and emits **pure HTML + CSS + vanilla JS + tokens + `vercel.json`
++ `sitemap.xml`** into a `website/` folder.
+
+## What's inside
+
+| File | What it gives you |
+|---|---|
+| `SKILL.md` | Orchestrator: demo-first philosophy, mandates, workflow, output, checklist |
+| `design-principles.md` | Show-don't-tell philosophy, hierarchy laws, do/don'ts |
+| `color-system.md` | Neutral product-forward palette + **Product Frame** tokens (CSS vars) |
+| `typography-system.md` | Fonts (sans + mono), fluid type scale, roles |
+| `spacing-system.md` | 4/8-pt scale, container widths, frame-lift rhythm |
+| `layout-system.md` | 12-col grid + canonical demo-first layouts |
+| `component-library.md` | 17 components + Product Frame + demo components |
+| `motion-system.md` | Demo interactions: tabbed demos, autoplay clips, scrub, parallax |
+| `accessibility-system.md` | Contrast, focus, **demo a11y**, keyboard, reduced motion |
+| `website-generation-rules.md` | Pure-vanilla build: pages, clean URLs + `vercel.json`, nav, SEO |
+| `example-page-structures.md` | Demo-first page blueprints per site type |
+
+## The look
+
+A clean, neutral, product-forward canvas (white / `#f7f8fa`) with soft panels so the
+**product pops**, a confident **indigo** accent, modern functional type, generous space,
+and a signature **Product Frame** (elevated browser/app/device chrome) that makes every
+screenshot, clip, and live demo look real. Light by default; dark theme included.
+
+## Components (17 + demo toolkit)
+
+Navbar · Demo Hero · Feature-with-demo Grid · Bento of demos · Testimonials · Logos ·
+Pricing · FAQ · CTA · Footer · Dashboard Preview · Agent Workflow · Code Preview ·
+Terminal Preview · Trust · Security · Enterprise — **plus** Product Frame · Interactive
+Demo · Video Demo · Before/After · Annotated Walkthrough · Tabbed Feature Demo.
+
+## Rules it enforces
+
+- **Demo-first** — every page leads with a Demo Hero; **≥3 demo moments/page**; every
+  major feature proven by a Product Frame (never claim-only); all product media framed
+  (no empty/lorem frames).
+- **Multipage scale (mandatory)** — **15+ pages (≈20)**, **≥10 sections/page (≈12)**, and
+  **no borders/dividers between sections** (separation by whitespace + panels + frame shadow).
+- **Pure vanilla stack** — HTML5 + CSS3 + vanilla JS only (demos included); **no React/
+  Vue/Angular/Svelte/Bootstrap/Tailwind/jQuery/any library**; no build step.
+- **Clean Vercel-ready URLs** — extensionless routes (`/pricing`), with `vercel.json`
+  (`cleanUrls`), `sitemap.xml`, `robots.txt`; refresh + deep links work.
+- **Full navigation + SEO** — desktop dropdowns, mobile overlay, breadcrumbs; per-page
+  title/description, Open Graph, Twitter card, canonical, JSON-LD (+ `VideoObject` for demos).
+- **Centralized tokens**, **accessible by default** (incl. demo a11y: keyboard, captions,
+  reduced motion, no-JS fallbacks), **mobile-first responsive**, **restraint** (calm page,
+  vivid product). **Zero anti-patterns** — no template look, frameworks in the shipped
+  site, claim-only sections, or fake product frames.
+
+See `SKILL.md` for the full workflow and the companion files for every token and spec.

package/skills/product-demo-first-design-system/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: product-demo-first-design-system
+description: >-
+  A world-class, PRODUCT-DEMO-FIRST design system for building websites where the
+  product itself — framed screenshots, interactive demos, video, code/terminal, and
+  live previews — is the hero of every page. Distilled from product-forward leaders
+  (Linear, Vercel, Stripe, Retool, Framer, Loom, Arc) and modern AI sites (OpenAI,
+  Anthropic, Perplexity, Cursor, Replit). It gives coding/design/UI/branding/website-
+  generation agents a complete, reusable system: design philosophy, color/typography/
+  spacing/grid/layout tokens (with a signature product-frame treatment), a 17+ -
+  component library (Demo Hero, Product Frame, Interactive Demo, Video Demo,
+  Before/After, Annotated Walkthrough…), a motion system, 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/Tailwind/Bootstrap/jQuery/any library),
+  with clean Vercel-ready URLs (no `.html`), navigation, and full SEO. Use when the
+  user asks for a "product-led / demo-first website", "show the product", "interactive
+  product demo landing page", "make it like Linear/Vercel/Retool", or "a product
+  design system / tokens". The full system is baked into the companion files (live
+  research optional). Outputs a generated site/system into a `website/` folder.
+---
+
+# Product Demo First Design System
+
+A complete, agent-ready design system for **product-led websites** where, on every
+page, the visitor **sees the product working** — not just reads about it. Every
+section is built around a demo: a framed screenshot, an interactive preview, a short
+autoplay clip, a code/terminal sample, a before/after, or an annotated walkthrough.
+"Show, don't tell." Distilled from Linear, Vercel, Stripe, Retool, Framer, Loom, Arc,
+and modern AI sites (OpenAI, Anthropic, Perplexity, Cursor, Replit).
+
+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 — demo-first on every page
+
+- **Lead with the product.** Every page opens with a **Demo Hero** that shows the
+  product (interactive preview, video, or a crisp framed screenshot), not a stock illo.
+- **Every major feature is proven by a demo.** Pair each claim with a visual: a
+  product frame, a short clip, a code sample, or a before/after — never claim-only.
+- **At least one interactive/visual demo per major section**, and **≥3 distinct demo
+  moments per page** (hero demo + feature demos + a deeper interactive/video demo).
+- **The product frame is the signature.** A reusable browser/device/app frame (its own
+  elevated chrome) makes product media look real and premium on any page.
+
+## 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**,
+   each built around a demo or the product where possible.
+3. **No borders/dividers between sections.** **Zero border widths, lines, rules, or
+   `<hr>` between sections.** Separate sections with whitespace, soft background panels,
+   elevation (framed product media), and type hierarchy — never a border.
+4. **Pure HTML + CSS + vanilla JS — no frameworks/libraries.** The generated site uses
+   **only HTML5, CSS3, and vanilla JavaScript** (including all interactive demos). No
+   React/Vue/Angular/Svelte/Next, no Bootstrap/Tailwind/any CSS framework, no jQuery/
+   any UI or JS 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, animation-ready.
+
+See `website-generation-rules.md` for the required page list, required sections, 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
+**product-led / demo-first** (Linear/Vercel/Retool/Loom energy) — for a SaaS product,
+AI startup, developer platform, or enterprise tool — 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 demo-first philosophy, hierarchy laws, do/don'ts |
+| `color-system.md` | Neutral product-forward palette + product-frame tokens (CSS vars) |
+| `typography-system.md` | Fonts, fluid type scale, weights, tracking, roles |
+| `spacing-system.md` | 4/8-pt scale, container widths, section/card rhythm |
+| `layout-system.md` | Grid + the canonical demo-first section layouts |
+| `component-library.md` | Specs for all 17 components + the demo components |
+| `motion-system.md` | Demo interactions: tabbed demos, autoplay clips, scrub, parallax |
+| `accessibility-system.md` | Contrast, focus, motion, demo a11y, keyboard |
+| `website-generation-rules.md` | Pure-vanilla build: pages, clean URLs + `vercel.json`, nav, SEO |
+| `example-page-structures.md` | Ready demo-first 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, components, motion, and
+the product-demo patterns. **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, 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 centered on showing the product.
+
+## Phase 2 — Generate (the workflow)
+
+1. **Clarify intent:** site type (SaaS / dev platform / AI / enterprise tool), the key
+   product surfaces to demo, brand accent (or default indigo), 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. **Plan the demos:** for each page, list the product moments to show (hero demo +
+   per-feature demos + one deep interactive/video demo). Demos drive the layout.
+4. **Compose layouts + components:** use the demo-first layouts and the Product Frame /
+   Interactive Demo / Video Demo / Before-After / Annotated Walkthrough components.
+5. **Apply motion + a11y:** demo interactions per `motion-system.md`, gated by
+   `prefers-reduced-motion`; meet every rule in `accessibility-system.md`.
+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 sections each, demo-first, no
+  inter-section borders), linked with **extensionless URLs** (`/pricing`)
+- `website/css/tokens.css` + `website/css/styles.css`
+- `website/js/main.js` (vanilla nav, demo interactions, motion — progressively enhanced)
+- `website/vercel.json`, `website/sitemap.xml`, `website/robots.txt`
+- `website/assets/` (product screenshots, clips, device frames, 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 clean, neutral, product-forward canvas (white / `#f7f8fa`) with soft panels so the
+**product pops**, a confident **indigo** accent, modern functional type, generous
+space, and a signature **product frame** (elevated browser/device chrome — often dark)
+that makes every screenshot, clip, and live demo look real and premium. Quiet, precise
+motion that animates the *product*, not the page. (Light by default; a dark theme is
+included — for fully dark identity use `ai-dark-futuristic-design-system`, for Apple
+minimal use `apple-premium-minimal-design-system`.)
+
+## Anti-patterns (never ship these)
+
+Outdated startup designs · Bootstrap/ThemeForest/WordPress-template look · generic SaaS
+or old-startup templates · **claim-only sections with no product/demo** · poor
+typography · weak visual hierarchy · overloaded gradients · excessive glassmorphism ·
+poor accessibility · inconsistent spacing · **borders or dividers between sections ·
+single-page sites or thin pages with fewer than 10 sections · any framework/library in
+the shipped site (React/Vue/Tailwind/Bootstrap/jQuery/…) · `.html` in URLs · fake/empty
+product frames or lorem screenshots**. The result must feel like Linear/Vercel/Retool —
+never like a template.
+
+## Verification checklist (run before finishing)
+
+0. **Multipage scale met:** the site has **> 15 pages** (≈20), each page has **≥ 10
+   sections** (≈12), and there are **no borders/dividers between sections**.
+0b. **Demo-first met:** every page leads with a Demo Hero and contains **≥3 distinct
+   demo moments**; major feature sections each prove the claim with a product visual.
+0c. **Pure vanilla + clean URLs:** zero frameworks/libraries; all routes extensionless
+   with a working `vercel.json` (`cleanUrls`), `sitemap.xml`, and `robots.txt`.
+0d. **Nav + SEO:** desktop nav/dropdowns + mobile menu + breadcrumbs; per-page title/
+   description, Open Graph + Twitter card, canonical, and 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 section is a recognized layout; every component matches `component-library.md`;
+   the Product Frame is used for all product media.
+4. Body text ≥ 4.5:1 contrast, large text ≥ 3:1; visible focus; motion respects
+   `prefers-reduced-motion`; semantic landmarks + alt text present; demos keyboard-usable.
+5. Fully responsive (360 → 1440+), no horizontal scroll, tap targets ≥ 44px.
+6. Trips **zero** anti-patterns; product media is real (not empty/lorem frames).
+7. Output looks like it belongs next to Linear/Vercel/Retool — product-led and
+   conversion-focused.

package/skills/product-demo-first-design-system/accessibility-system.md

@@ -0,0 +1,58 @@
+# Accessibility System — Product Demo First
+
+Product-led pages add a11y risk: **interactive demos, autoplay video, and annotated
+frames** must be perceivable and operable for everyone. This system bakes WCAG 2.1 AA
+into the look, including the demo components.
+
+## Color & contrast
+- **Body text ≥ 4.5:1**, large/UI text **≥ 3:1**, on its real panel. Use
+  `--text-secondary`/`--text-muted` for content. Check **in-frame text** (`--frame-text`
+  on `--frame-bg`) too — both page and product-frame text must pass.
+- **Non-text contrast ≥ 3:1** for controls, focus rings, demo annotations/callouts, and
+  before/after handles.
+- **Don't encode meaning in color alone** — annotations pair color with a number/label;
+  status pairs color with an icon.
+- **Gradient/low-contrast text banned for body**; `--grad-text` only on large hero display.
+
+## Demos & media (the key area)
+- **Autoplay video** is **muted, loop, `playsinline`**, plays only on scroll-in, and has
+  a **visible play/pause control**. Under `prefers-reduced-motion`, show the **poster
+  only** (no autoplay). Provide captions/track for any narrated video.
+- **Interactive demos** are fully **keyboard operable** (tab/enter/space/arrows), have
+  visible focus, and a **no-JS fallback** (a static framed screenshot with alt text).
+- **Annotated walkthroughs** provide a **text equivalent** (an ordered `<ol>` of the
+  steps) so the information isn't conveyed by visuals/motion alone; advanceable by keyboard.
+- **Before/After** sliders are operable with arrow keys and have labelled sides.
+- **Tabbed demos** use `role="tablist"/tab/tabpanel`, `aria-selected`, arrow-key nav.
+- Informative product screenshots have meaningful **`alt`**; pure chrome (frame bars,
+  traffic-light dots, spotlight glows) is `aria-hidden`/`alt=""`.
+- No flashing > 3×/sec; no autoplaying audio.
+
+## Focus & keyboard
+- **Always-visible focus:** `:focus-visible { outline:2px solid var(--ring);
+  outline-offset:2px }` on every control — including demo controls. Never bare `outline:none`.
+- **Full keyboard operability**, logical tab order matching visual order; no traps
+  (except intended modal focus-trap with 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>`.
+- Buttons vs links: `<button>` actions, `<a href>` navigation. Lists `<ul>/<ol>`; quotes
+  `<blockquote><cite>`; code `<pre><code>`. Native elements over ARIA; minimal correct ARIA.
+
+## Forms
+- Programmatic `<label>` for every input (placeholders aren't labels); `<fieldset><legend>`
+  for groups; errors in text + `aria-describedby`, focus to first error.
+
+## Touch & responsive
+- **Tap targets ≥ 44×44px** (incl. demo controls/handles). Reflow to 320px, no horizontal
+  scroll, 200% zoom OK, pinch-zoom not disabled.
+
+## Checklist (run before finishing)
+1. Page **and** in-frame text/controls meet AA contrast.
+2. Autoplay video muted + scroll-gated + has controls + poster-only under reduced motion.
+3. Every interactive demo: keyboard-operable, visible focus, no-JS fallback.
+4. Annotated/walkthrough/before-after/tabbed demos have text equivalents + ARIA + key nav.
+5. Visible focus everywhere; skip link; correct landmarks + one H1.
+6. Informative product images have alt; chrome/decorative hidden; reduced-motion honored.
+7. 44px targets; reflow to 320px; 200% zoom; zoom not disabled.

package/skills/product-demo-first-design-system/color-system.md

@@ -0,0 +1,109 @@
+# Color System — Product Demo First
+
+A neutral, product-forward palette: a calm page so the **product pops**, one confident
+accent, and a signature **product-frame** treatment (elevated browser/device/app chrome
+— often dark) that makes screenshots, clips, and live demos look real. Sections separate
+via soft panels + whitespace + the floating frame — **never borders**. Override only
+`--accent-*` to rebrand. Contrast targets: body ≥ 4.5:1, large/secondary ≥ 3:1. A dark
+page theme is included.
+
+## Tokens (`:root`)
+
+```css
+:root {
+  /* ---- Page + section panels (light, neutral, product-forward) ---- */
+  --bg-page:    #ffffff;  /* base page */
+  --bg-canvas:  #f7f8fa;  /* default section panel (product floats on this) */
+  --bg-muted:   #f1f3f7;  /* alternate section panel */
+  --bg-tint:    #f3f2ff;  /* faint accent-tinted panel (rare) */
+
+  /* ---- Surfaces (cards) ---- */
+  --surface:        #ffffff;
+  --surface-muted:  #f5f6f9;
+  --surface-raised: #ffffff;
+  --surface-glass:  rgba(255,255,255,0.72); /* sticky nav glass */
+
+  /* ---- PRODUCT FRAME (the signature demo chrome — dark, elevated) ---- */
+  --frame-bg:      #0e1116;  /* product canvas / app background inside the frame */
+  --frame-bar:     #171b22;  /* the browser/title bar */
+  --frame-border:  rgba(255,255,255,0.08);
+  --frame-text:    #e6e9ef;  /* text inside the frame */
+  --frame-muted:   #9aa3b2;
+  --frame-dot1:    #ff5f57; --frame-dot2:#febc2e; --frame-dot3:#28c840; /* traffic lights */
+
+  /* ---- Text ramp (on the light page) ---- */
+  --text-primary:   #0b0d12;
+  --text-secondary: #3c4250;
+  --text-muted:     #697186;
+  --text-faint:     #9aa1b0;  /* decorative/disabled — non-essential only */
+  --text-on-accent: #ffffff;
+
+  /* ---- Borders / hairlines (cards/inputs/in-frame — NOT between sections) ---- */
+  --border-subtle:  rgba(11,13,18,0.06);
+  --border-default: rgba(11,13,18,0.10);
+  --border-strong:  rgba(11,13,18,0.16);
+  --ring:           #4f46e5;  /* focus ring */
+
+  /* ---- Accent (brand action color) ---- */
+  --accent:        #4f46e5;  /* indigo — primary actions/links */
+  --accent-hover:  #6366f1;
+  --accent-press:  #4338ca;
+  --accent-2:      #06b6d4;  /* cyan — annotations/highlights on demos */
+  --accent-soft:   rgba(79,70,229,0.10);
+
+  /* ---- Semantic ---- */
+  --success: #16a34a; --success-soft: rgba(22,163,74,0.12);
+  --warning: #b45309; --warning-soft: rgba(180,83,9,0.12);
+  --error:   #dc2626; --error-soft:   rgba(220,38,38,0.12);
+  --info:    #4f46e5; --info-soft:    rgba(79,70,229,0.12);
+
+  /* ---- Gradients (subtle; spotlight the product) ---- */
+  --grad-spotlight: radial-gradient(60% 70% at 50% 0%, rgba(79,70,229,0.12) 0%, transparent 62%);
+  --grad-soft:      linear-gradient(180deg, #ffffff 0%, #f1f3f7 100%);
+  --grad-accent:    linear-gradient(135deg, #4f46e5 0%, #06b6d4 100%);
+  --grad-text:      linear-gradient(90deg, #0b0d12 0%, #4f46e5 100%);
+
+  /* ---- Elevation (so the product frame floats) ---- */
+  --shadow-sm: 0 1px 2px rgba(11,13,18,0.06);
+  --shadow-md: 0 8px 24px rgba(11,13,18,0.10);
+  --shadow-lg: 0 30px 70px rgba(11,13,18,0.18);  /* product-frame float */
+  --shadow-frame: 0 40px 90px rgba(11,13,18,0.22), 0 0 0 1px var(--border-subtle);
+}
+```
+
+## Palette roles
+
+- **Page + panels** (`--bg-*`): full-bleed section fills. **Alternate `--bg-canvas` and
+  `--bg-muted`** (or white) between sections to separate by color — **never a border**.
+- **Surfaces** (`--surface-*`): cards/panels on a section, soft shadow, large radius.
+- **Product frame** (`--frame-*`): the signature chrome around every product
+  screenshot/clip/live demo — usually a dark browser/app frame with traffic-light dots,
+  floated with `--shadow-frame` so it pops off the light page. This is what makes demos
+  feel real; use it consistently for all product media.
+- **Text** (`--text-*`): primary headings, secondary body, muted meta. Never `--text-faint`
+  for real content.
+- **Borders** (`--border-*`): hairlines for cards/inputs and *inside* the product frame —
+  not for dividing page sections.
+- **Accent** (`--accent*`): primary CTA, active states, links; `--accent-2` for demo
+  annotations/highlights.
+- **Gradients** (`--grad-*`): `--grad-spotlight` behind the hero product; `--grad-soft`
+  for a gentle panel; `--grad-text` on one hero phrase. Keep subtle, behind the product.
+- **Success / Warning / Error / Info**: status, validation, badges only.
+
+## Usage rules
+
+1. **Calm page, vivid product.** Keep page chrome neutral so the framed product (with
+   its own UI colors) is the brightest thing on screen.
+2. **Separate sections with panels + space + frame shadow, not lines.** Mandatory.
+3. **Frame all product media.** Every screenshot/clip/live demo sits in the product
+   frame with `--shadow-frame`. Don't drop raw images on the page.
+4. **Gradients rare + subtle**, mostly as a spotlight *behind* the product.
+5. **Check contrast** on both the light page text and the in-frame (`--frame-text`)
+   text; both must meet AA.
+
+## Optional dark page theme
+
+Provide `[data-theme="dark"]`: `--bg-page:#06070a; --bg-canvas:#0b0d12;
+--bg-muted:#11141b; --text-primary:#f4f6fb; --text-secondary:#c3c9d6;
+--text-muted:#8a92a6;` — keep the same product frame (it already reads as a device) and
+re-verify contrast. **Light is the default identity.**

package/skills/product-demo-first-design-system/component-library.md

@@ -0,0 +1,142 @@
+# Component Library — Product Demo First
+
+Specs for the 17 required components **plus the demo components** that make this system
+product-led. Each: purpose, anatomy, tokens, states, responsive + a11y. Semantic HTML;
+shared tokens; **no borders between sections** (hairlines only inside cards/frames).
+
+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(--shadow-sm); }
+.btn-primary:hover { background: var(--accent-hover); }
+.btn-secondary { background: var(--surface-muted); color: var(--text-primary);
+  border-color: var(--border-default); }
+.card { background: var(--surface); border:1px solid var(--border-subtle);
+  border-radius: var(--radius-xl); padding: var(--space-8); box-shadow: var(--shadow-sm); }
+.card:hover { box-shadow: var(--shadow-md); }
+:where(a,button,input,[tabindex]):focus-visible { outline:2px solid var(--ring);
+  outline-offset:2px; border-radius: var(--radius-sm); }
+```
+
+## ★ Product Frame (the signature primitive — use for ALL product media)
+A reusable elevated **browser/app/device chrome** that wraps every screenshot, clip,
+interactive demo, or code/terminal. Anatomy: frame (`--frame-bg`, `--radius-frame`,
+`--shadow-frame`) · title bar (`--frame-bar`) with traffic-light dots + optional URL/
+tab/toolbar · content area (screenshot `<img>`, `<video>`, live HTML/CSS UI, or `<pre>`).
+Variants: **Browser** (URL bar), **App** (sidebar+topbar via Layout D-A), **Mobile**
+(phone outline), **Code/Terminal** (mono). Floats on the page with `--frame-lift` air.
+a11y: informative screenshots get real `alt`; the frame chrome is `aria-hidden`; live
+demos are keyboard-operable.
+
+```css
+.frame { background: var(--frame-bg); border:1px solid var(--frame-border);
+  border-radius: var(--radius-frame); box-shadow: var(--shadow-frame); overflow:hidden; }
+.frame__bar { display:flex; align-items:center; gap: var(--space-2);
+  padding: var(--space-3) var(--space-4); background: var(--frame-bar); }
+.frame__dots span{ width:11px;height:11px;border-radius:50%; display:inline-block; }
+.frame__body { color: var(--frame-text); }
+```
+
+---
+
+## 1. Navbar (+ dropdown/mega-menu + breadcrumb)
+Sticky glass bar (`--surface-glass` + `backdrop-filter: blur(16px)`). Logo · nav links ·
+primary CTA + "Sign in" · mobile hamburger. **Extensionless hrefs** (`/platform`).
+**Dropdown/mega-menu** (vanilla JS) opens a multi-column panel — and may include a tiny
+product thumbnail per item. Mobile: full-screen overlay, accordion, focus-trap, ESC.
+**Breadcrumb** on deep pages. a11y: `aria-haspopup/expanded`, `aria-current="page"`.
+
+## 2. Hero → **Demo Hero**
+Layout DH-A/DH-B/DH-C. Eyebrow · H1 · short lead · CTA pair · **large Product Frame**
+(interactive demo, autoplay clip, or crisp screenshot) with `--grad-spotlight`. The
+frame is the largest element. One H1, one primary CTA. The hero MUST show the product.
+
+## 3. Feature Grid → **Feature-with-demo**
+`.grid.cols-3` cards, but each card includes a **mini Product Frame / clip / code
+snippet** above the title + text — never icon-only. Hover: shadow lift.
+
+## 4. Bento Grid (of demos)
+Asymmetric soft-card tiles, several containing small framed product moments, a metric, a
+mini chart, or a short clip. One large product tile anchors it. Single column on mobile.
+
+## 5. Testimonials
+3-up quote cards or one featured quote; optionally paired with the customer's product
+screenshot/result in a frame. `<blockquote>` + `<cite>`; carousel optional.
+
+## 6. Logos Section
+"Trusted by" eyebrow + neutral-gray logo row/marquee (pausable). Whitespace generous.
+
+## 7. Pricing
+Layout P-A/P-B. Tier cards (price tabular-nums, feature list, CTA); highlighted tier
+(accent ring + "Most popular"); monthly/annual toggle. a11y: real `role="switch"`/radio.
+
+## 8. FAQ
+Accordion (Q-A). `<button>` + collapsible answer; height/opacity animation; in-list
+hairline ok. a11y: `aria-expanded`/`aria-controls`.
+
+## 9. CTA
+Layout C-A: soft panel (no border), big H2, supporting line, primary + text CTA — often
+with a final **mini Product Frame** or a "try it" interactive demo. `--section-y-lg`.
+
+## 10. Footer
+FT-A: brand · 4–6 link columns · legal · locale/social. Muted text, generous space, soft
+panel; optional hairline at the very top edge only. `<footer>`, `<nav>` link lists.
+
+## 11. Dashboard Preview
+The product's app shell (Layout D-A) inside an **App Product Frame**: sidebar + top bar +
+content with real-looking data. Central to most pages; may show soft parallax/scroll.
+
+## 12. Agent Workflow Section
+Step pipeline (Plan → Retrieve → Act → Verify) as connected cards, ideally with a
+**Product Frame** showing the agent running. Animate sequential reveal. a11y: `<ol>` text equivalent.
+
+## 13. Code Preview
+Mono code in a **Code Product Frame** (filename tab, copy button, optional language
+tabs). Low-saturation syntax tint on `--frame-text`. `<pre><code>`; copy `aria-label`.
+
+## 14. Terminal Preview
+**Terminal Product Frame**: header + prompt lines; optional typewriter (reduced-motion →
+final state). Real text, not an image.
+
+## 15. Trust Section
+Metrics band: big tabular-nums numbers + muted labels (count-up on reveal; final value in
+DOM). Often beside a demo to convert "looks good" → "teams rely on it".
+
+## 16. Security Section
+Compliance badges (SOC 2/ISO/GDPR/HIPAA) + assurances (encryption, SSO/SAML, audit logs)
++ "Read security docs". Calm, factual. Badges have alt text.
+
+## 17. Enterprise Section
+"Built for enterprise" panel: SSO/RBAC/SLAs/VPC props + "Talk to sales" + logo wall.
+Soft panel, no border.
+
+---
+
+## Demo components (the product-first toolkit)
+- **Interactive Demo** — a live, vanilla-JS mini product inside a Product Frame the user
+  can click/type/toggle (e.g., a working mini editor, toggle, filter, builder). Keyboard
+  operable; degrades to a static screenshot without JS.
+- **Video Demo** — `<video muted playsinline loop>` inside a Product Frame, **autoplay on
+  scroll into view**, pause off-screen; poster image; reduced-motion → poster only; a
+  visible play/pause control.
+- **Before/After** — draggable slider or side-by-side framed comparison; keyboard
+  (arrow keys) accessible; labels for each side.
+- **Annotated Walkthrough** — one large Product Frame with sequential numbered callouts
+  (`--accent-2`) pointing at UI; advances on scroll or prev/next; `<ol>` text equivalent.
+- **Tabbed Feature Demo** — tabs swap the content of one Product Frame (Layout F-B);
+  `role="tablist"`/`tab`/`tabpanel`, arrow-key nav.
+
+## Component rules
+- **Frame all product media** with the Product Frame; never drop raw images on the page.
+- Compose from shared `.btn`/`.card`/`.frame`/tokens — no bespoke colors/radii.
+- Every interactive element + demo has hover **and** `:focus-visible`; demos are keyboard
+  operable and have a no-JS fallback (static framed screenshot).
+- Every component responsive to single-column by `md`/`sm`.
+- Decorative visuals `aria-hidden`; informative product shots have meaningful `alt`.
+- Restraint: ≤ one subtle gradient per section (usually a spotlight behind the product);
+  hairlines only inside cards/frames — **never between page sections**.

package/skills/product-demo-first-design-system/design-principles.md

@@ -0,0 +1,66 @@
+# Design Principles — Product Demo First
+
+The philosophy distilled from product-led leaders (Linear, Vercel, Stripe, Retool,
+Framer, Loom, Arc) and modern AI sites (OpenAI, Anthropic, Perplexity, Cursor, Replit).
+
+## The one-sentence philosophy
+
+**Show the product working.** The website's job is to let visitors *see and feel* the
+product on every screen — through framed UI, interactive demos, clips, and code — so
+the product, not the copy, does the convincing.
+
+## Core principles
+
+1. **Demo-first, always.** Every page leads with the product and proves every major
+   claim with a visual demo. If a section makes a claim with no product moment, it's
+   incomplete.
+2. **The product is the hero.** Layouts exist to frame and spotlight product media.
+   Headlines orient; the demo persuades.
+3. **Make it feel real.** Use a consistent, elevated **product frame** (browser/device/
+   app chrome) so screenshots and live previews look like the actual product, not art.
+4. **Interactive > static > words.** Prefer an interactive demo, then a short clip, then
+   a crisp screenshot, then text — in that order, for any feature.
+5. **One idea, one demo per section.** Each section shows one capability via one focused
+   demo. Don't cram multiple product shots fighting for attention.
+6. **Quiet UI, loud product.** The page chrome is neutral and calm so the product (often
+   with its own color/UI) pops. One restrained brand accent for actions.
+7. **Depth through elevation, not borders.** Separate sections with whitespace, soft
+   panels, and the floating product frame's shadow — **never** lines between sections.
+8. **Motion animates the product.** Tabbed demos, autoplay-on-scroll clips, scrubbable
+   walkthroughs, gentle device parallax — motion reveals how the product works, never
+   decorates the page. Always honor `prefers-reduced-motion`.
+9. **Annotate to teach.** Use callouts/labels on product frames to point at the exact UI
+   that delivers the benefit (Loom/Stripe style).
+10. **Trust beside the demo.** Pair demos with proof — logos, metrics, security — so
+    "it looks great" becomes "and teams rely on it."
+
+## Visual-hierarchy laws
+
+- **One H1 per page**, but the **largest visual is usually the product frame**, not type.
+- **Demo placement is hierarchy:** the most important capability gets the biggest,
+  highest demo (the hero); supporting features get smaller framed demos below.
+- **Contrast ladder:** primary text near-black, secondary mid, tertiary muted — readable
+  grays only (AA). The product frame contrasts with the page panel so it floats.
+- **One primary CTA per viewport**, ideally next to or under the demo it relates to.
+- **Group by space + panel + frame**, not by boxes/borders.
+- **Accent = the action**, not decoration — reserve it for the primary CTA and links.
+
+## Reference cues (what each does well)
+
+- **Linear:** framed UI hero, tabbed feature demos, precise spacing, dark product frame
+  on a clean page.
+- **Vercel:** product/code front and center, deploy demos, crisp dev aesthetic.
+- **Stripe:** elegant code + dashboard demos, annotated flows, refined motion.
+- **Retool / Framer:** interactive builder demos, drag/preview, "try it" moments.
+- **Loom:** video-first product storytelling with annotations.
+- **Cursor / Replit / OpenAI:** live code/terminal demos proving the product in seconds.
+
+## Do / Don't
+
+**Do:** open with a Demo Hero · frame every product shot · prefer interactive/video over
+static · annotate the UI · one demo per section · neutral calm chrome · one accent ·
+elevation + whitespace to separate · real product data.
+
+**Don't:** claim-only sections · empty/lorem/fake product frames · borders between
+sections · five product shots in one section · heavy gradients/glass over the product ·
+tiny low-contrast text · motion that distracts from the product · stock "AI brain" art.