spirewise 1.7.1 → 1.8.0

package/skills/enterprise-data-viz-design-system/design-principles.md

@@ -0,0 +1,75 @@
+# Design Principles — Enterprise Data Visualization
+
+The philosophy distilled from data-led references (Stripe, Linear, Vercel/Analytics,
+Datadog, Grafana, Retool, Mixpanel, Notion) and modern AI sites (OpenAI, Anthropic,
+Perplexity, Cursor, Scale AI). The guiding standard: **clarity, honesty, and trust** — the
+craft of good information design (Tufte) applied to a polished enterprise product site.
+
+## The one-sentence philosophy
+
+**Let the data speak, honestly.** Build a calm, precise canvas where dashboards, charts,
+KPIs, and tables are the heroes — maximizing data-ink, minimizing chart-junk, and never
+distorting the numbers.
+
+## Core principles
+
+1. **Data is the hero.** Lead with real-looking dashboards, charts, KPI tiles, and metrics —
+   not abstract illustration. The product's value is its numbers; show them.
+2. **Clarity over decoration (data-ink).** Every pixel earns its place: thin gridlines,
+   direct labels, generous whitespace. Remove anything that isn't data or essential context.
+3. **Honesty is non-negotiable.** Axes start at a sensible baseline (usually 0 for bars);
+   never truncate/invert/cherry-pick scales to exaggerate; label units and time ranges; show
+   sample sizes where relevant. Misleading charts destroy enterprise trust.
+4. **A disciplined data palette.** Use a small **categorical** set for series (distinct,
+   color-blind-safe), **sequential** scales for magnitude, **diverging** scales for
+   above/below a midpoint, and **semantic deltas** for change — never color alone.
+5. **Tabular precision.** Numerals are tabular and right-aligned; units consistent; deltas
+   show direction + value (▲ +12.4%). Tables are crisp, scannable, sortable.
+6. **Restrained, neutral UI.** The interface is mostly neutral so the data's color pops.
+   One brand accent for actions/links; chart color is reserved for series, not chrome.
+7. **Choose the right chart for the message.** Trend → line/area; comparison → bar; part-to-
+   whole → stacked/donut (sparingly); distribution → histogram/box; relationship → scatter;
+   single value → KPI/sparkline. Don't force a pie where a bar is clearer.
+8. **Density with legibility.** Enterprise users want information density, but it must stay
+   readable — consistent spacing, alignment, and grouping make dense layouts calm.
+9. **Accessible data.** Every chart has a **data-table equivalent** + summary; encodings work
+   without color (labels, patterns, direct values); keyboard/screen-reader reachable.
+10. **Trust signals throughout.** Security, compliance, SLAs, real metrics, and customer
+    logos reinforce that this is enterprise-grade.
+
+## Visual-hierarchy laws
+
+- **One H1 per page**; in a dashboard, the **primary KPI / chart** is the focal point.
+- **KPI → trend → detail.** Lead a data section with headline KPIs, then the trend chart,
+  then supporting tables/breakdowns.
+- **Contrast ladder:** primary metric brightest/biggest, labels muted, gridlines faint.
+- **One primary CTA per viewport** (a clear button), distinct from data color.
+- **Align everything.** Numbers right-aligned, labels left; a strict baseline grid makes
+  dense data read as orderly.
+- **Accent ≠ data color.** Keep the brand accent out of the categorical series to avoid
+  confusion; reserve it for actions.
+
+## Chart-craft rules (data-ink in practice)
+
+- No 3D, no drop shadows on data marks, no heavy gradient fills (a faint area fill is ok).
+- Direct-label series (or a clear legend); avoid legends that force back-and-forth scanning.
+- Gridlines are thin and few; remove chart borders; let whitespace frame the plot.
+- Consistent axis scales when comparing charts side by side; annotate notable points.
+- Format numbers humanely (1.2k, 3.4M, 12.4%), consistent decimals, with units.
+
+## Reference cues (what each does well)
+
+- **Datadog / Grafana:** dense, legible dashboards; clear time-series; status colors.
+- **Stripe:** beautiful, honest charts; refined tables; trust + clarity.
+- **Linear / Vercel Analytics:** minimal precise metrics, tasteful sparklines, fast feel.
+- **Mixpanel / Retool:** funnels, breakdowns, builder/dashboard density done cleanly.
+
+## Do / Don't
+
+**Do:** lead with real dashboards/KPIs/charts · maximize data-ink · honest axes · categorical/
+sequential/diverging scales used correctly · tabular numerals · crisp tables · neutral UI +
+data color · data-table for every chart · color-blind-safe encodings.
+
+**Don't:** chart-junk (3D/shadows/gradients on data) · misleading axes · rainbow scales for
+ordered data · color-only encoding · pie charts for many categories · illegible dense tables ·
+brand accent inside the series · borders between sections · charting libraries.

