feat(ui): token foundation and Cooklang palette, existing layout kept

[dubadub]

Rebuilds the web UI's styling on a Tailwind v4 CSS-first token layer and adopts the Cooklang design-system palette with flat, hairline-bordered surfaces. Every page keeps the layout, spacing and dimensions it has on main.

This replaces the earlier version of this PR, which bundled the same foundation with a density pass (48px app bar, 60px index rows, sticky ingredient rail, compact lists). The density work is dropped; the foundation, palette, type scale and bug fixes are kept.

Foundation

• input.css is fully CSS-first: @import "tailwindcss" source(none) with explicit @source lines and @custom-variant dark replace tailwind.config.js, which is deleted. Only templates, static/js, and the one Rust file that emits class names are scanned, so nothing from docs/ leaks into the built CSS.
• Twenty semantic tokens (--bg, --surface, --text, --accent, …) registered with @theme inline, so bg-surface / text-muted / border-line are real utilities that flip under .dark with no override rules.
• components.css holds the component vocabulary (.card, .btn, .btn-sm, .icon-btn, .nav-card, .nav-pill, .menu-item, .recipe-card, .step-box, .ingredient-row, .pantry-item, .stepper, …), every one sized to what main rendered. Every colour resolves through a token; no raw hex outside @media print.
• Deleted: custom-styles.css (shadowed output.css), styles.css (unreferenced), and the ~450-line .dark .* override block in base.html. The print block is rewritten against the current markup.

Look

Cooklang DS palette, no gradients, one accent, 6px radii, hairline borders, two-value elevation scale. Inline entities are weight + tint (ingredients) and a dotted underline (cookware), so the distinction no longer rests on a red/green hue pair. Cook mode is on the same tokens.

Type

Seven-step scale with per-step line-heights; Tailwind's size names are aliased onto it. Page titles stay at 30px. Recipe step text keeps its 2.0 leading.

Behaviour fixes carried over or found in review

• Index sorter reads data-name, collates numerically, persists in sessionStorage; covered by a new recipes-sort.spec.ts.
• Scale changes preserve scroll position; the −/+ stepper shares adjustScale with the keyboard shortcuts. The scale URL is built from a JSON-encoded path, which fixes scaling for recipes whose name contains & or an apostrophe, and empty or out-of-range values no longer navigate to a 400 page. The menu page uses the same code.
• Every page has exactly one h1 and no skipped heading level (shopping list and error page gained theirs).
• Cook mode is legible in light theme and its step capture no longer scrapes layout utilities.
• Print path works from dark theme.
• CodeMirror dark caret and gutters (rules moved out of @layer).
• Pantry out-of-stock quantities are red again (a utility on the element had been beating the state rule); the new-recipe form's error border shows again (two stacked border utilities).
• menu_api_test.rs no longer pins CSS classes; recipe-display.spec.ts lost its vacuous guard; the pantry spec asserts the out-of-stock colour; preference toggles expose aria-pressed.

Verification

• cargo fmt, cargo clippy --all-targets, cargo test clean.
• Playwright (Chromium, serial): 143 passed, 5 pre-existing skips, 0 failed.
• Each page compared against main at 1440/1024/820px in light and dark; print preview checked from dark theme; static build checked over file://.

Follow-ups (pre-existing on main, not addressed here)

• The recipes index sorts server-side by byte order (src/web/builders.rs) while the client re-sorts with a natural collator, so the no-JS first paint of the static site can differ from the JS order.
• The server-mode inline search script in base.html interpolates recipe names into innerHTML unescaped; search.js (static mode) escapes. A recipe name containing < breaks the row.
• Icon-button aria-labels ("Toggle theme", "Dismiss", "Increase scale", …) are hard-coded English rather than locale keys.
• clearList() on the shopping list adds hidden to #shopping-list-results and nothing removes it, so the empty-state message is invisible until reload.
• The editor's syntax-highlight colours in static/js/src/editor.js are raw hex and not theme-aware.
• Opening /edit/… fires an autosave immediately, showing "Saved" with no edits.
• /api-docs skips from h2 to h4 inside endpoint articles; sectioned recipes render section names as h3 under the page h1.
• The static-site writer copies the whole embedded static/ tree, so input.css and components.css source ship alongside output.css.

