From a5ee5440c524f1a2dca8a0c8d726e4bb47b6f43c Mon Sep 17 00:00:00 2001
From: Adnaan Badr <badr.adnaan@gmail.com>
Date: Fri, 24 Jul 2026 05:27:09 +0000
Subject: [PATCH 1/5] M4 kickoff: expand house-style-on-brand-by-construction
 design (convention 9)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Expands the outline-only M4 into full phase blocks, informed by an Explore of
tinkerdown + lvt/components (2026-07-24). Operator decisions: spine-only, no
enforcement lint.

Re-scoped all three parts of the plan's filing ("component vocabulary +
enforceable house style, upstream lvt/components + tinkerdown"):
- TINKERDOWN-ONLY (like M3): tinkerdown consumes 1 of lvt/components' ~29
  components (datatable) and reimplements the rest natively. New components would
  be tinkerdown-local; upstream is opt-in for reuse, not a dependency.
- SPINE-ONLY: the verified in-grain gap is that style_guide is a
  declared-but-unconsumed config field and the design-token layer already exists
  but is duplicated + partial (4 consumed tokens never defined; fallbacks
  re-hardcoded per use). Component enrichment deferred (operator decision).
- NO ENFORCEMENT LINT: a "flag free-form HTML" lint fights tinkerdown's
  semantic-HTML-first / PicoCSS-classless model. The vision (guaranteed on-brand,
  no generic LLM aesthetic) is delivered by tokens-BY-CONSTRUCTION, not rejection
  — the mechanism was mis-specified, not the intent.

Two tinkerdown phases:
1. Design-token system — single-source the implicit :root token set (server.go),
   define the 4 undefined tokens, drop the per-use re-hardcoded fallbacks, drive
   from a tokens config. Semantic HTML + PicoCSS then renders on-brand by
   construction.
2. Wire the house style into generation — the skill consumes the manifest's
   style_guide + a token summary (closing the unconsumed-field gap); style block
   stays optional (default tokens skin the page).

Roadmap, gap-row-4, deliverables, house-style-gap section, and headers updated in
step; M5 remains outline-only.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018M9pJSPmG6i1D8s6rpEV4h
---
 docs/plans/2026-07-09-ephemeral-ui-reframe.md | 86 +++++++++++++++++--
 1 file changed, 77 insertions(+), 9 deletions(-)

diff --git a/docs/plans/2026-07-09-ephemeral-ui-reframe.md b/docs/plans/2026-07-09-ephemeral-ui-reframe.md
index 7f621c6..14a2689 100644
--- a/docs/plans/2026-07-09-ephemeral-ui-reframe.md
+++ b/docs/plans/2026-07-09-ephemeral-ui-reframe.md
@@ -21,7 +21,7 @@ What this reframe ships, most-important first. **M1 is the headline** (makes the
 
 **M0 — foundation:** repositioned narrative (README/SKILL/llms.txt) + upstream version bump to latest (`livetemplate` v0.10→latest, client, components).
 
-**M2–M5 — hardening:** `livetemplate.Validate()` API + policy lint *(M2, upstream + tinkerdown)* · runtime approved-surface enforcement *(M3, tinkerdown; field-name validation deferred — needs a schema source)* · richer `lvt/components` + enforceable design-token style guide *(M4)* · save/share gallery (stores captured skills) + external-embed handshake *(M5)*.
+**M2–M5 — hardening:** `livetemplate.Validate()` API + policy lint *(M2, upstream + tinkerdown)* · runtime approved-surface enforcement *(M3, tinkerdown; field-name validation deferred — needs a schema source)* · house style on-brand by construction — formalized design tokens + wired `style_guide` *(M4, tinkerdown; no lint)* · save/share gallery (stores captured skills) + external-embed handshake *(M5)*.
 
 ---
 
@@ -92,7 +92,7 @@ The brief names four things a team defines once so LLMs can safely generate agai
 
 **How the plan threads the UX style guide:**
 - **M1 (this milestone) — make house style LLM-consumable, coarse enforcement.** The manifest's style block = `theme` + `site_css` **plus a short `style-guide.md`** (house tone, layout conventions, which `lvt/components` to prefer, do/don't) that the `/tinkerdown` skill injects into its generation context so output conforms by construction. **The whole style block is optional** — with none, generation falls back to tinkerdown's sane defaults (PicoCSS semantic styling + default theme), so a team can adopt generation with zero style setup and add house style later. Enforcement in M1 is coarse (the shared `site_css` skins every generated page; the visual-conformance check in Phase 5). *This is a conscious M1 scope: consume the style guide, don't yet mechanically enforce tokens.*
-- **M4 — elevate to an enforceable spec.** Alongside the `lvt/components` enrichment, promote house style to **design tokens + an enforced component set** (the real "style guide object" the exploration found missing), so generated UIs can't drift off-brand even without a careful prompt.
+- **M4 — make house style on-brand by construction** *(re-scoped at kickoff 2026-07-24; see § M4 phases).* Formalize the design-token layer that already exists implicitly (single-source it, define the four undefined tokens, drive it from a `tokens` config) and **wire the declared-but-unconsumed `style_guide`** into generation, so generated UIs can't drift off-brand even without a careful prompt — delivered by **tokens, not an enforced-component lint** (that fights tinkerdown's semantic-HTML-first model; component enrichment deferred).
 
 ---
 
@@ -108,7 +108,7 @@ The brief names four things a team defines once so LLMs can safely generate agai
 | 1 | Generated docs get only a *plain* parse error; the structured, line-numbered parse/reactive-AST diagnostics live in `livetemplate/internal/parse` (unreachable downstream) and the public render path *swallows* them. Allowed-tags, bound-refs and action-param are tinkerdown-owned semantics livetemplate can't see. | **Split** (kickoff 2026-07-23): `livetemplate.Validate(templateText)` exposes the structured parse/AST diagnostics + optional render-determinism [server]; allowlist / bound-refs / action-param stay in tinkerdown `validate` | Deterministic first-pass correctness | **M2** |
 | 2 | No **field-name validation**: a misspelled `{{.Field}}` renders empty. (Action-name/`describes:` metadata already exists in `config.Summarize`.) | **Deferred** (M3 kickoff 2026-07-24): needs a *validate-time schema source* tinkerdown lacks — schema lives only in the runtime DB (gitignored, seed-built). Real fix = parse `CREATE TABLE` from a seed, or a declared `columns:` schema — a new introspection capability, not a lint. | `validate` catches a bad field before serve | **Deferred** (§ Risks) |
 | 3 | Runtime enforcement is generation-time only; a webhook / bypassing caller can invoke outside the approved surface (three action paths, no shared gate) | **Tinkerdown** policy gate at all three paths (kickoff 2026-07-24: an upstream `WithActionPolicy` is dead code — tinkerdown never uses livetemplate dispatch) | Runtime safety (defense in depth) | **M3** |
-| 4 | Primitive library too thin (no charts, badges, cards, stat tiles, alerts, empty-states) | Enrich `lvt/components` [components] | "LLMs rarely need custom HTML" | **M4** |
+| 4 | House style can't be guaranteed on-brand: the design-token layer is duplicated/partial + `style_guide` is a declared-but-unconsumed config field. (The `lvt/components` library is deep — ~29 components — but tinkerdown uses 1; enrichment is optional, not the gap.) | **Tinkerdown** (kickoff 2026-07-24): formalize the tokens + wire `style_guide` into generation — on-brand by construction, no lint | Guaranteed on-brand, no generic LLM aesthetic | **M4** |
 | 5 | External-app embedding is iframe-bridge only | Embed handshake [client] | Sandboxed external embeds | **M5** |
 | 6 | Generation→validate→serve **orchestration** | **Legitimately tinkerdown** (all 3 exploration agents concur) | The skill itself | **M1** |
 
