spirewise 1.7.0 → 1.8.0

package/skills/glassmorphism-design-system/design-principles.md

@@ -0,0 +1,77 @@
+# Design Principles — Glassmorphism
+
+The philosophy distilled from glass-leaning references (Apple/visionOS, Stripe, Linear,
+Family, Arc, Vercel) and modern AI sites (OpenAI, Anthropic, Perplexity, Cursor). The
+guiding tension: glassmorphism is beautiful but easy to overdo — this system makes it
+**tasteful, legible, and performant**.
+
+## The one-sentence philosophy
+
+**Frosted glass over living light, with discipline.** A vivid, gentle background provides
+color and depth; a *few* frosted-glass panels float above it to carry the UI — always
+legible, always with a fallback.
+
+## Core principles
+
+1. **One living background per page.** A soft mesh/gradient (optionally drifting) gives
+   the page its light. It stays **low-contrast behind text** so glass panels read.
+2. **Glass for surfaces, not everything.** Nav, key cards, modals, and a hero panel are
+   glass; body text, sections, and most content sit on calm, legible surfaces. Restraint
+   is the whole point.
+3. **Legibility is non-negotiable.** Every glass panel uses a tuned tint (and a scrim
+   where needed) so text clears **AA contrast**. If glass would hurt legibility, make the
+   panel more opaque — never sacrifice contrast for the effect.
+4. **Real glass = blur + tint + edge + shadow.** Translucency, `backdrop-filter: blur()`,
+   a thin top highlight (1px light inner border), and a soft drop shadow together sell
+   the material. Missing any one looks cheap.
+5. **Depth through layering + light.** Z-order, shadow, and a subtle highlight create
+   "panes of glass at different depths." Light appears to come from above.
+6. **Always provide a fallback.** Where `backdrop-filter` is unsupported, or the user
+   prefers reduced transparency, glass becomes a solid tinted surface with the same
+   contrast. The site must never break or become unreadable.
+7. **Motion is gentle light.** The mesh drifts slowly; panels catch a faint sheen on
+   hover; parallax is subtle. Nothing strobes or distracts. Honor reduced motion.
+8. **Performance matters.** `backdrop-filter` is expensive — limit how many large blurred
+   surfaces are on screen at once; reduce/disable blur on low-power/mobile if needed.
+9. **One restrained accent.** The background carries the color; the accent marks the
+   primary action and a few highlights — don't let glass + gradient + many accents fight.
+10. **Consistency over novelty.** Reuse the glass tokens/utilities and components; a
+    coherent glass system beats scattered bespoke effects.
+
+## Visual-hierarchy laws
+
+- **One H1 per page**, usually inside the hero glass panel, brightest against the backdrop.
+- **Contrast ladder on glass:** on-glass primary text near-white/near-black (per theme),
+  secondary tinted, tertiary muted — all still AA on the panel's tint.
+- **Depth = importance:** the most important panel is the most elevated/forward (stronger
+  shadow, slightly more opacity); supporting panels recede.
+- **One primary CTA per viewport** (a solid accent button, not glass — actions need to be
+  unmistakable).
+- **Group with glass panels + space**, not borders between sections.
+- **Accent sparingly** — primary action + 1–2 highlights per section.
+
+## Restraint rules (avoid "excessive glassmorphism")
+
+- **Max ~2–3 large glass surfaces visible per viewport** (e.g., nav + hero card + one
+  feature card) — not a wall of blurred boxes.
+- **No glass on tiny text or long paragraphs** unless the tint guarantees AA; prefer a
+  more opaque surface for reading.
+- **No busy imagery/high-contrast pattern directly behind text** — keep the backdrop soft
+  where words sit (add a scrim if needed).
+- **Don't stack many blurs** (glass on glass on glass) — it muddies and tanks performance.
+
+## Reference cues (what each does well)
+
+- **Apple / visionOS:** material glass with real depth, light, and impeccable legibility.
+- **Stripe:** vivid gradient backdrops + crisp content; glass used sparingly and cleanly.
+- **Linear / Arc / Family:** tasteful translucency, soft glow, premium restraint.
+
+## Do / Don't
+
+**Do:** one soft living background · a few deliberate glass panels · tuned tint + highlight
+edge + shadow · AA-legible on-glass text · solid accent CTAs · gentle mesh/sheen motion ·
+robust solid fallbacks · keep performance in check.
+
+**Don't:** glass on everything · low-contrast text on glass · busy backgrounds behind text
+· blur with no fallback · stacked blurs · borders between sections · rainbow gradients ·
+many competing accents · motion that distracts · stock "AI brain" clichés.

