left4me/docs/superpowers/specs/2026-05-18-create-modal-and-workshop-section-redesign.md

Create Overlay Modal + Workshop Items Section — Redesign

Context

Two UI surfaces still wear the pre-redesign vocabulary even though the global stylesheet was reworked from first principles in 308fa4e:

1. Create-overlay modal (templates/overlays.html, components.css:114-166) — uses the old .modal* class names, a <fieldset> with a native <legend> border around the Type radios (looks notched and archaic), native checkbox markup that wraps the input on its own line above the label, and a field order that buries the most-important field (Name) under the most-cluttered one (Type). The "path is generated automatically" hint at the bottom is stale copy from an earlier version where users picked their own paths; paths are now derived from the internal id, so the hint describes behavior the user can no longer influence.

2. Workshop items section on the overlay detail page (templates/overlay_detail.html:43-67) — same fieldset-border issue on the Items/Collection radios, two right-aligned buttons (Add, Refresh from Steam) overlapping with no margin (visual regression), and a forced choice between "items" and "collection" input modes that exists purely to tell the backend which Steam API endpoint to call. The dual mode is also a silent footgun: a user pasting a collection URL into the items field today produces a broken overlay with no warning.

The goal is to bring both surfaces in line with the redesigned stylesheet and, while we're in there, simplify the workshop form structurally (drop the Input-mode radio entirely — see decision rationale below).

Decisions

Create modal