package/skills/enterprise-data-viz-design-system/example-page-structures.md

@@ -0,0 +1,89 @@
+# Example Page Structures — Enterprise Data Visualization
+
+Ready-to-assemble, **data-led** page blueprints. Each section names a layout (see
+`layout-system.md`) and components (see `component-library.md`). Lead with dashboards, KPIs, and
+charts; keep the UI neutral so data pops; **every chart has a data-table equivalent**. No
+borders between sections (separate by whitespace + surface elevation + background tone).
+
+Legend: `DH-* / KR / CG / TB / FN / BN / 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 (**charts = inline SVG/Canvas, no library**), **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 (dashboard/metric) · Feature Sections · Product Highlights · Trust
+Signals · Testimonials · Use Cases · Statistics (KPI row) · Integrations · CTA · Footer.**
+
+---
+
+## 1. Home (default)
+1. **Navbar** — extensionless links
+2. **Hero** `DH-A` — copy + CTAs + **Dashboard Preview** (KPI row + primary chart + mini table)
+3. **Logos Section** — trusted-by row
+4. **KPI row** `KR` — 4 headline platform metrics (value, delta, sparkline)
+5. **Chart grid** `CG` — primary trend (`.span-8`) + breakdown (`.span-4`)
+6. **Feature** `F-C` — feature copy + a live mini chart
+7. **Table / breakdown** `TB` — a sortable data table (segments, with inline bars)
+8. **Testimonials** — quote + a customer result KPI/chart
+9. **Pricing** `P-A` (or teaser) — usage/seat tiers
+10. **CTA** `C-A` + **Footer** `FT-A`
+
+## 2. Platform / Product
+1. Navbar · 2. **Hero** `DH-A` (Dashboard Preview) · 3. **KPI row** · 4. **Chart grid** (trend +
+funnel `FN`) · 5. Feature `F-B` (copy↔chart) · 6. **Dashboard Preview** (APP shell, range picker)
+· 7. Table section · 8. Integrations · 9. Statistics/trust · 10. CTA + Footer
+
+## 3. Features / Analytics
+1. Navbar · 2. **Hero** `DH-C` (single big chart) · 3.–8. feature sections each pairing copy with
+the relevant chart type (trend/line, comparison/bar, distribution/histogram, funnel, scatter,
+heatmap) + a data table · 9. Integrations · 10. CTA + Footer
+
+## 4. Developers / Documentation
+- **Developers:** Navbar · **Hero** with **Code Preview** (analytics SDK/query) + the chart it
+  produces · Logos · Code Preview (tabbed) · KPI row (API metrics) · Use Cases · Statistics · CTA
+  ("Read docs"/"Get API key") · Footer (≥10).
+- **Docs:** `DOC-A` three-pane; inline charts + data tables; mono code; breadcrumb; sticky nav.
+
+## 5. Enterprise / Security
+1. Navbar · 2. Hero (outcome-led + SLA chart) · 3. Logos · 4. Feature `F-B` · 5. **Enterprise**
+(SSO/RBAC/SLAs/VPC + usage chart) · 6. **Security** (compliance badges) · 7. **KPI row** (uptime/
+p99/events) · 8. Testimonials (exec) · 9. CTA (contact) · 10. Footer
+
+## 6. Pricing
+1. Navbar · 2. Hero (short + plan/usage toggle) · 3. **Pricing** `P-A/P-B` (tiers, usage chart) ·
+4. Feature/usage comparison table · 5. Enterprise band · 6. Logos · 7. **KPI row** (value metrics)
+· 8. Testimonials · 9. **FAQ** `Q-A` · 10. CTA + Footer  (keep pricing tables crisp + honest)
+
+## 7. Content pages (About, Customers, Case Studies, Careers, Blog, Partners, Resources, Contact, FAQ)
+Reach **≥10 sections** with data where it helps: Hero → body sections (customer logo grid,
+**case-study with before/after KPIs + a chart**, values, open roles, article list, partner tiers,
+resource cards, contact form) → Trust Signals → **KPI row** → Testimonials → Integrations → CTA →
+Footer. Case studies especially lead with **result metrics + a chart**.
+
+---
+
+## Assembly notes
+- **Scale is mandatory:** 15+ pages, **≥10 sections each**. Never a single/thin page.
+- **Lead with data** (KPI → trend → detail); choose the right chart for each message; keep axes
+  honest; maximize data-ink; **every chart has a data-table equivalent**.
+- **Neutral UI, colorful data;** tabular numerals; crisp tables; brand accent for actions only.
+- **No borders/dividers between sections** — whitespace + surface elevation + background tone.
+  Gridlines/edges/row rules live inside components.
+- Use **real, plausible data** (not lorem numbers); mark guesses `[PLACEHOLDER]`.

package/skills/enterprise-data-viz-design-system/layout-system.md

@@ -0,0 +1,75 @@
+# Layout & Grid System — Enterprise Data Visualization
+
+A 12-column fluid grid + canonical **dashboard** and **marketing** layouts. Data sections use
+a compact dashboard grid (KPI rows, chart grids); marketing sections use airier layouts.
+**No borders between sections.**
+
+## Grid
+
+```css
+:root { --grid-cols: 12; --grid-gap: var(--dash-gap); }
+
+.grid { display: grid; gap: var(--grid-gap);
+        grid-template-columns: repeat(var(--grid-cols), 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); }
+.cols-6 { grid-template-columns: repeat(6, 1fr); }
+.split  { grid-template-columns: 1fr 1.2fr; }
+
+/* Dashboard span helpers (on a 12-col grid) */
+.span-3{grid-column:span 3} .span-4{grid-column:span 4} .span-6{grid-column:span 6}
+.span-8{grid-column:span 8} .span-12{grid-column:span 12}
+@media (max-width:1024px){ .span-3,.span-4{grid-column:span 6} .span-8{grid-column:span 12} }
+@media (max-width:680px){ [class*="span-"]{grid-column:1 / -1} .cols-2,.cols-3,.cols-4,.cols-6{grid-template-columns:1fr} }
+```
+
+Breakpoints: `sm 480` · `md 768` · `lg 1024` · `xl 1280` · `2xl 1440`. Mobile-first;
+dashboards reflow many columns → fewer → single; tables scroll or stack.
+
+## Canonical layouts
+
+### Hero
+- **DH-A Dashboard hero (default):** copy + CTAs on one side, a **Dashboard Preview** (KPI row
+  + a chart + a mini table) on the other (or full-width below). Lead with real-looking data.
+- **DH-B Metric hero:** a giant headline **KPI** (`--fs-kpi-lg`) + sparkline + supporting
+  stats — the "by the numbers" opener.
+- **DH-C Split:** copy left, a single large primary chart right.
+
+### Data sections
+- **KR KPI row:** `.grid.cols-4` (→2→1) of **KPI tiles** (value, label, delta, sparkline).
+- **CG Chart grid:** mixed-span chart cards (`.span-8` primary trend + `.span-4` breakdown;
+  `.span-6` × 2). One primary chart anchors; supporting charts around it.
+- **TB Table section:** a full **data table** (sortable, sticky header) with filters above.
+- **FN Funnel / breakdown:** a funnel or stacked-bar breakdown + a segments table.
+- **BN Bento of data:** a bento mixing a chart tile, KPI tiles, and a small table.
+
+### Feature / marketing
+- **F-A 3-up feature cards** · **F-B alternating copy↔chart** · **F-C feature + live chart**.
+
+### Pricing / CTA / FAQ / Footer
+- **P-A 3-tier** (middle highlighted) + usage/seat note; **P-B 2-tier + enterprise**. Tiers may
+  show a small usage chart. **C-A CTA band** (distinct from data color). **Q-A Accordion FAQ.**
+  **FT-A Mega footer.**
+
+### Dashboard app / Docs
+- **APP Dashboard shell:** left sidebar (nav/filters) + top bar (range picker, search) + a
+  responsive dashboard grid — the in-product layout shown in previews.
+- **DOC-A Three-pane docs:** nav · prose (`--container-md`) · TOC; inline charts/tables; mono
+  code blocks; breadcrumb.
+
+## Composition rules
+
+1. **Separate sections by surface/tone + space, NEVER borders.** Alternate `--bg-900`/`--bg-800`
+   (add `.section--alt`); `.section{border:0}`; no `<hr>`. Chart gridlines/table rules/card
+   edges are *inside* components, not section dividers.
+2. **Lead data sections with KPIs**, then the trend chart, then tables/breakdowns (KPI → trend
+   → detail). One primary chart per data section.
+3. **Right chart for the message** (see design-principles): trend→line/area, comparison→bar,
+   composition→stacked/donut, distribution→histogram, relationship→scatter, single→KPI/spark.
+4. **Align to the grid.** Dashboard cards snap to the 12-col grid; numbers right-aligned.
+5. **At least 10 sections per page**, **15+ pages.** Never thin.
+6. **Rhythm:** dashboard hero → logos/trust → KPI row → chart grid → feature (copy↔chart) →
+   table/breakdown → metrics/trust → pricing → FAQ → CTA → footer.
+7. **Reflow:** dashboard grids collapse columns; tables get a horizontal scroll container or
+   stack into key/value cards on mobile; charts stay legible (fewer ticks) at small sizes.

package/skills/enterprise-data-viz-design-system/motion-system.md

@@ -0,0 +1,86 @@
+# Motion System — Enterprise Data Visualization
+
+Motion here is **functional and restrained** — it clarifies data (a chart draws in, a value
+transitions, a tooltip appears), never decorates. Precision and calm signal trustworthiness.
+Everything degrades under `prefers-reduced-motion`, and **no motion is required to read data**.
+
+Distilled from Stripe/Linear/Vercel (crisp micro-interactions), Datadog/Grafana (clear
+tooltips/transitions), and OpenAI/Anthropic/Perplexity/Cursor (restraint).
+
+## Tokens
+
+```css
+:root {
+  --dur-fast: 120ms;   --dur-base: 220ms;  --dur-slow: 420ms;  --dur-chart: 700ms;
+  --ease-out: cubic-bezier(0.2, 1, 0.3, 1);
+  --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
+}
+```
+
+## Principles
+1. **Motion clarifies, never decorates.** Animate to show change (a trend draw-in, a value
+   ticking to its number, a series toggling) — not for flourish.
+2. **Short + eased** for UI (120–420ms); chart draw-ins up to ~700ms, once on reveal.
+3. **Compositor-friendly + cheap.** Animate `transform`/`opacity`/`stroke-dashoffset`/
+   `clip-path`; avoid layout thrash. rAF-throttle scroll; `IntersectionObserver` for reveals.
+4. **One animation per data section** at a glance — don't animate every chart simultaneously.
+5. **Final state is the truth.** With motion off, charts/values render fully and correctly.
+
+## Patterns
+
+- **Chart draw-in (on reveal):** line/area draws via `stroke-dashoffset` 1→0; bars grow from
+  baseline (`transform: scaleY` from 0, origin bottom); donut sweeps. `--dur-chart`, once.
+- **Value count-up:** KPI numbers count from a sensible start to the final value on reveal —
+  **final value is in the DOM** so it's correct without JS/motion.
+- **Tooltip / crosshair:** on hover **and keyboard focus** of a data point, show a tooltip
+  (value + label) and a crosshair; fade `--dur-fast`. Tooltips are also reachable by keyboard.
+- **Series toggle:** clicking a legend item fades a series in/out (`opacity`) and rescales
+  smoothly; `aria-pressed` reflects state.
+- **Table sort:** on sort, rows reorder with a brief fade/translate (`--dur-base`); never
+  obscure the data; reduced motion → instant reorder.
+- **Reveal:** sections/cards fade-rise on enter (IO), gentle stagger; calm.
+- **Hover:** card lift (subtle shadow), button bg shift, row hover background.
+- **Range change:** when the date range/filter changes, charts/KPIs transition values smoothly
+  (interpolate) rather than snapping — but keep it quick (`--dur-base`).
+- **Nav on scroll:** subtle background/shadow after ~24px.
+
+## Reduced motion (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; }
+}
+```
+Under reduced motion: charts render in **final drawn state** (full paths/bars), KPI numbers at
+**final value** (no count-up), table sort is instant, no draw-in/parallax. All data is fully
+legible immediately.
+
+## Minimal vanilla helpers
+
+```js
+const RM = matchMedia('(prefers-reduced-motion: reduce)').matches;
+// chart draw-in on reveal (SVG path with stroke-dasharray set to its length)
+const io = new IntersectionObserver((es)=>es.forEach(e=>{ if(e.isIntersecting){
+  const el=e.target;
+  if(!RM) el.classList.add('draw');         // CSS animates stroke-dashoffset → 0
+  else el.classList.add('drawn');           // final state instantly
+  io.unobserve(el);
+}}, {threshold:.3});
+document.querySelectorAll('[data-chart]').forEach(el=>io.observe(el));
+
+// count-up (final value always present in textContent as data-final)
+function countUp(el){ const end=+el.dataset.final; if(RM){ el.textContent=el.dataset.display; return; }
+  const t0=performance.now(), d=700;
+  (function f(t){ const p=Math.min(1,(t-t0)/d); el.textContent=fmt(end*p); if(p<1)requestAnimationFrame(f); else el.textContent=el.dataset.display; })(performance.now());
+}
+```
+```css
+[data-chart] path.series{ stroke-dasharray: var(--len); stroke-dashoffset: var(--len); }
+[data-chart].draw path.series{ transition: stroke-dashoffset var(--dur-chart) var(--ease-out); stroke-dashoffset:0; }
+[data-chart].drawn path.series{ stroke-dashoffset:0; }
+[data-reveal]{ opacity:0; transform: translateY(14px);
+  transition: opacity var(--dur-slow) var(--ease-out), transform var(--dur-slow) var(--ease-out); }
+[data-reveal].in{ opacity:1; transform:none; }
+```