package/skills/glassmorphism-design-system/example-page-structures.md

@@ -0,0 +1,92 @@
+# Example Page Structures — Glassmorphism
+
+Ready-to-assemble, **glass** page blueprints. Each section names a layout (see
+`layout-system.md`) and components (see `component-library.md`). Every page has **one
+living mesh background** with a *few* tasteful, **AA-legible** glass panels floating over
+it. No borders between sections (separate by whitespace + backdrop + glass elevation).
+
+Legend: `GH-* / F-* / P-* / C-* / Q-* / FT-*` layouts · components by name.
+
+## MANDATORY: 15+ page site map (≈20), 10+ sections/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 (≈12)**, **no borders/dividers between
+sections**, pure HTML/CSS/vanilla JS, **extensionless URLs**. 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-section** skeleton — extend toward 12, never fewer than 10.
+Every page must include: **Hero (glass) · Feature Sections · Product Highlights · Trust
+Signals · Testimonials · Use Cases · Statistics · Integrations · CTA · Footer.** Every page
+has exactly **one `.page-bg`** living background.
+
+---
+
+## 1. Home (default)
+1. **Navbar** `.glass--nav` (glass dropdowns) — extensionless links
+2. **Hero** `GH-A` — centered `.glass--strong` panel: eyebrow · H1 · lead · **solid CTA** +
+   ghost · product preview in a second glass panel
+3. **Logos Section** — slim glass strip / on-backdrop logos
+4. **Feature Grid** `F-A` — 3 `.glass` feature cards
+5. **Glass Bento** `F-C` — a few varied glass tiles (one anchor)
+6. **Statistics** — metric glass tiles (count-up)
+7. **Testimonials** — featured glass quote + small quote cards
+8. **Integrations** — glass app grid + "See all" link
+9. **Pricing** `P-A` (or teaser) — glass tier cards
+10. **CTA** `C-A` glass band (solid CTA) + **Footer** `FT-A`
+
+## 2. Platform / Product
+1. Navbar · 2. **Hero** `GH-B` split (glass copy + glass preview) · 3. Feature `F-B`
+alternating · 4. **Dashboard Preview** (glass frame) · 5. Glass Bento · 6. Code Preview
+(glass) · 7. Use Cases · 8. **Statistics** · 9. Testimonials · 10. CTA + Footer
+
+## 3. Features / Solutions
+1. Navbar · 2. Hero (glass) · 3.–8. feature sections (`F-A`/`F-B`/`F-D` tabbed) each with a
+glass card/preview · 9. Integrations · 10. CTA + Footer
+
+## 4. Developers / Documentation
+- **Developers:** Navbar · **Hero** with glass-framed **Code/Terminal Preview** · Logos ·
+  Code Preview (tabbed, glass) · Feature Grid · Use Cases · Statistics · CTA · Footer (≥10).
+- **Docs:** `DOC-A` three-pane (glass sidebar · prose on `glass--strong`/solid for reading ·
+  glass TOC); sticky glass top bar; breadcrumb; inline glass-framed code.
+
+## 5. Enterprise / Security
+1. Navbar · 2. Hero (outcome-led, glass) · 3. Logos · 4. Feature `F-A` · 5. **Enterprise
+Section** (glass panel) · 6. **Security Section** (compliance badges, glass) · 7.
+**Statistics**/ROI · 8. Testimonials (exec) · 9. CTA `C-A` (solid CTA / contact) · 10. Footer
+
+## 6. Pricing
+1. Navbar · 2. Hero (short + toggle) · 3. **Pricing** `P-A/P-B` glass tiers · 4. Feature
+comparison · 5. **Enterprise** band · 6. Logos · 7. **Statistics** · 8. Testimonials · 9.
+**FAQ** `Q-A` (glass panel) · 10. CTA + Footer
+
+## 7. Content pages (About, Careers, Customers, Case Studies, Blog, Partners, Resources, Contact, FAQ)
+Reach **≥10 sections** by composing glass panels over the backdrop: Hero (glass) → body
+sections (values, timeline, roles, customer grid, story, article list, partner tiers,
+resource cards, contact form on a `glass--strong` panel) → Trust Signals → Testimonials →
+Statistics → Integrations → CTA → Footer. Keep reading content on `glass--strong`/solid
+surfaces for legibility.
+
+---
+
+## Assembly notes
+- **Scale is mandatory:** 15+ pages, **≥10 sections each**. Never a single/thin page.
+- **One living background per page**; place a *few* deliberate glass panels — don't make
+  everything glass (anti-pattern).
+- **Legibility first:** reading content sits on `glass--strong`/solid; center hero/text
+  over calmer mesh regions; ship the solid fallback.
+- **No borders/dividers between sections** — whitespace + backdrop + glass elevation. One
+  layout + one idea per section.
+- **Primary CTAs are solid** accent buttons; glass is for surfaces.
+- Use real content; mark guesses `[PLACEHOLDER]`.