• Field order: Name → Type → System-wide. Name is the most-typed field and the simplest input; it goes first. Type is the bigger decision but benefits from the user having committed to something before they confront three options.
• No fieldset border. Type label becomes a regular .field-label (small uppercase or semibold, matches Name's label).
• Radios become a stacked custom-styled list. Each row: a circular dot control (outer ring with a colored inner dot when selected), bold label on the right, muted second-line description below the label. All descriptions are visible at once — users can compare options without clicking. Considered and rejected: segmented control — breaks down past 3-4 options (the codebase is plausibly heading toward more overlay types: git, zip, mirror). Considered and rejected: full selectable cards — too much vertical space for what is ultimately a single radio group.
• System-wide checkbox becomes a switch. Switch sits left-aligned in the row (same left edge as the radio dots), with bold label + muted second-line description to the right — visually consistent with the radio rows above. Switch is conceptually distinct from the type radios (binary on/off vs. one-of-three), so the different control shape reinforces the hierarchy.
• Drop the "path is generated automatically" paragraph. Legacy copy.
• Buttons keep their current placement (Cancel + Create, right-aligned in a bordered footer with a slightly muted background) — that part of the current modal already works.

Workshop items section

• Drop the Input-mode fieldset entirely. Single textarea accepts any mix of item IDs, item URLs, and collection URLs. Backend autodetects.

• Autodetect strategy (verified against live Steam API during brainstorming):

  1. Parse pasted input into a list of IDs (existing helper: steam_workshop.parse_workshop_input()).
  2. One batched call to ISteamRemoteStorage/GetCollectionDetails/v1/ with all parsed IDs. Steam returns one entry per ID:
     • result: 1 + children: [...] → it's a collection, expand to children IDs.
     • result: 9 (k_EResultFileNotFound) → not a collection, keep ID as-is.
  3. One batched call to ISteamRemoteStorage/GetPublishedFileDetails/v1/ with the flat list of final item IDs (collection-children + non-collection IDs).
  4. Persist.

  Cost: one extra Steam round-trip on submission (~150 ms), regardless of input size. This is simpler than today's code, which has two separate handler branches in routes/workshop_routes.py:36-99. The unified flow deletes the if input_mode == "items" / elif input_mode == "collection" branching.

• "Refresh from Steam" relocates to a controls row below the items table (not inside the table). The table ends with its last data row. Below the table sits a single row containing:

  • Left: a summary hint ({n} items · {total_size} total or 0 items when empty).
  • Right: a normal-styled ↻ Refresh from Steam button (disabled when the table is empty).

• Add button placement. Right-aligned in its own row immediately below the textarea, with proper top margin (today's "no margin" overlap with Refresh is the bug being fixed by moving Refresh).

• Textarea uses monospace font since pasted content is IDs and URLs.

• Header copy stays as Workshop items (page has other sections — Files, Used by — and section headers aid scanning).

• Helper text under the label: "Paste Steam Workshop IDs, item URLs, or collection URLs — one per line. Collections expand automatically." The last sentence is load-bearing — it tells the user they don't need to pre-classify their input.

Implementation surface

Files to modify

Path	Change
l4d2web/l4d2web/templates/overlays.html	Reorder fields (Name → Type → System-wide); replace native fieldset+radios+checkbox with new .field / .radio-row / .switch-row markup; drop the path-hint <p>; rename .modal* → .dialog* if aligning with the redesign plan.
l4d2web/l4d2web/templates/overlay_detail.html:43-67	Delete the <fieldset class="workshop-input-mode"> block; keep textarea but rewrite its surrounding markup as a .field block with label + helper text; move Refresh from Steam out of its own <form> and put it in a single .table-actions row below the items table; add a summary span on the left of that row.
l4d2web/l4d2web/templates/_overlay_item_table.html	Verify whether per-row actions exist (e.g., remove-item). Out of scope to change today, but flag for the implementation session: the design preserves whatever per-row actions are there.
l4d2web/l4d2web/static/css/components.css	Add the new component CSS (see below). Existing .modal* rules either stay (if we keep old class names) or get renamed to .dialog*. Remove .workshop-input-mode (no rules to remove — fieldset class has zero CSS today anyway).
l4d2web/l4d2web/routes/workshop_routes.py:36-99	Delete the input-mode branching; unify the handler to (1) parse input, (2) batch-resolve collections, (3) batch-fetch metadata. Existing helpers parse_workshop_input(), resolve_collection(), fetch_metadata_batch() all get reused.
l4d2web/l4d2web/steam/steam_workshop.py	Add (or refactor): a partition_collections_and_items(ids) helper that does one GetCollectionDetails batch call and returns (item_ids, collection_id_to_children). The exact shape can mirror existing module conventions.

Component CSS to add

These should live in components.css and be reusable beyond just these two surfaces — they form a small set of primitives the rest of the app can adopt as it migrates.

• .field (existing pattern, may already partially exist) — grid container with gap: var(--space-xs); children are .field-label, optional .field-hint, and the control.
• .radio-row — flex row, gap var(--space-s), custom radio dot via ::after; .radio-row.is-selected colors the inner dot.
• .radio-list — grid container for a vertical stack of .radio-rows with gap: var(--space-xs). Replaces the <fieldset> pattern.
• .switch + .switch-row — pill-shaped toggle, on-state uses --color-button-primary. Left-aligned in its row, consistent with .radio-row left edge.
• .table-actions — flex row with justify-content: space-between, align-items: center, top margin var(--space-m). Sits below a .table-wrap.

Existing tokens (already in tokens.css) are sufficient. No new color or spacing tokens needed.

Things explicitly not changing

• The <dialog> open/close JavaScript (data-inline-modal-close handlers) stays as-is.
• The overlay detail page's Files and Used by sections.
• The Delete overlay / Rename actions at the bottom of the page.
• The Steam-side caching/refresh logic — only the UI placement of the refresh button is moving.

Verification

End-to-end checks for the implementation session:

1. Dev server: python scripts/dev-server.py (not plain flask run — the latter misroutes LEFT4ME_ROOT on macOS).
2. Create modal: open the overlays list page, click "Create overlay".
   • Verify field order: Name → Type → System-wide.
   • Verify no fieldset border around Type.
   • Verify custom radio dots fill with accent color on selection.
   • Verify switch toggles state and visually animates.
   • Verify no "path is generated automatically" copy anywhere.
   • Submit with each of the three types in turn; verify the overlay is created with the correct type each time.
3. Workshop section:
   • Create a workshop overlay; navigate to its detail page.
   • Verify only one textarea + one Add button (no input-mode radio).
   • Paste a single item ID (e.g. 3726529483); click Add. Item appears.
   • Paste a collection URL (e.g. https://steamcommunity.com/sharedfiles/filedetails/?id=3724125665); click Add. The 6 children appear, not the collection itself.
   • Paste a mix of items and a collection in one submission; verify all resolve correctly.
   • Verify items table ends at its last row (no internal footer bar).
   • Verify summary + ↻ Refresh from Steam sit below the table as a single row.
   • Click Refresh from Steam; verify metadata refresh fires.
4. Stale-content sweep: grep -rn "path is generated automatically" l4d2web/ should return no matches after the change.
5. i18n check (if applicable): if the project uses i18n strings for these screens, verify the removed/changed strings are cleaned up.

Open follow-ups (out of scope)

• Once the new component CSS (.radio-row, .switch-row, .field, .table-actions) lands, sweep the rest of the templates for fieldsets and native checkboxes that could adopt the same vocabulary. Don't do this in the same commit — surface it as a follow-up so the diff for this change stays scoped.
• The superpowers:brainstorming skill's companion server has an owner-PID detection bug that kills the server when launched via Bash(run_in_background: true) on macOS. Workaround during this brainstorm was launching node server.cjs directly with BRAINSTORM_OWNER_PID=1. Small upstream PR opportunity, unrelated to this codebase.