package/skills/enterprise-data-viz-design-system/spacing-system.md

@@ -0,0 +1,85 @@
+# Spacing System — Enterprise Data Visualization
+
+A strict **4-point base / 8-point rhythm** tuned for **two densities**: spacious **marketing**
+sections and compact **dashboard/product** UI. Whitespace, surface elevation, and tone
+separate content — never borders.
+
+## Scale tokens
+
+```css
+:root {
+  /* 4-pt base, 8-pt rhythm */
+  --space-0: 0;        --space-1: 4px;   --space-2: 8px;   --space-3: 12px;
+  --space-4: 16px;     --space-5: 20px;  --space-6: 24px;  --space-8: 32px;
+  --space-10: 40px;    --space-12: 48px; --space-16: 64px; --space-20: 80px;
+  --space-24: 96px;    --space-28: 112px;--space-32: 128px;--space-40: 160px;
+
+  /* Radii — crisp, enterprise (smaller than playful systems) */
+  --radius-sm: 6px;  --radius-md: 8px;  --radius-lg: 12px;
+  --radius-xl: 16px; --radius-pill: 999px;
+
+  /* Containers */
+  --container-sm: 680px;   --container-md: 840px;  --container-lg: 1080px;
+  --container-xl: 1240px;  --container-2xl: 1440px;  /* wide dashboards */
+  --gutter: clamp(20px, 4vw, 40px);
+
+  /* Section rhythm (marketing) */
+  --section-y: clamp(64px, 8vw, 120px);
+  --section-y-lg: clamp(88px, 10vw, 160px);
+
+  /* Dashboard density (compact) */
+  --dash-gap:   clamp(12px, 1.2vw, 20px);   /* gap between dashboard cards/tiles */
+  --card-pad:   clamp(16px, 1.6vw, 24px);   /* padding inside a data card */
+  --cell-pad-y: 10px;  --cell-pad-x: 12px;  /* table cell padding (compact) */
+  --kpi-pad:    var(--space-5);
+  --stack: clamp(12px, 1.4vw, 20px);
+}
+```
+
+## Two densities
+
+- **Marketing density** (hero, features, pricing, CTA): generous — `--section-y` padding,
+  larger type, more whitespace. Sells the product.
+- **Dashboard density** (dashboard previews, KPI rows, chart grids, tables): compact —
+  `--dash-gap` between tiles, `--card-pad` inside cards, tight `--cell-pad-*` in tables.
+  Information-rich but aligned and calm.
+
+Use the right density per context; don't make a dashboard preview as airy as a hero, and
+don't cram marketing copy as tightly as a table.
+
+## Usage map
+
+- **4-pt** (`--space-1..6`): inside components — KPI label↔value, icon↔text, chart padding,
+  table cell padding, badge/button padding.
+- **8-pt** (`--space-8..16`): between components — card gaps (`--dash-gap`), KPI rows, form rows.
+- **Container widths:** marketing `--container-lg/xl`; **wide dashboards** `--container-2xl`;
+  prose/docs `--container-md`.
+- **Section spacing:** marketing sections `--section-y` (hero/CTA `--section-y-lg`); a
+  dashboard *section* still gets `--section-y`, but the dashboard *grid inside* uses `--dash-gap`.
+- **Grid gaps:** `--dash-gap` for dashboard/chart grids; `--space-6/8` for marketing grids.
+- **Page spacing:** sections stack with no extra margins and **no borders/dividers** —
+  `--section-y` + surface elevation + tone separate them.
+
+## Rules
+
+1. **Only use scale values.** No arbitrary `13px`/`27px` (except the deliberate cell-pad/density tokens).
+2. **Align to a baseline.** Consistent paddings + alignment make dense data read as orderly.
+3. **Consistent card radius/padding** across all data cards so a dashboard reads as one system.
+4. **Tables breathe just enough:** `--cell-pad` compact but tappable; row height ≥ 36px;
+   zebra/hover via background, not borders between rows where avoidable.
+5. **Whitespace + elevation > dividers.** Separate sections this way, never lines.
+
+## Helpers
+
+```css
+.container { width:100%; max-width: var(--container-xl);
+             margin-inline:auto; padding-inline: var(--gutter); }
+.container--wide { max-width: var(--container-2xl); }
+.section   { padding-block: var(--section-y); border: 0; }   /* never a section border */
+.section--lg { padding-block: var(--section-y-lg); }
+.section--alt { background: var(--bg-800); }                 /* alternate tone, not a line */
+.dash { display:grid; gap: var(--dash-gap); }
+.card { background: var(--surface-1); border:1px solid var(--border-default);
+        border-radius: var(--radius-lg); padding: var(--card-pad); }
+.stack > * + * { margin-top: var(--stack); }
+```

