left4me/docs/superpowers/specs/2026-05-17-stylesheet-redesign-design.md

Stylesheet redesign

Context

The current stylesheet is ~1,436 LOC across six files in l4d2web/static/css/: tokens.css (84 LOC), layout.css (42), components.css (1,177; ~196 class selectors), logs.css (13), console-autocomplete.css (88), editor.css (32). Tokens are real (CSS custom properties, light + dark via prefers-color-scheme), but components.css grew organically: 196 classes accumulated without a budget, specificity is uneven, and the same idea ("state pill") is expressed several ways in different places.

The result reads as "developer wrote some CSS" rather than "this is a system." That is a problem for human readers and a bigger problem for agentic development — when an LLM agent adds a feature, the cheapest path is to re-implement whichever pattern happens to be in its context window, which re-introduces the inconsistency the next agent then has to imitate. The incoherence compounds.

This redesign replaces the current stylesheet with a small, explicitly-tiered design system: two-tier tokens, an @layer-ordered cascade, a budgeted set of component classes, a handful of macros where markup correctness is load-bearing, and a live style guide that is the single canonical reference contributors (and agents) read before producing new UI.

Goals

• Coherent visual — every page in l4d2web reads as one system, in light and dark mode.
• Agentic-development friendly — an agent given a UI task can produce styled output by reading one file (the style guide) and following the conventions there. No tribal knowledge required.
• Smaller surface area — components.css's 1,177 LOC + 196 classes collapses to a deliberate ~400 LOC budget covering exactly the primitives used across the app; project-specific widgets live in their own files.
• Enforced cascade — specificity is determined by @layer order, not selector specificity, so adding a component never accidentally beats utilities or fights element defaults.
• Closed system — every page element comes from the catalog. New widget? Extend the system, then use it. No inline style="", no inventing class names off-system.

Non-goals:

• Adopting any CSS framework as a base. Pico v2, Simple.css, Bulma, and Tailwind were considered and rejected; see "Decisions" below.
• Changing the markup of project-specific widgets (file-tree, overlay-picker, console-autocomplete, CodeMirror skin, log viewer, live-state). They get relocated into the new file layout but keep their existing structure.
• Changing routes, blueprints, or htmx contracts.
• Adopting Open Props or any external token library. The refined tokens.css remains the single source of truth.
• Build-step tooling. No Sass, no PostCSS, no bundler. Plain CSS using modern features (@layer, color-mix(), CSS custom properties) the production browsers already support.

Architecture

The eight layers

The cascade order is declared once in the entry stylesheet:

@layer reset, tokens, elements, layout, components, widgets, utilities;

Each layer has one responsibility:

#	Layer	Contains	File(s)
1	reset	Modern reset (Andy-Bell / Josh-Comeau-style; ~30 LOC)	reset.css
2	tokens	Primitives + semantic tokens, light + dark	tokens/primitives.css, tokens/semantic.css
3	elements	Bare HTML defaults: body, h1-h6, a, code, kbd, hr, form elements, tables	elements.css
4	layout	Composition primitives: .container, .stack, .stack-h	layout.css
5	components	Named widgets: .btn, .field, .table, .panel, .modal, .tabs, .badge, .nav, .dropdown	components/<name>.css
6	widgets	Project-specific composites: .file-tree, .overlay-picker, .console-autocomplete, log viewer, editor skin	widgets/<name>.css
7	utilities	Single-purpose overrides: .muted, .mono, .truncate, .sr-only	utilities.css

The single entry file (main.css) declares the layer order and @imports the rest. base.html swaps its current five <link> tags for one <link rel="stylesheet" href="…/main.css">.

File layout

l4d2web/static/css/
  main.css                       ← @layer order + @imports
  reset.css
  tokens/
    primitives.css               ← raw palette: --gray-100, --blue-700, --space-4, --text-base, …
    semantic.css                 ← aliases: --color-primary, --color-bg, --space-m, …
                                   plus the data-theme="dark" branch
  elements.css                   ← bare HTML defaults
  layout.css
  components/
    button.css
    field.css
    table.css
    panel.css
    modal.css
    tabs.css
    badge.css
    nav.css
    dropdown.css
  widgets/
    file-tree.css                ← moved from current components.css
    overlay-picker.css           ← extracted from current components.css
    console-autocomplete.css     ← moved (currently at static/css/ root)
    editor.css                   ← moved
    logs.css                     ← moved
    live-state.css               ← extracted from components.css
  utilities.css

Tokens — two tiers

