docs: stylesheet redesign design
Replaces the current ~1.4k LOC stylesheet with a tiered design system: @layer-ordered cascade, two-tier tokens, budgeted component classes, five high-leverage macros, in-app style guide, and the "system is closed" workflow rule (every page element comes from the catalog). Validated by a throwaway /spike comparing Pico v2, Simple.css, and the pure-custom design; pure-custom won on the code-feel criterion the user weighted highest. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
mwiegand
parent
fa9acd3027
commit
a0501a20fb
1 changed files with 431 additions and 0 deletions
431
docs/superpowers/specs/2026-05-17-stylesheet-redesign-design.md
Normal file
431
docs/superpowers/specs/2026-05-17-stylesheet-redesign-design.md
Normal file
|
|
@ -0,0 +1,431 @@
|
||||||
|
# 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:
|
||||||
|
|
||||||
|
```css
|
||||||
|
@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 `@import`s 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`:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## 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.
|
||||||
Loading…
Reference in a new issue