package/skills/glassmorphism-design-system/layout-system.md

@@ -0,0 +1,81 @@
+# Layout & Grid System — Glassmorphism
+
+A 12-column fluid grid + canonical glass section layouts. Every page has **one living
+background**; layouts place a *few* glass panels over it. **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`.
+
+## The page shell (one living background)
+
+```css
+.page-bg { position: fixed; inset: 0; z-index:-1; background: var(--bg-mesh);
+           background-attachment: fixed; }
+.page-bg::after { content:""; position:absolute; inset:0;
+           background-image: var(--grain); opacity:.05; mix-blend-mode: overlay; }
+/* All sections are transparent so the one backdrop shows through; glass panels float on top. */
+.section { background: transparent; }
+```
+
+## Canonical glass section layouts
+
+### Hero
+- **GH-A Centered glass card (default):** eyebrow → H1 → lead → CTA pair inside a large
+  **`.glass`/`.glass--strong` hero panel**, centered over a calmer region of the mesh; a
+  product preview can sit in a second glass panel below.
+- **GH-B Split:** copy/CTAs in a glass panel (left), product/preview glass panel (right).
+- **GH-C Floating UI:** a few small glass cards/widgets float (subtle parallax) around a
+  central headline — the "visionOS" look. Keep text legible (calm backdrop behind it).
+
+### Feature
+- **F-A Glass card grid:** `.grid.cols-3` of `.glass` feature cards over the backdrop.
+- **F-B Alternating rows:** copy ↔ a glass product/media panel, flipping sides.
+- **F-C Glass bento:** a few varied glass tiles (one anchor) floating on the mesh.
+- **F-D Tabbed:** glass tabs switch a glass preview panel.
+
+### Pricing / CTA / FAQ / Footer
+- **P-A 3-tier glass cards** (middle highlighted with accent edge + slightly more opacity)
+  + monthly/annual toggle. **P-B 2-tier + enterprise** glass band.
+- **C-A CTA glass band:** a centered `.glass--strong` panel with big H2 + **solid accent
+  CTA**. `--section-y-lg`, no border.
+- **Q-A Accordion FAQ** inside a glass panel (`--container-md`); **Q-B FAQ tiles**.
+- **FT-A Mega footer** on a `.glass--nav`/solid panel; **FT-B minimal**.
+
+### Dashboard / Docs
+- **D-A Dashboard glass:** product app shell inside a glass frame, floated with shadow.
+- **DOC-A Three-pane docs:** glass sidebar + prose (on a `glass--strong`/solid surface for
+  reading) + glass TOC; sticky glass top bar; breadcrumb.
+
+## Composition rules
+
+1. **One background, transparent sections, few glass panels.** `.section{background:
+   transparent; border:0}`; the fixed `.page-bg` shows through; place a *few* `.glass`
+   panels per section — not a wall of glass.
+2. **Separate sections by space + backdrop shift + panel elevation, NEVER borders.** No
+   `<hr>`/divider/`border-top`.
+3. **Keep text over calm backdrop.** Center hero/reading panels over softer mesh regions;
+   use `.glass--strong`/`--scrim` where the backdrop is bright behind text.
+4. **One layout + one idea per section.**
+5. **At least 10 sections per page**, **15+ pages.** Never thin.
+6. **Rhythm:** Glass hero → logos/trust → glass feature grid → glass bento/tabs →
+   metrics → testimonials → integrations → pricing → FAQ → glass CTA band → footer.
+7. **Performance:** limit large blurred panels per viewport; the background is one fixed
+   layer (not re-blurred per panel beyond the panel area).

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

@@ -0,0 +1,86 @@
+# Motion System — Glassmorphism
+
+Motion is **gentle light**: the living background drifts slowly, glass panels catch a faint
+sheen and lift on hover, and a little parallax gives depth. The page feels alive but calm.
+Everything degrades under `prefers-reduced-motion` (and respects reduced transparency).
+
+Distilled from Apple/visionOS depth + light, Stripe gradient motion, and OpenAI/Anthropic/
+Perplexity/Cursor restraint.
+
+## Tokens
+
+```css
+:root {
+  --dur-fast: 150ms;   --dur-base: 260ms;  --dur-slow: 420ms;  --dur-slower: 700ms;
+  --ease-out: cubic-bezier(0.2, 1, 0.3, 1);
+  --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
+  --mesh-drift: 26s;   /* one slow background loop */
+}
+```
+
+## Principles
+1. **Light, not motion.** The strongest "movement" is the slow mesh drift + hover sheen —
+   subtle, premium, never distracting.
+2. **Short + eased** for UI (150–420ms); long + linear for the background loop.
+3. **Move a little:** panel hover lift 2–4px, sheen sweep, parallax ≤ 10px.
+4. **One focal animation per viewport.** Don't animate every panel.
+5. **Cheap props only** (`transform`/`opacity`/`background-position`); avoid animating
+   `backdrop-filter` (expensive).
+
+## Patterns
+
+- **Background drift (signature):** the mesh slowly shifts position/hue over `--mesh-drift`,
+  infinite + alternate, very low amplitude. Pauses for reduced motion.
+- **Scroll reveal:** sections/panels start `opacity:0; translateY(18px)` → `.in` via
+  `IntersectionObserver`, `--dur-slow` `--ease-out`, gentle stagger. Reveal once.
+- **Glass hover sheen:** on hover, a soft diagonal highlight sweeps across the panel +
+  shadow lift (`--glass-shadow` deepens). Use a `::after` gradient translating across.
+- **Panel parallax (GH-C floating UI):** small glass cards translate a few px on scroll/
+  pointer for depth; desktop only; off for touch/reduced motion.
+- **Pointer glow:** a faint radial light follows the cursor on a hero panel (CSS vars on
+  `pointermove`); subtle, desktop only.
+- **Micro-interactions:** copy-button check swap, toggle slide, accordion height + chevron
+  rotate, tab indicator slide, count-up on metric tiles.
+- **Nav on scroll:** glass tint strengthens slightly + shadow appears after ~24px.
+- **Marquee (logos):** slow, linear, pausable.
+
+## Reduced motion / transparency (required)
+
+```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; }
+  .page-bg { animation: none !important; }   /* freeze the mesh */
+}
+/* reduced transparency handled in color-system: glass → solid tinted surface */
+```
+Under reduced motion: freeze the mesh, show reveals/panels in final state, disable
+parallax/sheen/pointer-glow/marquee, render count-ups at final value.
+
+## Minimal vanilla helpers
+
+```js
+// reveal
+const io = new IntersectionObserver((es)=>es.forEach((e,i)=>{ if(e.isIntersecting){
+  e.target.style.transitionDelay = `${Math.min(i*80,360)}ms`;
+  e.target.classList.add('in'); io.unobserve(e.target);} }, {threshold:.15}));
+document.querySelectorAll('[data-reveal]').forEach(el=>io.observe(el));
+
+// pointer glow on hero glass (skip if reduced motion)
+if(!matchMedia('(prefers-reduced-motion: reduce)').matches){
+  document.querySelectorAll('.glass[data-glow]').forEach(el=>{
+    el.addEventListener('pointermove', e=>{ const r=el.getBoundingClientRect();
+      el.style.setProperty('--gx', `${e.clientX-r.left}px`);
+      el.style.setProperty('--gy', `${e.clientY-r.top}px`); }); });
+}
+```
+```css
+[data-reveal]{ opacity:0; transform: translateY(18px);
+  transition: opacity var(--dur-slow) var(--ease-out), transform var(--dur-slow) var(--ease-out); }
+[data-reveal].in{ opacity:1; transform:none; }
+.page-bg{ background-size: 160% 160%; animation: meshDrift var(--mesh-drift) ease-in-out infinite alternate; }
+@keyframes meshDrift { from{ background-position: 0% 0%; } to{ background-position: 100% 100%; } }
+.glass[data-glow]::after{ content:""; position:absolute; inset:0; border-radius:inherit; pointer-events:none;
+  background: radial-gradient(220px 220px at var(--gx) var(--gy), rgba(255,255,255,.10), transparent 60%); }
+```

package/skills/glassmorphism-design-system/spacing-system.md

@@ -0,0 +1,73 @@
+# Spacing System — Glassmorphism
+
+A strict **4-point base / 8-point rhythm**, tuned so glass panels have room to float over
+the living background. Generous space + the backdrop + panel elevation separate sections —
+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 — glass panels use large, soft corners (light catches the edge) */
+  --radius-sm: 10px;  --radius-md: 14px; --radius-lg: 18px;
+  --radius-xl: 22px;  --radius-2xl: 28px; --radius-pill: 999px;
+
+  /* Containers */
+  --container-sm: 680px;   --container-md: 820px;  --container-lg: 1060px;
+  --container-xl: 1200px;  --container-2xl: 1320px;
+  --gutter: clamp(20px, 5vw, 48px);
+
+  /* Section rhythm (fluid, generous so glass floats) */
+  --section-y: clamp(72px, 9vw, 136px);
+  --section-y-lg: clamp(100px, 12vw, 188px);  /* hero / major sections */
+  --stack: clamp(16px, 2vw, 24px);
+  --glass-pad: clamp(20px, 2.6vw, 36px);      /* padding inside a glass panel */
+  --glass-lift: clamp(20px, 3.5vw, 48px);     /* air around a floated glass panel */
+}
+```
+
+## Usage map
+
+- **4-pt system** (`--space-1..6`): inside panels/components — icon↔label, button/badge
+  padding, list-item gaps, input padding.
+- **8-pt system** (`--space-8..16`): glass-panel padding (`--glass-pad`), gaps between
+  panels, copy↔panel gaps, form rows, grid gaps.
+- **Container widths:** standard sections `--container-lg/xl`; wide showcases
+  `--container-2xl`; prose/docs `--container-md`.
+- **Section spacing:** `padding-block: var(--section-y)`; hero + major sections use
+  `--section-y-lg`. Add `--glass-lift` margin around a floated hero panel so its shadow
+  reads against the backdrop.
+- **Panel padding:** generous `--glass-pad`; don't crowd content to the frosted edge.
+- **Page spacing:** sections stack with no extra margins and **no borders/dividers** —
+  `--section-y` padding + the backdrop's shifts + panel elevation separate them.
+
+## Rules
+
+1. **Only use scale values.** No arbitrary `13px`/`27px`.
+2. **Give glass air.** Use `--glass-lift` so the panel's shadow + highlight read against
+   the mesh; cramped glass loses its depth.
+3. **Consistent panel radius/padding.** All glass panels share `--radius-xl/2xl` +
+   `--glass-pad` so the material reads as one system.
+4. **Whitespace + backdrop + elevation > dividers.** Separate sections this way, never lines.
+5. **Don't over-tile glass.** Spacing should leave the background visible between panels —
+   the contrast of glass-on-light is the effect.
+
+## Helpers
+
+```css
+.container { width:100%; max-width: var(--container-xl);
+             margin-inline:auto; padding-inline: var(--gutter); }
+.container--wide   { max-width: var(--container-2xl); }
+.container--narrow { max-width: var(--container-md); }
+.section   { padding-block: var(--section-y); border: 0; }   /* never a section border */
+.section--hero { padding-block: var(--section-y-lg); }
+.glass { padding: var(--glass-pad); border-radius: var(--radius-xl); }  /* + glass utility from color-system */
+.glass-wrap { margin-block: var(--glass-lift); }             /* air around a floated panel */
+.stack > * + * { margin-top: var(--stack); }
+```