Spec: docs/superpowers/specs/2026-09-04-web-ui-tokens-design.md. Plan: docs/superpowers/plans/2026-09-04-web-ui-tokens.md.

https://claude.ai/code/session_013urND2B6Y3Z7WQuDpE8ZDu

[claude]

Review: feat(ui) design refresh with semantic tokens

Went through the diff file by file (design tokens/components.css, the JS that got repointed at new class names, and every migrated template). Overall this is a careful, well-reasoned refactor — the in-code comments explaining why (cascade-layer specificity for CodeMirror, the hidden-vs-inline ordering trick, the .cooking-overlay token scoping, the shopping-list race condition notes) are genuinely useful and make the diff much easier to trust than a typical mass-restyle.

Strengths

• Design tokens are applied consistently almost everywhere. Raw text-gray-900 dark:text-gray-100-style utility pairs are gone in favor of text-text/text-muted/etc., which is exactly the point of the change and should make future dark-mode bugs much rarer.
• XSS hygiene is solid in the touched JS. shopping_list.html and search.js consistently run user/recipe data through escHtml/escapeHtml before interpolating into innerHTML, including in spots that were rewritten from scratch (renderRefs, category/pantry rendering).
• Deliberate preservation of E2E-load-bearing class names (.nav-pill, .recipe-card, .ingredient-badge, .metadata-pill) is called out and honored — good discipline for a change this wide.
• Real bugs fixed along the way are legitimate and independently verifiable from the diff: cooking-mode.js was scraping .md\:col-span-2 ol / .leading-8, both deleted by the recipe template migration, and is correctly repointed to .step-list / .step-body. The pantry's applyFilter() no longer reaches for the recipes-index's .recipe-card/.grid.
• tests/e2e/tablet.spec.ts is a good regression net for the actual motivating use case (tablet in the kitchen), and the recipe-display.spec.ts fix (if (metadataPills.count() > 0) silently skipping all assertions) is a genuine test-coverage improvement, not just a refactor.

Issues

1. Incomplete token migration: API docs method badges still use raw Tailwind palette classes.
   src/web/templates.rs (EndpointDoc::method_classes, ~line 743) still returns hardcoded bg-blue-100 text-blue-800 dark:bg-blue-900 dark:text-blue-200-style strings for the GET/POST/PUT/DELETE badges in templates/api_docs.html. Every other color in this PR was intentionally routed through the new --info/--ok/--accent/--danger tokens (per the comment in input.css: "Do not introduce raw hex values or Tailwind palette utilities in templates"), so this is the one remaining spot still hand-picking a light/dark pair per method. Minor, but worth a follow-up so the api-docs page doesn't silently diverge from the rest of the dark-mode contrast work that was otherwise verified for AA compliance.

2. Scroll-preserving rescale wasn't ported to the menu page.
   templates/recipe.html now calls goToScale(this.value) on the scale <input>'s onchange, which stashes scrollY in sessionStorage before navigating so a rescale doesn't dump you back at the top (called out explicitly in the PR description as a fix). templates/menu.html has the identical stepper UI (−/+ buttons calling the same adjustScale()), but its <input> still wires onchange="window.location.href = ... + '?scale=${this.value}' + " directly — the old behavior. Since adjustScale() dispatches a change event on the same input, using the stepper on a menu page still jumps back to the top. Looks like a straightforward miss rather than an intentional difference; would be a one-line fix to swap in goToScale() there too.

3. docs/superpowers/ adds ~2,700 lines of planning/spec/mockup docs to the tree.
   docs/superpowers/plans/…-web-ui-refresh.md (2114 lines), the design spec (224 lines), and a standalone mockup HTML (395 lines) make up more than half the diff's line count. This is clearly high-quality planning material, but it's not referenced by CLAUDE.md as a documented convention, and it's the kind of implementation-process artifact that often ages poorly once merged (task checklists, "measured baseline" tables, environment-specific notes like the macOS Playwright workaround). Worth a quick check with the team on whether this should land in the repo permanently vs. staying attached to the PR/issue.

Nits

