trentuna/opencd
8
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
opencd/CSS_QUALITY.md

14 KiB
Raw Blame History

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:

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: 
    --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:

/* 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: 
    .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: 
    .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