From c96cdd3212914d2b13e122a44fe7c5d89442232d Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 29 Aug 2026 11:54:34 -0700
Subject: [PATCH 1/7] docs(specs): design the inline-style substrate migration
 (project 2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extends the data-ui/data-mdx hook pattern already shipping in 21 places rather
than introducing CSS Modules; splits the CSS into six files so each batch maps
1:1 to a file and can be reverted alone.

Corrects a count carried through project 1: the real figure is 908 style-prop
sites, not 802. `grep 'style={{'` sees only object literals at the call site and
misses 106 sites that pass a named CSSProperties variable — Button.tsx does
this and was miscounted as already migrated. The 1,188 token-reference figure is
unaffected, having been counted from `tokens.*` directly.

Records the no-visual-harness decision as an explicitly accepted risk, with two
cheap non-harness mitigations: a text-level value-equality check per batch, and
a one-page computed-style spot check.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 ...-design-token-css-var-completion-design.md |   5 +
 ...inline-style-substrate-migration-design.md | 183 ++++++++++++++++++
 2 files changed, 188 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-29-inline-style-substrate-migration-design.md

diff --git a/docs/superpowers/specs/2026-08-29-design-token-css-var-completion-design.md b/docs/superpowers/specs/2026-08-29-design-token-css-var-completion-design.md
index 08cf6daf5..ddf581a6d 100644
--- a/docs/superpowers/specs/2026-08-29-design-token-css-var-completion-design.md
+++ b/docs/superpowers/specs/2026-08-29-design-token-css-var-completion-design.md
@@ -19,6 +19,11 @@ then apply the polish. That splits into three projects:
    reachable from CSS.
 2. **Substrate migration** — 802 inline style objects across 90 files, in
    reviewable batches, ending with an ESLint rule.
+   *(Corrected 2026-08-29: the real figure is 908. `grep 'style={{'` misses
+   components that build a `CSSProperties` object in a variable and pass
+   `style={someStyle}` — 106 such sites. The 1,188 token-reference count is
+   unaffected; it was counted from `tokens.*` directly. See
+   `2026-08-29-inline-style-substrate-migration-design.md`.)*
 3. **The polish arc** — three PRs against the findings audit.
 
 Project 2 is blocked on this one: 29% of the site's token references have no CSS
diff --git a/docs/superpowers/specs/2026-08-29-inline-style-substrate-migration-design.md b/docs/superpowers/specs/2026-08-29-inline-style-substrate-migration-design.md
new file mode 100644
index 000000000..dbbab360a
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-29-inline-style-substrate-migration-design.md
@@ -0,0 +1,183 @@
+# Inline-style substrate migration — design
+
+**Date:** 2026-08-29
+**Status:** Proposed. Project 2 of a three-project arc.
+**Depends on:** Project 1, merged as #845 (`6c0685b7`).
+
+## Where this sits
+
+A visual review of the docs site found defects that cannot be *written* as
+fixes, because the components style themselves with inline `style={{}}` objects
+and inline styles cannot express `:focus-visible`, `:hover`, `:last-child`, or a
+media query. The arc:
+
+1. **Token CSS-var completion** — merged (#845). Every token now has a CSS
+   counterpart, machine-checked.
+2. **Substrate migration** — this document.
+3. **The polish arc** — three PRs against
+   `audits/2026-08-29-docs-visual-review-findings.md`.
+
+## Correction to a number carried in Project 1
+
+Project 1's spec, plan, and PR body all say **802** inline style objects. That
+count came from `grep -c 'style={{'`, which sees only object literals written
+at the call site. It misses components that build a `CSSProperties` object in a
+variable and pass `style={someStyle}` — `Button.tsx` does exactly this, and was
+miscounted as already migrated.
+
+Measured properly:
+
+| shape | sites |
+|---|---:|
+| `style={{ … }}` object literal | 802 |
+| `style={namedVariable}` | 106 |
+| **total** | **908** |
+
+The 1,188 token-reference figure is **unaffected** — it was counted from
+`tokens.*` occurrences directly, not derived from style sites.
+
+The 106 are concentrated in three files (`app/docs/page.tsx` 33,
+`app/docs/licensing/page.tsx` 26, `app/about/page.tsx` 14) and are the *easier*
+shape: one object reused across many elements is already rule-shaped. They
+convert to a single CSS rule, not N.
+
+## Problem
+
+908 style-prop sites across ~90 files. Beyond blocking the polish work, the
+inline substrate causes real defects today — the comment on `[data-ui="card"]`
+in `global.css` records one: inline styles beat any stylesheet `:hover` rule, so
+the card's hover lift rendered only the transform until its resting styles were
+moved into CSS.
+
+## Goal
+
+Presentation lives in CSS. Components keep structure, semantics, and genuinely
+dynamic values. The polish fixes in Project 3 become one-liners.
+
+## Non-goals
+
+- **No visual change.** Any pixel that moves is a bug, not an improvement.
+  Restyling opportunities spotted along the way get logged, not taken.
+- **No fix from the findings audit.** That is Project 3, deliberately, so that
+  a migration diff never mixes with a behaviour diff.
+- **No component API changes.** Props stay as they are.
+- **No dark theme.**
+
+## Design
+
+### 1. Extend the pattern that already exists
+
+This is not a new convention. The codebase already ships **21 `data-*` style
+hooks**:
+
+```
+data-ui="button|card|container|section|eyebrow|pill|faq|faq-item|faq-chevron
+         |logo-mark|browser-frame|browser-frame-body|ecosystem-tile"
+data-mdx="callout|card|feature-chip"
+data-docs-navlink
+modifiers: data-surface, data-accent, data-hoverable
+```
+
+Nine of the eleven `components/ui` primitives already emit one. The migration
+finishes a job that is partly done, rather than importing CSS Modules and
+running two competing conventions through a long migration.
+
+`page.module.css` — an empty, unused stub — is deleted as part of batch 1, so
+there is exactly one answer to "where does styling live".
+
+**Rules for what stays inline.** A reviewer should reject a batch that moves
+these into CSS:
+
+- A value computed from props or state that is not a bounded set
+  (`width: `${pct}%``, a measured offset).
+- A value bounded to a few options becomes a `data-*` modifier and moves to CSS
+  (`data-variant="primary"`), because that is what `Button`'s three variants
+  and two sizes are.
+- CSS custom properties set on an element to parameterise a rule
+  (`style={{ '--row-count': n }}`) are the preferred escape hatch when a value
+  is dynamic but its *use* is presentational.
+
+### 2. CSS file layout
+
+`global.css` becomes an index. It is 329 lines today; 908 migrated sites in one
+file would push it past 3,000 and make every batch conflict with every other.
+
+```
+src/app/global.css          @import the rest; keeps preflight + base element rules
+src/styles/ui.css           data-ui primitives
+src/styles/chrome.css       Nav, Footer, AnnouncementToast
+src/styles/docs.css         docs chrome + the .docs-prose rules moved out of global.css
+src/styles/landing.css      landing blocks
+src/styles/marketing.css    pricing, blog, contact, solutions
+src/styles/pages.css        app/** route-level styling
+```
+
+One batch, one file — so batches do not conflict, and a batch can be reverted
+by reverting one file plus its components.
+
+### 3. Batches
+
+Ordered so that dependencies migrate before their consumers.
+
+| # | scope | sites | files | note |
+|---|---|---:|---:|---|
+| 1 | `components/ui` | 25 | 11 | primitives; 9 already have hooks; delete `page.module.css` |
+| 2 | `components/shared` | 73 | 3 | Nav, Footer, AnnouncementToast |
+| 3 | `components/docs` | 168 | 22 | unblocks Project 3 |
+| 4 | `components/landing` | 159 | 17 | |
+| 5 | pricing + blog + contact + solutions | 114 | 15 | |
+| 6 | `app/**` routes | 263 | 23 | includes 73 of the 106 variable-shaped sites |
+
+Each batch is its own PR. Batch 1 is deliberately small and lands first as the
+pattern-setter; its review establishes what the remaining five look like.
+
+### 4. Guarding the swap
+
+**Decision: no visual-regression harness.** Screenshot baselines and
+computed-style suites were both considered and declined on cost. This is a real
+accepted risk and is recorded as such: a subtle regression on a
+rarely-viewed page can ship unnoticed, and the website's vitest suite is
+already 5-failures red with no `nx test` target running it in CI.
+
+Two cheap mitigations that are *not* a harness:
+
+**A per-batch value-equality check.** Most of the 908 sites are static objects
+whose values come from `tokens.*`. A batch script extracts every
+`property: value` pair removed from TSX and every pair added to CSS, resolves
+`tokens.X.Y` and `var(--z)` to their common value via the Project 1 parity map,
+and reports any pair whose value changed. This is text-level, runs in seconds,
+and catches the dominant failure mode — a mistyped or mismapped value. It does
+not catch specificity, cascade, or layout changes; nothing here does.
+
+**A one-page spot check per batch.** For each batch, one representative page is
+opened and the migrated components' computed styles are compared to the same
+page on `main`. Manual, ~10 minutes, catches cascade mistakes the text check
+cannot.
+
+If a regression does slip through, the fix is to revert that batch's file — the
+reason batches map 1:1 to CSS files.
+
+### 5. The ESLint rule, last
+
+After batch 6, a rule that reports a `style` JSX attribute whose value is an
+object expression with only literal/`tokens.*` members. Dynamic values pass.
+Landing it before batch 6 would mean 900 suppressions; landing it after means
+it only ever sees new code.
+
+Ships as `warn` for one release, then `error`.
+
+## Risks
+
+- **Cascade and specificity.** Inline styles have the highest specificity; CSS
+  rules do not. A value that silently won as inline may lose to an existing
+  rule once moved. This is the failure mode the text-level check cannot see and
+  the spot check exists for.
+- **Tailwind utility collision.** Many components carry both `className`
+  utilities and inline styles. Moving a property into a `data-ui` rule can put
+  it in conflict with a utility on the same element; the utility wins or loses
+  depending on source order. Batch 1's review must establish the convention
+  (`@layer components` for the migrated rules, so utilities keep winning).
+- **Six PRs of pure refactor** with no user-visible payoff, before Project 3
+  delivers anything a reader sees. That was accepted when the arc was ordered.
+- **`app/**` at 263 sites is the largest batch** and may need splitting once
+  batch 5 has calibrated the real per-site cost.

From 326048132b6ae1453ab4a2fe14957203851611e8 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 29 Aug 2026 12:03:18 -0700
Subject: [PATCH 2/7] docs(plans): full implementation plan for the substrate
 migration

Seven migration PRs plus an ESLint guard, each batch mapping 1:1 to a CSS file
so it reverts alone. Locks the conventions every batch follows: data-ui hooks
for primitives, component-prefixed classes elsewhere, four worked shape
archetypes (static literal, variant map, hover handler, reused variable), and
the custom-property escape hatch for dynamic values.

Planning corrected the spec in four places, each verified rather than assumed:

- The @layer components suggestion was backwards. Tailwind v4 layers
  everything and unlayered author CSS beats all layers - the precedence inline
  styles had. Migrated rules stay unlayered, like global.css today.
- A third substrate: 12 components embed <style> tags interpolating tokens.*.
- Satori OG images and the dev-only primitives route are excluded (inline
  styles are load-bearing there); in-scope is ~877 sites, not 908.
- 33 onMouseEnter presentation handlers (23 in Footer) become :hover rules.

Ships an advisory value-equality checker and a computed-style snapshot snippet
as the agreed non-harness mitigations.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 ...-08-29-inline-style-substrate-migration.md | 623 ++++++++++++++++++
 ...inline-style-substrate-migration-design.md |  33 +-
 2 files changed, 652 insertions(+), 4 deletions(-)
 create mode 100644 docs/superpowers/plans/2026-08-29-inline-style-substrate-migration.md

diff --git a/docs/superpowers/plans/2026-08-29-inline-style-substrate-migration.md b/docs/superpowers/plans/2026-08-29-inline-style-substrate-migration.md
new file mode 100644
index 000000000..bb8321108
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-29-inline-style-substrate-migration.md
@@ -0,0 +1,623 @@
+# Inline-Style Substrate Migration Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Move all static presentation in `apps/website` out of inline `style` props and embedded `<style>` tags into stylesheet rules, with zero visual change, so Project 3's polish fixes become expressible.
+
+**Architecture:** Extend the `data-ui`/`data-mdx` hook pattern that already ships in 21 places. `global.css` becomes an index importing six scope files under `src/styles/`; each migration batch maps 1:1 to one CSS file and one PR, so a bad batch reverts by reverting one file plus its components. All migrated rules are **unlayered** (like the existing `global.css` rules) so they keep beating Tailwind's layered utilities exactly as inline styles did. Ends with an ESLint guard so new code cannot regress.
+
+**Tech Stack:** Next.js 16, Tailwind CSS v4, plain CSS custom properties from `@threadplane/design-tokens/theme.css` (completed in #845), ESLint flat config, `tsx` for the checker script.
+
+**Spec:** `docs/superpowers/specs/2026-08-29-inline-style-substrate-migration-design.md`
+**Prerequisite:** Project 1 merged (#845). Every `tokens.*` leaf now has a CSS var or a documented exclusion, machine-checked by `token-css-parity.spec.ts`.
+
+---
+
+## Context an engineer needs before starting
+
+### Scope corrections measured on 2026-08-29
+
+- **908 style-prop sites**, not 802: 802 literal `style={{…}}` plus 106
+  `style={namedVariable}` sites (a `CSSProperties` object built in a variable —
+  `Button.tsx`, `app/docs/page.tsx`, `app/docs/licensing/page.tsx`,
+  `app/about/page.tsx` are the main holders).
+- **A third substrate exists:** 12 components embed a `<style>{`…`}</style>`
+  tag whose CSS interpolates `${tokens.*}` values. These render one `<style>`
+  element per component instance. They migrate too (Batches 3–4).
+- **Exclusions — do not touch:**
+  - `src/app/opengraph-image.tsx` and `src/app/blog/[slug]/opengraph-image.tsx`
+    (14 sites): rendered by Satori via `next/og` `ImageResponse`. Satori has no
+    stylesheet; inline styles are the only mechanism. Migrating them breaks OG
+    images.
+  - `src/app/dev/primitives/page.tsx` (17 sites): dev-only route, documented
+    in-file as slated for deletion.
+  - `apps/website/emails/**`: email clients cannot use custom properties.
+  - `*.spec.tsx` files.
+
+In-scope: **~877 style-prop sites + 12 embedded `<style>` tags across 88 files.**
+
+### The cascade decision (and why the spec's first guess was wrong)
+
+Tailwind v4 emits `@layer theme, base, components, utilities` — everything
+layered. The existing `global.css` rules (including all `[data-ui]` rules) are
+**unlayered**, and unlayered author CSS beats *all* layered CSS regardless of
+specificity or order.
+
+Inline styles beat utilities today. A migrated rule must keep beating them, or
+any element carrying both a utility and a formerly-inline value for the same
+property changes appearance. Therefore: **all migrated rules are unlayered**,
+in the six `src/styles/*.css` files, imported by `global.css` exactly like the
+current rules. Do NOT wrap them in `@layer components` — that inverts the
+winner. (The spec's risk section originally suggested `@layer components`;
+it has been corrected.)
+
+Within unlayered CSS, conflicts resolve by specificity then source order.
+Keep selectors flat — one attribute or one class, max one descendant level —
+and this never bites.
+
+### Commands
+
+- Dev server: Browser pane `preview_start` with the `website-dev` launch entry.
+  Never `npm run dev` via Bash.
+- Website tests: `cd apps/website && npx vitest run --config vite.config.mts`
+  — there is **no `nx test website` target**. Baseline: `5 failed | 341 passed`
+  (pre-existing content-assertion drift in `PostCard`, `Differentiator`,
+  `thanks/page`). Exactly those 5 must still fail after every batch; a 6th is
+  yours.
+- Lint errors (CI fails on errors, tolerates warnings; strip ANSI first):
+  `npx nx lint website 2>&1 | sed -r 's/\x1b\[[0-9;]*m//g' | grep -cE '  error  '`
+- Prod build gate before every PR: `npx nx build website --configuration=production`
+- Migration checker: `npx tsx apps/website/scripts/check-style-migration.mts [base-ref]`
+
+### Conventions (locked here; every batch follows them)
+
+1. **Hook naming.** Reusable primitives keep/extend `data-ui="<name>"`.
+   Single-use components get semantic class names prefixed by component:
+   `.nav-…`, `.footer-…`, `.docs-sidebar-…`, `.pricing-compare-…`. Precedent:
+   `.why-row`, `.wp-grid`, `.hero-grid` already exist in landing components.
+2. **What stays inline** (a reviewer rejects a batch that moves these):
+   - values computed from unbounded props/state (`width: `${pct}%``);
+   - third-party requirements (Satori — excluded files);
+   - CSS custom properties used to parameterise a rule:
+     `style={{ '--rows': n } as React.CSSProperties}` is the escape hatch
+     when a value is dynamic but its use is presentational.
+3. **Bounded variants become `data-*` modifiers**, not inline branches:
+   `data-variant="primary" data-size="lg"`, one CSS rule per value.
+4. **JS hover/focus handlers whose only job is presentation**
+   (`onMouseEnter={e => e.currentTarget.style.color = …}`) are replaced by
+   `:hover` / `:focus-visible` rules and the handlers deleted. 33 such
+   handlers exist (23 in `Footer`, 5 in `Nav`, 5 in docs components).
+5. **Embedded `<style>` tags**: move the CSS text verbatim into the batch file,
+   replacing every `${tokens.X.Y}` interpolation with its `var(--…)` per the
+   parity map in `token-css-parity.spec.ts`, then delete the tag.
+6. **React numeric values**: React serialises `fontSize: 14` as `14px` (except
+   unitless properties: `lineHeight`, `fontWeight`, `opacity`, `zIndex`,
+   `flex`, `order`, `flexGrow`, `flexShrink`). Write the unit explicitly in
+   CSS. Getting this wrong is the #1 mechanical error; the checker normalises
+   for it.
+7. **Token → var mapping** is exactly `CSS_VAR_BY_PATH` in
+   `libs/design-tokens/src/lib/token-css-parity.spec.ts`. `tokens.typography.h2.size`
+   → `var(--text-h2)`, `tokens.space.sectionY` → `var(--spacing-section-y)`,
+   `tokens.colors.accent` → `var(--color-accent)`, etc. `.family` values are
+   already `var(--font-*)` strings — copy them through.
+8. **Zero visual change.** Restyling urges get logged in the findings audit,
+   not taken.
+
+### The four shape archetypes (worked examples referenced by every batch)
+
+**Shape A — static literal → rule.** `Card.tsx` today:
+
+```tsx
+<div data-ui="card" style={{ borderRadius: tokens.radius.lg, padding: PAD[padding] }} …>
+```
+
+becomes
+
+```tsx
+<div data-ui="card" data-padding={padding} …>
+```
+
+```css
+[data-ui="card"] { border-radius: var(--radius-lg); }
+[data-ui="card"][data-padding="sm"] { padding: 16px; }
+[data-ui="card"][data-padding="md"] { padding: 24px; }
+[data-ui="card"][data-padding="lg"] { padding: 32px; }
+```
+
+**Shape B — variant maps → data-modifiers.** `Button.tsx` builds
+`VARIANT_STYLES`/`SIZE_STYLES` records and passes `style={combinedStyle}`. The
+records become CSS; the component emits `data-ui="button" data-variant={variant}
+data-size={size}` and keeps only the caller-supplied `style` passthrough:
+
+```css
+[data-ui="button"] {
+  display: inline-flex; align-items: center; justify-content: center;
+  gap: 8px; border-radius: var(--radius-md); font-weight: 600;
+  text-decoration: none; cursor: pointer; border: 1px solid transparent;
+  transition: background 160ms ease, border-color 160ms ease, color 160ms ease;
+}
+[data-ui="button"][data-variant="primary"] {
+  background: var(--color-accent); color: var(--color-text-inverted);
+  border-color: var(--color-accent);
+}
+[data-ui="button"][data-variant="secondary"] {
+  background: var(--color-surface); color: var(--color-text-primary);
+  border-color: var(--color-border-strong);
+}
+[data-ui="button"][data-variant="ghost"] {
+  background: transparent; color: var(--color-accent); border-color: transparent;
+}
+[data-ui="button"][data-size="md"] { height: 40px; padding: 0 16px; font-size: 14px; }
+[data-ui="button"][data-size="lg"] { height: 48px; padding: 0 22px; font-size: 16px; }
+```
+
+(Transcribe the actual current values from the component when implementing —
+the component file is the source of truth, not this excerpt.)
+
+**Shape C — hover handlers → `:hover`.** `Footer.tsx` today, 23 times:
+
+```tsx
+<Link href={l.href} style={linkStyle}
+  onMouseEnter={(e) => (e.currentTarget.style.color = tokens.colors.accent)}
+  onMouseLeave={(e) => (e.currentTarget.style.color = tokens.colors.textSecondary)}>
+```
+
+becomes
+
+```tsx
+<Link href={l.href} className="footer-link">
+```
+
+```css
+.footer-link { color: var(--color-text-secondary); text-decoration: none; /* + rest of linkStyle */ }
+.footer-link:hover { color: var(--color-accent); }
+```
+
+Delete both handlers. If the component then has no other client-side behaviour,
+remove `'use client'` only when nothing else in the file needs it.
+
+**Shape D — reused style variable → one rule.** `app/docs/licensing/page.tsx`
+defines `const cellStyle: CSSProperties = {…}` used 9×. It becomes one class
+used 9×. This is why the 106 variable-shaped sites are cheap: one rule, not N.
+
+### Per-batch verification ritual (identical for every batch)
+
+1. `npx tsx apps/website/scripts/check-style-migration.mts` — the value-equality
+   report must show **0 mismatches / 0 unaccounted removals** (or each flagged
+   line explained in the PR body — the tool is advisory and has known blind
+   spots listed in its header).
+2. Website vitest: exactly the 5 pre-existing failures.
+3. Lint errors: 0.
+4. Prod build: green.
+5. **Manual spot check** on the batch's representative page: paste
+   `apps/website/scripts/computed-style-snapshot.js` into the browser console
+   on `main`'s dev server, save the JSON; check out the branch, repeat, diff
+   the two JSONs. Any property delta on a migrated element is a defect.
+   (~10 min; this is the only defence against cascade/specificity mistakes —
+   the accepted-risk decision means there is no automated net behind it.)
+6. Commit per file-group as specified; one PR per batch; arm auto-merge only
+   after reading the AI review comments (CONTRIBUTING #728).
+
+---
+
+## File Structure
+
+| File | Responsibility |
+|---|---|
+| `src/styles/ui.css` | Batch 1 — `data-ui` primitives |
+| `src/styles/chrome.css` | Batch 2 — Nav, Footer, AnnouncementToast |
+| `src/styles/docs.css` | Batch 3 — docs chrome + mdx components + the `.docs-prose`/docs rules moved out of `global.css` |
+| `src/styles/landing.css` | Batch 4 — landing blocks (incl. hoisted `<style>` tags) |
+| `src/styles/marketing.css` | Batch 5 — pricing, blog, contact, solutions |
+| `src/styles/pages.css` | Batch 6 — `app/**` route-level styling |
+| `src/app/global.css` | Becomes index: imports + preflight/base element rules only |
+| `src/app/page.module.css` | **Deleted** (empty, unused) |
+| `apps/website/scripts/check-style-migration.mts` | Advisory value-equality checker |
+| `apps/website/scripts/computed-style-snapshot.js` | Browser-console snapshot snippet for spot checks |
+| `eslint.config.mjs` (repo root) | Final task — the guard rule |
+
+---
+
+## Task 0: Infrastructure (lands with Batch 1's PR)
+
+**Files:**
+- Create: `apps/website/src/styles/{ui,chrome,docs,landing,marketing,pages}.css`
+- Modify: `apps/website/src/app/global.css` (add imports)
+- Delete: `apps/website/src/app/page.module.css`
+- Create: `apps/website/scripts/check-style-migration.mts`
+- Create: `apps/website/scripts/computed-style-snapshot.js`
+
+- [ ] **Step 1: Create the six scope files**, each with only a header:
+
+```css
+/*
+ * <name>.css — presentation for <scope>, migrated from inline style props.
+ *
+ * Rules here are deliberately UNLAYERED: Tailwind v4 puts utilities in
+ * @layer utilities, and unlayered author CSS beats all layers — which is
+ * exactly the precedence the inline styles being replaced had. Wrapping
+ * these in @layer would let utilities win and change rendering.
+ *
+ * Migration: docs/superpowers/plans/2026-08-29-inline-style-substrate-migration.md
+ */
+```
+
+- [ ] **Step 2: Wire imports.** In `global.css`, immediately after the two
+existing `@import` lines and the local `:root` block, add:
+
+```css
+@import "../styles/ui.css";
+@import "../styles/chrome.css";
+@import "../styles/docs.css";
+@import "../styles/landing.css";
+@import "../styles/marketing.css";
+@import "../styles/pages.css";
+```
+
+- [ ] **Step 3: Delete the stub.** `git rm apps/website/src/app/page.module.css`
+(verified: zero importers).
+
+- [ ] **Step 4: Write the checker.** Create
+`apps/website/scripts/check-style-migration.mts`:
+
+```ts
+#!/usr/bin/env tsx
+/**
+ * Advisory value-equality check for the inline-style migration.
+ *
+ * Diffs the working tree (or HEAD) against a base ref, extracts
+ * `property: value` pairs REMOVED from .tsx style objects and pairs ADDED to
+ * the migration CSS files, normalises both sides (camelCase→kebab, React
+ * numeric px, tokens.* → resolved value, var(--x) → resolved value), and
+ * reports removals with no matching addition plus per-property value changes.
+ *
+ * KNOWN BLIND SPOTS (by design — this is a text tool, not a harness):
+ *   - cascade/specificity: a correct value can still lose to another rule;
+ *   - shorthand vs longhand (`padding: '0 16px'` vs padding-top…);
+ *   - selectors: it compares property/value multisets, not which element
+ *     they apply to.
+ * Treat every flagged line as a question to answer in the PR body, not
+ * necessarily a bug.
+ *
+ * Usage: npx tsx apps/website/scripts/check-style-migration.mts [baseRef=origin/main]
+ */
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { tokens } from '../../../libs/design-tokens/src/index.ts';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO = resolve(HERE, '..', '..', '..');
+const BASE = process.argv[2] ?? 'origin/main';
+
+// --- resolve var(--x) via the committed theme.css + website-local :root vars
+const themeCss = readFileSync(
+  resolve(REPO, 'libs/design-tokens/src/lib/theme.css'), 'utf8');
+const globalCss = readFileSync(
+  resolve(REPO, 'apps/website/src/app/global.css'), 'utf8');
+const cssVars = new Map<string, string>();
+for (const m of (themeCss + globalCss).matchAll(/(--[a-z0-9-]+):\s*([^;]+);/g))
+  cssVars.set(m[1], m[2].trim());
+
+// --- resolve tokens.a.b.c to its value
+function tokenValue(path: string): string | undefined {
+  let cur: unknown = tokens;
+  for (const k of path.split('.')) {
+    if (cur == null || typeof cur !== 'object') return undefined;
+    cur = (cur as Record<string, unknown>)[k];
+  }
+  return cur == null || typeof cur === 'object' ? undefined : String(cur);
+}
+
+const UNITLESS = new Set(['line-height','font-weight','opacity','z-index',
+  'flex','flex-grow','flex-shrink','order']);
+
+function normProp(p: string): string {
+  return p.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase());
+}
+function normValue(prop: string, raw: string): string {
+  let v = raw.trim().replace(/^['"`]|['"`]$/g, '');
+  const tok = v.match(/^tokens\.([a-zA-Z.]+)$/);
+  if (tok) v = tokenValue(tok[1]) ?? v;
+  v = v.replace(/var\((--[a-z0-9-]+)\)/g, (_, name) => cssVars.get(name) ?? _);
+  if (/^-?\d+(\.\d+)?$/.test(v) && !UNITLESS.has(prop)) v = `${v}px`;
+  return v.replace(/\s+/g, ' ').toLowerCase();
+}
+
+function diffLines(pathspec: string, sign: '+' | '-'): string[] {
+  const out = execSync(
+    `git diff -U0 ${BASE} -- ${pathspec}`, { cwd: REPO, encoding: 'utf8' });
+  return out.split('\n')
+    .filter((l) => l.startsWith(sign) && !l.startsWith(sign.repeat(3)))
+    .map((l) => l.slice(1));
+}
+
+// pairs removed from TSX (style-object members: `foo: bar,`)
+const removed = new Map<string, number>();
+for (const line of diffLines("'apps/website/src/**/*.tsx'", '-')) {
+  const m = line.match(/^\s*([a-zA-Z]+):\s*(.+?),?\s*$/);
+  if (!m) continue;
+  const prop = normProp(m[1]);
+  if (!/^[a-z-]+$/.test(prop)) continue;
+  const key = `${prop} :: ${normValue(prop, m[2])}`;
+  removed.set(key, (removed.get(key) ?? 0) + 1);
+}
+// pairs added to migration CSS
+const added = new Map<string, number>();
+for (const line of diffLines(
+  "'apps/website/src/styles/*.css' 'apps/website/src/app/global.css'", '+')) {
+  for (const m of line.matchAll(/([a-z-]+):\s*([^;{}]+);/g)) {
+    const key = `${m[1]} :: ${normValue(m[1], m[2])}`;
+    added.set(key, (added.get(key) ?? 0) + 1);
+  }
+}
+
+let flagged = 0;
+for (const [key, n] of [...removed.entries()].sort()) {
+  if (!added.has(key)) {
+    console.log(`REMOVED, NO MATCHING CSS  (${n}x)  ${key}`);
+    flagged++;
+  }
+}
+console.log(`\n${removed.size} distinct pairs removed, ${added.size} added, ${flagged} unaccounted.`);
+if (flagged > 0 && process.argv.includes('--strict')) process.exit(1);
+```
+
+- [ ] **Step 5: Write the snapshot snippet.** Create
+`apps/website/scripts/computed-style-snapshot.js`:
+
+```js
+/**
+ * Paste into the browser console on a page BEFORE and AFTER a migration
+ * batch (on main's dev server, then the branch's), then diff the two JSONs.
+ * Serialises computed styles for every element carrying a migration hook.
+ */
+(() => {
+  const PROPS = ['color','background-color','border-color','border-radius',
+    'font-size','font-family','font-weight','line-height','letter-spacing',
+    'padding','margin','gap','height','width','max-width','box-shadow',
+    'display','align-items','justify-content','text-transform','opacity'];
+  const hooks = document.querySelectorAll(
+    '[data-ui],[data-mdx],[data-docs-navlink],[class]');
+  const out = {};
+  hooks.forEach((el, i) => {
+    const key = `${el.tagName}#${el.id || i}.${el.getAttribute('data-ui')
+      || el.getAttribute('data-mdx') || String(el.className).slice(0, 40)}`;
+    const cs = getComputedStyle(el);
+    out[key] = Object.fromEntries(PROPS.map((p) => [p, cs.getPropertyValue(p)]));
+  });
+  copy(JSON.stringify(out, null, 1));
+  return `snapshot of ${hooks.length} elements copied to clipboard`;
+})();
+```
+
+- [ ] **Step 6: Smoke the checker on a no-op tree.** Run
+`npx tsx apps/website/scripts/check-style-migration.mts HEAD` — expected:
+`0 distinct pairs removed, 0 added, 0 unaccounted.` Then mutation-test it:
+temporarily delete one `style={{…}}` line from any component, rerun against
+`HEAD`, confirm it reports the removed pairs; revert.
+
+- [ ] **Step 7: Verify the empty imports build.** Prod build + dev server
+renders the homepage unchanged.
+
+- [ ] **Step 8: Commit** —
+`feat(website): scaffold the style-migration file layout and checker`
+
+---
+
+## Task 1 / Batch 1: `components/ui` → `ui.css` (25 sites, 11 files) — PR 1
+
+The pattern-setter. 9 of 11 files already emit a `data-ui` hook.
+
+**Inventory and shapes:**
+
+| file | sites | shape / gotcha |
+|---|---:|---|
+| `BrowserFrame.tsx` | 9 | A; hooks `browser-frame`/`browser-frame-body` exist |
+| `FAQ.tsx` | 5 | A; `faq-item`/`faq-chevron` rules already in global.css — extend them |
+| `ClipPlayer.tsx` | 2 | A; **add** `data-ui="clip-player"` |
+| `LogoMark.tsx` | 2 | A + size prop → `data-size` |
+| `TabGroup.tsx` | 2 | A; **add** `data-ui="tab-group"`; active-tab state → `data-active` |
+| `Button.tsx` | 2 (var) | **B — the worked example above.** Keep caller `style` passthrough |
+| `Card.tsx` | 1 | A — worked example; `PAD` map → `data-padding` |
+| `Container.tsx` / `Eyebrow.tsx` / `Pill.tsx` / `Section.tsx` | 1 each | A; Pill/Eyebrow variants → `data-variant` |
+
+- [ ] Step 1: migrate `Card`, `Container`, `Eyebrow`, `Pill`, `Section` (the
+  five one-siters). Run checker + vitest. Commit:
+  `refactor(website): move ui primitive resting styles to ui.css (1/3)`
+- [ ] Step 2: migrate `Button` (shape B) + `FAQ` + `LogoMark`. Note `Button`
+  merges caller `style` last — that passthrough **stays**. Commit (2/3).
+- [ ] Step 3: migrate `BrowserFrame`, `ClipPlayer`, `TabGroup` (add their
+  hooks). Commit (3/3).
+- [ ] Step 4: full verification ritual. Spot-check page: `/` (homepage uses
+  every primitive). Also move the existing `[data-ui="card"]`, `faq`, and
+  `heading-anchor`-adjacent primitive rules from `global.css` into `ui.css`
+  (pure cut-paste — they are already CSS).
+- [ ] Step 5: PR — `refactor(website): batch 1 — ui primitives off inline styles`.
+  Body includes checker output and the spot-check verdict. Auto-merge on green
+  after reading AI review.
+
+---
+
+## Task 2 / Batch 2: `components/shared` → `chrome.css` (76 sites, 3 files) — PR 2
+
+| file | sites | shape / gotcha |
+|---|---:|---|
+| `Nav.tsx` | 33 | A + C (5 hover handlers) + two dropdowns; `tabStyle`/`subTabStyle` functions → `data-active` modifier rules (shape B). Keep: `top: 57` overlay offset stays until Project 3's `--nav-h` work — migrate it verbatim as a literal. |
+| `Footer.tsx` | 30 | **C ×23** — the hover-handler motherlode. One `.footer-link` class + `:hover` rule replaces 46 handler props. |
+| `AnnouncementToast.tsx` | 13 | A; keep the entrance-animation state inline if it interpolates, else migrate. |
+
+- [ ] Step 1: `Footer.tsx` alone (biggest single-file win). Commit.
+- [ ] Step 2: `Nav.tsx`. Desktop links, dropdowns, mobile overlay each get
+  `.nav-*` classes. Commit.
+- [ ] Step 3: `AnnouncementToast.tsx`. Commit.
+- [ ] Step 4: ritual. Spot-check pages: `/` **and** `/docs/chat/components/chat`
+  (nav renders docs-mode UI), both desktop and 375px (mobile overlay).
+  Extra check: hamburger, both dropdowns, and the mobile docs tree still
+  open/close — `Nav` keeps `'use client'` (it has real state).
+- [ ] Step 5: PR — auto-merge on green.
+
+---
+
+## Task 3 / Batch 3: `components/docs` → `docs.css` (~180 sites, 22 files) — PR 3
+
+Unblocks Project 3. Also: move every existing docs rule out of `global.css`
+into `docs.css` (`.docs-prose`, `.docs-table-scroll`, code-figure rules, the
+`--docs-*` local constants block, heading anchors) — pure cut-paste, zero edits.
+
+| file | sites | gotcha |
+|---|---:|---|
+| `ApiDocRenderer.tsx` | 29 | A throughout; tables get `.api-doc-*` classes |
+| `ArchFlowDiagram.tsx` | 23 + `<style>` tag | hoist tag per convention 5 |
+| `DocsSidebar.tsx` | 21 + `<style>` tag | the tag interpolates `${tokens.*}` → `var(--*)`; `[data-docs-navlink]` rules move here |
+| `ApiRefTable.tsx` | 11 | A |
+| `AgUiArchDiagram.tsx` | 10 | `.ag-ui-arch-grid` rules already in global.css — reunite them here |
+| `DocsSearch.tsx` | 9 | A; overlay/positioning static → migrate; keyboard-selected row → `data-selected` |
+| `DocsPrevNext.tsx` | 9 | A |
+| `DocsBreadcrumb.tsx` | 9 | A; migrate **verbatim** — do NOT fix the alignment bug here (that is Project 3; a fix mixed into a migration diff is unreviewable) |
+| `mdx/Steps.tsx`, `mdx/Card.tsx` | 8 each | A; Steps' connector stays per-step for now (Project 3 adds `:last-child`) |
+| `PageActions.tsx`, `mdx/FeatureChips.tsx` | 6 each | C ×1 in FeatureChips |
+| `mdx/Callout.tsx` | 5 | tone map → `data-tone` (attribute already emitted!) |
+| `CodeGroup`, `DocsPageHeader` | 4 each | C ×1 in CodeGroup |
+| `Tabs`, `CodeBlock`, `LibraryMark`, `DocsTOC` | 3 each | C ×1 in Tabs; TOC active state → `data-active` |
+| `MdxRenderer`, `CopyPromptButton`, `CopyButton` | 1 each | MdxRenderer's `--tw-prose-*` custom-prop object is **already the escape hatch** — stays |
+
+- [ ] Step 1: cut-paste the existing docs rules from `global.css` → `docs.css`.
+  Prod build + spot check must show **zero** change. Commit.
+- [ ] Step 2: mdx components (9 files). Commit.
+- [ ] Step 3: sidebar + search + TOC + breadcrumb + header + actions. Commit.
+- [ ] Step 4: API renderers + diagrams (hoisting both `<style>` tags). Commit.
+- [ ] Step 5: ritual. Spot-check: `/docs/chat/components/chat` (densest page)
+  at 1280 and 375. PR; auto-merge on green.
+
+---
+
+## Task 4 / Batch 4: `components/landing` → `landing.css` (~166 sites + 10 `<style>` tags, 17 files) — PR 4
+
+Every file listed hoists its `<style>` tag (10 of 17 have one) and migrates its
+style props. Files: `WhitePaperBlock` 20, `Differentiator` 15, `PilotBlock` 13,
+`Hero` 13, `FeatureBlock` 13, `EcosystemStrip` 13, `DemoModal` 12,
+`DemoShowcase` 9, three `*CodeShowcase` 8 each, `Promises` 7, `RecentArticles` 6,
+`FinalCTA` 5, `BackendsGrid` 4, `HomeFAQ` 4, `HighlightedCode` 1.
+
+Gotchas: the `<style>` tags already use semantic classes (`.why-row`,
+`.wp-grid`, `.hero-grid`) — keep those names. `DemoModal` iframe sizing that
+depends on runtime measurement stays inline. `ClipPlayer` consumers must not
+re-declare what Batch 1 already put in `ui.css`.
+
+- [ ] Step 1: `Hero`, `FeatureBlock`, `Differentiator`, `WhitePaperBlock`. Commit.
+- [ ] Step 2: `PilotBlock`, `EcosystemStrip`, `Promises`, `RecentArticles`,
+  `FinalCTA`, `HomeFAQ`, `BackendsGrid`. Commit.
+- [ ] Step 3: `DemoModal`, `DemoShowcase`, the three code showcases,
+  `HighlightedCode`. Commit.
+- [ ] Step 4: ritual. Spot-check: `/` at 1280 / 768 / 375 — this batch owns the
+  page with the known 320px overflow bugs; they must be **unchanged, not fixed**.
+  PR; auto-merge on green.
+
+---
+
+## Task 5 / Batch 5: pricing + blog + contact + solutions → `marketing.css` (~112 sites, 15 files) — PR 5
+
+Files: `CompareTable` 31, `LeadForm` 29, `ContactForm` 14, `CompatibilityMatrix` 7,
+`AltChannelRow` 6, `PostCard` 6, `SolutionDemoBlock` 6, `SolutionCodeBlock` 6,
+`FeaturedPostCard` 5, `BlogTagFilter` 5, `PricingFAQ` 4, `AuthorByline` 4,
+`SlaCard` 2, `TagChips` 2, `GitHubStarsPill` 1.
+
+Gotchas: `LeadForm`/`ContactForm` have focus/validation states — those become
+`:focus-visible` and `data-invalid` rules (shape B/C), and the forms keep
+`'use client'`. `CompareTable`'s repeated cell styles are shape D — a handful
+of classes replace 31 sites.
+
+- [ ] Step 1: pricing (4 files). Commit. Step 2: blog (6 files). Commit.
+  Step 3: contact + solutions (5 files). Commit.
+- [ ] Step 4: ritual. Spot-check: `/pricing`, `/blog`, `/contact` at 1280/375.
+  **Note:** `PostCard.spec.tsx` and `Differentiator.spec.tsx` are two of the 5
+  pre-existing failures — they must fail in exactly the same way after
+  migration (content assertions, not style). PR; auto-merge on green.
+
+---
+
+## Task 6 / Batch 6: `app/**` routes → `pages.css` — TWO PRs
+
+**6a — docs-adjacent pages (~115 sites): PR 6.**
+`app/docs/licensing/page.tsx` 61 (30 shape-D variables), `app/docs/page.tsx` 50
+(33 shape-D), `app/docs/choosing-an-adapter/page.tsx` 2,
+`app/docs/[library]/[section]/[slug]/page.tsx` 2.
+
+The shape-D density makes this cheap: `bodyStyle`, `cellStyle`, `headingStyle`
+etc. each become one class. The docs shell's `overflow-x-hidden` + `paddingTop: 80`
+migrate **verbatim** — Project 3 changes them, not this.
+
+- [ ] Migrate, one commit per page file. Ritual; spot-check `/docs` and
+  `/docs/licensing`. PR; auto-merge on green.
+
+**6b — remaining routes (~192 sites): PR 7.**
+`solutions/[slug]` 28, `pilot-to-prod` 28, `about` 23, `solutions` 15,
+`render` 12, `chat` 11, `ag-ui` 11, `blog` 10, `langgraph` 9, `blog/[slug]` 8,
+`thanks` 7, `error` 7, `pricing` 6, `page` 6, `contact` 6, `not-found` 5.
+(Excluded, restated: both `opengraph-image.tsx`, `dev/primitives`.)
+
+- [ ] Migrate in three commits (solutions+pilot+about / library landing pages /
+  the rest). Ritual; spot-check `/about`, `/pilot-to-prod`, `/langgraph`.
+  PR; auto-merge on green.
+
+---
+
+## Task 7: The ESLint guard — PR 8
+
+Only after Batch 6b merges (landing it earlier means hundreds of suppressions).
+
+**Files:** Modify `eslint.config.mjs` (repo root).
+
+- [ ] **Step 1:** Read the existing flat config; append a block **preserving its
+  structure**:
+
+```js
+// Inline-style guard — apps/website migrated off static inline styles
+// (docs/superpowers/specs/2026-08-29-inline-style-substrate-migration-design.md).
+// Flags identifier-keyed members of a style object literal. The escape hatch
+// for dynamic values — style={{ '--x': value }} — uses string-literal keys and
+// passes. Genuinely dynamic identifier-keyed values (rare) get a targeted
+// eslint-disable-next-line with a reason.
+{
+  files: ['apps/website/src/**/*.tsx'],
+  ignores: [
+    'apps/website/src/app/opengraph-image.tsx',
+    'apps/website/src/app/blog/[slug]/opengraph-image.tsx', // Satori: inline-only
+    'apps/website/src/**/*.spec.tsx',
+  ],
+  rules: {
+    'no-restricted-syntax': ['warn', {
+      selector:
+        'JSXAttribute[name.name="style"] > JSXExpressionContainer > ObjectExpression > Property[key.type="Identifier"]',
+      message:
+        'Static presentation belongs in src/styles/*.css (see the substrate-migration spec). For dynamic values, set a CSS custom property: style={{ \'--x\': value }}.',
+    }],
+  },
+},
+```
+
+- [ ] **Step 2: Prove it fires and doesn't over-fire.** Add a scratch
+`style={{ color: 'red' }}` to any component → lint reports it. Change to
+`style={{ '--x': v }}` → silent. Revert. Confirm repo-wide warn count is small
+(only the deliberate dynamic stragglers) and **error count is 0** — CI fails on
+errors only.
+- [ ] **Step 3:** Escalate `'warn'` → `'error'` in a follow-up one release later
+(note it in the PR body as a deliberate two-step).
+- [ ] **Step 4:** PR — `chore(website): lint guard against new static inline styles`.
+
+---
+
+## Completion definition
+
+- `grep -rc 'style={{' apps/website/src` counts only: the two Satori files,
+  `dev/primitives`, custom-property escape hatches, and documented dynamic
+  values.
+- Zero embedded `<style>` tags outside `*.spec.tsx`.
+- `global.css` contains only imports, preflight, base element rules, and the
+  `--docs-*` constants (or those moved to `docs.css` — either, but one place).
+- Website vitest: same 5 pre-existing failures, no more.
+- The ESLint guard is live at `warn`.
+- Project 3 can begin: every selector it needs (`:hover`, `:focus-visible`,
+  `:last-child`, media queries) now has a stylesheet to live in.
diff --git a/docs/superpowers/specs/2026-08-29-inline-style-substrate-migration-design.md b/docs/superpowers/specs/2026-08-29-inline-style-substrate-migration-design.md
index dbbab360a..d2f0a8440 100644
--- a/docs/superpowers/specs/2026-08-29-inline-style-substrate-migration-design.md
+++ b/docs/superpowers/specs/2026-08-29-inline-style-substrate-migration-design.md
@@ -166,6 +166,27 @@ it only ever sees new code.
 
 Ships as `warn` for one release, then `error`.
 
+## Amendments from planning (2026-08-29)
+
+Facts found while writing the implementation plan
+(`plans/2026-08-29-inline-style-substrate-migration.md`), which supersede the
+corresponding text above:
+
+- **A third substrate exists.** 12 components embed a `<style>{`…`}</style>`
+  tag interpolating `${tokens.*}` (10 in landing, 2 in docs), one element per
+  component instance. They migrate in Batches 3–4: CSS text moves verbatim
+  into the batch file with interpolations replaced by `var(--*)`.
+- **Exclusions.** `app/opengraph-image.tsx` and `app/blog/[slug]/opengraph-image.tsx`
+  (14 sites) render through Satori, where inline styles are the only mechanism —
+  migrating them breaks OG images. `app/dev/primitives/page.tsx` (17 sites) is a
+  dev-only route documented as slated for deletion. In-scope is therefore
+  **~877 style-prop sites + 12 `<style>` tags across 88 files**, not 908.
+- **Batch 6 splits into 6a (docs-adjacent pages, ~115 sites) and 6b (remaining
+  routes, ~192)** — measured, `app/**` was too large for one review. The arc is
+  seven migration PRs plus the ESLint PR, not six.
+- **33 JS hover handlers** (`onMouseEnter` presentation writes — 23 in Footer
+  alone) convert to `:hover` rules as part of their component's batch.
+
 ## Risks
 
 - **Cascade and specificity.** Inline styles have the highest specificity; CSS
@@ -173,10 +194,14 @@ Ships as `warn` for one release, then `error`.
   rule once moved. This is the failure mode the text-level check cannot see and
   the spot check exists for.
 - **Tailwind utility collision.** Many components carry both `className`
-  utilities and inline styles. Moving a property into a `data-ui` rule can put
-  it in conflict with a utility on the same element; the utility wins or loses
-  depending on source order. Batch 1's review must establish the convention
-  (`@layer components` for the migrated rules, so utilities keep winning).
+  utilities and inline styles. Moving a property into a rule can put it in
+  conflict with a utility on the same element.
+  **Resolved at planning (2026-08-29), reversing this section's first guess:**
+  migrated rules are **unlayered**, like the existing `global.css` rules.
+  Tailwind v4 layers everything (`@layer theme, base, components, utilities`),
+  and unlayered author CSS beats all layers — which is the precedence inline
+  styles had. `@layer components` would invert the winner and change rendering;
+  unlayered preserves it. Verified against `node_modules/tailwindcss/index.css`.
 - **Six PRs of pure refactor** with no user-visible payoff, before Project 3
   delivers anything a reader sees. That was accepted when the arc was ordered.
 - **`app/**` at 263 sites is the largest batch** and may need splitting once

From 246ae0b1a5e3c007ca61862ed1a6957f7f8b015c Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 29 Aug 2026 12:17:24 -0700
Subject: [PATCH 3/7] feat(website): scaffold the style-migration file layout
 and checker

---
 .../website/scripts/check-style-migration.mts | 111 ++++++++++++++++++
 .../scripts/computed-style-snapshot.js        |  22 ++++
 apps/website/src/app/global.css               |   7 ++
 apps/website/src/app/page.module.css          |   2 -
 apps/website/src/styles/chrome.css            |  10 ++
 apps/website/src/styles/docs.css              |  10 ++
 apps/website/src/styles/landing.css           |  10 ++
 apps/website/src/styles/marketing.css         |  10 ++
 apps/website/src/styles/pages.css             |  10 ++
 apps/website/src/styles/ui.css                |  10 ++
 10 files changed, 200 insertions(+), 2 deletions(-)
 create mode 100644 apps/website/scripts/check-style-migration.mts
 create mode 100644 apps/website/scripts/computed-style-snapshot.js
 delete mode 100644 apps/website/src/app/page.module.css
 create mode 100644 apps/website/src/styles/chrome.css
 create mode 100644 apps/website/src/styles/docs.css
 create mode 100644 apps/website/src/styles/landing.css
 create mode 100644 apps/website/src/styles/marketing.css
 create mode 100644 apps/website/src/styles/pages.css
 create mode 100644 apps/website/src/styles/ui.css

diff --git a/apps/website/scripts/check-style-migration.mts b/apps/website/scripts/check-style-migration.mts
new file mode 100644
index 000000000..8869892ba
--- /dev/null
+++ b/apps/website/scripts/check-style-migration.mts
@@ -0,0 +1,111 @@
+#!/usr/bin/env tsx
+/**
+ * Advisory value-equality check for the inline-style migration.
+ *
+ * Diffs the working tree (or HEAD) against a base ref, extracts
+ * `property: value` pairs REMOVED from .tsx style objects and pairs ADDED to
+ * the migration CSS files, normalises both sides (camelCase→kebab, React
+ * numeric px, tokens.* → resolved value, var(--x) → resolved value), and
+ * reports removals with no matching addition.
+ *
+ * KNOWN BLIND SPOTS (by design — this is a text tool, not a harness):
+ *   - cascade/specificity: a correct value can still lose to another rule;
+ *   - shorthand vs longhand (`padding: '0 16px'` vs padding-top…);
+ *   - selectors: it compares property/value multisets, not which element
+ *     they apply to.
+ * Treat every flagged line as a question to answer in the PR body, not
+ * necessarily a bug.
+ *
+ * Usage: npx tsx apps/website/scripts/check-style-migration.mts [baseRef=origin/main] [--strict]
+ */
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// NOTE: libs/design-tokens has no `"type": "module"` in its package.json, so
+// Node's ESM loader resolves this .ts file as CommonJS. A static named
+// import (`import { tokens } from ...`) then depends on cjs-module-lexer
+// statically detecting the export from tsx's on-the-fly transform, which it
+// does not for this file — it only ever finds the synthetic `default`
+// (whole-module) binding. Importing the namespace and reading `.default`
+// sidesteps that without touching the shared library's module format.
+import * as designTokens from '../../../libs/design-tokens/src/index.ts';
+const { tokens } = (designTokens as unknown as { default: typeof designTokens }).default
+  ?? designTokens;
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO = resolve(HERE, '..', '..', '..');
+const BASE = process.argv[2] && !process.argv[2].startsWith('--')
+  ? process.argv[2] : 'origin/main';
+
+// --- resolve var(--x) via the committed theme.css + website-local :root vars
+const themeCss = readFileSync(
+  resolve(REPO, 'libs/design-tokens/src/lib/theme.css'), 'utf8');
+const globalCss = readFileSync(
+  resolve(REPO, 'apps/website/src/app/global.css'), 'utf8');
+const cssVars = new Map<string, string>();
+for (const m of (themeCss + globalCss).matchAll(/(--[a-z0-9-]+):\s*([^;]+);/g))
+  cssVars.set(m[1], m[2].trim());
+
+// --- resolve tokens.a.b.c to its value
+function tokenValue(path: string): string | undefined {
+  let cur: unknown = tokens;
+  for (const k of path.split('.')) {
+    if (cur == null || typeof cur !== 'object') return undefined;
+    cur = (cur as Record<string, unknown>)[k];
+  }
+  return cur == null || typeof cur === 'object' ? undefined : String(cur);
+}
+
+const UNITLESS = new Set(['line-height','font-weight','opacity','z-index',
+  'flex','flex-grow','flex-shrink','order']);
+
+function normProp(p: string): string {
+  return p.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase());
+}
+function normValue(prop: string, raw: string): string {
+  let v = raw.trim().replace(/^['"`]|['"`]$/g, '');
+  const tok = v.match(/^tokens\.([a-zA-Z.]+)$/);
+  if (tok) v = tokenValue(tok[1]) ?? v;
+  v = v.replace(/var\((--[a-z0-9-]+)\)/g, (_, name) => cssVars.get(name) ?? _);
+  if (/^-?\d+(\.\d+)?$/.test(v) && !UNITLESS.has(prop)) v = `${v}px`;
+  return v.replace(/\s+/g, ' ').toLowerCase();
+}
+
+function diffLines(pathspec: string, sign: '+' | '-'): string[] {
+  const out = execSync(
+    `git diff -U0 ${BASE} -- ${pathspec}`, { cwd: REPO, encoding: 'utf8' });
+  return out.split('\n')
+    .filter((l) => l.startsWith(sign) && !l.startsWith(sign.repeat(3)))
+    .map((l) => l.slice(1));
+}
+
+// pairs removed from TSX (style-object members: `foo: bar,`)
+const removed = new Map<string, number>();
+for (const line of diffLines("'apps/website/src/**/*.tsx'", '-')) {
+  const m = line.match(/^\s*([a-zA-Z]+):\s*(.+?),?\s*$/);
+  if (!m) continue;
+  const prop = normProp(m[1]);
+  if (!/^[a-z-]+$/.test(prop)) continue;
+  const key = `${prop} :: ${normValue(prop, m[2])}`;
+  removed.set(key, (removed.get(key) ?? 0) + 1);
+}
+// pairs added to migration CSS
+const added = new Map<string, number>();
+for (const line of diffLines(
+  "'apps/website/src/styles/*.css' 'apps/website/src/app/global.css'", '+')) {
+  for (const m of line.matchAll(/([a-z-]+):\s*([^;{}]+);/g)) {
+    const key = `${m[1]} :: ${normValue(m[1], m[2])}`;
+    added.set(key, (added.get(key) ?? 0) + 1);
+  }
+}
+
+let flagged = 0;
+for (const [key, n] of [...removed.entries()].sort()) {
+  if (!added.has(key)) {
+    console.log(`REMOVED, NO MATCHING CSS  (${n}x)  ${key}`);
+    flagged++;
+  }
+}
+console.log(`\n${removed.size} distinct pairs removed, ${added.size} added, ${flagged} unaccounted.`);
+if (flagged > 0 && process.argv.includes('--strict')) process.exit(1);
diff --git a/apps/website/scripts/computed-style-snapshot.js b/apps/website/scripts/computed-style-snapshot.js
new file mode 100644
index 000000000..d5ee9a2cd
--- /dev/null
+++ b/apps/website/scripts/computed-style-snapshot.js
@@ -0,0 +1,22 @@
+/**
+ * Paste into the browser console on a page BEFORE and AFTER a migration
+ * batch (on main's dev server, then the branch's), then diff the two JSONs.
+ * Serialises computed styles for every element carrying a migration hook.
+ */
+(() => {
+  const PROPS = ['color','background-color','border-color','border-radius',
+    'font-size','font-family','font-weight','line-height','letter-spacing',
+    'padding','margin','gap','height','width','max-width','box-shadow',
+    'display','align-items','justify-content','text-transform','opacity'];
+  const hooks = document.querySelectorAll(
+    '[data-ui],[data-mdx],[data-docs-navlink],[class]');
+  const out = {};
+  hooks.forEach((el, i) => {
+    const key = `${el.tagName}#${el.id || i}.${el.getAttribute('data-ui')
+      || el.getAttribute('data-mdx') || String(el.className).slice(0, 40)}`;
+    const cs = getComputedStyle(el);
+    out[key] = Object.fromEntries(PROPS.map((p) => [p, cs.getPropertyValue(p)]));
+  });
+  copy(JSON.stringify(out, null, 1));
+  return `snapshot of ${hooks.length} elements copied to clipboard`;
+})();
diff --git a/apps/website/src/app/global.css b/apps/website/src/app/global.css
index 2869e1953..a6e15cbc1 100644
--- a/apps/website/src/app/global.css
+++ b/apps/website/src/app/global.css
@@ -30,6 +30,13 @@
   --docs-accent-tint-line: color-mix(in srgb, var(--color-accent) 10%, transparent);
 }
 
+@import "../styles/ui.css";
+@import "../styles/chrome.css";
+@import "../styles/docs.css";
+@import "../styles/landing.css";
+@import "../styles/marketing.css";
+@import "../styles/pages.css";
+
 * {
   box-sizing: border-box;
 }
diff --git a/apps/website/src/app/page.module.css b/apps/website/src/app/page.module.css
deleted file mode 100644
index 8a13e21cb..000000000
--- a/apps/website/src/app/page.module.css
+++ /dev/null
@@ -1,2 +0,0 @@
-.page {
-}
diff --git a/apps/website/src/styles/chrome.css b/apps/website/src/styles/chrome.css
new file mode 100644
index 000000000..30c39d9c4
--- /dev/null
+++ b/apps/website/src/styles/chrome.css
@@ -0,0 +1,10 @@
+/*
+ * chrome.css — presentation for the shared chrome (Nav, Footer, AnnouncementToast), migrated from inline style props.
+ *
+ * Rules here are deliberately UNLAYERED: Tailwind v4 puts utilities in
+ * @layer utilities, and unlayered author CSS beats all layers — which is
+ * exactly the precedence the inline styles being replaced had. Wrapping
+ * these in @layer would let utilities win and change rendering.
+ *
+ * Migration: docs/superpowers/plans/2026-08-29-inline-style-substrate-migration.md
+ */
diff --git a/apps/website/src/styles/docs.css b/apps/website/src/styles/docs.css
new file mode 100644
index 000000000..e4ef38d5f
--- /dev/null
+++ b/apps/website/src/styles/docs.css
@@ -0,0 +1,10 @@
+/*
+ * docs.css — presentation for the docs surface (components/docs + mdx), migrated from inline style props.
+ *
+ * Rules here are deliberately UNLAYERED: Tailwind v4 puts utilities in
+ * @layer utilities, and unlayered author CSS beats all layers — which is
+ * exactly the precedence the inline styles being replaced had. Wrapping
+ * these in @layer would let utilities win and change rendering.
+ *
+ * Migration: docs/superpowers/plans/2026-08-29-inline-style-substrate-migration.md
+ */
diff --git a/apps/website/src/styles/landing.css b/apps/website/src/styles/landing.css
new file mode 100644
index 000000000..599cc6f63
--- /dev/null
+++ b/apps/website/src/styles/landing.css
@@ -0,0 +1,10 @@
+/*
+ * landing.css — presentation for the landing blocks (components/landing), migrated from inline style props.
+ *
+ * Rules here are deliberately UNLAYERED: Tailwind v4 puts utilities in
+ * @layer utilities, and unlayered author CSS beats all layers — which is
+ * exactly the precedence the inline styles being replaced had. Wrapping
+ * these in @layer would let utilities win and change rendering.
+ *
+ * Migration: docs/superpowers/plans/2026-08-29-inline-style-substrate-migration.md
+ */
diff --git a/apps/website/src/styles/marketing.css b/apps/website/src/styles/marketing.css
new file mode 100644
index 000000000..9fcbb1c50
--- /dev/null
+++ b/apps/website/src/styles/marketing.css
@@ -0,0 +1,10 @@
+/*
+ * marketing.css — presentation for pricing, blog, contact, and solutions components, migrated from inline style props.
+ *
+ * Rules here are deliberately UNLAYERED: Tailwind v4 puts utilities in
+ * @layer utilities, and unlayered author CSS beats all layers — which is
+ * exactly the precedence the inline styles being replaced had. Wrapping
+ * these in @layer would let utilities win and change rendering.
+ *
+ * Migration: docs/superpowers/plans/2026-08-29-inline-style-substrate-migration.md
+ */
diff --git a/apps/website/src/styles/pages.css b/apps/website/src/styles/pages.css
new file mode 100644
index 000000000..55730ebf4
--- /dev/null
+++ b/apps/website/src/styles/pages.css
@@ -0,0 +1,10 @@
+/*
+ * pages.css — presentation for app/** route-level presentation, migrated from inline style props.
+ *
+ * Rules here are deliberately UNLAYERED: Tailwind v4 puts utilities in
+ * @layer utilities, and unlayered author CSS beats all layers — which is
+ * exactly the precedence the inline styles being replaced had. Wrapping
+ * these in @layer would let utilities win and change rendering.
+ *
+ * Migration: docs/superpowers/plans/2026-08-29-inline-style-substrate-migration.md
+ */
diff --git a/apps/website/src/styles/ui.css b/apps/website/src/styles/ui.css
new file mode 100644
index 000000000..440b08a5f
--- /dev/null
+++ b/apps/website/src/styles/ui.css
@@ -0,0 +1,10 @@
+/*
+ * ui.css — presentation for the data-ui primitives in components/ui, migrated from inline style props.
+ *
+ * Rules here are deliberately UNLAYERED: Tailwind v4 puts utilities in
+ * @layer utilities, and unlayered author CSS beats all layers — which is
+ * exactly the precedence the inline styles being replaced had. Wrapping
+ * these in @layer would let utilities win and change rendering.
+ *
+ * Migration: docs/superpowers/plans/2026-08-29-inline-style-substrate-migration.md
+ */

From 4ff94f693af30ddbb211554f5415fbcd6c5e0a4b Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 29 Aug 2026 12:21:43 -0700
Subject: [PATCH 4/7] refactor(website): move ui primitive resting styles to
 ui.css (1/3)

Card, Container, Eyebrow, Pill, Section move static presentation from
inline style props into unlayered rules in ui.css, keyed off the
existing data-ui/data-variant/data-surface hooks (plus new
data-padding on Card and data-tight on Section). Also cut-pastes the
existing [data-ui="card"] and [data-ui="faq-item"] blocks out of
global.css into ui.css unchanged. Zero visual change: every value
moved verbatim, token references resolved via CSS_VAR_BY_PATH.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/src/app/global.css              |  57 --------
 apps/website/src/components/ui/Card.tsx      |  23 +---
 apps/website/src/components/ui/Container.tsx |  11 +-
 apps/website/src/components/ui/Eyebrow.tsx   |  19 +--
 apps/website/src/components/ui/Pill.tsx      |  42 +-----
 apps/website/src/components/ui/Section.tsx   |  15 +--
 apps/website/src/styles/ui.css               | 133 +++++++++++++++++++
 7 files changed, 145 insertions(+), 155 deletions(-)

diff --git a/apps/website/src/app/global.css b/apps/website/src/app/global.css
index a6e15cbc1..efe57991a 100644
--- a/apps/website/src/app/global.css
+++ b/apps/website/src/app/global.css
@@ -232,63 +232,6 @@ html {
 .docs-prose td { padding: 0.5rem 0.75rem; border-bottom: 1px solid var(--docs-accent-tint-soft); color: var(--color-text-secondary); }
 .docs-prose td code { font-size: 0.8em; }
 
-/* UI primitive — Card.
- * Resting background / border / shadow live here (not inline on the element)
- * so the :hover rules below can override border-color and box-shadow. Inline
- * styles beat any stylesheet :hover rule, which previously left the lift
- * rendering only the transform. See components/ui/Card.tsx. */
-[data-ui="card"] {
-  background: var(--color-surface);
-  border: 1px solid var(--color-border);
-  box-shadow: var(--shadow-sm);
-  transition: box-shadow 160ms ease, border-color 160ms ease, transform 160ms ease;
-}
-[data-ui="card"][data-surface="tinted"] {
-  background: var(--color-surface-tinted);
-}
-[data-ui="card"][data-surface="dim"] {
-  background: var(--color-surface-dim);
-}
-/* Accent-filled cards (e.g. docs backend / generative-UI cards). */
-[data-ui="card"][data-accent] {
-  background: var(--color-accent-surface);
-  border-color: var(--color-accent-border);
-}
-
-/* Hoverable cards are virtually always links; pointer is the right default.
- * If a non-link gets `data-hoverable`, override inline. */
-[data-ui="card"][data-hoverable] {
-  cursor: pointer;
-}
-[data-ui="card"][data-hoverable]:not([data-accent]):hover {
-  box-shadow: var(--shadow-md);
-  border-color: var(--color-border-strong);
-  transform: translateY(-1px);
-}
-/* Accent cards keep their accent border and gain an accent ring on hover. */
-[data-ui="card"][data-hoverable][data-accent]:hover {
-  box-shadow: 0 0 0 3px var(--color-accent-glow), var(--shadow-md);
-  transform: translateY(-1px);
-}
-@media (prefers-reduced-motion: reduce) {
-  [data-ui="card"][data-hoverable]:hover {
-    transform: none;
-  }
-}
-
-/* UI primitive — FAQ */
-[data-ui="faq-item"] > summary::-webkit-details-marker {
-  display: none;
-}
-[data-ui="faq-item"][open] [data-ui="faq-chevron"] {
-  transform: rotate(180deg);
-}
-[data-ui="faq-item"] > summary:focus-visible {
-  outline: none;
-  box-shadow: var(--shadow-focus);
-  border-radius: var(--radius-sm);
-}
-
 /* AG-UI architecture diagram */
 .ag-ui-arch-grid {
   display: grid;
diff --git a/apps/website/src/components/ui/Card.tsx b/apps/website/src/components/ui/Card.tsx
index fb9eef4ea..827da24ca 100644
--- a/apps/website/src/components/ui/Card.tsx
+++ b/apps/website/src/components/ui/Card.tsx
@@ -1,5 +1,4 @@
 import type { ReactNode, HTMLAttributes } from 'react';
-import { tokens } from '@threadplane/design-tokens';
 import { cn } from '../../lib/cn';
 
 type Surface = 'white' | 'tinted' | 'dim';
@@ -20,11 +19,6 @@ interface CardProps extends HTMLAttributes<HTMLDivElement> {
   surface?: Surface;
 }
 
-const PADDING: Record<Padding, string> = {
-  md: '20px',
-  lg: '28px',
-};
-
 export function Card({
   children,
   hoverable = false,
@@ -35,23 +29,20 @@ export function Card({
   style,
   ...rest
 }: CardProps) {
-  // Resting background / border / shadow live in the `[data-ui="card"]`
-  // stylesheet (apps/website/src/app/global.css) — never inline — so the
-  // :hover rules can actually override border-color and box-shadow. Inline
-  // styles beat any stylesheet :hover rule, which previously left the lift
-  // rendering only the transform.
+  // Resting background / border / shadow / radius / padding live in the
+  // `[data-ui="card"]` stylesheet (apps/website/src/styles/ui.css) — never
+  // inline — so the :hover rules can actually override border-color and
+  // box-shadow. Inline styles beat any stylesheet :hover rule, which
+  // previously left the lift rendering only the transform.
   return (
     <div
       data-ui="card"
       data-hoverable={hoverable || undefined}
       data-accent={accent || undefined}
       data-surface={surface !== 'white' ? surface : undefined}
+      data-padding={padding !== 'md' ? padding : undefined}
       className={cn(className)}
-      style={{
-        borderRadius: tokens.radius.lg,
-        padding: PADDING[padding],
-        ...style,
-      }}
+      style={style}
       {...rest}
     >
       {children}
diff --git a/apps/website/src/components/ui/Container.tsx b/apps/website/src/components/ui/Container.tsx
index 33aece3ec..9bea6582c 100644
--- a/apps/website/src/components/ui/Container.tsx
+++ b/apps/website/src/components/ui/Container.tsx
@@ -1,5 +1,4 @@
 import type { ReactNode, HTMLAttributes } from 'react';
-import { tokens } from '@threadplane/design-tokens';
 import { cn } from '../../lib/cn';
 
 interface ContainerProps extends HTMLAttributes<HTMLDivElement> {
@@ -15,20 +14,12 @@ export function Container({
   style,
   ...rest
 }: ContainerProps) {
-  const maxWidth = size === 'wide' ? '1320px' : tokens.space.containerMax;
   return (
     <div
       data-ui="container"
       data-size={size}
       className={cn(className)}
-      style={{
-        width: '100%',
-        maxWidth,
-        margin: '0 auto',
-        paddingLeft: tokens.space.containerX,
-        paddingRight: tokens.space.containerX,
-        ...style,
-      }}
+      style={style}
       {...rest}
     >
       {children}
diff --git a/apps/website/src/components/ui/Eyebrow.tsx b/apps/website/src/components/ui/Eyebrow.tsx
index 6195d7a43..25de09fa8 100644
--- a/apps/website/src/components/ui/Eyebrow.tsx
+++ b/apps/website/src/components/ui/Eyebrow.tsx
@@ -1,5 +1,4 @@
 import type { ReactNode, HTMLAttributes } from 'react';
-import { tokens } from '@threadplane/design-tokens';
 import { cn } from '../../lib/cn';
 
 type Tone = 'muted' | 'accent' | 'angular';
@@ -10,12 +9,6 @@ interface EyebrowProps extends HTMLAttributes<HTMLParagraphElement> {
   tone?: Tone;
 }
 
-const TONE_COLOR: Record<Tone, string> = {
-  muted: tokens.colors.textMuted,
-  accent: tokens.colors.accent,
-  angular: tokens.colors.angularRed,
-};
-
 export function Eyebrow({
   children,
   tone = 'muted',
@@ -28,17 +21,7 @@ export function Eyebrow({
       data-ui="eyebrow"
       data-tone={tone}
       className={cn(className)}
-      style={{
-        fontFamily: tokens.typography.eyebrow.family,
-        fontSize: tokens.typography.eyebrow.size,
-        fontWeight: tokens.typography.eyebrow.weight,
-        letterSpacing: tokens.typography.eyebrow.letterSpacing,
-        textTransform: tokens.typography.eyebrow.transform,
-        lineHeight: tokens.typography.eyebrow.line,
-        color: TONE_COLOR[tone],
-        margin: 0,
-        ...style,
-      }}
+      style={style}
       {...rest}
     >
       {children}
diff --git a/apps/website/src/components/ui/Pill.tsx b/apps/website/src/components/ui/Pill.tsx
index b3f275b64..d1e0beabd 100644
--- a/apps/website/src/components/ui/Pill.tsx
+++ b/apps/website/src/components/ui/Pill.tsx
@@ -1,5 +1,4 @@
 import type { ReactNode, HTMLAttributes } from 'react';
-import { tokens } from '@threadplane/design-tokens';
 import { cn } from '../../lib/cn';
 
 type PillVariant = 'neutral' | 'accent' | 'angular';
@@ -9,30 +8,6 @@ interface PillProps extends HTMLAttributes<HTMLSpanElement> {
   variant?: PillVariant;
 }
 
-interface VariantStyle {
-  bg: string;
-  border: string;
-  color: string;
-}
-
-const VARIANT_STYLES: Record<PillVariant, VariantStyle> = {
-  neutral: {
-    bg: tokens.surfaces.surface,
-    border: tokens.surfaces.border,
-    color: tokens.colors.textSecondary,
-  },
-  accent: {
-    bg: tokens.colors.accentSurface,
-    border: tokens.colors.accentBorder,
-    color: tokens.colors.accent,
-  },
-  angular: {
-    bg: 'rgba(221, 0, 49, 0.06)',
-    border: 'rgba(221, 0, 49, 0.18)',
-    color: tokens.colors.angularRed,
-  },
-};
-
 export function Pill({
   children,
   variant = 'neutral',
@@ -40,27 +15,12 @@ export function Pill({
   style,
   ...rest
 }: PillProps) {
-  const v = VARIANT_STYLES[variant];
   return (
     <span
       data-ui="pill"
       data-variant={variant}
       className={cn(className)}
-      style={{
-        display: 'inline-flex',
-        alignItems: 'center',
-        gap: 6,
-        fontFamily: tokens.typography.fontMono,
-        fontSize: 11,
-        fontWeight: 500,
-        padding: '4px 10px',
-        borderRadius: tokens.radius.full,
-        background: v.bg,
-        border: `1px solid ${v.border}`,
-        color: v.color,
-        lineHeight: 1.4,
-        ...style,
-      }}
+      style={style}
       {...rest}
     >
       {children}
diff --git a/apps/website/src/components/ui/Section.tsx b/apps/website/src/components/ui/Section.tsx
index 01762cdba..183bb26fe 100644
--- a/apps/website/src/components/ui/Section.tsx
+++ b/apps/website/src/components/ui/Section.tsx
@@ -1,5 +1,4 @@
 import type { ReactNode, HTMLAttributes } from 'react';
-import { tokens } from '@threadplane/design-tokens';
 import { cn } from '../../lib/cn';
 
 type Surface = 'canvas' | 'tinted' | 'white';
@@ -16,12 +15,6 @@ interface SectionProps extends Omit<HTMLAttributes<HTMLElement>, 'id'> {
   ariaLabelledBy?: string;
 }
 
-const SURFACE_BG: Record<Surface, string> = {
-  canvas: tokens.surfaces.canvas,
-  tinted: tokens.surfaces.surfaceTinted,
-  white: tokens.surfaces.surface,
-};
-
 export function Section({
   children,
   surface = 'canvas',
@@ -38,13 +31,9 @@ export function Section({
       aria-labelledby={ariaLabelledBy}
       data-ui="section"
       data-surface={surface}
+      data-tight={tight || undefined}
       className={cn(className)}
-      style={{
-        background: SURFACE_BG[surface],
-        paddingTop: tight ? tokens.space.sectionYTight : tokens.space.sectionY,
-        paddingBottom: tight ? tokens.space.sectionYTight : tokens.space.sectionY,
-        ...style,
-      }}
+      style={style}
       {...rest}
     >
       {children}
diff --git a/apps/website/src/styles/ui.css b/apps/website/src/styles/ui.css
index 440b08a5f..50c2d301f 100644
--- a/apps/website/src/styles/ui.css
+++ b/apps/website/src/styles/ui.css
@@ -8,3 +8,136 @@
  *
  * Migration: docs/superpowers/plans/2026-08-29-inline-style-substrate-migration.md
  */
+
+/* UI primitive — Card.
+ * Resting background / border / shadow live here (not inline on the element)
+ * so the :hover rules below can override border-color and box-shadow. Inline
+ * styles beat any stylesheet :hover rule, which previously left the lift
+ * rendering only the transform. See components/ui/Card.tsx. */
+[data-ui="card"] {
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  box-shadow: var(--shadow-sm);
+  transition: box-shadow 160ms ease, border-color 160ms ease, transform 160ms ease;
+}
+[data-ui="card"][data-surface="tinted"] {
+  background: var(--color-surface-tinted);
+}
+[data-ui="card"][data-surface="dim"] {
+  background: var(--color-surface-dim);
+}
+/* Accent-filled cards (e.g. docs backend / generative-UI cards). */
+[data-ui="card"][data-accent] {
+  background: var(--color-accent-surface);
+  border-color: var(--color-accent-border);
+}
+
+/* Hoverable cards are virtually always links; pointer is the right default.
+ * If a non-link gets `data-hoverable`, override inline. */
+[data-ui="card"][data-hoverable] {
+  cursor: pointer;
+}
+[data-ui="card"][data-hoverable]:not([data-accent]):hover {
+  box-shadow: var(--shadow-md);
+  border-color: var(--color-border-strong);
+  transform: translateY(-1px);
+}
+/* Accent cards keep their accent border and gain an accent ring on hover. */
+[data-ui="card"][data-hoverable][data-accent]:hover {
+  box-shadow: 0 0 0 3px var(--color-accent-glow), var(--shadow-md);
+  transform: translateY(-1px);
+}
+@media (prefers-reduced-motion: reduce) {
+  [data-ui="card"][data-hoverable]:hover {
+    transform: none;
+  }
+}
+
+/* UI primitive — Card: static shape. Bounded padding tiers via data-padding
+ * (default 'md' has no attribute — see components/ui/Card.tsx). */
+[data-ui="card"] {
+  border-radius: var(--radius-lg);
+  padding: 20px;
+}
+[data-ui="card"][data-padding="lg"] {
+  padding: 28px;
+}
+
+/* UI primitive — Container */
+[data-ui="container"] {
+  width: 100%;
+  margin: 0 auto;
+  padding-left: var(--spacing-container-x);
+  padding-right: var(--spacing-container-x);
+  max-width: var(--container-page);
+}
+[data-ui="container"][data-size="wide"] {
+  max-width: 1320px;
+}
+
+/* UI primitive — Eyebrow */
+[data-ui="eyebrow"] {
+  font-family: var(--font-mono);
+  font-size: var(--text-eyebrow);
+  font-weight: var(--text-eyebrow--font-weight);
+  letter-spacing: var(--text-eyebrow--letter-spacing);
+  text-transform: uppercase;
+  line-height: var(--text-eyebrow--line-height);
+  margin: 0;
+}
+[data-ui="eyebrow"][data-tone="muted"] {
+  color: var(--color-text-muted);
+}
+[data-ui="eyebrow"][data-tone="accent"] {
+  color: var(--color-accent);
+}
+[data-ui="eyebrow"][data-tone="angular"] {
+  color: var(--color-angular-red);
+}
+
+/* UI primitive — Pill */
+[data-ui="pill"] {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-family: var(--font-mono);
+  font-size: 11px;
+  font-weight: 500;
+  padding: 4px 10px;
+  border-radius: var(--radius-full);
+  line-height: 1.4;
+}
+[data-ui="pill"][data-variant="neutral"] {
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  color: var(--color-text-secondary);
+}
+[data-ui="pill"][data-variant="accent"] {
+  background: var(--color-accent-surface);
+  border: 1px solid var(--color-accent-border);
+  color: var(--color-accent);
+}
+[data-ui="pill"][data-variant="angular"] {
+  background: rgba(221, 0, 49, 0.06);
+  border: 1px solid rgba(221, 0, 49, 0.18);
+  color: var(--color-angular-red);
+}
+
+/* UI primitive — Section */
+[data-ui="section"] {
+  padding-top: var(--spacing-section-y);
+  padding-bottom: var(--spacing-section-y);
+}
+[data-ui="section"][data-tight] {
+  padding-top: var(--spacing-section-y-tight);
+  padding-bottom: var(--spacing-section-y-tight);
+}
+[data-ui="section"][data-surface="canvas"] {
+  background: var(--color-canvas);
+}
+[data-ui="section"][data-surface="tinted"] {
+  background: var(--color-surface-tinted);
+}
+[data-ui="section"][data-surface="white"] {
+  background: var(--color-surface);
+}

From ea080db24498f6fa10966d6b100f496a95f19d60 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 29 Aug 2026 12:24:01 -0700
Subject: [PATCH 5/7] refactor(website): move ui primitive resting styles to
 ui.css (2/3)

Button, FAQ, LogoMark move static presentation from inline style props
(VARIANT_STYLES/SIZE_STYLES records, per-item inline objects) into
unlayered rules in ui.css, keyed off data-ui/data-variant/data-size
(new data-size on LogoMark, new data-ui="logo-mark-icon" hook).
Caller `style` passthrough is preserved on Button and LogoMark. Zero
visual change: every value moved verbatim.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/src/components/ui/Button.tsx   |  61 +----------
 apps/website/src/components/ui/FAQ.tsx      |  61 +----------
 apps/website/src/components/ui/LogoMark.tsx |  22 +---
 apps/website/src/styles/ui.css              | 112 ++++++++++++++++++++
 4 files changed, 122 insertions(+), 134 deletions(-)

diff --git a/apps/website/src/components/ui/Button.tsx b/apps/website/src/components/ui/Button.tsx
index 464bf7e41..c887cb168 100644
--- a/apps/website/src/components/ui/Button.tsx
+++ b/apps/website/src/components/ui/Button.tsx
@@ -2,9 +2,7 @@ import type {
   ReactNode,
   AnchorHTMLAttributes,
   ButtonHTMLAttributes,
-  CSSProperties,
 } from 'react';
-import { tokens } from '@threadplane/design-tokens';
 import { cn } from '../../lib/cn';
 
 type Variant = 'primary' | 'secondary' | 'ghost';
@@ -30,35 +28,6 @@ type NativeButtonProps = CommonProps &
 
 export type ButtonProps = AnchorButtonProps | NativeButtonProps;
 
-interface VariantStyle {
-  bg: string;
-  color: string;
-  border: string;
-}
-
-const VARIANT_STYLES: Record<Variant, VariantStyle> = {
-  primary: {
-    bg: tokens.colors.accent,
-    color: tokens.colors.textInverted,
-    border: tokens.colors.accent,
-  },
-  secondary: {
-    bg: tokens.surfaces.surface,
-    color: tokens.colors.textPrimary,
-    border: tokens.surfaces.borderStrong,
-  },
-  ghost: {
-    bg: 'transparent',
-    color: tokens.colors.accent,
-    border: 'transparent',
-  },
-};
-
-const SIZE_STYLES: Record<Size, { padding: string; fontSize: number; height: number }> = {
-  md: { padding: '0 16px', fontSize: 14, height: 40 },
-  lg: { padding: '0 22px', fontSize: 16, height: 48 },
-};
-
 export function Button(props: ButtonProps) {
   const {
     children,
@@ -68,32 +37,6 @@ export function Button(props: ButtonProps) {
     className,
     style,
   } = props;
-  const v = VARIANT_STYLES[variant];
-  const s = SIZE_STYLES[size];
-
-  const combinedStyle: CSSProperties = {
-    display: 'inline-flex',
-    alignItems: 'center',
-    justifyContent: 'center',
-    gap: 8,
-    height: s.height,
-    padding: s.padding,
-    fontFamily: tokens.typography.fontSans,
-    fontSize: s.fontSize,
-    fontWeight: 600,
-    lineHeight: 1,
-    background: v.bg,
-    color: v.color,
-    border: `1px solid ${v.border}`,
-    borderRadius: tokens.radius.md,
-    boxShadow: variant === 'primary' ? tokens.shadows.sm : 'none',
-    cursor: 'pointer',
-    textDecoration: 'none',
-    transition:
-      'background-color 120ms ease, color 120ms ease, border-color 120ms ease, box-shadow 120ms ease',
-    whiteSpace: 'nowrap',
-    ...style,
-  };
 
   const content = (
     <>
@@ -120,7 +63,7 @@ export function Button(props: ButtonProps) {
         data-variant={variant}
         data-size={size}
         className={cn(className)}
-        style={combinedStyle}
+        style={style}
         {...anchorAttrs}
       >
         {content}
@@ -145,7 +88,7 @@ export function Button(props: ButtonProps) {
       data-variant={variant}
       data-size={size}
       className={cn(className)}
-      style={combinedStyle}
+      style={style}
       {...buttonAttrs}
     >
       {content}
diff --git a/apps/website/src/components/ui/FAQ.tsx b/apps/website/src/components/ui/FAQ.tsx
index 4a5a680d8..478a6855f 100644
--- a/apps/website/src/components/ui/FAQ.tsx
+++ b/apps/website/src/components/ui/FAQ.tsx
@@ -1,5 +1,4 @@
 import type { ReactNode } from 'react';
-import { tokens } from '@threadplane/design-tokens';
 import { cn } from '../../lib/cn';
 
 export interface FAQItem {
@@ -18,66 +17,16 @@ interface FAQProps {
  */
 export function FAQ({ items, className }: FAQProps) {
   return (
-    <div
-      data-ui="faq"
-      className={cn(className)}
-      style={{
-        display: 'flex',
-        flexDirection: 'column',
-        gap: 12,
-      }}
-    >
+    <div data-ui="faq" className={cn(className)}>
       {items.map((item, i) => (
-        <details
-          key={i}
-          data-ui="faq-item"
-          style={{
-            background: tokens.surfaces.surface,
-            border: `1px solid ${tokens.surfaces.border}`,
-            borderRadius: tokens.radius.lg,
-            boxShadow: tokens.shadows.sm,
-            padding: '0 20px',
-          }}
-        >
-          <summary
-            style={{
-              display: 'flex',
-              alignItems: 'center',
-              justifyContent: 'space-between',
-              gap: 16,
-              padding: '20px 0',
-              cursor: 'pointer',
-              fontFamily: tokens.typography.fontSans,
-              fontSize: 17,
-              fontWeight: 600,
-              color: tokens.colors.textPrimary,
-              listStyle: 'none',
-            }}
-          >
+        <details key={i} data-ui="faq-item">
+          <summary>
             <span>{item.q}</span>
-            <span
-              aria-hidden="true"
-              data-ui="faq-chevron"
-              style={{
-                transition: 'transform 200ms ease',
-                fontSize: 14,
-                color: tokens.colors.textSecondary,
-              }}
-            >
+            <span aria-hidden="true" data-ui="faq-chevron">
               ▼
             </span>
           </summary>
-          <div
-            style={{
-              paddingBottom: 20,
-              fontFamily: tokens.typography.fontSans,
-              fontSize: 16,
-              lineHeight: 1.6,
-              color: tokens.colors.textSecondary,
-            }}
-          >
-            {item.a}
-          </div>
+          <div>{item.a}</div>
         </details>
       ))}
     </div>
diff --git a/apps/website/src/components/ui/LogoMark.tsx b/apps/website/src/components/ui/LogoMark.tsx
index c0693e165..fa7b9cce5 100644
--- a/apps/website/src/components/ui/LogoMark.tsx
+++ b/apps/website/src/components/ui/LogoMark.tsx
@@ -1,5 +1,4 @@
 import type { HTMLAttributes } from 'react';
-import { tokens } from '@threadplane/design-tokens';
 import { cn } from '../../lib/cn';
 
 type LogoSize = 'sm' | 'md';
@@ -10,11 +9,6 @@ interface LogoMarkProps extends HTMLAttributes<HTMLSpanElement> {
   iconOnly?: boolean;
 }
 
-const SIZE: Record<LogoSize, { icon: number; label: number }> = {
-  sm: { icon: 18, label: 14 },
-  md: { icon: 22, label: 16 },
-};
-
 export function LogoMark({
   size = 'md',
   iconOnly = false,
@@ -22,25 +16,15 @@ export function LogoMark({
   style,
   ...rest
 }: LogoMarkProps) {
-  const s = SIZE[size];
   return (
     <span
       data-ui="logo-mark"
+      data-size={size}
       className={cn(className)}
-      style={{
-        display: 'inline-flex',
-        alignItems: 'center',
-        gap: 8,
-        fontFamily: tokens.typography.fontSerif,
-        fontSize: s.label,
-        fontWeight: 700,
-        color: tokens.colors.textPrimary,
-        lineHeight: 1,
-        ...style,
-      }}
+      style={style}
       {...rest}
     >
-      <span aria-hidden="true" style={{ fontSize: s.icon, lineHeight: 1 }}>🛩️</span>
+      <span aria-hidden="true" data-ui="logo-mark-icon">🛩️</span>
       {iconOnly ? null : <span>Threadplane</span>}
     </span>
   );
diff --git a/apps/website/src/styles/ui.css b/apps/website/src/styles/ui.css
index 50c2d301f..1067332eb 100644
--- a/apps/website/src/styles/ui.css
+++ b/apps/website/src/styles/ui.css
@@ -141,3 +141,115 @@
 [data-ui="section"][data-surface="white"] {
   background: var(--color-surface);
 }
+
+/* UI primitive — Button */
+[data-ui="button"] {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  font-family: var(--font-inter);
+  font-weight: 600;
+  line-height: 1;
+  border-radius: var(--radius-md);
+  cursor: pointer;
+  text-decoration: none;
+  transition: background-color 120ms ease, color 120ms ease, border-color 120ms ease, box-shadow 120ms ease;
+  white-space: nowrap;
+}
+[data-ui="button"][data-size="md"] {
+  height: 40px;
+  padding: 0 16px;
+  font-size: 14px;
+}
+[data-ui="button"][data-size="lg"] {
+  height: 48px;
+  padding: 0 22px;
+  font-size: 16px;
+}
+[data-ui="button"][data-variant="primary"] {
+  background: var(--color-accent);
+  color: var(--color-text-inverted);
+  border: 1px solid var(--color-accent);
+  box-shadow: var(--shadow-sm);
+}
+[data-ui="button"][data-variant="secondary"] {
+  background: var(--color-surface);
+  color: var(--color-text-primary);
+  border: 1px solid var(--color-border-strong);
+  box-shadow: none;
+}
+[data-ui="button"][data-variant="ghost"] {
+  background: transparent;
+  color: var(--color-accent);
+  border: 1px solid transparent;
+  box-shadow: none;
+}
+
+/* UI primitive — FAQ.
+ * The summary::-webkit-details-marker hide, open-state chevron rotation, and
+ * summary focus-visible rules are pre-existing and stay above (cut-pasted
+ * verbatim from global.css); these are the resting styles that were inline. */
+[data-ui="faq"] {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+[data-ui="faq-item"] {
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-lg);
+  box-shadow: var(--shadow-sm);
+  padding: 0 20px;
+}
+[data-ui="faq-item"] > summary {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  padding: 20px 0;
+  cursor: pointer;
+  font-family: var(--font-inter);
+  font-size: 17px;
+  font-weight: 600;
+  color: var(--color-text-primary);
+  list-style: none;
+}
+[data-ui="faq-chevron"] {
+  transition: transform 200ms ease;
+  font-size: 14px;
+  color: var(--color-text-secondary);
+}
+[data-ui="faq-item"] > div {
+  padding-bottom: 20px;
+  font-family: var(--font-inter);
+  font-size: 16px;
+  line-height: 1.6;
+  color: var(--color-text-secondary);
+}
+
+/* UI primitive — LogoMark */
+[data-ui="logo-mark"] {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  font-family: var(--font-garamond);
+  font-weight: 700;
+  color: var(--color-text-primary);
+  line-height: 1;
+}
+[data-ui="logo-mark"][data-size="sm"] {
+  font-size: 14px;
+}
+[data-ui="logo-mark"][data-size="md"] {
+  font-size: 16px;
+}
+[data-ui="logo-mark-icon"] {
+  line-height: 1;
+}
+[data-ui="logo-mark"][data-size="sm"] > [data-ui="logo-mark-icon"] {
+  font-size: 18px;
+}
+[data-ui="logo-mark"][data-size="md"] > [data-ui="logo-mark-icon"] {
+  font-size: 22px;
+}

From d4e0da3f0e65180c18e53b15660908c49fb80f59 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 29 Aug 2026 12:26:09 -0700
Subject: [PATCH 6/7] refactor(website): move ui primitive resting styles to
 ui.css (3/3)

BrowserFrame, ClipPlayer, TabGroup move static presentation from
inline style props into unlayered rules in ui.css. BrowserFrame gains
data-elevation plus new data-ui hooks on its title bar/dots/url
pill/spacer (transform-rotate and max-width stay inline, genuinely
dynamic per-instance values); ClipPlayer and TabGroup get their first
data-ui hooks (data-ui="clip-player", data-ui="tab-group"/"tab-group-
list"/"tab-group-tab" with data-active). TabGroup's hardcoded
`Inter, sans-serif` font stack and `8px` radius are copied verbatim
rather than mapped to the (different-valued) --font-inter/--radius-md
tokens. Zero visual change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../src/components/ui/BrowserFrame.tsx        |  63 ++--------
 apps/website/src/components/ui/ClipPlayer.tsx |  10 +-
 apps/website/src/components/ui/TabGroup.tsx   |  23 +---
 apps/website/src/styles/ui.css                | 109 ++++++++++++++++++
 4 files changed, 125 insertions(+), 80 deletions(-)

diff --git a/apps/website/src/components/ui/BrowserFrame.tsx b/apps/website/src/components/ui/BrowserFrame.tsx
index 39ff24c28..9866f3cf2 100644
--- a/apps/website/src/components/ui/BrowserFrame.tsx
+++ b/apps/website/src/components/ui/BrowserFrame.tsx
@@ -1,5 +1,4 @@
 import type { ReactNode, HTMLAttributes } from 'react';
-import { tokens } from '@threadplane/design-tokens';
 import { cn } from '../../lib/cn';
 
 type Elevation = 'sm' | 'md' | 'lg';
@@ -16,12 +15,6 @@ interface BrowserFrameProps extends HTMLAttributes<HTMLDivElement> {
   maxWidth?: number | string;
 }
 
-const ELEVATION: Record<Elevation, string> = {
-  sm: tokens.shadows.sm,
-  md: tokens.shadows.md,
-  lg: tokens.shadows.lg,
-};
-
 export function BrowserFrame({
   children,
   url,
@@ -35,13 +28,11 @@ export function BrowserFrame({
   return (
     <div
       data-ui="browser-frame"
+      data-elevation={elevation}
       className={cn(className)}
       style={{
-        background: tokens.surfaces.surface,
-        border: `1px solid ${tokens.surfaces.border}`,
-        borderRadius: tokens.radius.lg,
-        boxShadow: ELEVATION[elevation],
-        overflow: 'hidden',
+        // Genuinely dynamic — computed from unbounded caller props, so these
+        // stay inline. Everything else here is static and lives in ui.css.
         transform: rotate ? `rotate(${rotate}deg)` : undefined,
         maxWidth,
         ...style,
@@ -49,53 +40,21 @@ export function BrowserFrame({
       {...rest}
     >
       {/* Title bar */}
-      <div
-        style={{
-          display: 'flex',
-          alignItems: 'center',
-          gap: 10,
-          padding: '10px 14px',
-          background: tokens.surfaces.surfaceTinted,
-          borderBottom: `1px solid ${tokens.surfaces.border}`,
-        }}
-      >
+      <div data-ui="browser-frame-titlebar">
         {/* Traffic lights */}
-        <div style={{ display: 'flex', gap: 6 }} aria-hidden="true">
-          <span style={{ width: 12, height: 12, borderRadius: tokens.radius.full, background: '#FF5F57' }} />
-          <span style={{ width: 12, height: 12, borderRadius: tokens.radius.full, background: '#FEBC2E' }} />
-          <span style={{ width: 12, height: 12, borderRadius: tokens.radius.full, background: '#28C840' }} />
+        <div data-ui="browser-frame-dots" aria-hidden="true">
+          <span />
+          <span />
+          <span />
         </div>
         {/* URL pill */}
-        {url ? (
-          <div
-            style={{
-              flex: 1,
-              textAlign: 'center',
-              fontFamily: tokens.typography.fontMono,
-              fontSize: 11,
-              color: tokens.colors.textMuted,
-              background: tokens.surfaces.surface,
-              border: `1px solid ${tokens.surfaces.border}`,
-              borderRadius: tokens.radius.sm,
-              padding: '4px 10px',
-              maxWidth: 360,
-              margin: '0 auto',
-              overflow: 'hidden',
-              textOverflow: 'ellipsis',
-              whiteSpace: 'nowrap',
-            }}
-          >
-            {url}
-          </div>
-        ) : null}
+        {url ? <div data-ui="browser-frame-url">{url}</div> : null}
         {/* Right spacer to balance traffic lights */}
-        <div style={{ width: 54 }} aria-hidden="true" />
+        <div data-ui="browser-frame-spacer" aria-hidden="true" />
       </div>
 
       {/* Frame body */}
-      <div data-ui="browser-frame-body" style={{ position: 'relative', background: tokens.surfaces.surface }}>
-        {children}
-      </div>
+      <div data-ui="browser-frame-body">{children}</div>
     </div>
   );
 }
diff --git a/apps/website/src/components/ui/ClipPlayer.tsx b/apps/website/src/components/ui/ClipPlayer.tsx
index 1db1521e4..5834f6e4d 100644
--- a/apps/website/src/components/ui/ClipPlayer.tsx
+++ b/apps/website/src/components/ui/ClipPlayer.tsx
@@ -30,14 +30,7 @@ interface ClipPlayerProps {
 export function ClipPlayer({ clip, overlay, url }: ClipPlayerProps) {
   return (
     <BrowserFrame url={url ?? clip.url} elevation="lg">
-      <div
-        style={{
-          position: 'relative',
-          width: '100%',
-          aspectRatio: '16 / 10',
-          background: '#15161f',
-        }}
-      >
+      <div data-ui="clip-player">
         <video
           autoPlay
           muted
@@ -45,7 +38,6 @@ export function ClipPlayer({ clip, overlay, url }: ClipPlayerProps) {
           playsInline
           poster={clip.poster}
           aria-label={clip.caption}
-          style={{ width: '100%', height: '100%', objectFit: 'cover', display: 'block' }}
         >
           <source src={clip.videoWebm} type="video/webm" />
           <source src={clip.videoMp4} type="video/mp4" />
diff --git a/apps/website/src/components/ui/TabGroup.tsx b/apps/website/src/components/ui/TabGroup.tsx
index 629fc132a..ba5e7a651 100644
--- a/apps/website/src/components/ui/TabGroup.tsx
+++ b/apps/website/src/components/ui/TabGroup.tsx
@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: MIT
 'use client';
 import { useRef, useState, type KeyboardEvent as ReactKeyboardEvent, type ReactNode } from 'react';
-import { tokens } from '@threadplane/design-tokens';
 
 export interface TabPane {
   /** Unique within a group — used for React keys and DOM ids. */
@@ -76,13 +75,8 @@ export function TabGroup({ groupId, label, panes, onSelect }: TabGroupProps) {
   };
 
   return (
-    <div>
-      <div
-        role="tablist"
-        aria-label={label}
-        onKeyDown={onKeyDown}
-        style={{ display: 'flex', gap: 6, marginBottom: 12 }}
-      >
+    <div data-ui="tab-group">
+      <div data-ui="tab-group-list" role="tablist" aria-label={label} onKeyDown={onKeyDown}>
         {panes.map((pane, index) => {
           const selected = index === active;
           return (
@@ -92,23 +86,14 @@ export function TabGroup({ groupId, label, panes, onSelect }: TabGroupProps) {
                 tabRefs.current[index] = el;
               }}
               id={tabId(pane.id)}
+              data-ui="tab-group-tab"
+              data-active={selected || undefined}
               role="tab"
               type="button"
               aria-selected={selected}
               aria-controls={panelId(pane.id)}
               tabIndex={selected ? 0 : -1}
               onClick={() => select(index)}
-              style={{
-                fontFamily: 'Inter, sans-serif',
-                fontSize: 13,
-                fontWeight: 600,
-                padding: '8px 14px',
-                borderRadius: 8,
-                border: 'none',
-                cursor: 'pointer',
-                background: selected ? tokens.colors.accent : tokens.colors.accentSurface,
-                color: selected ? tokens.colors.textInverted : tokens.colors.textMuted,
-              }}
             >
               {pane.label}
             </button>
diff --git a/apps/website/src/styles/ui.css b/apps/website/src/styles/ui.css
index 1067332eb..1e83fbfa7 100644
--- a/apps/website/src/styles/ui.css
+++ b/apps/website/src/styles/ui.css
@@ -253,3 +253,112 @@
 [data-ui="logo-mark"][data-size="md"] > [data-ui="logo-mark-icon"] {
   font-size: 22px;
 }
+
+/* UI primitive — BrowserFrame.
+ * `transform` (rotate) and `max-width` are genuinely dynamic (unbounded
+ * caller props) and stay inline — see components/ui/BrowserFrame.tsx. */
+[data-ui="browser-frame"] {
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-lg);
+  overflow: hidden;
+}
+[data-ui="browser-frame"][data-elevation="sm"] {
+  box-shadow: var(--shadow-sm);
+}
+[data-ui="browser-frame"][data-elevation="md"] {
+  box-shadow: var(--shadow-md);
+}
+[data-ui="browser-frame"][data-elevation="lg"] {
+  box-shadow: var(--shadow-lg);
+}
+[data-ui="browser-frame-titlebar"] {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 14px;
+  background: var(--color-surface-tinted);
+  border-bottom: 1px solid var(--color-border);
+}
+[data-ui="browser-frame-dots"] {
+  display: flex;
+  gap: 6px;
+}
+[data-ui="browser-frame-dots"] > span {
+  width: 12px;
+  height: 12px;
+  border-radius: var(--radius-full);
+}
+[data-ui="browser-frame-dots"] > span:nth-child(1) {
+  background: #FF5F57;
+}
+[data-ui="browser-frame-dots"] > span:nth-child(2) {
+  background: #FEBC2E;
+}
+[data-ui="browser-frame-dots"] > span:nth-child(3) {
+  background: #28C840;
+}
+[data-ui="browser-frame-url"] {
+  flex: 1;
+  text-align: center;
+  font-family: var(--font-mono);
+  font-size: 11px;
+  color: var(--color-text-muted);
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-sm);
+  padding: 4px 10px;
+  max-width: 360px;
+  margin: 0 auto;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+[data-ui="browser-frame-spacer"] {
+  width: 54px;
+}
+[data-ui="browser-frame-body"] {
+  position: relative;
+  background: var(--color-surface);
+}
+
+/* UI primitive — ClipPlayer */
+[data-ui="clip-player"] {
+  position: relative;
+  width: 100%;
+  aspect-ratio: 16 / 10;
+  background: #15161f;
+}
+[data-ui="clip-player"] > video {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  display: block;
+}
+
+/* UI primitive — TabGroup.
+ * `font-family: Inter, sans-serif` and `border-radius: 8px` are copied
+ * verbatim from the original inline literals — they are NOT the
+ * `--font-inter` / `--radius-md` tokens (which resolve to different
+ * fallback stacks / 10px respectively), so mapping them to those vars
+ * would be a value change, not a verbatim move. */
+[data-ui="tab-group-list"] {
+  display: flex;
+  gap: 6px;
+  margin-bottom: 12px;
+}
+[data-ui="tab-group-tab"] {
+  font-family: Inter, sans-serif;
+  font-size: 13px;
+  font-weight: 600;
+  padding: 8px 14px;
+  border-radius: 8px;
+  border: none;
+  cursor: pointer;
+  background: var(--color-accent-surface);
+  color: var(--color-text-muted);
+}
+[data-ui="tab-group-tab"][data-active] {
+  background: var(--color-accent);
+  color: var(--color-text-inverted);
+}

From ed813693e43cab23fcd711eb9ff8f5c7eb6a2458 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 29 Aug 2026 12:37:05 -0700
Subject: [PATCH 7/7] =?UTF-8?q?fix(website):=20font=20families=20stay=20ve?=
 =?UTF-8?q?rbatim=20literals=20=E2=80=94=20next/font=20shadows=20the=20tok?=
 =?UTF-8?q?en=20vars?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

layout.tsx loads fonts via next/font with variable names identical to the
theme.css font vars, so var(--font-inter) resolves to next/font's stack at
runtime, not tokens.typography.fontSans. The batch-1 migration onto the vars
changed Button's rendered font (widths shifted ~2.5px, measured by
computed-style diff against the pre-migration baseline). Sites whose inline
value was the raw stack keep it as a literal; Eyebrow, whose inline value was
already 'var(--font-mono)', keeps the var.

After this fix the baseline diff is 0 real changes across 143 elements x 26
properties (4 remaining diffs are the hero clip's lazy-mount heights).

Recorded as findings §10 and as a locked exception in the migration plan.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/next-env.d.ts                    |  2 +-
 apps/website/src/styles/ui.css                | 26 ++++++++++++++-----
 .../2026-08-29-docs-visual-review-findings.md | 25 ++++++++++++++++++
 ...-08-29-inline-style-substrate-migration.md | 11 ++++++++
 4 files changed, 57 insertions(+), 7 deletions(-)

diff --git a/apps/website/next-env.d.ts b/apps/website/next-env.d.ts
index fdbfe5258..c4b7818fb 100644
--- a/apps/website/next-env.d.ts
+++ b/apps/website/next-env.d.ts
@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./../../dist/apps/website/.next/types/routes.d.ts";
+import "./.next/dev/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
diff --git a/apps/website/src/styles/ui.css b/apps/website/src/styles/ui.css
index 1e83fbfa7..334b08d9d 100644
--- a/apps/website/src/styles/ui.css
+++ b/apps/website/src/styles/ui.css
@@ -95,12 +95,26 @@
   color: var(--color-angular-red);
 }
 
+/*
+ * FONT FAMILIES ARE VERBATIM LITERALS, NOT var(--font-*), on purpose.
+ *
+ * layout.tsx loads fonts via next/font, which SHADOWS --font-inter,
+ * --font-mono, and --font-garamond on <html> with its own stacks
+ * ("Inter Fallback" etc.). var(--font-inter) therefore resolves to the
+ * next/font value at runtime, NOT the theme.css token value — measured:
+ * migrating Button to the var changed its rendered font and shifted
+ * widths ~2.5px. Sites whose inline style was the raw token stack keep
+ * that stack verbatim; only sites that already used a
+ * `tokens.typography.*.family` value (which IS 'var(--font-*)') keep
+ * the var. Unifying fonts onto next/font is a real visual change that
+ * belongs to the polish arc, not this migration.
+ */
 /* UI primitive — Pill */
 [data-ui="pill"] {
   display: inline-flex;
   align-items: center;
   gap: 6px;
-  font-family: var(--font-mono);
+  font-family: "JetBrains Mono", monospace;
   font-size: 11px;
   font-weight: 500;
   padding: 4px 10px;
@@ -148,7 +162,7 @@
   align-items: center;
   justify-content: center;
   gap: 8px;
-  font-family: var(--font-inter);
+  font-family: Inter, system-ui, sans-serif;
   font-weight: 600;
   line-height: 1;
   border-radius: var(--radius-md);
@@ -209,7 +223,7 @@
   gap: 16px;
   padding: 20px 0;
   cursor: pointer;
-  font-family: var(--font-inter);
+  font-family: Inter, system-ui, sans-serif;
   font-size: 17px;
   font-weight: 600;
   color: var(--color-text-primary);
@@ -222,7 +236,7 @@
 }
 [data-ui="faq-item"] > div {
   padding-bottom: 20px;
-  font-family: var(--font-inter);
+  font-family: Inter, system-ui, sans-serif;
   font-size: 16px;
   line-height: 1.6;
   color: var(--color-text-secondary);
@@ -233,7 +247,7 @@
   display: inline-flex;
   align-items: center;
   gap: 8px;
-  font-family: var(--font-garamond);
+  font-family: "EB Garamond", Georgia, serif;
   font-weight: 700;
   color: var(--color-text-primary);
   line-height: 1;
@@ -301,7 +315,7 @@
 [data-ui="browser-frame-url"] {
   flex: 1;
   text-align: center;
-  font-family: var(--font-mono);
+  font-family: "JetBrains Mono", monospace;
   font-size: 11px;
   color: var(--color-text-muted);
   background: var(--color-surface);
diff --git a/docs/superpowers/audits/2026-08-29-docs-visual-review-findings.md b/docs/superpowers/audits/2026-08-29-docs-visual-review-findings.md
index f9c3351de..64f25018c 100644
--- a/docs/superpowers/audits/2026-08-29-docs-visual-review-findings.md
+++ b/docs/superpowers/audits/2026-08-29-docs-visual-review-findings.md
@@ -245,6 +245,31 @@ Consequences worth knowing:
 the `.shiki` rule would become live again if `keepBackground` were turned off.
 It belongs in the polish arc alongside the rest of the docs CSS work.
 
+## 10. next/font shadows the three token font vars
+
+Found during substrate-migration Batch 1 (2026-08-29), by computed-style diff.
+`layout.tsx` loads Inter, JetBrains Mono, and EB Garamond via next/font with
+`variable: '--font-inter'` etc. — the SAME custom-property names the design
+tokens' `theme.css` defines. next/font's `<html>`-level values win, so at
+runtime:
+
+| var | theme.css says | actually resolves to |
+|---|---|---|
+| `--font-inter` | `Inter, system-ui, sans-serif` | `Inter, "Inter Fallback"` (next/font) |
+| `--font-mono` | `"JetBrains Mono", monospace` | `"JetBrains Mono", "JetBrains Mono Fallback"` |
+| `--font-garamond` | `"EB Garamond", Georgia, serif` | `"EB Garamond", "EB Garamond Fallback"` |
+
+Consequences:
+
+- The token↔CSS parity guard is value-true against `theme.css` but
+  **runtime-false** for these three vars.
+- Components whose inline styles used the raw token stacks (`fontSans` etc.)
+  render a *different font stack* than components using `var(--font-*)` —
+  measured ~2.5px width differences on buttons. The site today is a mix.
+- Unifying everything onto the next/font vars (arguably the better end state —
+  size-adjusted fallbacks, no FOUT) is a **real visual change** and belongs to
+  the polish arc as its own decision, not to the migration.
+
 ---
 
 ## Reproducing
diff --git a/docs/superpowers/plans/2026-08-29-inline-style-substrate-migration.md b/docs/superpowers/plans/2026-08-29-inline-style-substrate-migration.md
index bb8321108..0cca8d46a 100644
--- a/docs/superpowers/plans/2026-08-29-inline-style-substrate-migration.md
+++ b/docs/superpowers/plans/2026-08-29-inline-style-substrate-migration.md
@@ -100,6 +100,17 @@ and this never bites.
    → `var(--text-h2)`, `tokens.space.sectionY` → `var(--spacing-section-y)`,
    `tokens.colors.accent` → `var(--color-accent)`, etc. `.family` values are
    already `var(--font-*)` strings — copy them through.
+
+   **⚠ EXCEPTION — the three font vars (found the hard way in Batch 1).**
+   `layout.tsx` loads fonts via next/font, which SHADOWS `--font-inter`,
+   `--font-mono`, and `--font-garamond` on `<html>` with its own stacks. So
+   `var(--font-inter)` resolves to next/font's value at runtime, NOT
+   `tokens.typography.fontSans` — migrating Button onto the var changed its
+   rendered font and shifted widths ~2.5px. Rule: a site whose inline value
+   was the **raw stack** (`fontSans`/`fontMono`/`fontSerif`) keeps that stack
+   as a **verbatim literal** in CSS; only sites already using a `.family`
+   value (which IS `'var(--font-*)'`) use the var. The rationale comment
+   lives at the top of `ui.css` — reference it, don't re-derive it.
 8. **Zero visual change.** Restyling urges get logged in the findings audit,
    not taken.