# CSS_QUALITY.md — Quality Gate Criteria for OpenCD CSS Overhaul

> **Author:** Amy Amanda "Triple A" Allen (A-Team Quality & Verification)  
> **Status:** Gate — define PASS criteria and FAIL blockers  
> **Context:** BUGFIX_PLAN.md (8-bug analysis) cross-referenced against current codebase at commit `6a85ae7`  
> **Date:** 2026-05-26

---

## Source Verification

I inspected every file referenced in BUGFIX_PLAN.md against the current working tree (clean — no uncommitted work). All measurements below are from the actual files on disk.

| File | Lines | Status |
|------|-------|--------|
| `opencd.css` | 711 | **Current state** — trim target ~640 per plan |
| `templates/jewel-case.html` | 130 | inline `<style>` 8–55 (48 lines) |
| `templates/back-tray.html` | 151 | inline `<style>` 8–60 (53 lines) |
| `templates/leaflet.html` | 183 | inline `<style>` 8–86 (79 lines) + 8 inline `style=""` attrs |
| `templates/demo.css` | — | **Does not exist** — not yet created |

---

## PASS Criteria

### Criterion 1 — No inline CSS in templates

**Specification:** All three templates (`jewel-case.html`, `back-tray.html`, `leaflet.html`) must contain zero `<style>` blocks and zero `style=""` attribute values. All presentation comes from `<link>`-ed stylesheets.

**Current state:** FAIL across all three templates.
- `jewel-case.html`: `<style>` block lines 8–55 (48 lines)
- `back-tray.html`: `<style>` block lines 8–60 (53 lines) including `.demo-tray-container`
- `leaflet.html`: `<style>` block lines 8–86 (79 lines) **plus 8 inline `style=""` attributes** on `<main>`, `.cd-jewel-inner`, `<ul>`, `<dl>`, `<dt>`, `<dd>`, `<p>`, and `<aside>`

**Verification method:** `grep -rn '<style' templates/ && grep -rn 'style="' templates/'` — both must return empty.

**Target:** All `<style>` blocks extracted to `templates/demo.css`. All inline `style=""` attributes replaced with class-based rules in `opencd.css` (`.cd-jewel-case--leaflet`, `.leaflet-page ul`, `.leaflet-page dl`, `.leaflet-page dt`, `.leaflet-page dd`, `.leaflet-page p + p`, `.human-advisory--inline`).

---

### Criterion 2 — CSS reset present and expanded

**Specification:** The reset block in `opencd.css` must cover not only `box-sizing`, `margin`, and `padding` on all elements, but also:
- `html { font-size: 100%; line-height: 1.5; -webkit-text-size-adjust: 100%; }`
- `body { font-family: inherit; }`
- `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–h6 { font-size: inherit; font-weight: inherit; }`

**Current state:** PARTIAL. The existing 5-line reset (lines 191–195) covers `box-sizing`, `margin`, `padding` only. The expanded ~35-line reset from BUGFIX_PLAN §4 is not yet implemented.

**Verification method:** Read `opencd.css` lines ~191–230. Confirm all 7 listed properties are present. The reset must be self-contained — no `@import` of an external reset library.

---

### Criterion 3 — All 3 templates use same `--cd-*` tokens

**Specification:** No raw Open Props tokens (`var(--gray-*)`, `var(--red-*)`, `var(--font-*)`, `var(--size-*)`, `var(--radius-*)`, `var(--shadow-*)`, `var(--ease-*)`, `var(--font-size-*)`, `var(--size-fluid-*)`) appear in any template file or `demo.css`. Every CSS value is either a `--cd-*` token or a literal that is itself a zero-magic-numbers value.

**Current state:** FAIL. Raw Open Props tokens are in all three templates:
- `var(--font-sans)` — in all three `<style>` blocks
- `var(--red-6)` — in jewel-case and back-tray checkbox styles
- `var(--gray-6)`, `var(--gray-5)`, `var(--gray-0)`, `var(--gray-2)` — in `<style>` blocks across all three
- `var(--radius-2)` — in jewel-case and leaflet `<style>` blocks
- `var(--font-mono)` — in leaflet `<style>` block and inline `style=""`
- `var(--size-fluid-1)` — in leaflet inline `style=""` on `<dl>`

**Verification method:** 
```
grep -rn 'var(--\(gray\|red\|font\|size\|radius\|shadow\|ease\|blue\|green\|orange\|purple\|yellow\|teal\|cyan\|pink\|indigo\))' templates/
```
Must return zero matches across all files in `templates/`.

