bugfix: hannibal analysis — BUGFIX_PLAN.md with 8-bug analysis, line-level CSS audit, dimension fix, reset strategy, Murdock+BA work breakdown

2026-05-25 23:57:48 +02:00 · 2026-05-25 23:57:48 +02:00 · 6a85ae7adf
commit 6a85ae7adf
parent f39c9e0810
1 changed files with 488 additions and 0 deletions
--- a/BUGFIX_PLAN.md
+++ b/BUGFIX_PLAN.md
@ -0,0 +1,488 @@
+# BUGFIX_PLAN.md — OpenCD CSS Overhaul
+
+> **Author:** Colonel John Hannibal Smith (A-Team command)  
+> **Status:** Approved — execute per work breakdown  
+> **Context:** Bug analysis of opencd.css + 3 templates against Ludo's 8 critical bugs  
+> **Date:** 2026-05-25
+
+---
+
+## Table of Contents
+
+1. [Bug-by-Bug Analysis](#1-bug-by-bug-analysis)
+2. [CSS to Cut — Line-Level Audit](#2-css-to-cut--line-level-audit)
+3. [CD Dimension Recalculation](#3-cd-dimension-recalculation)
+4. [Reset Strategy](#4-reset-strategy)
+5. [Work Breakdown](#5-work-breakdown)
+
+---
+
+## 1. Bug-by-Bug Analysis
+
+### Bug #1 — Inline `<style>` blocks in all 3 templates
+
+**Current state:** Each template has an inline `<style>` block containing demo page chrome:
+
+| Template | Lines | What's in the block |
+|----------|-------|---------------------|
+| jewel-case.html | 8–55 | `body` flex layout, `.demo-controls`, `.demo-footnote` |
+| back-tray.html | 8–60 | Same body + `.demo-tray-container` wrapper |
+| leaflet.html | 8–86 | Same body + `.leaflet-content--multi`, `.leaflet-pages` |
+
+**Verdict:** These are demo scaffolding, not framework component CSS. Removing `<style>` entirely without moving this chrome somewhere breaks the demos. There are two clean approaches:
+
+**Option A (recommended):** Create `templates/demo.css` — a shared demo chrome file imported by all 3 templates. This gets <style> out of the HTML without polluting the framework. Move all common body/control/footnote styles there. Template-specific overrides (`.leaflet-content--multi`, `.leaflet-pages`) stay close to their template but still in `demo.css`.
+
+**Option B:** Move everything into `opencd.css` under `.demo-*` namespaced classes and import from there. This keeps a single stylesheet but bloats the framework with demo-only code.
+
+**Decision:** Option A. Demo chrome is not framework. `demo.css` lives in `templates/` alongside the HTML.
+
+**What moves to `demo.css`:**
+- `body` block (min-height, display:flex, align-items:center, gap, padding, background) — deduplicated across all 3
+- `.demo-controls` — deduplicated (leaflet has extra button + page-indicator styles, those separate)
+- `.demo-footnote` — deduplicated
+- `.demo-tray-container` — back-tray only
+- `.leaflet-content--multi`, `.leaflet-pages` — leaflet only
+
+**Result after fix:** Each template has `<link rel="stylesheet" href="demo.css">`, zero `<style>` blocks.
+
+---
+
+### Bug #2 — No comprehensive CSS user-agent reset
+
+**Current state:** opencd.css lines 191–195 has:
+```css
+*, *::before, *::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+```
+
+This resets box-sizing, margin, and padding — which is good. But it's missing:
+
+| Missing | Why it matters |
+|---------|---------------|
+| `font-family: inherit` | Prevents inconsistent form inputs inheriting browser default fonts |
+| `font-size: 100%` | Prevents `<h1>`–`<h6>` and `<small>` from breaking the type scale |
+| `line-height: 1.5` | Normalizes vertical rhythm across browsers |
+| `border: 0` on common elements | Prevents fieldset/button/input default borders |
+| `background: transparent` on buttons | Prevents default button backgrounds |
+| `list-style: none` on `<ul>` / `<ol>` | Only needed if using list reset (currently `.tray-credits ol` does this) |
+| `text-decoration: none` on `<a>` | For framework-styled links |
+
+**Verdict:** Expand the existing reset to cover font inheritance, line-height, and form element defaults. Not a full `normalize.css` — just the basics that affect the jewel case layout.
+
+---
+
+### Bug #3 — back-tray.html renders as ~280×1305px (unreadable vertical slab)
+
+**Root cause:** The back tray has no height constraint.
+
+The `.back-tray` grid uses `grid-template-columns: var(--cd-spine-width) 1fr var(--cd-spine-width)` but no row template — the grid auto-creates rows per content item. The `.tray-credits` section contains 8 tracklist items, 3 production credit paragraphs, and technical info text — all flowing vertically without bound.
+
+Physical back tray paper is 151×118mm. At 2× scale that's ~302×236px. The standalone demo should show the back tray at roughly that proportion.
+
+**Fix strategy:**
+
+1. **Add `--cd-tray-height`** calculated from physical dimensions:
+   ```
+   --cd-tray-height: calc(236px * var(--cd-scale));  /* 118mm × 2 */
+   ```
+
+2. **Constrain `.back-tray` height** with `max-height: var(--cd-tray-height)` and `overflow-y: auto` (matching the real paper footprint — content that overflows physical space gets scrollable, just like a real multi-page tray insert).
+
+3. **Tighten the content.** Back tray should show a compact tracklist + credits, not verbose paragraphs. This is a content reduction, not a CSS reduction — but B.A. should audit the template text.
+
+4. **Fix `.demo-tray-container`** — currently `width: var(--cd-jewel-width)` but no height constraint. Add `max-height: var(--cd-tray-height)` so the demo wrapper also constrains.
+
+---
+
+### Bug #4 — jewel-case.html too narrow
+
+**Root cause:** The `.cd-jewel-case` has `width: var(--cd-jewel-width)` = 280px at default scale. This IS the correct physical dimension at 2× (142mm × 2 = 284px, rounded to 280px). The issue is that the container doesn't respond to viewport width on large screens — it sits as a tiny box center-aligned.
+
+The body centers it with flexbox, so on a 1920px screen you get a 280px box in the middle of a sea of cream background. It looks "too narrow" because there's no visual connection to viewport scale.
+
+**Fix:**
+- Add a `max-width` constraint rather than a fixed `width` on `.cd-jewel-case`:
+  ```
+  width: min(var(--cd-jewel-width), 100% - 2rem);
+  ```
+  This lets it fill smaller viewports while capping at CD dimensions on larger ones.
+- Keep the center-alignment, but the jewel case will feel proportional rather than dwarfed.
+
+---
+
+### Bug #5 — leaflet.html width completely broken
+
+**Root cause:** Inline styles override the entire layout structure:
+```html
+<main class="cd-jewel-case" style="width: auto; box-shadow: none; background: transparent;">
+  <div class="cd-jewel-inner" style="grid-column:1/-1; gap: var(--cd-space-inset);">
+```
+
+`width: auto` on the jewel case destroys the CD dimension constraint. The inner div's `grid-column: 1/-1` spans past the content column into the spine column. The `.leaflet-content` has `max-width: var(--cd-leaflet-size)` (240px) but the wrapper is now unconstrained.
+
+**Fix:**
+- Remove inline `width: auto` — use `.cd-jewel-case--leaflet` modifier class instead:
+  ```css
+  .cd-jewel-case--leaflet {
+    width: var(--cd-leaflet-size);
+    box-shadow: none;
+    background: transparent;
+  }
+  ```
+- Remove inline `grid-column: 1/-1` — the `.cd-jewel-inner` already lives in grid-column 2 via the base CSS. The leaflet template doesn't have a spine, so just hide the spine grid area or use grid-template-columns differently.
+- All the inline style overrides become `.cd-jewel-case--leaflet` and `.cd-jewel-case--leaflet .cd-jewel-inner` rules in opencd.css.
+
+---
+
+### Bug #6 — 711 lines is ~80% bloat
+
+**Audit of current opencd.css (previously hardened — already less bloated than original):**
+
+| Section | Lines | Verdict |
+|---------|-------|---------|
+| 1. Custom properties (`:root`) | 169 | **Accept as-is** — all `--cd-*` are semantic tokens per DESIGN.md. No magic numbers. |
+| 2. Reset | 5 | Accept — minimal, effective |
+| 3. Jewel Case | 35 | Accept — core layout |
+| 4. Spine | 35 | Accept — core layout |
+| 5. Leaflet | 60 | Could trim ~15 lines of redundant comments |
+| 6. Disc Art | 65 | Could trim ~20 lines — `.disc-art--sheen` gradient is very verbose |
+| 7. Human Advisory | 55 | Could trim ~10 lines — `.advisory-row--*` variants use only 3 of 6 defined |
+| 8. Back Tray | 70 | Accept — core layout + tracklist styling |
+| 9. Grid Overlay | 45 | Accept — 4 variants, all in use |
+| 10. Open/Closed | 10 | Accept — state management |
+| 11. Responsive | 55 | Accept — container queries for 3 breakpoints |
+| 12. Print | 30 | Accept — needed |
+| 13. Grain | 20 | Accept — texture utility |
+
+**Target after trimming:** ~640 lines (trim ~70 lines of verbose comments and disc art gradient).
+
+**Specific cuts:**
+1. Lines 18–20, 38–40, 49–52, 70–73, 83–86, 90–93, 98–99, 106–109, 117–119, 131–134, 147–149, 155–157, 162–164, 169–171, 178–180 — decorative ASCII comment separators between sections. Replace with simple `/* Section name */` comments. Saves ~45 lines.
+2. Lines 386–406 — `.disc-art--sheen` gradient — the 3-layer radial gradient with repeating ring is over-engineered for a disc gradient. Can be simplified to a 2-layer radial gradient. Saves ~15 lines.
+3. Lines 444–452 — `.advisory-row--red` and `.advisory-row--white` background variants. Only 3 of 6 advisory variants are used. Keep `.advisory-row--black` and `.advisory-row--white`. Saves ~10 lines.
+
+---
+
+### Bug #7 — Design tokens inconsistent across templates
+
+**Current state analysis:** All 3 templates link to `opencd.css`, so `--cd-*` tokens ARE consistent at the framework level. However:
+
+1. Each template's inline `<style>` block references Open Props directly (`var(--gray-6)`, `var(--red-6)`, `var(--radius-2)`, `var(--font-sans)`) instead of using `--cd-*` tokens.
+2. Different font sizes used in demo controls across templates (`.875rem` in jewel-case, `.75rem` in back-tray footnotes).
+
+**Fix:** Once `<style>` blocks are moved to `demo.css` (Bug #1), convert all direct Open Props references to `--cd-*` tokens:
+- `var(--gray-6)` → `var(--cd-text-muted)` or `var(--cd-text-secondary)`
+- `var(--red-6)` → `var(--cd-advisory-red)`
+- `var(--radius-2)` → `var(--cd-jewel-radius)`
+- `var(--font-sans)` → `var(--cd-font-label)`
+- `var(--font-mono)` → `var(--cd-font-mono)`
+
+This ensures every CSS reference across all files uses the `--cd-*` semantic layer — never raw Open Props tokens.
+
+---
+
+### Bug #8 — `.cd-spine--side` renders wrong
+
+**Root cause analysis:**
+
+```css
+.cd-spine {
+  writing-mode: vertical-rl;       /* text reads top-to-bottom */
+  flex-direction: column;           /* items stack vertically */
+}
+
+.cd-spine--side {
+  writing-mode: horizontal-tb;     /* text reads left-to-right */
+  flex-direction: row;              /* items sit side-by-side */
+}
+```
+
+In `back-tray.html`, the `.back-tray` grid is:
+```css
+grid-template-columns: var(--cd-spine-width) 1fr var(--cd-spine-width);
+/* = 14px + auto + 14px */
+```
+
+The side spines (`.cd-spine--side`) sit in 14px-wide columns with `writing-mode: horizontal-tb`. Text like "OPENCD" or "TRENTUNA" in a 14px horizontal column overflows — it's illegible.
+
+**Physical reference:** On a real CD back tray, the side spines (~7mm each) have text printed VERTICALLY — reading top-to-bottom on the left spine, bottom-to-top on the right. The text runs along the spine's length, not across its width.
+
+**Fix:** The `.cd-spine--side` variant should NOT change writing mode — it should keep `writing-mode: vertical-rl` from the base. Instead, it should just adjust positioning:
+
+```css
+.cd-spine--side {
+  /* Keep base vertical writing mode but adjust layout */
+  writing-mode: vertical-rl;      /* inherit from base — DON'T override */
+}
+```
+
+Remove `writing-mode: horizontal-tb` and `flex-direction: row` from `.cd-spine--side`. The side spine will read vertically along its height, which fits within the 14px × 236px column perfectly.
+
+For left-vs-right orientation: the back-tray.html already places `cd-spine--side` elements in columns 1 and 3 of the grid. Both will read top-to-bottom. If RTL support is needed later, add `cd-spine--side--r-t-b` for right-to-bottom (inverted vertical).
+
+---
+
+## 2. CSS to Cut — Line-Level Audit
+
+### From opencd.css
+
+| Lines | Content | Action | Saves |
+|-------|---------|--------|-------|
+| 1–7 | File header banner | Keep — project identity | 0 |
+| 11–16 | Section header for variables | Simplify to `/* 1. Tokens */` | -3 |
+| 18–20, 38–40, etc. | Decorative `══════` comment blocks | Remove decorative lines, keep one-line headers | ~45 |
+| 191–192 | Section header for reset | Keep | 0 |
+| 197–198 | Section header for jewel case | Keep | 0 |
+| 386–406 | `.disc-art--sheen` 3-layer gradient | Simplify to 2-layer | ~15 |
+| 443, 448, 453 | `.advisory-row--red`, `.advisory-row--white` unused background variants | Consolidate to `.advisory-row--black` and `.advisory-row--white` classes with `--red` via modifier | ~10 |
+| 694–711 | `.cd-grain` texture | Keep — used for tray paper texture | 0 |
+| **Total trim target** | | | **~70 lines** |
+
+**Target final size:** ~640 lines (from 711)
+
+### From templates (inline `<style>` blocks)
+
+Each template's inline `<style>` block ranges 30–60 lines. After moving to `demo.css`:
+
+| Template | Lines removed | Destination |
+|----------|--------------|-------------|
+| jewel-case.html | 8–55 (48 lines) | `templates/demo.css` |
+| back-tray.html | 8–60 (53 lines) | `templates/demo.css` |
+| leaflet.html | 8–86 (79 lines) | `templates/demo.css` |
+
+### From leaflet.html inline style attributes
+
+| Inline style | Action |
+|--------------|--------|
+| `style="width: auto; box-shadow: none; background: transparent;"` on `<main>` | Move to `.cd-jewel-case--leaflet` class |
+| `style="grid-column:1/-1; gap: var(--cd-space-inset);"` on `.cd-jewel-inner` | Move to `.cd-jewel-case--leaflet .cd-jewel-inner` |
+| `style="position:static; align-self:flex-end;"` on `.human-advisory` | Consider `.human-advisory--inline` variant |
+| `style="margin-left:1rem; color:var(--cd-text-secondary); line-height:1.6;"` on `<ul>` | Move to opencd.css: `.leaflet-page ul` rule |
+| `style="margin-top:.5rem; display:grid; gap:.25rem; font-size:var(--size-fluid-1);"` on `<dl>` | Move to opencd.css: `.leaflet-page dl` rule |
+| `style="font-family:var(--font-mono); color:var(--gray-6);"` on `<dt>` | Move to opencd.css: `.leaflet-page dt` rule |
+| `style="color:var(--gray-7);"` on `<dd>` | Move to opencd.css: `.leaflet-page dd` rule |
+| `style="margin-top:.5rem;"` on `<p>` | `.leaflet-page p + p` sibling rule in CSS |
+
+---
+
+## 3. CD Dimension Recalculation
+
+### Current dimension tokens
+
+| Token | Current value | Physical | Ratio |
+|-------|--------------|----------|-------|
+| `--cd-jewel-width` | calc(280px × scale) | 142mm | 1.97px/mm |
+| `--cd-jewel-height` | calc(245px × scale) | 125mm | 1.96px/mm |
+| `--cd-jewel-open-width` | calc(560px × scale) | 284mm | 1.97px/mm |
+| `--cd-spine-width` | calc(14px × scale) | ~7mm | 2.0px/mm |
+| `--cd-disc-diameter` | calc(240px × scale) | 120mm | 2.0px/mm |
+| `--cd-leaflet-size` | calc(240px × scale) | 120mm | 2.0px/mm |
+| `--cd-tray-width` | calc(260px × scale) | ~130mm | 2.0px/mm |
+| `--cd-tray-height` | **MISSING** | 118mm | — |
+
+### Correction needed
+
+**Add `--cd-tray-height`:**
+```
+--cd-tray-height: calc(236px * var(--cd-scale));  /* 118mm × 2 */
+```
+
+**This dimension drives Bug #3 fix** — the back tray height constraint.
+
+### `--cd-scale` semantics (already correct in current code)
+
+Current implementation: `--cd-scale: 1` = default 2× display scale. The formulas use the 2× px value multiplied by scale. This is unambiguous:
+```
+Default (scale=1): width = 280px
+1× physical (scale=0.5): width = 140px
+4× display (scale=2): width = 560px
+```
+
+Document this clearly in `_variables.css` comment. No changes needed — the current approach matches RECON.md recommendation.
+
+### Template width fixes
+
+| Template | Current width | Fixed width | Rationale |
+|----------|--------------|-------------|-----------|
+| jewel-case.html | 280px (fixed) | `min(280px, 100% - 2rem)` | Responsive on small, accurate on large |
+| back-tray.html | 280px (via `.demo-tray-container`) | `min(280px, 100% - 2rem)` with `max-height: var(--cd-tray-height)` | Physical constraints |
+| leaflet.html | `auto` (broken) | `min(var(--cd-leaflet-size), 100% - 2rem)` via `.cd-jewel-case--leaflet` | CD leaflet size + responsive |
+
+---
+
+## 4. Reset Strategy
+
+### Target: Minimal but complete
+
+The existing reset covers: box-sizing, margin, padding on all elements.
+
+**Expanded reset:**
+
+```css
+*, *::before, *::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+html {
+  font-size: 100%;
+  line-height: 1.5;
+  -webkit-text-size-adjust: 100%;
+}
+
+body {
+  font-family: inherit;  /* Each template sets its own family via demo.css */
+}
+
+img, svg, video, canvas {
+  display: block;
+  max-width: 100%;
+}
+
+button, input, select, textarea {
+  font: inherit;
+  border: 0;
+  background: transparent;
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+ul, ol {
+  list-style: none;
+}
+
+h1, h2, h3, h4, h5, h6 {
+  font-size: inherit;
+  font-weight: inherit;
+}
+```
+
+This is ~35 lines — lean, covers all the gaps identified in Bug #2. No external normalize, no `@import` of reset. The reset is self-contained.
+
+---
+
+## 5. Work Breakdown
+
+### Phase 1 — Murdock: `templates/demo.css` (Bug #1, #7)
+
+**Task:** Extract all inline `<style>` blocks into `templates/demo.css`.
+
+**Steps:**
+1. Create `templates/demo.css` with all common demo chrome (body flex layout, `.demo-controls`, `.demo-footnote`)
+2. Convert all raw Open Props references to `--cd-*` tokens
+3. Add template-specific sections for leaflet's `.leaflet-content--multi`, `.leaflet-pages` styles
+4. Update all 3 templates to: remove `<style>` blocks, add `<link rel="stylesheet" href="demo.css">`
+5. Verify all 3 templates render identically in a browser
+
+**Files:** `templates/demo.css` (new), `templates/jewel-case.html` (edit), `templates/back-tray.html` (edit), `templates/leaflet.html` (edit)
+
+---
+
+### Phase 2 — Murdock: Leaflet inline styles to CSS (Bug #5)
+
+**Task:** Replace all inline `style="..."` attributes in leaflet.html with proper CSS classes.
+
+**Steps:**
+1. Add `.cd-jewel-case--leaflet` modifier in opencd.css
+2. Add `.cd-jewel-case--leaflet .cd-jewel-inner` override
+3. Add `.human-advisory--inline` variant for leaflet's positioned static advisory
+4. Add `.leaflet-page ul`, `.leaflet-page dl`, `.leaflet-page dt`, `.leaflet-page dd`, `.leaflet-page p + p` rules in opencd.css leaflet section
+5. Update leaflet.html: remove all inline style attributes, add classes
+
+**Files:** `opencd.css` (edit), `templates/leaflet.html` (edit)
+
+---
+
+### Phase 3 — B.A.: CSS trim + spine fix (Bug #6, #8)
+
+**Task:** Trim bloat from opencd.css and fix `.cd-spine--side`.
+
+**Steps:**
+1. Strip decorative comment blocks, replace with simple `/* Section */` headers
+2. Simplify `.disc-art--sheen` gradient to 2-layer
+3. Consolidate `.advisory-row--*` variants
+4. Fix `.cd-spine--side`: remove `writing-mode: horizontal-tb` and `flex-direction: row` overrides
+5. Verify `.cd-spine--side` renders vertically in back-tray.html
+
+**Files:** `opencd.css` (edit)
+
+---
+
+### Phase 4 — B.A.: Reset expansion + dimension fixes (Bug #2, #3, #4)
+
+**Task:** Expand the reset in opencd.css, add tray height, fix jewel case width strategy.
+
+**Steps:**
+1. Replace existing 5-line reset with ~35-line expanded reset
+2. Add `--cd-tray-height` token in `:root`
+3. Add `max-height: var(--cd-tray-height)` to `.back-tray` with `overflow-y: auto`
+4. Change `.cd-jewel-case` width from fixed to `min(var(--cd-jewel-width), 100% - 2rem)`
+5. Add `max-height: var(--cd-tray-height)` to `.demo-tray-container` (in demo.css)
+6. Tighten back-tray.html content — condense verbose paragraphs
+
+**Files:** `opencd.css` (edit), `templates/demo.css` (edit), `templates/back-tray.html` (edit)
+
+---
+
+### Phase 5 — Amy: Validation (after BA completes Phases 3 & 4)
+
+**Task:** Visual regression check on all 3 templates.
+
+**Checklist:**
+- [ ] jewel-case.html renders at ~280×245px, centered, responsive on small viewports
+- [ ] jewel-case.html `data-jewel-state="open"` doubles width, back-tray appears
+- [ ] back-tray.html renders at ~280×236px, not a vertical slab
+- [ ] back-tray.html side spines show vertical text, readable
+- [ ] leaflet.html renders at ~240×240px, not stretched to full viewport
+- [ ] leaflet.html multi-page navigation works (prev/next buttons)
+- [ ] No `<style>` blocks in any HTML template
+- [ ] No raw Open Props tokens (`var(--gray-*)`, `var(--font-*)`, etc.) in any file except opencd.css `:root` definitions
+- [ ] All 3 templates look identical to current renders after the refactor
+
+---
+
+## Execution Order
+
+```
+                   ┌─────────────────────┐
+                   │ PHASE 1  (Murdock)  │
+                   │ demo.css extraction │
+                   │ + token conversion  │
+                   └─────────┬───────────┘
+                             │
+                   ┌─────────▼───────────┐
+                   │ PHASE 2  (Murdock)  │
+                   │ leaflet inline→CSS  │
+                   └─────────┬───────────┘
+                             │
+             ┌───────────────┼───────────────┐
+             │               │               │
+    ┌────────▼───────┐ ┌────▼───────┐       │
+    │ PHASE 3 (BA)   │ │ PHASE 4   │       │
+    │ CSS trim +     │ │ (BA)      │       │
+    │ spine fix      │ │ Reset +   │       │
+    └────────┬───────┘ │ dimensions │       │
+             │         └────┬───────┘       │
+             │               │               │
+             └───────────────┼───────────────┘
+                             │
+                   ┌─────────▼───────────┐
+                   │ PHASE 5  (Amy)      │
+                   │ Visual validation   │
+                   └─────────────────────┘
+```
+
+Murdock handles content extraction (Phases 1–2). B.A. handles structural CSS (Phases 3–4). Amy validates (Phase 5). I oversee and sign off.
+
+---
+
+*"I love it when a plan comes together."*
+— Colonel John Hannibal Smith, A-Team Commander