Tier 1 (primitives) in tokens/primitives.css is the raw palette: ~30 custom properties for the grayscale ramp, brand blue ramp, semantic state colors (red / green / amber), spacing scale, type scale, radii, shadow scale, motion durations and easings, and font stacks. No semantic meaning. The primitives never appear in component CSS directly — they are consumed only by semantic tokens.

Tier 2 (semantic) in tokens/semantic.css aliases primitives by role: --color-bg, --color-surface, --color-text, --color-muted, --color-border, --color-primary, --color-on-primary, --color-danger, --color-warning, --color-success, --color-focus, plus --space-s, --space-m, --space-l, --radius-s, --shadow-sm, --shadow-md, etc. Dark mode lives here, in a [data-theme="dark"] selector — the primitives do not change between modes; the semantic aliases re-point at different primitives. This keeps dark mode in one file instead of duplicated inside a @media (prefers-color-scheme: dark) block.

A rule the agent can follow mechanically: components reference only semantic tokens (var(--color-*), var(--space-*), etc.). Raw hex codes appear only in tokens/primitives.css. This rule is codified in AGENTS.md and is the simplest possible expression of the two-tier contract.

Dark mode is opted into by setting data-theme="dark" on the <html> element. The initial value comes from prefers-color-scheme via a small inline script at the top of <head> (avoids a flash of wrong theme on first paint); a future user-preference toggle would write to localStorage and override the OS default. Implementing the toggle is out of scope for this redesign — the redesign only ensures the mechanism is in place.

Components — class-based, CSS-only

Vocabulary (the components layer in full):

• .btn with variants .btn-primary, .btn-secondary, .btn-danger, .btn-outline, .btn-link, plus .btn-sm. States: [disabled], [aria-busy="true"] (loading). Loading state shows a spinner via a CSS animation; no extra markup required.
• .button-row — flex+gap container for groups of buttons.
• .field — wrapper containing .field-label, input / select / textarea, optional .field-hint, optional .field-error. Error state uses native [aria-invalid="true"] on the input — no separate .field-input-error class. Hint/error text is associated via aria-describedby (enforced by the macro; see below).
• .inline-save — flex layout for the input + submit pair used several places today (.inline-save exists already; conventions preserved).
• .table — bordered, slight zebra optional via .table-striped.
• .panel — bordered card with optional .panel-heading, .panel-body, .panel-footer. Subsumes the current .panel / .card aliases.
• .modal — styles <dialog>. Optional .modal-wide for the wider variant already used today. Header / body / footer subdivisions. The existing modals.js open/close machinery is unchanged.
• .tabs with .tab and .tab-panel. State is encoded as [aria-selected="true"] on the tab — no .tab-active class. The existing tabs.js reads and writes those ARIA attributes already; no JS changes needed.
• .badge with semantic variants (.badge-success, .badge-warning, .badge-danger, .badge-muted) and state variants (.state-running, .state-stopped, .state-unknown, .state-transient, .state-drift). The state variants exist today; preserved for templating continuity.
• .site-header + .primary-nav + .account-nav + .brand — already present, restyled on the new token base.
• .dropdown — styling around native <select> and a small custom menu pattern if needed.

State as ARIA attributes, not modifier classes: [disabled], [aria-busy="true"], [aria-selected="true"], [aria-invalid="true"]. This avoids the class-vs-aria drift that produces broken accessibility.

Variant naming convention is uniform: <component> <component>-<variant> <component>-<size>. No exceptions. New variants must be added to the component's file and to the style guide entry in the same commit.

Macros — five high-leverage primitives

A new directory l4d2web/templates/ui/ adds Jinja macros for primitives where markup correctness is load-bearing — i.e., where hand-assembling gets accessibility wrong easily:

Macro file	Macros	Why
ui/_field.html	ui.field, ui.checkbox, ui.select	Owns <label for>/<input id> pairing, aria-describedby wiring for hint+error, aria-invalid on error
ui/_modal.html	ui.modal	Owns the <dialog> + modal-header/modal-body/modal-footer structure and the close-button + JS hooks
ui/_tabs.html	ui.tabs, ui.tab_panel	Owns the role="tablist" / role="tab" / role="tabpanel" + aria-controls / aria-selected wiring
ui/_confirm_form.html	ui.confirm_form	Owns CSRF token, POST action, and standard button row for destructive actions
ui/_badge.html	ui.badge_state(state)	Maps a server-state string to the correct state-* class — encapsulates a real source of inconsistency today

CSS-only is the default for trivial primitives — <button class="btn btn-primary">Save</button> is its own canonical form and does not need a macro wrapper. The macro tier is reserved for "if you forget a piece of this, the result is silently wrong."