• recipes.html still emits data-modified/data-created attributes on every recipe card even though the client-side sorter that read them was deleted in this same PR. Harmless, but dead weight in the rendered HTML unless it's intentionally there for a future server-side sort.
• Pre-existing (not introduced here) but adjacent to code this PR touches: the inline recipe-search dropdown built in templates/base.html interpolates ${recipe.name} into innerHTML without escaping, whereas the sibling implementation in static/js/search.js does escape via escapeHtml. Given recipe titles are local/user-authored content it's low severity, but since this PR already touches that exact block (just for class names) it might be worth folding in the same escaping for consistency.
• static/css/input.css and a couple of other touched files end without a trailing newline (pre-existing, not this PR's doing, but flagged since they're right next to new content).

Test coverage

E2E additions look appropriately targeted (tablet.spec.ts, the corrected metadata assertions, the loosened method-badge regex in menu_api_test.rs). No Rust logic changed outside of test files, so cargo test/clippy/fmt claims in the description are plausible as stated. I didn't run the Playwright suite myself as part of this review.

No security concerns beyond item 2 above (which is a UX regression, not a vulnerability) — the escaping discipline in the rewritten JS is good.

[claude]

Review: feat(ui): design refresh — token system, Cooklang palette, Primer structure

Reviewed the full diff (gh pr diff 456, 28 files) against CLAUDE.md's conventions (token-driven CSS, Askama templates, Playwright/cargo test gates). Overall this is a well-executed, unusually well-documented refactor — the write-up below focuses on what needs attention before merge, but the design-system foundation itself is solid.

Strengths

• The 17-token contract in static/css/input.css (--bg, --surface, --text, --accent, …) wired through Tailwind's @theme inline is a real improvement over the ~330-line hand-maintained .dark .* override block it replaces — one source of truth per color, and it was verified there's no raw hex outside token definitions and the @media print block.
• Deleting custom-styles.css and styles.css (dead/silently-conflicting stylesheets, one of them shipping a .btn-primary that visibly disagreed with itself on hover) is good cleanup, not just churn.
• adjustScale() reuse between keyboard shortcuts and the new −/+ stepper buttons is clean — no duplicated scaling logic.
• The cooking-mode selector fix, the CodeMirror @layer components cascade fix, the print-stylesheet reset, and the class-agnostic tests/menu_api_test.rs regex all check out against the diff — these aren't just claimed in the description, they're actually there.
• New test coverage (tests/e2e/recipes-sort.spec.ts, tests/e2e/tablet.spec.ts) is substantive rather than smoke-test-shaped, and the previously-vacuous assertion in recipe-display.spec.ts (guarded behind if (metadataPills.count() > 0), which had silently become uncheckable) is genuinely fixed.
• The sort feature's sessionStorage read is guarded with a corrupt-JSON fallback, and uses Intl.Collator with numeric collation instead of bare localeCompare — correctly fixes the "Recipe 10 sorts before Recipe 9" class of bug.

Findings

Moderate — theme-toggle transition race not fully eliminated.
The PR description says all token-colour CSS transitions were removed to fix a Chrome custom-property-invalidation race (recipe cards briefly staying white after .dark toggles). components.css does strip transition from .btn:hover / .recipe-card:hover with a comment explaining why. But templates/base.html's mobile #more-dropdown nav links and the search-result links (static/js/search.js / base.html's inline handler) still pair transition-colors with token-backed hover colors (hover:bg-sunk hover:text-text) — the exact pattern removed elsewhere. Worth confirming whether these were intentionally left in (maybe they don't respond to the initial .dark flip since they're not visible at toggle time) or missed in the sweep.

Moderate — scale stepper buttons behave inconsistently between recipe.html and menu.html.
templates/menu.html picked up the same new −/+ scale buttons as templates/recipe.html, but only recipe.html wires them to goToScale() with the sessionStorage scroll-position preservation described in the PR. On the menu page, clicking the stepper still does a bare window.location.href navigation, dropping the user back to the top — the exact "scale tap jumped you back to the top" bug the PR set out to fix, still present on one of the two pages that got the new control.

Nit — planning artifacts committed to docs/.
docs/superpowers/plans/2026-08-15-web-ui-refresh.md and the paired spec/mockup files (~2,700 lines combined) read as internal AI-assisted planning narration (task-numbered, e.g. "Task 4", "Task 13") rather than reference documentation. Worth a call on whether these belong in the shipped tree or should stay out-of-band.