package/skills/glassmorphism-design-system/typography-system.md

@@ -0,0 +1,90 @@
+# Typography System — Glassmorphism
+
+Clean, modern grotesk type tuned for **legibility on translucent surfaces**. On glass,
+type needs a touch more weight/contrast than on a solid panel — these rules bake that in.
+Fluid scale across breakpoints.
+
+## Fonts
+
+```css
+:root {
+  --font-sans: "Inter", "Geist", -apple-system, BlinkMacSystemFont, "Segoe UI",
+               Roboto, Helvetica, Arial, sans-serif;
+  --font-display: var(--font-sans);          /* or "Geist" for tighter display */
+  --font-mono: "Geist Mono", "JetBrains Mono", "SF Mono", ui-monospace, Menlo, monospace;
+}
+```
+Inter/Geist render crisply on blurred backdrops. Mono for code/terminal glass panels.
+
+## Fluid type scale (clamp)
+
+```css
+:root {
+  --fs-display: clamp(2.5rem, 1.4rem + 5.2vw, 5rem);     /* 40 → 80px hero */
+  --fs-h1:      clamp(2.125rem, 1.5rem + 2.9vw, 3.5rem); /* 34 → 56px */
+  --fs-h2:      clamp(1.625rem, 1.25rem + 1.9vw, 2.5rem);/* 26 → 40px */
+  --fs-h3:      clamp(1.3125rem, 1.12rem + 1vw, 1.75rem);/* 21 → 28px */
+  --fs-h4:      clamp(1.0625rem, 1rem + 0.4vw, 1.3125rem);/* 17 → 21px */
+  --fs-lead:    clamp(1.125rem, 1.02rem + 0.55vw, 1.4375rem);/* 18 → 23px subhead */
+  --fs-body:    1rem;          /* 16px base */
+  --fs-body-lg: 1.0625rem;     /* 17px */
+  --fs-small:   0.875rem;      /* 14px caption */
+  --fs-micro:   0.75rem;       /* 12px labels/eyebrow */
+}
+```
+
+## Roles (each: size · weight · line-height · tracking)
+
+| Role | Size | Weight | Line-height | Tracking | Color |
+|---|---|---|---|---|---|
+| **Display** (hero) | `--fs-display` | 600–700 | 1.05 | -0.02em | `--text-primary` (or `--grad-text` on 1 word) |
+| **H1** | `--fs-h1` | 600–700 | 1.08 | -0.02em | `--text-primary` |
+| **H2** (section) | `--fs-h2` | 600 | 1.12 | -0.015em | `--text-primary` |
+| **H3** | `--fs-h3` | 600 | 1.25 | -0.01em | `--text-primary` |
+| **H4 / overline** | `--fs-h4` | 600 | 1.3 | 0 | `--text-primary` |
+| **Eyebrow / label** | `--fs-micro` | 600 | 1.2 | 0.07em, UPPERCASE | `--accent`/`--text-muted` |
+| **Lead / subhead** | `--fs-lead` | 400–500 | 1.5 | 0 | `--text-secondary` |
+| **Body** | `--fs-body`/`-lg` | 400 | 1.6 | 0 | `--text-secondary` |
+| **Body on glass** | `--fs-body`/`-lg` | **450–500** | 1.6 | 0 | `--text-secondary`+ |
+| **Caption / meta** | `--fs-small` | 400–500 | 1.45 | 0 | `--text-muted` |
+| **Button** | `--fs-body` (`0.9375rem` compact) | 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.25rem,1.8rem+2vw,3.25rem)` | 700 | 1 | -0.02em | `--text-primary` |
+| **Code (glass panel)** | `--fs-small` | 400–500 | 1.6 | 0 | mono, `--text-primary` |
+
+## On-glass legibility rules (the key difference)
+
+1. **Slightly heavier body on glass.** Bump body to ~450–500 weight on translucent panels;
+   thin text shimmers and loses contrast over a blurred backdrop.
+2. **Guarantee AA over the brightest backdrop region** the text can overlap; if it fails,
+   use `--glass-bg-strong`, add `--scrim`, or increase weight/size.
+3. **Avoid huge thin display text directly over the busiest mesh area** — center the hero
+   panel over a calmer region or sit it on `glass--strong`.
+4. **No gradient text on small/secondary text** (`--grad-text` only on one large hero phrase).
+5. **Don't rely on text-shadow as a contrast crutch** — fix the surface tint instead
+   (a subtle shadow is fine for polish, not for legibility).
+
+## General rules
+
+1. **Tighten as it grows;** body ~1.6, 0 tracking. Measure ≤ 68ch.
+2. **Weights:** body 400 (450–500 on glass), UI/emphasis 600, headings 600–700.
+3. **One display moment per page** (the hero).
+4. **Eyebrows** label sections; **numbers** use `font-variant-numeric: 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: 600; text-wrap: balance; letter-spacing: -0.02em; }
+h1 { font-size: var(--fs-h1); line-height: 1.08; }
+.eyebrow { font-size: var(--fs-micro); font-weight:600; letter-spacing:.07em;
+           text-transform:uppercase; color: var(--accent); }
+.lead { font-size: var(--fs-lead); color: var(--text-secondary); max-width: 60ch; }
+.glass p, .glass li { font-weight: 460; }   /* a touch heavier on glass for legibility */
+a { color: var(--accent-2); text-underline-offset: 2px; }
+p { max-width: 68ch; }
+code, pre { font-family: var(--font-mono); }
+```