**Token mapping table (from BUGFIX_PLAN §1, Bug #7):**

| Raw Open Props | Replacement `--cd-*` token |
|----------------|---------------------------|
| `var(--gray-6)` | `var(--cd-text-muted)` |
| `var(--gray-5)` | `var(--cd-text-muted)` (or `--cd-grid-color`) |
| `var(--gray-0)` | (body background: use `demo.css` value) |
| `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)` |
| `var(--size-fluid-1)` | `var(--cd-space-inset)` or `var(--cd-space-stack)` |

---

### Criterion 4 — `opencd.css` < 250 lines

**Specification:** The main framework stylesheet must be under 250 lines after the overhaul. Comments count toward the total; blank lines do not (they're formatting, not content). Line count measured by `wc -l`.

**Current state:** FAIL. `opencd.css` is **711 lines**.

**CONCERN — Feasibility:** The BUGFIX_PLAN §2 (Bug #6) targets ~640 lines after trimming ~70 lines of decorative comments and disc art gradient. This leaves a gap of **~390 lines** between the plan's own target and this criterion. Reaching <250 lines would require:
- Eliminating the `:root` custom properties block (currently 169 lines) — but this is the core of the zero-magic-numbers principle
- Cutting ~70% of component CSS (jewel case, spine, leaflet, disc art, human advisory, back tray, grid overlay, responsive, print, grain — ~430 lines combined)
- The custom properties + minimal component definitions alone are architecturally essential

**Recommendation:** Either raise this criterion to ~640 lines (matching BUGFIX_PLAN target) or define explicitly what sections are excluded from the count (e.g., `:root` tokens don't count). As written, this criterion is inconsistent with the plan it gates.

---

### Criterion 5 — Jewel case width fills viewport

**Specification:** `.cd-jewel-case` must use a responsive width strategy:
```css
width: min(var(--cd-jewel-width), 100% - 2rem);
```
This caps at CD dimensions on large screens while filling smaller viewports. The open state must also scale: `width: min(var(--cd-jewel-open-width), 100% - 2rem)` (or equivalent).

**Current state:** FAIL. `.cd-jewel-case` (line 205) has `width: var(--cd-jewel-width)` — fixed at 280px. The open state (line 220) has `width: var(--cd-jewel-open-width)` — fixed at 560px. Neither has a `min()` responsive wrapper.

**Verification method:** Read the `width` property of `.cd-jewel-case` (lines 205–206) and `.cd-jewel-case--open` (lines 219–221). Confirm `min(...)` pattern is used.

**Note:** The container query breakpoints (`@container (max-width: 350px)` and `@container (min-width: 351px) and (max-width: 549px)`) already handle narrow parent containers with `width: 100% !important`. The `min()` strategy covers the mid-range between 350px and 549px where the fixed 280px feels too small but the breakpoints don't activate.

---

### Criterion 6 — Back-tray readable

**Specification:** The back-tray standalone page must render at approximately CD physical proportions (~302×236px at 2× scale) — not an unreadable vertical slab.

**Required changes:**
1. `--cd-tray-height` token must exist in `:root`:
   ```css
   --cd-tray-height: calc(236px * var(--cd-scale));  /* 118mm × 2 */
   ```
2. `.back-tray` must have `max-height: var(--cd-tray-height)` with `overflow-y: auto`
3. `.demo-tray-container` must have `max-height: var(--cd-tray-height)` (in `demo.css`)
4. Back-tray content (tracklist, credits) must not overflow to >236px at default scale

**Current state:** FAIL.
- `--cd-tray-height` token is **missing** from `opencd.css :root`
- `.back-tray` has **no height constraint** — no `max-height`, no `overflow-y`
- `.demo-tray-container` has `width: var(--cd-jewel-width)` but no height limit
- The content (8 tracklist items + 3 credit paragraphs + technical paragraph) flows vertically unbounded

**Verification method:**
```css
/* Confirm in :root */
--cd-tray-height: calc(236px * var(--cd-scale));

/* Confirm on .back-tray */
max-height: var(--cd-tray-height);
overflow-y: auto;

/* Confirm on .demo-tray-container (in demo.css) */
max-height: var(--cd-tray-height);
```

**Visual check:** Open `templates/back-tray.html` in a browser. The container should not exceed ~280×236px at default scale. Content that exceeds this becomes scrollable.

---

### Criterion 7 — Leaflet width correct

**Specification:** The leaflet template `.cd-jewel-case` must use its proper CD leaflet dimensions — not stretch to fill the viewport.

**Required changes:**
1. Remove inline `width: auto` from `<main>` — replace with `.cd-jewel-case--leaflet` modifier in `opencd.css`:
   ```css
   .cd-jewel-case--leaflet {
     width: min(var(--cd-leaflet-size), 100% - 2rem);
     box-shadow: none;
     background: transparent;
   }
   ```
2. Remove inline `grid-column: 1/-1` from `.cd-jewel-inner` — replace with `.cd-jewel-case--leaflet .cd-jewel-inner`:
   ```css
   .cd-jewel-case--leaflet .cd-jewel-inner {
     grid-column: 2;
     gap: var(--cd-space-inset);
   }
   ```
3. All 8 inline `style="..."` attributes on leaflet.html elements must be replaced with CSS class rules.

**Current state:** FAIL.
- `<main class="cd-jewel-case" style="width: auto; box-shadow: none; background: transparent;">` — `width: auto` destroys the CD dimension constraint
- `<div class="cd-jewel-inner" style="grid-column:1/-1; gap: var(--cd-space-inset);">` — `grid-column: 1/-1` spans into the spine column
- 6 more inline `style=""` attributes on `<ul>`, `<dl>`, `<dt>`, `<dd>`, `<p>`, `<aside>`

**Verification method:**
- `grep 'style=' templates/leaflet.html` must return empty
- `.cd-jewel-case--leaflet` must exist in `opencd.css` with `width: min(var(--cd-leaflet-size), 100% - 2rem)`

**Visual check:** Open `templates/leaflet.html` in a browser. The leaflet should render at ~240px wide (at 2× scale), centered like the other templates. Not stretched to full viewport width.

---

## FAIL Blockers

Any of these conditions causes an automatic FAIL verdict, regardless of other criteria:

### F-1: Inline `<style>` or `style=""` remains in any template
The primary architectural decision in BUGFIX_PLAN is to extract all inline CSS. If even one `<style>` block or `style=""` attribute remains after the overhaul, the core rewrite has failed.

### F-2: `--cd-tray-height` token not defined
Without this token, the back-tray height constraint cannot work. This is a new dependency introduced by BUGFIX_PLAN Bug #3 — its absence means the fix was not applied.

### F-3: `.cd-spine--side` still has `writing-mode: horizontal-tb`
This is the root cause of Bug #8. If the override is still present, the side spine text will remain illegible on the back-tray page. Check line 270 of `opencd.css` — must be removed or set to `writing-mode: vertical-rl`.

### F-4: leaflet `<main>` still has inline `width: auto`
This is the root cause of Bug #5. If it persists, the leaflet page is still broken — the CD dimension constraint is overridden.

### F-5: Raw Open Props tokens used outside `opencd.css :root`
The design principle is that `--cd-*` tokens are the sole API surface. Any raw `var(--gray-*)`, `var(--red-*)`, `var(--font-*)`, etc. in template files, `demo.css`, or component CSS (outside `:root` definitions) is a semantic layer violation.

### F-6: Any template fails to render or has visible layout defects
If a find-and-replace error breaks the layout of any template (elements overlapping, text invisible, layout collapsed), the deliverable fails regardless of how many criteria pass on paper. Validation is by visual inspection in a browser.

---

## Summary Table

| # | Criterion | Current State | Priority | Risk |
|---|-----------|---------------|----------|------|
| 1 | No inline CSS in templates | **FAIL** — 48–79 lines per template | Critical | H |
| 2 | CSS reset expanded | **PARTIAL** — basic reset present, not expanded | High | M |
| 3 | All templates use `--cd-*` tokens | **FAIL** — 10+ raw Open Props references | Critical | H |
| 4 | `opencd.css` < 250 lines | **FAIL** — 711 lines; **see CONCERN below** | Medium | **H** |
| 5 | Jewel case width fills viewport | **FAIL** — fixed `width`, no `min()` | High | H |
| 6 | Back-tray readable | **FAIL** — no height constraint, `--cd-tray-height` missing | High | H |
| 7 | Leaflet width correct | **FAIL** — `width: auto` in inline style | Critical | H |

### Verdict on Criterion 4 (`opencd.css < 250 lines`)

**CONCERN — Feasibility mismatch.** 

Cross-referencing the BUGFIX_PLAN (which this gate criteria document is supposed to gate) shows an explicit target of ~640 lines (Bug #6, §2). The plan identifies ~70 lines of trimmable material. Getting to <250 requires removing ~65% of the file — more than 460 lines of CSS that the plan considers architecturally essential.

The `:root` custom properties section alone is 169 lines. The component CSS (jewel case, spine, leaflet, disc art, human advisory, back tray, grid, responsive, print, grain) totals ~430 lines. Trimming to <250 would require either:
- **Merging all components into minified single-line rules** — violates the plan's readability and maintainability principles
- **Dropping features** — no responsive breakpoints, no print styles, no grid overlays, no grain texture
- **Excluding certain sections from the count** — not currently specified

**Recommendation:** Revise this criterion to ~640 lines per BUGFIX_PLAN, or clarify which sections are excluded. If the intent is that `opencd.css` is the production build (post-minification), state that explicitly. As written, the criterion and the plan are contradictory, and I cannot pass a deliverable that meets both.

---

*"There's always a bigger story. The question is whether you find it before the plan goes sideways."*
— Amy Amanda Allen, A-Team Intelligence Officer