package/skills/enterprise-data-viz-design-system/typography-system.md

@@ -0,0 +1,100 @@
+# Typography System — Enterprise Data Visualization
+
+Clean, neutral, highly legible type built for **numbers and density**: a precise sans with a
+true **tabular-numeral** mode for all metrics, tables, and axes, plus mono for code/IDs.
+Restrained and functional — type supports the data, it doesn't perform. Fluid scale.
+
+## Fonts
+
+```css
+:root {
+  --font-sans: "Inter", "Geist", "IBM Plex Sans", -apple-system, BlinkMacSystemFont,
+               "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  --font-display: var(--font-sans);
+  /* Numeric/mono — for metrics, tables, axes, IDs, code */
+  --font-num:  "Geist Mono", "IBM Plex Mono", "JetBrains Mono", ui-monospace, Menlo, monospace;
+  --font-mono: var(--font-num);
+}
+```
+Notes:
+- Inter/Geist/IBM Plex have excellent **tabular figures** — use `font-variant-numeric:
+  tabular-nums` for all metrics, deltas, table cells, and axis ticks so digits align.
+- A mono (`--font-num`) is great for large KPI numbers, IDs, timestamps, and code/terminal.
+
+## Fluid type scale (clamp)
+
+```css
+:root {
+  --fs-display: clamp(2.25rem, 1.5rem + 3.4vw, 3.75rem);  /* 36 → 60px hero */
+  --fs-h1:      clamp(2rem, 1.5rem + 2.4vw, 3rem);        /* 32 → 48px */
+  --fs-h2:      clamp(1.5rem, 1.2rem + 1.6vw, 2.25rem);   /* 24 → 36px section */
+  --fs-h3:      clamp(1.25rem, 1.1rem + 0.8vw, 1.625rem); /* 20 → 26px panel title */
+  --fs-h4:      clamp(1.0625rem, 1rem + 0.4vw, 1.25rem);  /* 17 → 20px */
+  --fs-lead:    clamp(1.0625rem, 1rem + 0.5vw, 1.3125rem);/* 17 → 21px */
+  --fs-body:    0.9375rem;     /* 15px base (dense, enterprise) */
+  --fs-body-lg: 1.0625rem;     /* 17px marketing body */
+  --fs-small:   0.8125rem;     /* 13px caption / table / axis */
+  --fs-micro:   0.6875rem;     /* 11px chart tick / dense label */
+
+  /* KPI numbers */
+  --fs-kpi:     clamp(1.75rem, 1.3rem + 1.8vw, 2.75rem);  /* 28 → 44px headline metric */
+  --fs-kpi-lg:  clamp(2.5rem, 1.8rem + 2.6vw, 3.75rem);   /* 40 → 60px hero metric */
+}
+```
+
+## Roles (each: family · size · weight · line-height · tracking)
+
+| Role | Family | Size | Weight | LH | Tracking |
+|---|---|---|---|---|---|
+| **Display** (hero) | sans | `--fs-display` | 600–700 | 1.06 | -0.02em |
+| **H1** | sans | `--fs-h1` | 600–700 | 1.08 | -0.02em |
+| **H2** (section) | sans | `--fs-h2` | 600 | 1.15 | -0.015em |
+| **H3** (panel title) | sans | `--fs-h3` | 600 | 1.25 | -0.01em |
+| **Eyebrow / label** | sans | `--fs-micro` | 600 | 1.2 | 0.08em, UPPERCASE |
+| **Lead / deck** | sans | `--fs-lead` | 400 | 1.5 | 0 |
+| **Body** | sans | `--fs-body`/`-lg` | 400 | 1.6 | 0 |
+| **KPI number** | num | `--fs-kpi`/`-lg` | 600–700 | 1 | -0.01em · tabular-nums |
+| **KPI label** | sans | `--fs-small` | 500 | 1.3 | 0.02em |
+| **Delta** | num | `--fs-small` | 600 | 1 | 0 · tabular-nums (▲/▼ + value) |
+| **Table header** | sans | `--fs-small` | 600 | 1.3 | 0.02em, UPPERCASE optional |
+| **Table cell (number)** | num | `--fs-small` | 400–500 | 1.4 | 0 · tabular-nums, right-aligned |
+| **Table cell (text)** | sans | `--fs-small` | 400 | 1.4 | 0 |
+| **Axis tick / legend** | num/sans | `--fs-micro` | 400–500 | 1.2 | 0 · tabular-nums |
+| **Button** | sans | `--fs-body` | 600 | 1 | 0 |
+| **Navigation** | sans | `--fs-small`/`--fs-body` | 500 | 1 | 0 |
+| **Pricing amount** | num | `clamp(2.25rem,1.8rem+2vw,3.25rem)` | 700 | 1 | -0.02em · tabular-nums |
+| **Code / ID / timestamp** | num | `--fs-small` | 400–500 | 1.5 | 0 |
+
+## Rules (numbers-first)
+
+1. **Tabular numerals everywhere data appears** — metrics, deltas, tables, axes, pricing:
+   `font-variant-numeric: tabular-nums`. Digits must align in columns and not shift on update.
+2. **Right-align numeric table columns; left-align text.** Headers match their column.
+3. **Format humanely & consistently:** 1.2k / 3.4M / 12.4% / $4,210; fixed decimals per
+   column; units in the header or beside the KPI (not repeated per cell when avoidable).
+4. **Deltas: direction + sign + color + arrow** (▲ +12.4% in `--good`; ▼ −3.1% in `--bad`).
+5. **Dense but legible:** body 15px in product/dashboard contexts, 17px for marketing prose;
+   table line-height ~1.4; never below ~13px for data you expect users to read.
+6. **Restraint:** sans only (no decorative faces); weight + size + tabular alignment carry
+   hierarchy. Mono for big KPI numbers/IDs/code adds the "instrument" feel.
+7. **Measure** marketing prose ≤ 68ch; data labels are short and direct.
+
+## 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 { color: var(--text-primary); font-family: var(--font-display); font-weight: 600;
+           text-wrap: balance; letter-spacing: -0.015em; }
+h1 { font-size: var(--fs-h1); line-height: 1.08; }
+.eyebrow { font-size: var(--fs-micro); font-weight:600; letter-spacing:.08em;
+           text-transform:uppercase; color: var(--text-muted); }
+.num, .kpi__value, .delta, td.num, th.num, .axis, .legend, .price__amount {
+  font-family: var(--font-num); font-variant-numeric: tabular-nums; }
+td.num, th.num { text-align: right; }
+.delta--up { color: var(--good); } .delta--down { color: var(--bad); }
+.delta--flat { color: var(--neutral); }
+a { color: var(--accent); text-underline-offset: 2px; }
+p { max-width: 68ch; }
+```