Nit — missing trailing newline.
static/css/input.css (and the deleted custom-styles.css) don't end in a newline; minor, but worth a pass for tracked text files.

Not flagged, but worth confirming before merge

Per CLAUDE.md, please confirm cargo fmt, cargo clippy, and cargo test are clean, and that the Playwright suite result quoted in the description (148 passed / 0 failed / 5 skipped) is reproducible on CI rather than only locally — the shopping-list race noted as "pre-existing" is fine to leave, just flagging it's environment-dependent (serial execution requirement) rather than fixed here.

No security issues found — XSS hygiene (escHtml usage, Askama auto-escaping) looked consistent everywhere it was touched, and no unvalidated sessionStorage/user input reached innerHTML or a URL sink.

---

🤖 Automated review generated with Claude Code

[claude]

Review: Tailwind v4 token foundation + Cooklang palette

This is a large but well-scoped refactor - the diff is dominated by mechanical class-name substitutions, and the actual logic changes are small, deliberate, and well commented. Overall this is high quality work. Notes below.

Strengths

• Token architecture is clean and consistent. input.css's CSS-first @theme inline setup, the .dark/.cooking-overlay co-registration, and the @media print token override are a good use of Tailwind v4. Every color in components.css resolves through a token - no raw hex leaked in, as promised.
• Real dead-code removal, not just a coat of paint. custom-styles.css, styles.css, tailwind.config.js, and the ~450-line .dark .* override soup in base.html are gone outright rather than left to rot alongside the new system.
• Good defensive JS fixes bundled in:
  • adjustScale/goToScale (static/js/keyboard-shortcuts.js, templates/recipe.html, templates/menu.html) now guard against NaN from a cleared input instead of silently navigating to ?scale=NaN.
  • sessionStorage access in the scroll-restore and sort-persistence code is wrapped in try/catch for private-browsing/quota failures.
  • templates/recipe.html's showError banner switched from interpolating ${message} directly into innerHTML to building the node and setting .textContent - a real (if unstated) XSS-hardening fix, not just a style change.
• Test coverage grew with the behavior changes - recipes-sort.spec.ts is thorough (corrupt sessionStorage, reload persistence, directory grouping, a11y label), and the new recipe-scaling.spec.ts cases target the exact NaN/encoding fixes above.
• The PR description's disclosed list of pre-existing, out-of-scope issues (unescaped search innerHTML in server mode, clearList() leaving the empty state hidden, hardcoded aria-label strings, the API-docs h2->h4 skip) all check out against the diff - nice transparency, and I didn't re-flag any of those.

Issue found

templates/shopping_list.html: heading order regression, contradicts the PR's own claim. The PR description states "Every page has exactly one h1 and no skipped heading level (shopping list and error page gained theirs)." In the current diff:

• Lines 10 and 16: the sidebar renders <h2>{{ shopping-selected-recipes }}</h2> and <h2>{{ shopping-in-pantry }}</h2>.
• Line 47: the page's only <h1> ({{ shopping-title }}) lives inside #shopping-list-header, which sits after the sidebar in DOM order and starts with the hidden class, only unhidden once setHeaderVisible(shoppingList.length > 0) determines the list is non-empty.

Two consequences:

1. Even once populated, a screen-reader user navigating by heading level encounters h2 -> h2 -> h1 - the two subsection headings precede the page's only top-level heading, with nothing above them.
2. On first paint / empty-list state, the h1 is display: none and never enters the accessibility tree at all - the page exposes zero h1s.

Since this is the exact page the PR calls out as fixed, it's worth a follow-up rather than filing as a new pre-existing item: either move #shopping-list-header (or at least the <h1>) above the sidebar in markup, or demote the two sidebar labels to .card-head style text instead of real headings if they're meant to be secondary content, not page structure.

Minor / non-blocking

• goToScale() is duplicated near-verbatim between templates/recipe.html and templates/menu.html (both ~15 lines, identical clamping logic). Given adjustScale was already extracted to keyboard-shortcuts.js and shared via window.adjustScale, goToScale could follow the same path - not urgent, just a spot where the "one place for this logic" principle stated in the PR description isn't fully carried through.

Nice work overall - the token layer, dark-mode handling, and print styles all look correct, and the accompanying Playwright coverage gives good confidence the visual refactor didn't regress behavior.