@@ -187,13 +187,13 @@ All follow the Anthropic skill shape already used by `skills/tinkerdown/` (conci
 
 ## Roadmap
 
-Ordered milestones. **M0, M1, M2 and M3 are fully detailed** (full phase blocks); M4–M5 are outline-only and get expanded at their kickoff (see LLM session guide convention 9).
+Ordered milestones. **M0, M1, M2, M3 and M4 are fully detailed** (full phase blocks); M5 is outline-only and gets expanded at its kickoff (see LLM session guide convention 9).
 
 - **M0 — Reframe + upstream bump + a trustworthy vocabulary.** Reposition the narrative (README/SKILL/llms.txt/ai-generation) around ephemeral generated UIs; **bump `livetemplate` + client + components to their latest tags** and absorb behavior changes; **reconcile the `lvt-*` attribute reference with what the client actually implements** (Phase 2 — added after Phase 1's Audit found 8 of 11 sampled attributes stale). *Lights up:* the fast, correct runtime substrate, the honest story, and a vocabulary reference that is safe to hand an LLM — the last being a hard prerequisite for M1, not polish. *(no demo yet)*
 - **M1 — THE DEMO (thin vertical slice).** The five M1 deliverables (see § Deliverables at a glance) on existing primitives. *Lights up:* the target acceptance test — generate a real, friction-removing UI in ~30s — *and* re-run it from a skill in seconds.
 - **M2 — Deterministic validation (upstream `Validate()` + tinkerdown lint).** `livetemplate.Validate(templateText)` exposes the **structured, line-numbered parse / reactive-AST diagnostics** that today live in livetemplate's `internal/parse` (unreachable downstream) and that its public render path silently *swallows* — plus an optional render-determinism check. tinkerdown's `validate` consumes it per lvt block and adds the **tinkerdown-owned** semantic checks livetemplate cannot see: **bound-refs** (a used `lvt-source` must resolve to a declared source), **action-param completeness**, a **state-ref diagnostic that teaches the real `lvt-source` fix**, and the **`lvt-persist`→removed-with-migration** cleanup. *Lights up:* first-pass generation reliability — richer diagnostics for the skill's self-correct loop, and the "validates clean but breaks at serve" gaps M1 kept hitting closed at the gate. *(The attribute allowlist stays in tinkerdown, guarded against the vendored client bundle — livetemplate-Go can't own it, as it never references the client-only `lvt-mod:`/`lvt-nav:`/`lvt-ignore` namespaces. Design expanded at kickoff 2026-07-23 — see § M2 design.)*
 - **M3 — Runtime approved-surface enforcement (tinkerdown).** A server-side policy gate at all three action paths (WS-custom, webhook, builtins) so a running app — or a webhook / crafted-message caller — may only invoke **approved** actions against **approved** sources, respecting readonly: defense-in-depth beyond the *generation-time* lint. *Lights up:* the running app can't exceed the approved surface — the server-side gate `confirm:` never was. *(Kickoff 2026-07-24 re-scoped this **tinkerdown-only** — the planned upstream `WithActionPolicy` would be dead code for tinkerdown, which never routes actions through livetemplate. **Field-name validation was de-scoped** — it needs a validate-time schema source tinkerdown lacks; see § M3 phases and § Risks.)*
-- **M4 — Component vocabulary + enforceable house style (upstream `lvt/components` + tinkerdown).** Charts, badges, cards, stat tiles, alerts, empty-states; **plus** promoting the UX style guide from coarse (`site_css` + `style-guide.md`) to **design tokens + an enforced component set** (the "style guide object" the exploration found missing). *Lights up:* richer generated dashboards with no free-form HTML, guaranteed on-brand.
+- **M4 — House style on-brand by construction (tinkerdown).** Formalize the design-token layer that already exists implicitly (single-source it, define the four undefined tokens, drive it from a `tokens` config) so semantic HTML + PicoCSS renders on-brand **by construction**; and wire the **declared-but-unconsumed** `style_guide` into the generation context. *Lights up:* guaranteed on-brand generated UIs — no generic LLM aesthetic — via tokens, not a rejecting lint. *(Kickoff 2026-07-24 re-scoped this **tinkerdown-only** [tinkerdown consumes 1 of `lvt/components`' ~29 components], **spine-only** [component enrichment deferred, operator decision], and **no enforcement lint** [it fights semantic-HTML-first]; see § M4 phases.)*
 - **M5 — Persist to the malleable substrate (save & share).** This is where **malleability lives**: persist a generated UI to the repo + a gallery + share link by storing the captured **skill** (per convention 13 / M1 Phase 6), not just the `app.md` — so "save" means a re-runnable workflow you evolve, while individual UIs stay ephemeral; plus **substrate extensibility** (teams can add their own approved source types) and the external-app embed handshake. *Lights up:* "throw away the UI, keep + reshape the substrate" (folds issues #223 host read-only apps, #282 review mode, #249 external embed, #216 writable WASM sources, #222 custom Go+WASM sources).
 
 **Open-issue walkthrough.** Triaged into three buckets against this reframe. *(Counts drift: **48 open** at plan authoring, **82** by 2026-07-19 — the repo files `from-review` issues continuously. The named issue→milestone mappings below stay valid; **re-run the triage at M0 kickoff** rather than trusting the totals, same as the version pins.)*
@@ -1002,12 +1002,80 @@ type Diagnostic struct {
 
 ---
 
-### M4–M5 phases — outline only (expanded at milestone kickoff per convention 9)
+### M4 phases — house style on-brand by construction (expanded at kickoff 2026-07-24, per convention 9)
 
-The *what* + *why* of each is in § Roadmap; here is only each milestone's **kickoff design checklist** — the sections to write into full phase blocks when that milestone starts (per convention 9):
+> **Milestone shape (settled at kickoff):** **tinkerdown-only, spine-scoped, no enforcement lint** (operator decision 2026-07-24). The plan filed M4 as "component vocabulary + enforceable house style (upstream `lvt/components` + tinkerdown)"; a direct read (Explore 2026-07-24) reshaped all three parts:
+> - **Tinkerdown-only** (like M3). tinkerdown consumes **exactly one** of `lvt/components`' ~29 components (datatable) and reimplements the rest natively (charts/tabs/status-banners as parser transforms; accordion as raw `<details>`). New components would be tinkerdown-local by default; upstream is opt-in for *reuse*, at a cross-module release cost — not a dependency.
+> - **Spine-scoped.** The verified, in-grain gap is *not* "no components" — it is that `style_guide` is a **declared-but-unconsumed config field** (`GenerationConfig.StyleGuide`, no runtime reader) and the design-token layer already exists but is **duplicated + partial**. M4 builds outward from that; component enrichment is deferred (operator chose spine-only).
+> - **No enforcement lint.** M4 as filed promised "no free-form HTML." A validate lint that rejects hand-written HTML where a component exists fights tinkerdown's core model (semantic-HTML-first, PicoCSS-classless — the "no CSS classes needed" selling point; the FAQ example uses raw `<details>` deliberately). **The vision (guaranteed on-brand, no generic LLM aesthetic) is delivered by tokens-by-construction, not by rejection** — the mechanism was mis-specified, not the intent.
 
-*(M2 and M3 were expanded to full phase blocks at kickoff — see § M2 phases and § M3 phases above. The M3 upstream `WithActionPolicy` hook was dropped as dead code for tinkerdown; a livetemplate-side hook for its own consumers is separable framework work, not tinkerdown's M3.)*
-- **M4** (upstream `lvt/components` + tinkerdown): the component list + options; how the skill's reference advertises them; the design-token/enforced-component style-guide schema.
+**Kickoff Audit findings (Explore of tinkerdown + `lvt/components`, 2026-07-24):**
+
+- **A real token set already exists — implicit, duplicated, partial.** `server.go:1196-1234` defines `:root` + `[data-theme="dark"]` with ~12 custom properties (`--bg-*`, `--text-*`, `--border-color`, `--card-*`, `--accent`) + `--pico-*` overrides. The client CSS consumes them **with the fallback literal re-hardcoded at every use site** (`var(--accent, #0066cc)` in dozens of places), and four consumed tokens (`--bg-hover`, `--badge-bg`, `--highlight-bg`, `--hover-bg`) are **never defined**. M4-Phase-1 is **extract/dedupe/wire this existing set**, not greenfield.
+- **The only author knobs into the token layer are `primary_color` (→ `--accent`) and `font`.** `StylingConfig` (`config.go:676-693`) = `theme`/`primary_color`/`font`/`site_css`/`custom_css`; `theme` maps name→light/dark/auto (`styling.go`, "clean"=light, "minimal" unrecognized→auto). No colors/spacing/typography schema.
+- **`style_guide` is wired to nothing.** `GenerationConfig.StyleGuide` (`config.go:181`) is documented "injected into the generation context" but has **no runtime consumer** — `SKILL.md`/`reference.md` never mention style/tokens; no command marshals it. So "`site_css` + a `style-guide.md`" overstates reality: `site_css` is wired, the style-guide half is a dead field. M4-Phase-2 builds the first style-guide pipeline.
+- **PicoCSS is the classless substrate.** Embedded (`assets.go:22`), applied to semantic HTML; the one upstream component (datatable) renders class-less because tinkerdown imports no style adapter, so `.Styles.X` is empty → `<table class="">` → PicoCSS skins it. The token layer sits on top of this — that is why tokens (not classes) are the right on-brand lever.
+
+#### Phase 1 (M4, tinkerdown) — Design-token system: on-brand by construction (~1 session)
+
+> **Goal at end:** the design tokens the page already renders against become a **formalized, complete, single-sourced schema driven from config** — every consumed token defined (the four currently-undefined ones included), the re-hardcoded per-use fallbacks removed, and a team able to set its palette once. Semantic HTML + PicoCSS then renders on-brand **by construction**, no prompt and no lint required.
+
+**Design refs:**
+- § house-style gap · § M4 design (the token-inventory finding)
+- tinkerdown `internal/server/server.go:1196-1234` (the `:root`/`[data-theme="dark"]` block + its `<head>` injection at `:3121`), `internal/styling/styling.go` (`buildStylingOverrideCSS` — `theme`→light/dark, `primary_color`→`--accent`, `font`), `internal/config/config.go:676-693` (`StylingConfig`), `internal/assets/client/tinkerdown-client.browser.css` (token consumers + the re-hardcoded fallbacks + the undefined `--bg-hover`/`--badge-bg`/`--highlight-bg`/`--hover-bg`)
+
+**Audit (first task):**
+- [ ] **Design-ref completeness check.**
+- [ ] Inventory the full **consumed** token set (grep `var(--` across the client CSS) vs the **defined** set (`server.go:1196-1234`); list the four undefined tokens + everywhere a fallback literal is re-hardcoded. That diff *is* the work.
+- [ ] Design the **token schema**: the semantic set the client already consumes (colors: `--bg-*`, `--text-*`, `--border-color`, `--accent`, `--card-*`, `--code-bg`/`--pre-bg`, + the four undefined), single-sourced in `:root`/`[data-theme=dark]`. Decide the **config surface**: extend `StylingConfig` with a `tokens` block (a team sets values once → drives `:root`), with `theme`/`primary_color`/`font` kept as shortcuts (presets).
+- [ ] Confirm this is **structural** (skins the page regardless of the prompt) — distinct from Phase 2's generation-context wiring.
+
+**Implementation:**
+- [ ] Single-source the token layer: define **all** consumed tokens (add the four undefined) in one `:root`/`[data-theme=dark]` block; remove the per-use re-hardcoded fallbacks in the client CSS (or reduce to one authoritative fallback).
+- [ ] Extend `StylingConfig` with a `tokens` config that sets the `:root` values; `theme`/`primary_color`/`font` remain shortcuts. Default tokens = today's values (no visual change with no config).
+- [ ] `CHANGELOG.md`.
+
+**Acceptance criteria:**
+- [ ] **Simplify:** `/simplify` the diff.
+- [ ] **Unit:** no consumed-but-undefined token remains (a test that fails if the client CSS references a `var(--x)` not defined in the `:root` block); a custom `tokens` config yields the expected `:root` CSS; `theme`/`primary_color` shortcuts drive the right tokens.
+- [ ] **Integration:** the `examples/` corpus renders unchanged under defaults (no style regression — the default token values equal today's).
+- [ ] **E2E (chromedp, four-channel):** a page with a custom `tokens` config renders on-brand — assert the computed CSS custom properties (accent/card/bg) match the config, and screenshot; the default page renders with the default tokens.
+
+**Learn:** what surprised us / plan drift / feed-forward to Phase 2's Audit / new-or-changed risks.
+
+#### Phase 2 (M4, tinkerdown) — Wire the house style into the generation context (~1 session)
+
+> **Goal at end:** the `/tinkerdown` skill **consumes** the manifest's `style_guide` + a summary of the token schema, so generated UIs are authored against the house style — closing the declared-but-unconsumed gap (`style_guide` is a config field the skill never reads). The style block stays **optional**: with none, Phase 1's default tokens already skin the page on-brand.
+
+**Design refs:**
+- Phase 1 (the token schema) · § house-style gap (the style block = `theme` + `site_css` + `style-guide.md`, all optional)
+- tinkerdown `internal/config/config.go:181` (`GenerationConfig.StyleGuide` — unconsumed), `skills/tinkerdown/SKILL.md` + `reference.md` (the generation context; today advertise only the `lvt-*` vocabulary + "datatable, dropdown")
+
+**Audit (first task):**
+- [ ] **Design-ref completeness check.**
+- [ ] Confirm `style_guide` has no runtime consumer (Explore verified). Decide the read path: the skill loads the manifest's `style_guide` (a `style-guide.md` path) + a **token summary** (the available tokens/theme) and injects both into the generation context.
+- [ ] Decide whether a command surfaces the style guide to the skill (like `validate --summary` for operations) or the skill reads the manifest directly — prefer the smallest that lets the skill see the house style deterministically.
+- [ ] Pin the guidance: generated UIs use **semantic HTML** (skinned on-brand by the tokens) + the house `style-guide.md` patterns, and **do not hardcode colors** (use the tokens) — the anti-off-brand rule, delivered as guidance + tokens, not a lint.
+
+**Implementation:**
+- [ ] `SKILL.md` (+ `reference.md` if needed): load + inject the manifest's `style_guide` + token summary; add the "semantic HTML + tokens, don't hardcode colors, follow the style-guide" guidance. Keep the style block optional (absent → default tokens).
+- [ ] `CHANGELOG.md`.
+
+**Acceptance criteria:**
+- [ ] **Simplify:** prose + asset pass.
+- [ ] **Unit/structural:** a test asserting the skill wires the `style_guide` (mirror `skill_examples_test.go`); the style-guide reference resolves.
+- [ ] **Integration:** a manifest with a `style_guide` → the skill's generation context includes it + the token summary (verifiable deterministically).
+- [ ] **E2E:** N/A (generation-context, as with M1 Phase 3) — the on-brand *rendering* guarantee is Phase 1's tokens (structural); this phase's deliverable is that the skill *sees* the house style, verified by the structural/integration test.
+
+**Learn:** what surprised us / plan drift / feed-forward to **M5**'s Audit / new-or-changed risks.
+
+---
+
+### M5 phases — outline only (expanded at milestone kickoff per convention 9)
+
+The *what* + *why* of each is in § Roadmap; here is only the milestone's **kickoff design checklist** — the sections to write into full phase blocks when it starts (per convention 9):
+
+*(M2, M3, M4 were expanded to full phase blocks at kickoff — see § M2/M3/M4 phases above. Re-scopes recorded there: M3's upstream `WithActionPolicy` dropped as dead code + field-name validation deferred; M4 re-scoped tinkerdown-only, spine-only, no enforcement lint — the on-brand vision delivered by tokens, not rejection.)*
 - **M5** (tinkerdown + `client`): the persistence model (stores captured *skills*, not just `app.md`); gallery UX; the external-embed handshake protocol; **substrate extensibility** — writable WASM sources (#216) + custom Go+WASM source types (#222), and how a team-authored source enters the *approved* set.
 
 #### Standing Audit item for milestones that bump `@livetemplate/client` (M2, M5) — artifact provenance

From 3821012738911fd00ca5dc48b2be77e94d342d53 Mon Sep 17 00:00:00 2001
From: Adnaan Badr <badr.adnaan@gmail.com>
Date: Fri, 24 Jul 2026 06:28:44 +0000
Subject: [PATCH 2/5] =?UTF-8?q?feat(styling):=20declarative=20design=20tok?=
 =?UTF-8?q?ens=20(styling.tokens)=20=E2=80=94=20M4=20Phase=201?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A project can set its on-brand page-shell palette once via `styling.tokens`
in tinkerdown.yaml — snake_case keys (accent, card_bg, …) mapped to the CSS
custom properties they drive in every page's :root, overriding the built-in
default through the same mechanism primary_color already uses for --accent.
Generated UIs are on-brand by construction, not by careful prompting.

- StylingConfig.Tokens + KnownStyleTokens (14 page-shell tokens) +
  ValidateStyleTokens() wired into Load — an unknown key fails loudly at
  config load (names the key, lists the known set); absent, built-in defaults
  apply (backward-compatible).
- buildStylingOverrideCSS emits a sorted, CSS-injection-sanitized
  :root { --token: value } block, after the primary_color block so an
  explicit tokens.accent wins by source order (the two :root blocks must stay
  separate — precedence is load-bearing).
- Unit: emission + sanitization (server); round-trip, fail-loud typo,
  backward-compat, map↔validator drift (config).
- E2E (four-channel): getComputedStyle proves the override reaches pixels
  through the real cascade (#ff00ff), not just emitted <style> text; an
  unconfigured site keeps the default (#007bff = DefaultConfig.PrimaryColor).

Scope (settled at M4 kickoff, advisor-confirmed): page-shell palette IN; the
generated client-chrome CSS (search/tabs re-hardcoded fallbacks + the four
undefined tokens) is OUT — internal chrome, never author-facing house style,
and hand-editing a generated/minified artifact is the #295 provenance trap.
Token overrides are single-value across both themes, like primary_color.

Plan Phase-1 block rewritten from the pre-kickoff full scope to the shipped
spine + Learn recorded (drift fixed in this commit).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018M9pJSPmG6i1D8s6rpEV4h
---
 CHANGELOG.md                                  |  16 +++
 docs/plans/2026-07-09-ephemeral-ui-reframe.md |  32 +++--
 internal/config/config.go                     |  52 +++++++
 internal/config/style_tokens_test.go          |  88 ++++++++++++
 internal/server/styling.go                    |  35 ++++-
 internal/server/styling_test.go               |  23 +++
 styling_tokens_e2e_test.go                    | 134 ++++++++++++++++++
 7 files changed, 363 insertions(+), 17 deletions(-)
 create mode 100644 internal/config/style_tokens_test.go
 create mode 100644 styling_tokens_e2e_test.go

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9af207e..ee373d4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,22 @@ Earlier releases (v0.1.x) are documented in the
 
 ## [Unreleased]
 
+### Added — declarative design tokens (`styling.tokens`)
+
+A project can now set its on-brand palette declaratively, without writing raw
+CSS. `styling.tokens` in `tinkerdown.yaml` maps snake_case design-token names to
+values — e.g. `accent: "#5a67d8"`, `card_bg: "#ffffff"` — and each drives the
+matching CSS custom property (`--accent`, `--card-bg`, …) in every page's
+`:root`, overriding the built-in default via the same mechanism `primary_color`
+already uses for `--accent`. Because the override skins the *semantic* HTML the
+generator emits, a generated UI is on-brand by construction rather than by
+careful prompting. An unknown token key fails loudly at config load (naming the
+key and listing the known tokens) so a typo can't silently skin nothing; token
+values are sanitized against CSS-injection at render. Absent, built-in defaults
+apply — existing projects are unaffected. A token override is a single value that
+applies to **both** light and dark themes (same as `primary_color`); per-theme
+palettes are not yet expressible.
+
 ### Added — runtime approved-surface enforcement
 
 When a project declares a `generation:` block, Tinkerdown now enforces the
diff --git a/docs/plans/2026-07-09-ephemeral-ui-reframe.md b/docs/plans/2026-07-09-ephemeral-ui-reframe.md
index 14a2689..35ca530 100644
--- a/docs/plans/2026-07-09-ephemeral-ui-reframe.md
+++ b/docs/plans/2026-07-09-ephemeral-ui-reframe.md
@@ -1018,30 +1018,34 @@ type Diagnostic struct {
 
 #### Phase 1 (M4, tinkerdown) — Design-token system: on-brand by construction (~1 session)
 
-> **Goal at end:** the design tokens the page already renders against become a **formalized, complete, single-sourced schema driven from config** — every consumed token defined (the four currently-undefined ones included), the re-hardcoded per-use fallbacks removed, and a team able to set its palette once. Semantic HTML + PicoCSS then renders on-brand **by construction**, no prompt and no lint required.
+> **Goal at end:** a team can set its on-brand **page-shell palette** once, declaratively, via a `styling.tokens` config block — each token driving the matching CSS custom property in every page's `:root`, overriding the built-in default through the **same mechanism `primary_color` already uses for `--accent`**. Semantic HTML + PicoCSS then renders on-brand **by construction**, no prompt and no lint required.
 
 **Design refs:**
 - § house-style gap · § M4 design (the token-inventory finding)
-- tinkerdown `internal/server/server.go:1196-1234` (the `:root`/`[data-theme="dark"]` block + its `<head>` injection at `:3121`), `internal/styling/styling.go` (`buildStylingOverrideCSS` — `theme`→light/dark, `primary_color`→`--accent`, `font`), `internal/config/config.go:676-693` (`StylingConfig`), `internal/assets/client/tinkerdown-client.browser.css` (token consumers + the re-hardcoded fallbacks + the undefined `--bg-hover`/`--badge-bg`/`--highlight-bg`/`--hover-bg`)
+- tinkerdown `internal/server/server.go:1196-1234` (the `:root`/`[data-theme="dark"]` block — the 14 author-facing page-shell tokens — + its `<head>` injection at `:3121`), `internal/server/styling.go` (`buildStylingOverrideCSS` — `theme`→light/dark, `primary_color`→`--accent`, `font`; and now `tokens`), `internal/config/config.go` (`StylingConfig`)
 
 **Audit (first task):**
-- [ ] **Design-ref completeness check.**
-- [ ] Inventory the full **consumed** token set (grep `var(--` across the client CSS) vs the **defined** set (`server.go:1196-1234`); list the four undefined tokens + everywhere a fallback literal is re-hardcoded. That diff *is* the work.
-- [ ] Design the **token schema**: the semantic set the client already consumes (colors: `--bg-*`, `--text-*`, `--border-color`, `--accent`, `--card-*`, `--code-bg`/`--pre-bg`, + the four undefined), single-sourced in `:root`/`[data-theme=dark]`. Decide the **config surface**: extend `StylingConfig` with a `tokens` block (a team sets values once → drives `:root`), with `theme`/`primary_color`/`font` kept as shortcuts (presets).
-- [ ] Confirm this is **structural** (skins the page regardless of the prompt) — distinct from Phase 2's generation-context wiring.
+- [x] **Design-ref completeness check** — corrected the styling path (`internal/server/styling.go`, not `internal/styling/`).
+- [x] **Scope split settled (advisor-confirmed): page-shell palette IN, client-chrome CSS OUT.** The inventory found two distinct token layers. (1) The **page-shell** palette — `server.go:1196-1234`'s `:root` (`--bg-*`, `--text-*`, `--border-color`, `--card-*`, `--code-bg`/`--pre-bg`, `--accent`) — is author-facing house style; **this is Phase 1's scope.** (2) The re-hardcoded `var(--x, literal)` fallbacks and the four undefined tokens (`--bg-hover`/`--badge-bg`/`--highlight-bg`/`--hover-bg`) live **only in `internal/assets/client/tinkerdown-client.browser.css`** — a *generated, minified* artifact (built from `client/src` via esbuild) skinning internal client **chrome** (toc/tabs/search), never author-facing. Hand-editing it is the #295 provenance trap, and a "consumed-but-undefined token" lint over generated CSS is a self-certifying guard. So that half is **EXCLUDED from M4** (not deferred — it was never house style), matching the milestone's **no-lint** shape.
+- [x] Config surface: extend `StylingConfig` with a `tokens` map (snake_case key → value); `primary_color`/`font` stay as shortcuts. An unknown key is a config **error** (fail-loud at load), not a silent skip.
 
 **Implementation:**
-- [ ] Single-source the token layer: define **all** consumed tokens (add the four undefined) in one `:root`/`[data-theme=dark]` block; remove the per-use re-hardcoded fallbacks in the client CSS (or reduce to one authoritative fallback).
-- [ ] Extend `StylingConfig` with a `tokens` config that sets the `:root` values; `theme`/`primary_color`/`font` remain shortcuts. Default tokens = today's values (no visual change with no config).
-- [ ] `CHANGELOG.md`.
+- [x] `StylingConfig.Tokens map[string]string` + `KnownStyleTokens` (the 14 page-shell keys → CSS custom properties) + `ValidateStyleTokens()`, wired into `config.Load` so a typo fails loudly (names the key, lists the known set). Absent → empty map, no behavior change (backward-compatible).
+- [x] `buildStylingOverrideCSS` emits a `:root { --token: value; … }` block from `styling.tokens`, in deterministic key order, values run through `sanitizeCSSValue` (CSS-injection defense). Emitted **after** the `primary_color` block, so an explicit `tokens.accent` wins over the defaulted `primary_color` (source-order precedence — load-bearing; the two `:root` blocks must stay separate).
+- [x] `CHANGELOG.md`.
 
 **Acceptance criteria:**
-- [ ] **Simplify:** `/simplify` the diff.
-- [ ] **Unit:** no consumed-but-undefined token remains (a test that fails if the client CSS references a `var(--x)` not defined in the `:root` block); a custom `tokens` config yields the expected `:root` CSS; `theme`/`primary_color` shortcuts drive the right tokens.
-- [ ] **Integration:** the `examples/` corpus renders unchanged under defaults (no style regression — the default token values equal today's).
-- [ ] **E2E (chromedp, four-channel):** a page with a custom `tokens` config renders on-brand — assert the computed CSS custom properties (accent/card/bg) match the config, and screenshot; the default page renders with the default tokens.
+- [x] **Simplify:** `/simplify` the diff — code-simplifier found it already minimal (no edits); confirmed the two-`:root`-block ordering is load-bearing, not churn.
+- [x] **Unit:** `TestBuildStylingOverrideCSS_Tokens`/`_TokensSanitized` (styling); `TestLoad_StylingTokens`, `_UnknownKeyRejected`, `_DefaultsEmpty`, `TestValidateStyleTokens_AllKnownKeysAccepted` (config-load: round-trip, fail-loud typo, backward-compat, map↔validator drift guard).
+- [x] **Integration:** the `examples/` corpus renders unchanged under defaults **by construction** — the token block is emitted only when `styling.tokens` is non-empty, so a no-tokens config produces byte-identical output; full suite green confirms no corpus regression.
+- [x] **E2E (chromedp, four-channel):** `TestStylingTokensComputedStyle` — a `tokens.accent: #ff00ff` + `card_bg: #00ff00` config produces exactly those **computed** `getComputedStyle(...).getPropertyValue()` values (through the real cascade, not just emitted `<style>` text); an unconfigured site keeps the default `#007bff`. Screenshot + four-channel capture wired.
 
-**Learn:** what surprised us / plan drift / feed-forward to Phase 2's Audit / new-or-changed risks.
+**Learn:**
+- **What surprised us.** The "effective default" `--accent` is **`#007bff` (`DefaultConfig.PrimaryColor`), not `#0066cc` (the page-shell `:root`)** — every loaded config emits a `primary_color` override, so the shell literal is never the computed value. The control assertion had to pin `#007bff`. This *also* validated the emission order: `tokens.accent` beating the defaulted `primary_color` proves the token block is emitted second and wins the cascade.
+- **Plan drift fixed in this commit.** This Phase 1 block still carried the pre-kickoff full scope (remove client-CSS fallbacks, define the four undefined tokens, a consumed-but-undefined lint) though the milestone-shape section was re-scoped to spine-only/no-lint at kickoff. Rewrote Goal/Design-refs/Audit/Implementation/Acceptance to the shipped spine + recorded the page-shell-IN / client-chrome-OUT split. Corrected the `internal/styling/` → `internal/server/styling.go` path.
+- **Feed-forward to Phase 2's Audit.** The token *names* the generator should be told about = `KnownStyleTokens`' 14 keys (the single source of truth for the palette summary Phase 2 wires into generation). Phase 2 reads `GenerationConfig.StyleGuide` (still declared-but-unconsumed) **plus** a summary derived from `KnownStyleTokens` — don't re-enumerate tokens by hand.
+- **New/changed risks.** None new. The excluded client-chrome tokens (`--bg-hover` et al.) remain undefined-but-consumed in the generated CSS; that is a pre-existing client-side condition, out of tinkerdown's house-style scope, and untouched here. Verified they are consumed **only** in `client/src/core/{search,tabs}.css` (search-result badge, tab hover) — chrome, never generated content — so the exclusion is sound.
+- **Known limitation (single-value, not per-theme).** A `tokens` override is one value applied to **both** light and dark (its `:root` block wins over `[data-theme="dark"]` by source order — identical to how `primary_color` already behaves). "Set your palette once" therefore means single-value today; per-theme palettes are a future affordance, not spine scope. Noted in CHANGELOG; a Phase 2 consideration if the generation context needs to advertise theme-awareness.
 
 #### Phase 2 (M4, tinkerdown) — Wire the house style into the generation context (~1 session)
 
diff --git a/internal/config/config.go b/internal/config/config.go
index 1872f71..33ace48 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -690,6 +690,55 @@ type StylingConfig struct {
 	// shell too, while CustomCSS stays quarantined to landing pages. On landing
 	// pages SiteCSS loads before CustomCSS so the landing layer can override it.
 	SiteCSS string `yaml:"site_css,omitempty"`
+	// Tokens overrides individual design tokens — the on-brand palette — declaratively,
+	// so a team sets its brand without writing raw CSS. Keys are the snake_case names
+	// in KnownStyleTokens (e.g. "accent", "bg_primary", "card_bg"); each drives the
+	// matching CSS custom property (--accent, --bg-primary, …) in the page's :root,
+	// overriding the built-in default via the same mechanism primary_color uses for
+	// --accent. Overriding a token skins the generated (semantic) HTML on-brand by
+	// construction. An unknown key is a config error (ValidateStyleTokens). Absent,
+	// the built-in defaults apply.
+	Tokens map[string]string `yaml:"tokens,omitempty"`
+}
+
+// KnownStyleTokens maps each overridable design-token key (snake_case, as used in
+// styling.tokens) to the CSS custom property it drives in the page's :root. This
+// is the page-shell on-brand palette (server.go's :root); client-chrome tokens
+// (search/tabs/toc) are internal and deliberately not author-facing.
+var KnownStyleTokens = map[string]string{
+	"bg_primary":     "--bg-primary",
+	"bg_secondary":   "--bg-secondary",
+	"text_primary":   "--text-primary",
+	"text_secondary": "--text-secondary",
+	"text_heading":   "--text-heading",
+	"border_color":   "--border-color",
+	"accent":         "--accent",
+	"card_bg":        "--card-bg",
+	"card_border":    "--card-border",
+	"card_shadow":    "--card-shadow",
+	"code_bg":        "--code-bg",
+	"code_border":    "--code-border",
+	"pre_bg":         "--pre-bg",
+	"pre_text":       "--pre-text",
+}
+
+// ValidateStyleTokens rejects any styling.tokens key that is not a known design
+// token, so a typo fails loudly at load rather than silently skinning nothing.
+func (c *Config) ValidateStyleTokens() error {
+	if c == nil {
+		return nil
+	}
+	for key := range c.Styling.Tokens {
+		if _, ok := KnownStyleTokens[key]; !ok {
+			known := make([]string, 0, len(KnownStyleTokens))
+			for k := range KnownStyleTokens {
+				known = append(known, k)
+			}
+			slices.Sort(known)
+			return fmt.Errorf("styling.tokens: %q is not a known design token (known: %s)", key, strings.Join(known, ", "))
+		}
+	}
+	return nil
 }
 
 // BlocksConfig holds block-related configuration
@@ -950,6 +999,9 @@ func Load(configPath string) (*Config, error) {
 	if err := config.ValidateActions(); err != nil {
 		return nil, err
 	}
+	if err := config.ValidateStyleTokens(); err != nil {
+		return nil, err
+	}
 
 	return config, nil
 }
diff --git a/internal/config/style_tokens_test.go b/internal/config/style_tokens_test.go
new file mode 100644
index 0000000..37591da
--- /dev/null
+++ b/internal/config/style_tokens_test.go
@@ -0,0 +1,88 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// styling.tokens round-trips from tinkerdown.yaml into the loaded config, and
+// each known snake_case key is accepted.
+func TestLoad_StylingTokens(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "tinkerdown.yaml")
+	yaml := "title: Site\n" +
+		"type: site\n" +
+		"styling:\n" +
+		"  tokens:\n" +
+		"    accent: \"#5a67d8\"\n" +
+		"    card_bg: \"#ffffff\"\n"
+	if err := os.WriteFile(path, []byte(yaml), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if got := cfg.Styling.Tokens["accent"]; got != "#5a67d8" {
+		t.Errorf("tokens[accent] = %q, want %q", got, "#5a67d8")
+	}
+	if got := cfg.Styling.Tokens["card_bg"]; got != "#ffffff" {
+		t.Errorf("tokens[card_bg] = %q, want %q", got, "#ffffff")
+	}
+}
+
+// An unknown token key is an author mistake — Load fails loudly, naming the
+// offending key and listing the known tokens, rather than silently ignoring it.
+func TestLoad_StylingTokensUnknownKeyRejected(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "tinkerdown.yaml")
+	yaml := "title: Site\n" +
+		"type: site\n" +
+		"styling:\n" +
+		"  tokens:\n" +
+		"    accnet: \"#5a67d8\"\n" // typo'd "accent"
+	if err := os.WriteFile(path, []byte(yaml), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	_, err := Load(path)
+	if err == nil {
+		t.Fatal("Load should reject an unknown token key")
+	}
+	if !strings.Contains(err.Error(), "accnet") {
+		t.Errorf("error should name the offending key, got: %v", err)
+	}
+	if !strings.Contains(err.Error(), "accent") {
+		t.Errorf("error should list known tokens (incl. accent), got: %v", err)
+	}
+}
+
+// Absent styling.tokens is backward-compatible: an empty map, no error.
+func TestLoad_StylingTokensDefaultsEmpty(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "tinkerdown.yaml")
+	if err := os.WriteFile(path, []byte("title: Site\ntype: site\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if len(cfg.Styling.Tokens) != 0 {
+		t.Errorf("cfg.Styling.Tokens = %v, want empty", cfg.Styling.Tokens)
+	}
+}
+
+// ValidateStyleTokens accepts every key in KnownStyleTokens — guards against the
+// map and the validator drifting apart.
+func TestValidateStyleTokens_AllKnownKeysAccepted(t *testing.T) {
+	tokens := make(map[string]string, len(KnownStyleTokens))
+	for k := range KnownStyleTokens {
+		tokens[k] = "#000000"
+	}
+	c := &Config{Styling: StylingConfig{Tokens: tokens}}
+	if err := c.ValidateStyleTokens(); err != nil {
+		t.Errorf("all known tokens should validate, got: %v", err)
+	}
+}
diff --git a/internal/server/styling.go b/internal/server/styling.go
index b04888a..f7ca38c 100644
--- a/internal/server/styling.go
+++ b/internal/server/styling.go
@@ -3,6 +3,7 @@ package server
 import (
 	"fmt"
 	"html"
+	"slices"
 	"strings"
 
 	"github.com/livetemplate/tinkerdown/internal/config"
@@ -27,20 +28,48 @@ func themeDefault(s config.StylingConfig) string {
 	return "auto"
 }
 
-// buildStylingOverrideCSS returns a <style> block overriding theme tokens
-// based on user config. Returns "" if no overrides are set.
+// buildStylingOverrideCSS returns a <style> block overriding theme tokens based
+// on user config (primary_color, font, and the styling.tokens design-token
+// palette). Returns "" if no overrides are set.
 func buildStylingOverrideCSS(s config.StylingConfig) string {
 	primary := sanitizeCSSValue(s.PrimaryColor)
 	font := sanitizeCSSValue(s.Font)
-	if primary == "" && font == "" {
+
+	// Design-token overrides, in deterministic key order. Unknown keys are
+	// rejected at config load (ValidateStyleTokens); skip defensively here.
+	keys := make([]string, 0, len(s.Tokens))
+	for k := range s.Tokens {
+		keys = append(keys, k)
+	}
+	slices.Sort(keys)
+	var tokenDecls []string
+	for _, key := range keys {
+		cssVar, ok := config.KnownStyleTokens[key]
+		if !ok {
+			continue
+		}
+		if val := sanitizeCSSValue(s.Tokens[key]); val != "" {
+			tokenDecls = append(tokenDecls, fmt.Sprintf("%s: %s;", cssVar, val))
+		}
+	}
+
+	if primary == "" && font == "" && len(tokenDecls) == 0 {
 		return ""
 	}
 
 	var out strings.Builder
 	out.WriteString("<style>\n")
+	// primary_color is shorthand for --accent; emit first so an explicit
+	// tokens.accent wins if a project sets both.
 	if primary != "" {
 		fmt.Fprintf(&out, "        :root { --accent: %s; }\n", primary)
 	}
+	// The token block is injected after the built-in :root and [data-theme="dark"]
+	// blocks (server.go), so — same specificity, later source order — it wins for
+	// both themes, exactly as --accent does.
+	if len(tokenDecls) > 0 {
+		fmt.Fprintf(&out, "        :root { %s }\n", strings.Join(tokenDecls, " "))
+	}
 	if font != "" {
 		fmt.Fprintf(&out, "        body { font-family: %s, -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif; }\n", font)
 	}
diff --git a/internal/server/styling_test.go b/internal/server/styling_test.go
index d9c2f02..f623071 100644
--- a/internal/server/styling_test.go
+++ b/internal/server/styling_test.go
@@ -70,6 +70,29 @@ func TestBuildStylingOverrideCSS_Both(t *testing.T) {
 	}
 }
 
+func TestBuildStylingOverrideCSS_Tokens(t *testing.T) {
+	got := buildStylingOverrideCSS(config.StylingConfig{
+		Tokens: map[string]string{"accent": "#ff00ff", "card_bg": "#00ff00"},
+	})
+	// snake_case keys map to the CSS custom property, emitted into :root.
+	if !strings.Contains(got, "--accent: #ff00ff;") {
+		t.Errorf("missing --accent override: %q", got)
+	}
+	if !strings.Contains(got, "--card-bg: #00ff00;") {
+		t.Errorf("missing --card-bg override: %q", got)
+	}
+}
+
+func TestBuildStylingOverrideCSS_TokensSanitized(t *testing.T) {
+	// A token value that tries to break out of the CSS context is dropped, not emitted.
+	got := buildStylingOverrideCSS(config.StylingConfig{
+		Tokens: map[string]string{"accent": "red; } body { display:none"},
+	})
+	if strings.Contains(got, "display:none") {
+		t.Errorf("malicious token value should be sanitized away, got: %q", got)
+	}
+}
+
 func TestSanitizeCSSValue_BlocksInjection(t *testing.T) {
 	blocked := []string{
 		"</style><script>alert(1)</script>",
diff --git a/styling_tokens_e2e_test.go b/styling_tokens_e2e_test.go
new file mode 100644
index 0000000..0672a33
--- /dev/null
+++ b/styling_tokens_e2e_test.go
@@ -0,0 +1,134 @@
+//go:build !ci
+
+package tinkerdown_test
+
+import (
+	"context"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/chromedp/cdproto/network"
+	"github.com/chromedp/chromedp"
+	"github.com/livetemplate/tinkerdown/internal/config"
+	"github.com/livetemplate/tinkerdown/internal/server"
+)
+
+// serveStyled writes a minimal one-page site with the given tinkerdown.yaml and
+// serves it exactly as `tinkerdown serve` does (LoadFromDir + NewWithConfig), so
+// the styling.tokens override runs through the real page-render path.
+func serveStyled(t *testing.T, manifest string) *httptest.Server {
+	t.Helper()
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "tinkerdown.yaml"), []byte(manifest), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "index.md"), []byte("# Styled\n\nHello.\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := config.LoadFromDir(dir)
+	if err != nil {
+		t.Fatalf("load manifest: %v", err)
+	}
+	srv := server.NewWithConfig(dir, cfg)
+	if err := srv.Discover(); err != nil {
+		t.Fatalf("discover: %v", err)
+	}
+	return httptest.NewServer(server.WithCompression(srv))
+}
+
+// cssVar reads a CSS custom property off the document root as the browser
+// actually computes it — the cascade-resolved value, not the authored text.
+// Dumps the four-channel capture before failing so a broken read is diagnosable.
+func cssVar(t *testing.T, ctx context.Context, ch *channels, name string) string {
+	t.Helper()
+	var v string
+	if err := chromedp.Run(ctx,
+		chromedp.Evaluate(
+			`getComputedStyle(document.documentElement).getPropertyValue('`+name+`').trim()`,
+			&v,
+		),
+	); err != nil {
+		ch.dump(t)
+		t.Fatalf("read %s: %v", name, err)
+	}
+	return v
+}
+
+// TestStylingTokensComputedStyle proves the styling.tokens design-token override
+// reaches the browser's computed style: a distinctive accent (#ff00ff) config
+// produces that computed --accent, while an unconfigured site keeps the default
+// accent (#007bff, from DefaultConfig.PrimaryColor). This is the M4 Phase 1
+// acceptance bar — token-in-config to pixels, through the real cascade, not just
+// emitted <style> text. That the token wins over the default primary_color also
+// verifies emission order: styling.go emits primary_color first, tokens second,
+// so an explicit tokens.accent takes precedence.
+//
+// Four-channel capture (CLAUDE.md): browser console + exceptions and WebSocket
+// frames via listen(); server log via captureServerLog(); rendered HTML/screenshot
+// via saveScreenshot(). All dumped on any failure.
+func TestStylingTokensComputedStyle(t *testing.T) {
+	serverLog := captureServerLog(t)
+
+	const styled = "title: Styled\n" +
+		"type: site\n" +
+		"styling:\n" +
+		"  theme: light\n" +
+		"  tokens:\n" +
+		"    accent: \"#ff00ff\"\n" +
+		"    card_bg: \"#00ff00\"\n"
+	const plain = "title: Plain\n" +
+		"type: site\n" +
+		"styling:\n" +
+		"  theme: light\n"
+
+	styledTS := serveStyled(t, styled)
+	defer styledTS.Close()
+	plainTS := serveStyled(t, plain)
+	defer plainTS.Close()
+
+	chromeCtx, cleanup := SetupDockerChrome(t, 60*time.Second)
+	defer cleanup()
+	ctx := chromeCtx.Context
+
+	ch := &channels{serverLog: serverLog}
+	listen(ctx, ch)
+
+	// Configured site: the override wins the cascade, so computed --accent and
+	// --card-bg are exactly the token values.
+	if err := chromedp.Run(ctx,
+		network.Enable(),
+		chromedp.Navigate(ConvertURLForDockerChrome(styledTS.URL)),
+		chromedp.WaitVisible(`body`, chromedp.ByQuery),
+	); err != nil {
+		ch.dump(t)
+		t.Fatalf("navigate styled: %v", err)
+	}
+	saveScreenshot(t, ctx, "styling-tokens-styled")
+	if got := cssVar(t, ctx, ch, "--accent"); !strings.EqualFold(got, "#ff00ff") {
+		ch.dump(t)
+		t.Errorf("styled --accent: got %q, want #ff00ff (token override did not reach computed style)", got)
+	}
+	if got := cssVar(t, ctx, ch, "--card-bg"); !strings.EqualFold(got, "#00ff00") {
+		ch.dump(t)
+		t.Errorf("styled --card-bg: got %q, want #00ff00", got)
+	}
+
+	// Site with no tokens: the token override machinery emits nothing, so the
+	// accent falls back to DefaultConfig.PrimaryColor — proving tokens don't leak
+	// across sites and the default stands unchanged when unconfigured.
+	if err := chromedp.Run(ctx,
+		chromedp.Navigate(ConvertURLForDockerChrome(plainTS.URL)),
+		chromedp.WaitVisible(`body`, chromedp.ByQuery),
+	); err != nil {
+		ch.dump(t)
+		t.Fatalf("navigate plain: %v", err)
+	}
+	if got := cssVar(t, ctx, ch, "--accent"); !strings.EqualFold(got, "#007bff") {
+		ch.dump(t)
+		t.Errorf("plain --accent: got %q, want #007bff (DefaultConfig.PrimaryColor)", got)
+	}
+}

From f5efea2fdce81b6dd7f000744381bc7a436a89f4 Mon Sep 17 00:00:00 2001
From: Adnaan Badr <badr.adnaan@gmail.com>
Date: Fri, 24 Jul 2026 07:06:18 +0000
Subject: [PATCH 3/5] =?UTF-8?q?feat(skill):=20consume=20the=20house=20styl?=
 =?UTF-8?q?e=20in=20generation=20=E2=80=94=20M4=20Phase=202?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The /tinkerdown generation skill now reads a project's house style and authors
against it, closing a declared-but-unconsumed gap: generation.style_guide (a
markdown file of house tone/layout/do-don't) was a config field nothing ever
read.

- SKILL.md: step 1 also reads styling (theme + tokens) + generation.style_guide
  and cats the style-guide file; step 2 carries the on-brand lever — write
  semantic HTML, never hardcode colours, follow the style-guide. Style block
  stays optional (absent → on-brand defaults).
- reference.md: new § House style — the rule + a 14-token table (snake_case key
  → CSS property → what it skins). Fixed the § Tailwind CSS example, which
  demonstrated hardcoded colours (bg-blue-500/text-gray-800/text-white) — a
  worked counter-example to the new rule, in the same LLM context; now
  layout/spacing only, colour from tokens.
- Tests: TestStyleTokensDocumented (forward drift-guard — KnownStyleTokens ⊆
  reference.md, so a new token can't go untaught; forward-only by design, since
  scraping token-like words from prose would false-match), TestSkillWiresHouseStyle
  (structural), TestPIIManifestHouseStyleConsumable (integration — LoadFromDir
  exposes Generation.StyleGuide, which resolves, + Styling.Tokens; proves the
  field is consumable, not that a Go path consumes it).
- The PII reference app ships a style-guide.md + styling.tokens (real token keys
  only) demonstrating a governed, on-brand console.

No Go runtime code: the skill cats the style-guide, so a missing path fails
loudly at generation, needing no load-time validator. House style is advisory
(guidance + Phase 1 tokens), never enforced — the no-lint milestone shape.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018M9pJSPmG6i1D8s6rpEV4h
---
 CHANGELOG.md                                  |  14 +++
 docs/plans/2026-07-09-ephemeral-ui-reframe.md |  28 +++--
 examples/pii-access-approval/style-guide.md   |  38 +++++++
 examples/pii-access-approval/tinkerdown.yaml  |  14 +++
 skills/tinkerdown/SKILL.md                    |  26 ++++-
 skills/tinkerdown/reference.md                |  61 +++++++++-
 style_guide_docs_test.go                      | 106 ++++++++++++++++++
 7 files changed, 272 insertions(+), 15 deletions(-)
 create mode 100644 examples/pii-access-approval/style-guide.md
 create mode 100644 style_guide_docs_test.go

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ee373d4..4340eae 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,20 @@ Earlier releases (v0.1.x) are documented in the
 
 ## [Unreleased]
 
+### Changed — the generation skill now consumes the house style
+
+The `/tinkerdown` generation skill reads a project's house style and authors
+against it, closing a declared-but-unconsumed gap: `generation.style_guide` (a
+markdown file of house tone/layout/do-don't) was a config field nothing ever
+read. The skill now reads it — plus the `styling` block (`theme` +
+`styling.tokens`) — and carries the on-brand rule into generation: **write
+semantic HTML, never hardcode colours** and let the design tokens skin it, follow
+the project's `style-guide.md`. The token vocabulary is documented in the skill
+`reference.md` (guarded against `KnownStyleTokens` so a new token can't go
+untaught). The whole style block stays optional — with none, generation falls
+back to on-brand defaults. The PII reference app now ships a `style-guide.md` +
+`styling.tokens` demonstrating a governed, on-brand console.
+
 ### Added — declarative design tokens (`styling.tokens`)
 
 A project can now set its on-brand palette declaratively, without writing raw
diff --git a/docs/plans/2026-07-09-ephemeral-ui-reframe.md b/docs/plans/2026-07-09-ephemeral-ui-reframe.md
index 35ca530..1ec091c 100644
--- a/docs/plans/2026-07-09-ephemeral-ui-reframe.md
+++ b/docs/plans/2026-07-09-ephemeral-ui-reframe.md
@@ -1056,22 +1056,28 @@ type Diagnostic struct {
 - tinkerdown `internal/config/config.go:181` (`GenerationConfig.StyleGuide` — unconsumed), `skills/tinkerdown/SKILL.md` + `reference.md` (the generation context; today advertise only the `lvt-*` vocabulary + "datatable, dropdown")
 
 **Audit (first task):**
-- [ ] **Design-ref completeness check.**
-- [ ] Confirm `style_guide` has no runtime consumer (Explore verified). Decide the read path: the skill loads the manifest's `style_guide` (a `style-guide.md` path) + a **token summary** (the available tokens/theme) and injects both into the generation context.
-- [ ] Decide whether a command surfaces the style guide to the skill (like `validate --summary` for operations) or the skill reads the manifest directly — prefer the smallest that lets the skill see the house style deterministically.
-- [ ] Pin the guidance: generated UIs use **semantic HTML** (skinned on-brand by the tokens) + the house `style-guide.md` patterns, and **do not hardcode colors** (use the tokens) — the anti-off-brand rule, delivered as guidance + tokens, not a lint.
+- [x] **Design-ref completeness check.**
+- [x] Confirmed `style_guide` (`GenerationConfig.StyleGuide`, config.go:181) has **no runtime consumer** — it appears only in its own declaration across all Go. Read path: the skill (which already `cat`s `tinkerdown.yaml` in step 1) also reads `styling` (theme + tokens) + `generation.style_guide`, and `cat`s the style-guide file.
+- [x] **Read-path decision (advisor-confirmed): skill reads the manifest directly + reference.md documents the token vocabulary — no new command.** `attribute_docs_test.go` is explicit precedent that `reference.md` is the LLM's vocabulary surface, guarded against the implementation. A `validate --style` command would be a second reader of what the skill already `cat`s. The token vocabulary is single-sourced by a **forward drift-guard** (`config.KnownStyleTokens` ⊆ reference.md), not re-enumerated by hand.
+- [x] Guidance pinned: **semantic HTML skinned by the tokens + never hardcode colours + follow `style-guide.md`** — the on-brand lever, delivered as guidance + tokens (Phase 1), not a lint.
 
 **Implementation:**
-- [ ] `SKILL.md` (+ `reference.md` if needed): load + inject the manifest's `style_guide` + token summary; add the "semantic HTML + tokens, don't hardcode colors, follow the style-guide" guidance. Keep the style block optional (absent → default tokens).
-- [ ] `CHANGELOG.md`.
+- [x] `SKILL.md`: step 1 reads `styling` + `generation.style_guide` (and `cat`s the file); step 2 carries the "semantic HTML, never hardcode colours, follow the style-guide" rule; Reference list gains "House style". Style block stays optional.
+- [x] `skills/tinkerdown/reference.md`: new **§ House style — design tokens** — the rule + a 14-token table (snake_case key → CSS property → what it skins).
+- [x] **(audit-derived)** The PII reference app ships a `style-guide.md` + `styling.tokens` (real `KnownStyleTokens` keys only — an unknown key fails `ValidateStyleTokens` at load and would break every pii E2E via `serveConsole`), demonstrating a governed, on-brand console and giving the integration test a real manifest.
+- [x] `CHANGELOG.md`.
 
 **Acceptance criteria:**
-- [ ] **Simplify:** prose + asset pass.
-- [ ] **Unit/structural:** a test asserting the skill wires the `style_guide` (mirror `skill_examples_test.go`); the style-guide reference resolves.
-- [ ] **Integration:** a manifest with a `style_guide` → the skill's generation context includes it + the token summary (verifiable deterministically).
-- [ ] **E2E:** N/A (generation-context, as with M1 Phase 3) — the on-brand *rendering* guarantee is Phase 1's tokens (structural); this phase's deliverable is that the skill *sees* the house style, verified by the structural/integration test.
+- [x] **Simplify:** prose pass — the guidance is layered across three surfaces by distinct role (SKILL.md workflow steps 1/2 + reference.md lookup), mirroring how the `lvt-*` vocabulary is already split; not redundant. The one Go file mirrors existing test idioms.
+- [x] **Unit/structural:** `TestSkillWiresHouseStyle` (SKILL.md wires `style_guide` + `styling.tokens` + the semantic-HTML/no-hardcode-colour guidance; reference.md carries the § + token table) + `TestStyleTokensDocumented` (forward drift-guard).
+- [x] **Integration:** `TestPIIManifestHouseStyleConsumable` — `config.LoadFromDir` on the demo exposes `Generation.StyleGuide` (resolves to a real file) + populated `Styling.Tokens`. Honest framing: this proves `StyleGuide` is now *consumable*, not that a Go path consumes it (the skill is instructions; `cat` fails loudly at generation if the file is missing, so no Go validator is needed).
+- [x] **E2E:** N/A (generation-context, as with M1 Phase 3) — the on-brand *rendering* guarantee is Phase 1's tokens (structural, E2E-verified there); this phase's deliverable is that the skill *sees* the house style, verified by the structural/integration tests.
 
-**Learn:** what surprised us / plan drift / feed-forward to **M5**'s Audit / new-or-changed risks.
+**Learn:**
+- **What surprised us.** (1) The drift-guard's shape: a naïve bidirectional token↔doc check would have to scrape token-like words (`accent`, `card_bg`) out of prose — words with no unique signature, unlike `lvt-` — so it would false-match or silently miss. Forward-only (`KnownStyleTokens` ⊆ reference.md) is robust and catches the failure that matters (a token the LLM is never told about); the reverse (phantom docs) is low-harm and deliberately not built. (2) **The generation context contradicted itself:** adding "never hardcode colours" while `reference.md § Tailwind CSS` still demonstrated `bg-blue-500`/`text-gray-800`/`text-white` — worked counter-examples in the same LLM context. A presence-check test (`TestSkillWiresHouseStyle`) can't catch a *contradiction*; fixed the example (Tailwind → layout/spacing only, colour from tokens) in the same commit. Same class as Phase 1's four-channel over-claim: the deliverable must not undercut its own goal.
+- **Plan drift fixed in this commit.** None — the Phase 2 block matched reality (unlike Phase 1's stale block).
+- **Feed-forward to M5's Audit.** House style is now consumed by the skill but is **advisory** (guidance + tokens), never enforced — consistent with the no-lint milestone shape. If M5's save/share gallery renders *saved* generated UIs, the same tokens skin them for free (they cascade from `:root`); a saved skill should capture its manifest's `styling`/`style_guide` so the palette travels with it.
+- **New/changed risks.** None. The `style_guide` file is read by `cat` at generation, so a manifest naming a nonexistent path fails loudly then (not silently) — acceptable without a load-time validator.
 
 ---
 
diff --git a/examples/pii-access-approval/style-guide.md b/examples/pii-access-approval/style-guide.md
new file mode 100644
index 0000000..d583904
--- /dev/null
+++ b/examples/pii-access-approval/style-guide.md
@@ -0,0 +1,38 @@
+# House style — PII access-approval console
+
+This is a compliance tool. An approver makes an irreversible, audited decision
+about who reaches sensitive data. The UI should read like a control panel, not a
+marketing page: sober, high-contrast, and unambiguous about state.
+
+## Tone
+
+- Plain and factual. Label things by what they are (`Requester`, `Row cap`,
+  `Justification`), never with cute copy.
+- Every privileged action states its consequence before it fires
+  (`data-confirm="Approve this request and run the bounded PII export?"`).
+
+## Layout
+
+- One decision per row. The pending queue is a table; each row carries the full
+  context an approver needs to decide without leaving the page (requester, dataset,
+  scope/row-cap, justification, ticket, TTL, sensitivity tags).
+- Group the intake form and its queue inside a single `lvt-source` container.
+- Lead with the pending queue; show approved/denied history below or behind a
+  toggle, not competing for attention.
+
+## Colour and tokens — do not hardcode
+
+- **Never write a raw colour** (`#3949ab`, `rgb(...)`, `red`) in the markup. The
+  house palette is set once in `styling.tokens` and applied through the page's
+  design tokens; hardcoding a colour bypasses it and drifts off-brand.
+- Use **semantic HTML** — `<table>`, `<article>`, `<mark>`, `<strong>`, headings —
+  and let the tokens skin it. Semantic elements inherit `--accent`, `--card-bg`,
+  `--text-heading` etc. automatically.
+- Convey status (pending / approved / denied) with text and semantic emphasis
+  (`<mark>`, `<strong>`), not with a hand-picked colour.
+
+## Components
+
+- Prefer a plain semantic `<table>` for the queue over any custom widget.
+- Confirm-gate every state-changing button with `data-confirm`.
+- No decorative imagery, gradients, or animation — this is a record of decisions.
diff --git a/examples/pii-access-approval/tinkerdown.yaml b/examples/pii-access-approval/tinkerdown.yaml
index ff4f1c1..01f8693 100644
--- a/examples/pii-access-approval/tinkerdown.yaml
+++ b/examples/pii-access-approval/tinkerdown.yaml
@@ -116,6 +116,20 @@ actions:
 generation:
   sources: [access_requests, audit_log, datasets]
   actions: [request-access, approve-export, deny-request]
+  # House style the generator authors against (Phase 2). The style guide is prose
+  # (tone, layout, do/don't); the design tokens below skin the semantic HTML
+  # on-brand by construction, so a generated console conforms without a careful
+  # prompt. Both are optional — absent, generation falls back to PicoCSS defaults.
+  style_guide: style-guide.md
 
 styling:
   theme: clean
+  # Sober compliance-console palette. Keys are the snake_case design tokens
+  # (see skills/tinkerdown/reference.md § House style); each drives the matching
+  # CSS custom property in every page's :root.
+  tokens:
+    accent: "#3949ab"       # indigo — links and primary actions
+    text_heading: "#1a237e" # deep indigo for headings
+    card_bg: "#ffffff"
+    card_border: "#e0e3eb"
+    border_color: "#d5d9e0"
diff --git a/skills/tinkerdown/SKILL.md b/skills/tinkerdown/SKILL.md
index 44aa5e8..fa0bb27 100644
--- a/skills/tinkerdown/SKILL.md
+++ b/skills/tinkerdown/SKILL.md
@@ -45,7 +45,7 @@ reaching for custom JavaScript.
 Follow these steps in order. They exist because each one catches something the next
 cannot.
 
-### 1. Read the approved surface, if there is one
+### 1. Read the approved surface and house style, if there is one
 
 If the project has a `tinkerdown.yaml` with a `generation:` block, it declares the
 sources and actions you may use — and those are the **only** ones you may use:
@@ -60,6 +60,21 @@ document's frontmatter** — a name outside the approved set fails validation, a
 redefining an approved name silently has no effect, because approved definitions are
 pinned and yours will be ignored.
 
+**Read the house style, too.** The same `tinkerdown.yaml` carries the project's
+style: a `styling` block (`theme`, and any `styling.tokens` design-token overrides)
+and an optional `generation.style_guide` pointing at a markdown file. If that field
+is set, read the file it names and follow it:
+
+```bash
+cat style-guide.md   # the path given by generation.style_guide
+```
+
+The style guide describes house tone, layout conventions, which components to prefer,
+and what to avoid. The design tokens (see `reference.md` § House style) skin semantic
+HTML on-brand automatically — so **write semantic HTML and never hardcode colours**;
+let the tokens apply. All of this is optional: with no style block, generation falls
+back to Tinkerdown's on-brand defaults.
+
 No `generation:` block means no approved surface: declare sources in frontmatter as
 normal.
 
@@ -81,6 +96,14 @@ Use only attributes from `reference.md`. If you need a capability you cannot fin
 there, check whether it exists before inventing an attribute for it — a plausible
 invention is the most common way generated pages fail.
 
+**Stay on-brand by construction — write semantic HTML, never hardcode colours.**
+Use semantic elements (`<table>`, `<article>`, `<mark>`, `<strong>`, headings); the
+project's design tokens skin them on-brand automatically. Do **not** write a raw
+colour (`#3949ab`, `rgb(...)`, a named colour) or reach for Tailwind colour classes —
+that bypasses the house palette and drifts off-brand. Follow the project's
+`style-guide.md` (from step 1) for layout, tone, and preferred components. With no
+style block the defaults are already on-brand, so this costs nothing.
+
 **Binding data and actions — three rules that cause most first-try failures:**
 
 - **State comes from `lvt-source` on the block's container.** `{{range .Data}}` and
@@ -236,6 +259,7 @@ See [reference.md](./reference.md) for complete API documentation:
 - Source configuration (pg, rest, csv, json, exec)
 - Template syntax (Go templates)
 - Components (datatable, dropdown)
+- House style (design tokens, style guide)
 
 ## Examples
 
diff --git a/skills/tinkerdown/reference.md b/skills/tinkerdown/reference.md
index 0a2e9de..d06bb3f 100644
--- a/skills/tinkerdown/reference.md
+++ b/skills/tinkerdown/reference.md
@@ -344,6 +344,58 @@ Tinkerdown uses Go templates.
 
 ## Styling
 
+### House style — design tokens
+
+**The on-brand default, and the way to style generated UIs.** A project sets its
+palette once in `tinkerdown.yaml`; every page renders against it automatically.
+Write **semantic HTML** and let the tokens skin it — do **not** hardcode colours.
+
+- **Never write a raw colour** (`#3949ab`, `rgb(...)`, a named colour) in generated
+  markup. Hardcoding bypasses the house palette and drifts off-brand.
+- Use semantic elements — `<table>`, `<article>`, `<mark>`, `<strong>`, headings —
+  which inherit the tokens (`--accent`, `--card-bg`, `--text-heading`, …) with no
+  classes and no inline styles.
+- If the project's `generation.style_guide` points at a markdown file, **read it and
+  follow it** (tone, layout conventions, which components to prefer, what to avoid).
+
+A project sets tokens under `styling.tokens`, each key mapped to the CSS custom
+property it drives in the page's `:root`:
+
+```yaml
+# tinkerdown.yaml
+generation:
+  style_guide: style-guide.md   # optional house-style prose the generator follows
+styling:
+  theme: clean                  # light / dark / auto — or a preset
+  tokens:                       # optional; absent → built-in on-brand defaults
+    accent: "#3949ab"
+    card_bg: "#ffffff"
+    text_heading: "#1a237e"
+```
+
+The overridable tokens (snake_case key → CSS custom property):
+
+| Key | CSS property | Skins |
+|-----|--------------|-------|
+| `accent` | `--accent` | Links, primary actions, active accents |
+| `bg_primary` | `--bg-primary` | Page background |
+| `bg_secondary` | `--bg-secondary` | Secondary / gradient background |
+| `text_primary` | `--text-primary` | Body text |
+| `text_secondary` | `--text-secondary` | Muted / secondary text |
+| `text_heading` | `--text-heading` | Headings |
+| `border_color` | `--border-color` | Rules and borders |
+| `card_bg` | `--card-bg` | Card / panel background |
+| `card_border` | `--card-border` | Card border |
+| `card_shadow` | `--card-shadow` | Card shadow |
+| `code_bg` | `--code-bg` | Inline code background |
+| `code_border` | `--code-border` | Inline code border |
+| `pre_bg` | `--pre-bg` | Code-block background |
+| `pre_text` | `--pre-text` | Code-block text |
+
+An unknown token key fails loudly at config load. A token value applies to both
+light and dark themes. Everything below (inline styles, Tailwind) is an escape
+hatch for the rare case tokens cannot express — reach for tokens first.
+
 ### Inline Styles
 
 Include `<style>` in your `lvt` block:
@@ -366,12 +418,15 @@ Include `<style>` in your `lvt` block:
 
 ### Tailwind CSS
 
-Tailwind CSS is included automatically. Use utility classes:
+Tailwind CSS is included automatically. Use utility classes for **layout and
+spacing** — but **not for colour**: in a house-styled project colour comes from the
+design tokens (above), so avoid colour utilities (`bg-blue-500`, `text-gray-800`,
+`text-white`) that would bypass the palette and drift off-brand.
 
 ```html
 <div class="max-w-xl mx-auto p-6">
-    <h1 class="text-2xl font-bold text-gray-800">My App</h1>
-    <button class="bg-blue-500 text-white px-4 py-2 rounded">
+    <h1 class="text-2xl font-bold">My App</h1>
+    <button class="px-4 py-2 rounded">
         Submit
     </button>
 </div>
diff --git a/style_guide_docs_test.go b/style_guide_docs_test.go
new file mode 100644
index 0000000..b129140
--- /dev/null
+++ b/style_guide_docs_test.go
@@ -0,0 +1,106 @@
+package tinkerdown_test
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/livetemplate/tinkerdown/internal/config"
+)
+
+const (
+	skillPath          = "skills/tinkerdown/SKILL.md"
+	skillReferencePath = "skills/tinkerdown/reference.md"
+)
+
+// TestStyleTokensDocumented is the forward drift-guard for the house-style
+// vocabulary: every design token the framework accepts (config.KnownStyleTokens)
+// must be named in the skill reference the LLM reads as generation context. A token
+// added to the map but never documented is one the generator is never told it can
+// theme — silent off-brand drift, the gap Phase 2 exists to close.
+//
+// Forward-only by design (mirrors the philosophy of attribute_docs_test.go, adapted
+// to a vocabulary with no unique textual signature). The reverse direction — a
+// documented token that no longer exists — would require scraping token-like words
+// out of prose; "accent"/"card_bg" are ordinary words, unlike "lvt-", so such a
+// scan would either false-match prose or silently miss tokens. That is a
+// self-certifying guard, and the reverse case is low-harm, so it is not built.
+func TestStyleTokensDocumented(t *testing.T) {
+	doc := readDocFile(t, skillReferencePath)
+	for key := range config.KnownStyleTokens {
+		if !strings.Contains(doc, key) {
+			t.Errorf("design token %q is in config.KnownStyleTokens but not documented in %s — "+
+				"the generator is never told it can theme it", key, skillReferencePath)
+		}
+	}
+}
+
+// TestSkillWiresHouseStyle asserts the generation skill actually consumes the house
+// style, closing the declared-but-unconsumed gap: SKILL.md instructs reading
+// generation.style_guide + styling.tokens and carries the on-brand guidance
+// (semantic HTML, don't hardcode colours), and reference.md documents the
+// design-token system. Structural, in the spirit of skill_examples_test.go.
+func TestSkillWiresHouseStyle(t *testing.T) {
+	skill := readDocFile(t, skillPath)
+	ref := readDocFile(t, skillReferencePath)
+
+	// SKILL.md must wire the read path + the guidance lever.
+	for _, want := range []string{"style_guide", "styling.tokens", "semantic HTML"} {
+		if !strings.Contains(skill, want) {
+			t.Errorf("%s does not wire the house style: missing %q", skillPath, want)
+		}
+	}
+	// The never-hardcode-colours rule is the on-brand lever (accept either spelling).
+	if !strings.Contains(skill, "hardcode colour") && !strings.Contains(skill, "hardcode color") {
+		t.Errorf("%s is missing the 'never hardcode colours' guidance", skillPath)
+	}
+	// reference.md must carry the House style section + the token vocabulary.
+	for _, want := range []string{"House style", "styling.tokens", "--accent"} {
+		if !strings.Contains(ref, want) {
+			t.Errorf("%s is missing house-style documentation: %q", skillReferencePath, want)
+		}
+	}
+}
+
+// TestPIIManifestHouseStyleConsumable is the integration check. There is no Go
+// "generation context" to assemble — the skill is instructions, not code — so what
+// is verifiable deterministically is that the demo manifest exposes the house style
+// the skill reads: generation.style_guide is set and resolves to a real file, and
+// styling.tokens is populated. This proves StyleGuide (formerly declared-but-
+// unconsumed) is now consumable, not that a Go path consumes it.
+func TestPIIManifestHouseStyleConsumable(t *testing.T) {
+	const dir = "examples/pii-access-approval"
+	cfg, err := config.LoadFromDir(dir)
+	if err != nil {
+		t.Fatalf("load manifest: %v", err)
+	}
+	if cfg.Generation == nil || cfg.Generation.StyleGuide == "" {
+		t.Fatal("demo manifest has no generation.style_guide")
+	}
+	guidePath := filepath.Join(dir, cfg.Generation.StyleGuide)
+	if _, err := os.Stat(guidePath); err != nil {
+		t.Errorf("generation.style_guide %q does not resolve to a file (%s): %v",
+			cfg.Generation.StyleGuide, guidePath, err)
+	}
+	if len(cfg.Styling.Tokens) == 0 {
+		t.Fatal("demo manifest has no styling.tokens")
+	}
+	// A concrete anchor: the accent we set is present and correct. (An unknown key
+	// would already have failed ValidateStyleTokens at load, above.)
+	if got := cfg.Styling.Tokens["accent"]; got != "#3949ab" {
+		t.Errorf("demo tokens.accent = %q, want #3949ab", got)
+	}
+}
+
+// readDocFile reads a repo-relative doc file for the assertions above. Local to this
+// (untagged) test file so it does not depend on helpers defined in //go:build !ci
+// files, which are absent from CI builds.
+func readDocFile(t *testing.T, path string) string {
+	t.Helper()
+	b, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read %s: %v", path, err)
+	}
+	return string(b)
+}

From e647f145d48d8997e68ac383f9f68212392a0bb7 Mon Sep 17 00:00:00 2001
From: Adnaan Badr <badr.adnaan@gmail.com>
Date: Fri, 24 Jul 2026 12:32:36 +0000
Subject: [PATCH 4/5] test(config): lock the token key-vs-value validation
 split
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses the claude-review note on PR #309: ValidateStyleTokens gates token
keys (fail-loud at load) but not values — an unsafe value round-trips into
config and is dropped at render (sanitizeCSSValue), the same as primary_color/
font. TestLoad_StylingTokensUnsafeValueAccepted pins that behavior so it can't
silently change.

Load-time value validation is deliberately not added: primary_color and font
have the identical silent-drop behavior, so validating only token values would
introduce a new inconsistency. A load-time sanity check across all style values
is a separate, out-of-scope consistency pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018M9pJSPmG6i1D8s6rpEV4h
---
 internal/config/style_tokens_test.go | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/internal/config/style_tokens_test.go b/internal/config/style_tokens_test.go
index 37591da..c1bfcb0 100644
--- a/internal/config/style_tokens_test.go
+++ b/internal/config/style_tokens_test.go
@@ -58,6 +58,31 @@ func TestLoad_StylingTokensUnknownKeyRejected(t *testing.T) {
 	}
 }
 
+// A known token key with an unsafe value is NOT a config error — ValidateStyleTokens
+// gates keys, not values. The value round-trips into config and is dropped later at
+// render (sanitizeCSSValue), exactly as primary_color/font handle an unsafe value.
+// This locks the key-vs-value split so it can't silently change: Load succeeds, the
+// bad value survives in config, and the render layer (not load) is what omits it.
+func TestLoad_StylingTokensUnsafeValueAccepted(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "tinkerdown.yaml")
+	yaml := "title: Site\n" +
+		"type: site\n" +
+		"styling:\n" +
+		"  tokens:\n" +
+		"    accent: \"red; }\"\n" // known key, unsafe value (CSS meta-characters)
+	if err := os.WriteFile(path, []byte(yaml), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatalf("Load should accept a known key regardless of value (values are gated at render): %v", err)
+	}
+	if got := cfg.Styling.Tokens["accent"]; got != "red; }" {
+		t.Errorf("value should round-trip into config unchanged (render sanitizes, not load): got %q", got)
+	}
+}
+
 // Absent styling.tokens is backward-compatible: an empty map, no error.
 func TestLoad_StylingTokensDefaultsEmpty(t *testing.T) {
 	dir := t.TempDir()

From 60261828a5423ec14f4d7044ec0fe7a09e8ca8aa Mon Sep 17 00:00:00 2001
From: Adnaan Badr <badr.adnaan@gmail.com>
Date: Fri, 24 Jul 2026 12:38:23 +0000
Subject: [PATCH 5/5] fix(config): deterministic ValidateStyleTokens error with
 multiple bad keys
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses the claude-review note on PR #309: iterating the tokens map and
returning on the first unknown key named a different key run-to-run when more
than one was wrong. Collect the unknown keys, sort, and report the first —
deterministic error message. TestValidateStyleTokens_MultipleUnknownDeterministic
locks it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018M9pJSPmG6i1D8s6rpEV4h
---
 internal/config/config.go            | 22 +++++++++++++++-------
 internal/config/style_tokens_test.go | 19 +++++++++++++++++++
 2 files changed, 34 insertions(+), 7 deletions(-)

diff --git a/internal/config/config.go b/internal/config/config.go
index 33ace48..5ab92f7 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -728,17 +728,25 @@ func (c *Config) ValidateStyleTokens() error {
 	if c == nil {
 		return nil
 	}
+	// Collect unknown keys and sort before reporting: iterating the map and
+	// returning on the first miss would name a different key run-to-run when more
+	// than one is wrong. Sorting makes the error message deterministic.
+	var unknown []string
 	for key := range c.Styling.Tokens {
 		if _, ok := KnownStyleTokens[key]; !ok {
-			known := make([]string, 0, len(KnownStyleTokens))
-			for k := range KnownStyleTokens {
-				known = append(known, k)
-			}
-			slices.Sort(known)
-			return fmt.Errorf("styling.tokens: %q is not a known design token (known: %s)", key, strings.Join(known, ", "))
+			unknown = append(unknown, key)
 		}
 	}
-	return nil
+	if len(unknown) == 0 {
+		return nil
+	}
+	slices.Sort(unknown)
+	known := make([]string, 0, len(KnownStyleTokens))
+	for k := range KnownStyleTokens {
+		known = append(known, k)
+	}
+	slices.Sort(known)
+	return fmt.Errorf("styling.tokens: %q is not a known design token (known: %s)", unknown[0], strings.Join(known, ", "))
 }
 
 // BlocksConfig holds block-related configuration
diff --git a/internal/config/style_tokens_test.go b/internal/config/style_tokens_test.go
index c1bfcb0..803d9ff 100644
--- a/internal/config/style_tokens_test.go
+++ b/internal/config/style_tokens_test.go
@@ -99,6 +99,25 @@ func TestLoad_StylingTokensDefaultsEmpty(t *testing.T) {
 	}
 }
 
+// With more than one unknown key, ValidateStyleTokens names the sorted-first key so
+// the error is deterministic run-to-run (not whichever the map iteration yields).
+func TestValidateStyleTokens_MultipleUnknownDeterministic(t *testing.T) {
+	c := &Config{Styling: StylingConfig{Tokens: map[string]string{
+		"zzz_bogus": "x",
+		"aaa_bogus": "x",
+	}}}
+	err := c.ValidateStyleTokens()
+	if err == nil {
+		t.Fatal("expected an error for unknown token keys")
+	}
+	if !strings.Contains(err.Error(), "aaa_bogus") {
+		t.Errorf("error should name the sorted-first unknown key (aaa_bogus): %v", err)
+	}
+	if strings.Contains(err.Error(), "zzz_bogus") {
+		t.Errorf("error should name only the deterministic first key, not zzz_bogus: %v", err)
+	}
+}
+
 // ValidateStyleTokens accepts every key in KnownStyleTokens — guards against the
 // map and the validator drifting apart.
 func TestValidateStyleTokens_AllKnownKeysAccepted(t *testing.T) {