Existing partials (_console_line.html, _overlay_file_tree.html, _overlay_picker_*.html, _recent_players_modal_body.html, _server_actions.html, _live_state.html) are unaffected. They are page-scoped composites that solve a different problem from ui/*; they keep their current shape and just reference the new class names. _macros.html continues to host CSRF/utility helpers.

Workflow principle — the system is closed

The redesign codifies a hard rule:

Every page element comes from the catalog. If the catalog lacks what you need, extend the catalog first, then use it.

What this means in practice:

• Adding a feature with existing widgets → just use them.
• Adding a feature that needs a new widget → three-step extension:
  1. Add the CSS to components/<name>.css or widgets/<name>.css.
  2. Add a style guide entry: rendered example + escaped source HTML, with at least one "do" example, and a "don't" entry if there's a foreseeable wrong way to use it.
  3. If the widget is composite or a11y-load-bearing, add a macro under templates/ui/.
  4. Only then use the widget on the page.
• New variant of an existing widget → add the variant class to the widget's CSS, add a style guide entry showing the variant alongside the existing ones, then use it.
• Page-specific tweak that doesn't reuse → it still gets a name and lives under widgets/. Documented in the style guide as "used only on X page." The bar is "documented" not "reused" — a singleton with a proper home is acceptable.
• One-off inline style="" → forbidden.

Enforcement is light and layered:

1. Cultural — code-review checklist: "did this change add UI without going through the system?"
2. Documented — AGENTS.md carries the rule verbatim so agents see it first.
3. Style guide is the source of truth — if a widget isn't in templates/styleguide.html, it doesn't exist; PRs adding widgets must update the style guide in the same commit.
4. Optional lint (deferred, post-redesign) — a small script scanning templates/*.html for style=", magic hex colors, and class names not present in the style guide. Cheap to add later; not blocking for this work.

The principle has an explicit cost: a feature that needs a new widget pays "add widget first" overhead. For human contributors that can feel slow; for agentic dev, the cost is much lower — an agent can extend the system in the same session, in the same commit, without context-switching. This is exactly the kind of friction that compounds positively.

Style guide

A new public route at /styleguide rendering templates/styleguide.html. Mounted by a small new blueprint l4d2web/routes/styleguide_routes.py. Public access (no login required) — it leaks nothing sensitive and a linkable URL is genuinely useful in PR descriptions and chat.

Each primitive gets a section showing:

1. The rendered widget, multiple variants if applicable.
2. The source HTML, captured once via {% set src %}…{% endset %} and rendered twice — once as {{ src|safe }} (the live widget), once inside <pre><code>{{ src|trim|e }}</code></pre> (copy-paste source). This guarantees the rendered example and the displayed source cannot drift.
3. Do / don't blocks on at least field, modal, tabs, and badge (the most-likely-to-be-screwed-up primitives). Format:
   • ✅ DO — correct example + source + one sentence on why it's right
   • ❌ DON'T — anti-pattern example + source + one sentence on what breaks (a11y wiring missing, wrong state class, etc.)

A token reference table at the top (or in a dedicated section) shows color swatches, spacing scale, type scale, shadow scale. Manually maintained as a Jinja loop over a Python dict — not parsing CSS. Stays in sync via the "add widget = update style guide" rule.

A dark-mode toggle button at the top of the style guide sets data-theme="dark" on <html>. Useful well beyond the style guide; included here because the style guide is the natural place to introduce it.

An entry in AGENTS.md:

## UI work

Before adding any UI markup:

1. Read `l4d2web/templates/styleguide.html` — it lists every available widget
   with a canonical example.
2. If your change needs a widget that isn't in the style guide, add it to
   the system FIRST:
   - CSS goes in `components/<name>.css` or `widgets/<name>.css`
   - Style guide entry with rendered example + source + at least one do/don't
   - If composite/a11y-bearing, add a macro in `templates/ui/_<name>.html`
   - Only then use the widget on the page
3. Never inline `style="…"` attributes.
4. Never invent class names outside the system.
5. Use only `var(--color-*)`, `var(--space-*)`, etc. in component CSS —
   raw hex codes appear only in `tokens/primitives.css`.

What the spike validated

A throwaway spike at /spike (gated on LEFT4ME_SPIKE=1) compared three options on a representative page: Pico v2 as base, Simple.css as base, and the proposed pure-custom design with the 8-layer cascade. The spike artifacts live at l4d2web/templates/spike.html and l4d2web/static/css/spike/{pico,simple,custom}.css.

Findings:

• Pico v2 required ~50 LOC to remap our semantic tokens onto its --pico-* variables, plus a width: auto override on buttons to undo Pico's full-width-in-form default. Every customization needs the "find Pico's variable → look up the docs → override" dance. The custom widgets (file-tree, overlay-picker) sit next to Pico-styled primitives in two-dialects mode.
• Simple.css was smaller and less opinionated, but its blog-flavored typography (large H1/H2/H3) and per-<section> top borders surprised in ways that would keep biting. ~165 LOC custom on top.
• Pure custom at ~280 LOC reads top-to-bottom as a design system: reset → primitives → semantic → elements → layout → components → widgets → utilities, each in its own @layer. No translation layer, no override-fights. The @layer cascade specifically means the agent writing new component CSS doesn't have to think about specificity at all.

Pure custom won on the criterion you weighted highest ("bad code feel leads to incoherent styling later"). The spike's custom.css is the seed for the production stylesheet; it is not the final form, but the layer ordering, the token shape, and the component vocabulary are validated.

Migration plan

One branch, work directly on master (per user preference), staged as clean commits each of which leaves the site functional (visual transition may be visible mid-series, which is fine):

1. Foundation — add main.css, reset.css, tokens/primitives.css, tokens/semantic.css. Old files still in place; base.html unchanged. Nothing renders differently.

2. Elements + layout — add elements.css, restructure layout.css into the new shape. Switch base.html to a single <link rel="stylesheet" href=".../main.css">. Old components.css no longer loads — pages look bare. Intentional and visible.

3. Core components — add components/button.css, components/panel.css, components/table.css, components/badge.css, components/nav.css. Half the surface starts looking right again.

4. Composite components + macros — add components/modal.css, components/tabs.css, components/field.css, components/dropdown.css, plus templates/ui/_field.html, _modal.html, _tabs.html, _confirm_form.html, _badge.html. Update templates that use these primitives to invoke the macros where appropriate.

5. Project widgets — move file-tree, overlay-picker, console-autocomplete, editor, logs, live-state into widgets/<name>.css. This is largely content-preserving — rename token references to the semantic-token namespace, otherwise the rules carry over.

6. Style guide — add routes/styleguide_routes.py, templates/styleguide.html with every primitive + do/don't blocks, token reference table, dark-mode toggle button. Update AGENTS.md with the UI workflow section.

7. Cleanup — delete the old components.css, the old tokens.css, the old root-level logs.css / console-autocomplete.css / editor.css (now under widgets/). Delete the spike artifacts in the same commit: l4d2web/static/css/spike/, l4d2web/templates/spike.html, l4d2web/routes/spike_routes.py, l4d2web/static/vendor/css/, and the if spike_enabled(): app.register_blueprint(spike_bp) block in app.py (plus the spike_routes import). Run the existing Chromium e2e suite and the pytest suite. Walk the major pages (dashboard, servers, server detail, overlay detail, blueprint detail, profile, admin) in light and dark mode, fixing any regressions in this commit.

The spike was scaffolding for the framework decision; once the design is in main.css, it is no longer load-bearing.

Per-commit verification: open the dev server (scripts/dev-server.py, which serves LEFT4ME_ROOT=.tmp/dev-server with seeded demo content), walk through the affected pages, fix any regressions in the same commit. Each commit should leave the functionality working even if mid-series visuals are transitional.

Decisions log

A summary of the brainstorm decisions and why, in case future-me needs to revisit them.

• Custom system, not a framework base. Pico, Simple.css, and Bulma were each considered. Pico is the only "minimal classless framework" with admin-app component coverage; the rest are blog-scale typography systems. The spike showed that even Pico's coverage costs ~50 LOC of token translation + override-fights, while the pure-custom path costs only ~+100 LOC and yields a much cleaner code surface. The "code feel bites incoherence later" criterion tipped this decisively.
• No Tailwind / utility-first. Off the table per user preference.
• No build step. No Sass, no PostCSS, no bundler. Modern CSS (@layer, color-mix(), custom properties) suffices and matches the project's zero-build philosophy.
• Two-tier tokens, not three. Three-tier (primitive / semantic / component-scoped, as in Material 3 or Adobe Spectrum) is over-engineered for a project this size. Two tiers buy clean dark mode and unambiguous agent rules without the indirection cost.
• @layer for cascade. Underused, well-supported since 2022, exactly fits the "layered design system" mental model. Replaces specificity hacks with declared layer ordering.
• Macros for five high-leverage primitives, CSS-only for the rest. The macro tier exists where forgetting a piece of markup silently breaks accessibility. Buttons and panels don't qualify; fields and modals do.
• Style guide as enforcement, not just documentation. Tied to a workflow rule ("the system is closed"), referenced in AGENTS.md, with do/don't anti-pattern blocks. Most leveraged change for the agentic-dev goal.
• Spike artifacts kept until cleanup commit. They seeded the decision; they go away when the production system lands.