#242 — extract design-system layer: tokens/base partials + shared appearance.js

[cmbays]

Summary

Implements the #241 design decision's mechanical slice: re-layers templates/report.css into shared askama partials and shares the appearance engine, so the report and explore page families consume ONE design system structurally.

• templates/partials/tokens.css — the design-system ROOT: the semantic token layer + ALL 8 [data-theme] blocks, extracted verbatim (exact current values, zero value changes; the extracted range verified byte-identical to its report.css source before deletion).
• templates/partials/base.css — the minimal cross-family page chassis ([hidden], html/body token skin, link colors, select/input/textarea skin), moved only where cascade-order-safe. The report body geometry deliberately stays in report.css — it must keep winning the equal-specificity contest against the 720px responsive body rule (order-sensitive; documented in both files' banners and pinned by an asset_embed gate).
• templates/report.css — keeps the report-specific remainder (style packs, settings chrome, tokenized components, density overrides, reconciliation + coverage layers, incl. every per-theme surface-scoped AA override family).
• templates/appearance.js (window.CuteAppearance) — the minimal shared appearance engine: reads cute-dbt.appearance.v1, resolves the prefers-color-scheme default, applies [data-theme] + html.dark, [data-style], [data-density], [data-difflayout], [data-coverage] and the accent custom properties. Embedded by both page families.
• templates/theme.js — now the report-only settings UI (control wiring/sync, DataTables reflow, DAG-engine dispatch) driving the shared engine; the storage-key literal lives in exactly one file (asset_embed-pinned).
• Explore pages adopt the tokens: both pages include the tokens + base partials and the appearance engine; their inline styles re-express on the semantic tokens (values mapped, not redesigned). One deliberate exception, documented in DESIGN.md: canvas-paired legend/status chips keep the fixed canvas palette (the report's fixed-DAG-palette posture) so the legend can never desync from what the Cytoscape engines draw; fills/strokes with an exact token twin use the fixed --dag-* tokens.

Acceptance criteria → evidence

• ZERO visual diff on the report pages. CSS rule-stream audit (comments stripped, whitespace-normalized, brace-tracked statement split) of old committed golden vs new render: the 672 non-moved rules are identical in content and order; the only content delta is the body rule splitting into token-skin + geometry halves with unchanged combined declarations; the 8 moved chassis rules land after the token layer and before the first style-pack rule, and the @media 720px body rule still precedes the body-geometry rule (index 289 < 291). All 67 pre-existing headless guards pass UNMODIFIED (every contrast pin, tooltip, interaction and layout guard in tests/headless_toggle.rs): cargo test --test headless_toggle --locked -- --ignored → 71 passed (67 existing + 4 new).
• Explore pages honor cute-dbt.appearance.v1 and render correctly on all 8 themes — four new headless guards pin it (inventory below), RED on the pre-extraction pages, GREEN after.
• No token value invented or changed — tokens.css extraction verified byte-identical to the source range; an asset_embed gate now pins exactly one [data-theme] block per theme in tokens.css and zero bare theme blocks in report.css. The design: shared block-diff palette + muted-text surfaces sub-AA on latte/rosepine/solarized (measured) #251 sub-AA muted-token debt is untouched (out of scope by design).
• Goldens regenerate via the exact CI commands; git diff --text -U0 audited — see below; all five re-verified byte-identical against fresh renderer output after commit.
• DESIGN.md + templates/README.md updated in the same PR — source-of-truth map now roots the design system at partials/tokens.css; the "Planned change (task: extract the design-system layer — tokens/base askama partials + shared appearance.js consumed by both page families #242)" paragraph replaced with the landed state; the explore-gaps list shrunk to the remaining items (.lineage-tooltip contract retrofit → design: explore pages never adopted the design system — token/theme/appearance sync mechanism needed #241 design pass, explore settings affordance → feature: settings toggle to enable/disable coverage-intelligence display (report + explorer) #219, style packs/density report-only).

Goldens-diff explanation (git diff --text -U0 -- examples/)

All three report goldens (jaffle-shop, playground, diff-showcase) carry the identical 26-hunk shape, fully explained by the re-layering:

1. CSS banner/comment rewrites (report.css head banner describing the new layering; the tokens partial's own banner + end sentinel appearing where the token section sat).
2. The moved base-chassis rules ([hidden], html, body token-skin/geometry split, a/a:hover, select/input/textarea family) — the rule moves verified order-safe above.
3. The theme.js → appearance.js + settings-UI split (one <script> block became two; same THEMES/ACCENTS tables, same apply functions, same persistence shape — the existing appearance persist guard passes unmodified).

No hunk touches markup, payload, or any computed-style-affecting declaration beyond the verified moves. The two explore goldens are additive: the tokens + base partials, the appearance engine <script>, and the tokenized page styles.

New explore guard inventory (tests/headless_toggle.rs, all -- --ignored)

Guard	Quantification	Pins
explore_pages_boot_applies_the_appearance_attributes	both pages	html[data-theme] follows the saved→prefers-color-scheme→light contract; html.dark tracks the theme family (storage-free, never platform-pinned)
explore_pages_honor_the_saved_appearance_key	both pages	a saved cute-dbt.appearance.v1 theme + density hydrates at boot (reload + poll; storage-gated exactly like the report's persist guard)
explore_dag_page_themes_correctly_on_every_theme	8 themes × dag.html	body paints the theme's resolved --bg token AND page-title / legend-chip / legend-code clear WCAG AA 4.5:1 against the effective composited backdrop
explore_tests_page_themes_correctly_on_every_theme	8 themes × tests.html	same sweep over page-title / model-heading / model-path-code / the shared test-card's label

Measurement hygiene baked in: * { transition: none !important; animation: none !important } injected before measuring (the 120ms body transition), visibility asserted via checkVisibility() (never rect>0, never first-match sampling) with fail-loud absentee naming.

Gates (run directly — lefthook skips in fresh worktrees; the pre-push hook then re-ran the battery on push)

Gate	Result
cargo fmt --check	pass
cargo clippy --all-targets --locked -- -D warnings (by exit code)	pass
cargo nextest run	1261 passed
cargo test --test bdd	163 scenarios / 1044 steps passed
cargo test --test headless_toggle --locked -- --ignored	71 passed (67 existing unmodified + 4 new)
cargo test --test headless_zero_egress --locked -- --ignored	10 passed (both page families, regenerated goldens)
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --locked	pass
cargo deny check	pass
Golden byte-identity (all 5, fresh render vs committed)	pass

Scope discipline held: no token value changed (#251 untouched), no .lineage-tooltip contract retrofit (#241's design pass), no explore settings/coverage toggle (#219 stays blocked-by this and lands later), no explore visual redesign beyond token adoption.

Closes #242

🤖 Generated with Claude Code

---

[coderabbitai]

Warning

Review limit reached

@cmbays, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 53 minutes and 19 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 076d95b5-2e90-4a0a-8f78-e5fa94bebf34

📥 Commits

Reviewing files that changed from the base of the PR and between b2315c3 and 7953e79.

⛔ Files ignored due to path filters (2)

• tests/snapshots/golden_report__rendered_report_skeleton.snap is excluded by !**/*.snap
• tests/snapshots/render_integration__rendered_chrome_jaffle_shop.snap is excluded by !**/*.snap

📒 Files selected for processing (19)

• DESIGN.md
• examples/diff-showcase-report.html
• examples/explore/dag.html
• examples/explore/tests.html
• examples/jaffle-shop-report.html
• examples/playground-report.html
• src/adapters/asset_embed.rs
• src/adapters/explore.rs
• src/adapters/render.rs
• templates/README.md
• templates/appearance.js
• templates/explore-dag.html
• templates/explore-tests.html
• templates/partials/base.css
• templates/partials/tokens.css
• templates/report.css
• templates/report.html
• templates/theme.js
• tests/headless_toggle.rs

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch infra-242-design-system-extraction

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[ghost]

Ready to review this PR? Stage has broken it down into 7 individual chapters for you:

	Title
1	Update design system documentation
2	Extract shared CSS tokens and base partials
3	Implement shared appearance engine
4	Wire shared assets into Rust adapters
5	Integrate design system into templates
6	Verify changes in examples and tests
7	Other changes

_{Chapters generated by Stage for commit 7953e79 on Jun 12, 2026 1:30am UTC.}

[github-actions]

📄 Rendered report preview

All golden examples regenerated cleanly.

🟡 Golden examples

Committed to examples/ and byte-identity gated — the canonical reports contributors and consumers browse. Stable across PRs.

Report	View	Download
playground-report.html	▶ Open ↗	⬇ Download
diff-showcase-report.html	▶ Open ↗	⬇ Download
jaffle-shop-report.html	▶ Open ↗	⬇ Download

🐶 Live dogfood preview

This PR doesn't touch dbt-project/, so there's no live dogfood preview.

▶ Open ↗ opens the report in your browser in one click —
published to this repo's GitHub Pages under /pr-264/.
⬇ Download fetches the same self-contained HTML as a workflow
artifact (auth-gated; works fully offline). Either way the report
makes zero external resource requests.

The Pages preview may take ~1 min to update after this comment
posts. On PRs from forks the Open link is unavailable (read-only
token) — use Download.

Alternative: GitHub CLI

# gh CLI >= 2.63 extracts into ./report-preview-playground/.
gh run download 27388564100 -R breezy-bays-labs/cute-dbt -n report-preview-playground
open report-preview-playground/playground-report.html

---

_{Posted by report-preview.yml for 7953e7919314067f9d30628fb770aee75ec06937. Affordance only — never blocks merge.}

[gemini-code-assist]

Code Review

This pull request refactors the design system and appearance engine of cute-dbt by extracting core tokens and base styles into shared CSS partials, and moving the core theme-handling logic into a new shared templates/appearance.js script. This enables both the report and explore pages to consistently consume the same design system and honor saved user preferences. Headless integration tests have also been added to verify theme application and WCAG contrast compliance. The review feedback suggests improving compatibility with older ES5 engines by avoiding the two-argument classList.toggle() in the shared appearance script, and adding a defensive guard in templates/theme.js to gracefully handle cases where the shared appearance engine fails to load.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[cmbays]

Adversarial verification report (orchestrator; 5 serial refutation agents, real Chromium over localhost, main b2315c3 vs PR 7953e79).

Claim	Verdict	Evidence headline
C1 zero visual diff on report pages	HELD (high)	35-prop computed-style sweep over EVERY body descendant: jaffle 497/497, diff-showcase 2531/2531 identical (light+dark, 1280px+375px); pixel diff 0–1px = same-file Mermaid antialiasing noise floor (controls: main-vs-main shows the identical 1px); 375px body geometry identical — the split-body-rule risk did not materialize
C2 appearance hydration on all 3 pages	HELD (high)	cute-dbt.appearance.v1 round-trips on dag/tests/report (data-theme + resolved --bg painted); corrupt JSON / wrong-shape / garbage payloads all degrade to sane light default, zero console errors
C3 AA 4.5:1 across all 8 themes on explore pages	REFUTED (high)	5 of 8 themes fail on ≥1 surface (worst: solarized links 3.41, rosepine muted 3.53). Classification: every failing combo is byte-identical to main's report-page tokens — pre-existing #251 debt newly EXPOSED on explore, not new values. Fixed canvas chips pass 14.87+ everywhere (the builder's by-construction claim holds). Routed to #251 with the full matrix + a token-AA-matrix-guard AC; recommend #251 next in render lane after this merges
C4 settings panel + interaction parity	HELD (high)	Element-for-element panel parity; theme/density/style/accent/difflayout/engine/coverage all apply+persist; Cytoscape↔Mermaid reversible; fold-only-in-Diff rule holds; full button census identical; 0 console errors both sides
C5 zero-egress on all 5 pages	HELD (high)	Exactly 1 network request (the document) per page after interaction incl. engine switches; structured resource-ref lint clean (data: favicon only; remaining hits are inert minified-bundle string literals)

Merge posture: the extraction itself is verified clean (C1/C2/C4/C5). C3 is pre-existing token debt that #242's own AC (exact current values; #251 out of scope) correctly excluded — fixing values here would break the zero-visual-diff review contract. Known consequence of merging: explore pages carry the sub-AA combos on 5 themes until #251 lands. Founder's call; held unmerged.