From 0be1681da29647a2d6a71c4734fb21114e737aba Mon Sep 17 00:00:00 2001
From: Hannibal Smith <hannibal@a-team.dev>
Date: Mon, 25 May 2026 22:30:19 +0200
Subject: [PATCH] =?UTF-8?q?opencd:=20plan=20framework=20architecture=20?=
 =?UTF-8?q?=E2=80=94=20DESIGN.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Covers:
- File layout and build principles
- Module responsibility matrix
- Open Props token mapping (CD dimensions + design tokens)
- Full component API reference with HTML examples
- Layout architecture diagram
- Responsive strategy
- Recon directions for Face
- Implementation sequence
---
 DESIGN.md | 402 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 402 insertions(+)
 create mode 100644 DESIGN.md

diff --git a/DESIGN.md b/DESIGN.md
new file mode 100644
index 0000000..396c26e
--- /dev/null
+++ b/DESIGN.md
@@ -0,0 +1,402 @@
+# OpenCD — Design Brief
+
+> **Framework Architecture & Component API Specification**
+> Author: Hannibal (A-Team command) | Status: Draft | v0.1.0
+
+---
+
+## 1. Framework Structure
+
+### File Layout
+
+```
+opencd/
+├── opencd.css                 # Main entry point — imports all modules in order
+├── opencd.min.css             # Production build (CSSO / lightningcss)
+│
+├── src/
+│   ├── _reset.css             # Minimal normalize + box-sizing
+│   ├── _variables.css         # CD dimension tokens + Open Props mapping
+│   ├── _jewel-case.css        # Jewel case container (.cd-jewel-case)
+│   ├── _spine.css             # CD spine navigation (.cd-spine)
+│   ├── _leaflet.css           # Leaflet booklet grid (.leaflet-content, .leaflet-page)
+│   ├── _back-tray.css         # Back tray with tray paper (.back-tray, .tray-credits)
+│   ├── _human-advisory.css    # Parental-Advisory style badge (.human-advisory)
+│   ├── _disc-art.css          # CD disc face (.disc-art)
+│   └── _utilities.css         # .cd-grid overlay, helpers, print styles
+│
+├── templates/
+│   ├── jewel-case.html        # Front-facing jewel case with disc art
+│   ├── leaflet.html           # Multi-page booklet with flip navigation
+│   └── back-tray.html         # Back tray with spines + tracklist
+│
+├── DESIGN.md                  # ← This file — architecture specification
+├── RECON.md                   # Face's research output
+├── README.md                  # Existing — user-facing documentation (keep)
+└── package.json               # (future — npm publish workflow)
+```
+
+### Build Principles
+
+- **No build step required** — `opencd.css` is importable directly from `src/` or via CDN
+- **Minified version** produced by lightningcss or CSSO at release time
+- **Pure CSS** — no JavaScript dependency. JS (leaflet page-turn) lives in inline `<script>` on templates
+- **Open Props as sole dependency** — imported via `@import "https://unpkg.com/open-props"` or npm
+- **Source ordering matters** — `_reset.css` → `_variables.css` → components → `_utilities.css`
+
+### Module Responsibility
+
+| Module | File | Exports | Dependencies |
+|--------|------|---------|-------------|
+| Reset | `_reset.css` | Box-sizing, margin reset | none |
+| Variables | `_variables.css` | `--cd-*` custom properties | Open Props |
+| Jewel Case | `_jewel-case.css` | `.cd-jewel-case` layout | Variables |
+| Spine | `_spine.css` | `.cd-spine`, `.spine-label`, `.spine-track` | Variables |
+| Leaflet | `_leaflet.css` | `.leaflet-content`, `.leaflet-page` | Variables |
+| Back Tray | `_back-tray.css` | `.back-tray`, `.tray-credits` | Variables |
+| Advisory | `_human-advisory.css` | `.human-advisory` | Open Props colors |
+| Disc Art | `_disc-art.css` | `.disc-art` | Variables |
+| Utilities | `_utilities.css` | `.cd-grid`, print, responsive overrides | Variables |
+
+---
+
+## 2. Open Props Token Mapping
+
+### CD Dimension Variables (defined in `_variables.css`)
+
+These map physical CD packaging measurements to CSS at 2× scale (1 mm → 2 px).
+
+```css
+:root {
+  /* ── Physical CD Dimensions (2× scale) ── */
+  --cd-jewel-width:      280px;   /* 142 mm × 2 */
+  --cd-jewel-height:     245px;   /* 125 mm × 2 */
+  --cd-jewel-open-width: 560px;   /* 284 mm × 2 — fully open jewel case */
+  --cd-disc-diameter:    240px;   /* 120 mm × 2 */
+  --cd-leaflet-size:     240px;   /* 120 mm × 2 — square booklet page */
+  --cd-spine-width:      14px;    /* ~7 mm × 2 */
+  --cd-tray-width:       260px;   /* ~130 mm × 2 — back tray paper */
+
+  /* ── Derived aspect ratios ── */
+  --cd-aspect-jewel:     280 / 245;
+  --cd-aspect-leaflet:   1 / 1;
+  --cd-aspect-disc:      1 / 1;
+}
+```
+
+### Design Token Mapping (Open Props → OpenCD)
+
+This table extends the README quick-reference with exact variable names.
+
+| Open Props Token | OpenCD Variable | Context | Purpose |
+|---|---|---|---|
+| `--size-fluid-1` | `--cd-space-inset` | Jewel case padding | Responsive breathing room inside the case |
+| `--size-fluid-2` | `--cd-space-stack` | Between leaflet sections | Vertical rhythm |
+| `--size-fluid-3` | `--cd-space-gutter` | Spine ↔ content gap | Separation between navigation and content |
+| `--font-size-fluid-1` | `--cd-font-size-body` | Leaflet body text | Readable booklet prose |
+| `--font-size-fluid-2` | `--cd-font-size-title` | Section headings | Title scale |
+| `--font-size-fluid-3` | `--cd-font-size-display` | Tracklist, hero text | Display / emphasis |
+| `--font-sans` | `--cd-font-label` | Spine, metadata, credits | Sans-serif for labels |
+| `--font-serif` | `--cd-font-body` | Leaflet body, prose | Serif for reading |
+| `--red-6` | `--cd-advisory-red` | Human Advisory badge | Warning / advisory accent |
+| `--red-7` | `--cd-advisory-red-dark` | Advisory badge hover | Darker shade for interaction |
+| `--surface-1` | `--cd-tray-bg` | Tray paper background | Base layer (visible grid) |
+| `--surface-2` | `--cd-tray-bg-raised` | Back tray raised panel | Secondary layer |
+| `--surface-3` | `--cd-tray-bg-sunken` | Inner leaflet area | Deeper layer |
+| `--surface-4` | `--cd-spine-bg` | Spine background | Darkest surface |
+| `--shadow-2` | `--cd-jewel-shadow` | Jewel case inset shadow | 3D depth on case edges |
+| `--shadow-3` | `--cd-jewel-shadow-raised` | Hover/active shadow | Raised state |
+| `--grid-1` | `--cd-grid-color` | Tray grid line color | Visible tray paper grid |
+| `--grid-2` | `--cd-grid-color-alt` | Alternate grid line | Cross-axis grid lines |
+| `--radius-2` | `--cd-jewel-radius` | Jewel case corners | Rounded edges on case |
+| `--radius-3` | `--cd-leaflet-radius` | Leaflet page corners | Rounded booklet pages |
+| `--gray-1` through `--gray-12` | `--cd-text-*` / `--cd-tray-*` | Monochrome palette | Full value range for text and surfaces |
+| `--font-size-0` through `--font-size-3` | `--cd-spine-font-*` | Spine typography | Compact labels on spine |
+
+### Semantic Color Tokens
+
+```css
+:root {
+  --cd-text-primary:    var(--gray-9);
+  --cd-text-secondary:  var(--gray-7);
+  --cd-text-muted:      var(--gray-5);
+  --cd-text-on-spine:   var(--gray-1);
+  --cd-tray-grid:       var(--gray-3);
+  --cd-tray-grid-alt:   var(--gray-2);
+  --cd-tray-bg:         var(--surface-1);
+  --cd-spine-bg:        var(--surface-4);
+  --cd-advisory-red:    var(--red-6);
+  --cd-advisory-bg:     var(--red-0);
+}
+```
+
+### Print & Motion Tokens
+
+```css
+:root {
+  --cd-print-jewel-width:  142mm;
+  --cd-print-jewel-height: 125mm;
+  --cd-transition-duration: 200ms;
+  --cd-ease-flip:          cubic-bezier(0.34, 1.56, 0.64, 1);
+}
+```
+
+---
+
+## 3. Component API
+
+### Class-Based API
+
+All components are opt-in classes applied to semantic HTML elements.
+
+#### `.cd-jewel-case`
+The outer document wrapper. Contains all other components.
+
+```html
+<main class="cd-jewel-case">…</main>
+```
+- **Layout:** `display: grid; grid-template-columns: var(--cd-spine-width) 1fr;`
+- **Sizing:** width = `var(--cd-jewel-width)`, height = `var(--cd-jewel-height)`
+- **Decoration:** rounded corners, box-shadow for 3D jewel case depth
+- **Variants:** `.cd-jewel-case--open` opens to double-width (`--cd-jewel-open-width`)
+
+#### `.cd-spine`
+Top/side navigation bar that reads like a CD spine label.
+
+```html
+<nav class="cd-spine">
+  <span class="spine-label">OPENCD · TRENTUNA</span>
+  <span class="spine-track">01 · jewel-case</span>
+</nav>
+```
+- **Layout:** `writing-mode: vertical-rl` on narrow viewports; horizontal on wide
+- **Typography:** `var(--cd-font-label)`, small caps, letter-spacing
+- **Background:** `var(--cd-spine-bg)` with text on top
+
+#### `.leaflet-content`
+The inner booklet area. Shows visible CD tray grid as background pattern.
+
+```html
+<section class="leaflet-content">
+  <article class="leaflet-page">
+    <h1>Page title</h1>
+    <p>Booklet content here.</p>
+  </article>
+  <article class="leaflet-page">
+    <!-- next page -->
+  </article>
+</section>
+```
+- **Layout:** `display: grid;` with a row per page, or column-based for multi-page
+- **Grid background:** CSS `repeating-linear-gradient` for visible tray paper lines
+- **Sizing:** `max-width: var(--cd-leaflet-size)`
+
+#### `.leaflet-page`
+An individual booklet page. Can be flipped.
+
+- **Layout:** `aspect-ratio: var(--cd-aspect-leaflet)` (square)
+- **Transition:** transform via `--cd-ease-flip` for page-turn effect
+- **Data attributes:**
+  - `data-leaflet-page` — page index (0-based)
+  - `data-leaflet-active` — current visible page (boolean)
+  - `data-leaflet-direction` — `"ltr" | "rtl"` for multi-page flow
+
+#### `.back-tray`
+The back card of the jewel case. Contains track listing and credits.
+
+```html
+<footer class="back-tray">
+  <section class="tray-credits">
+    <h2>Tracklist</h2>
+    <ol>
+      <li>01. jewel-case</li>
+      <li>02. leaflet</li>
+    </ol>
+  </section>
+</footer>
+```
+- **Layout:** `display: grid` with vertical spine labels on each side
+- **Background:** raised panel pattern (`var(--cd-tray-bg-raised)`)
+- **Grid lines:** finer than leaflet (subtle distinction between content and back)
+
+#### `.tray-credits`
+Credits / metadata section inside the back tray.
+
+#### `.human-advisory`
+Parental-Advisory-style badge.
+
+```html
+<aside class="human-advisory">
+  <span class="advisory-label">HUMAN MADE</span>
+  <span class="advisory-text">designed with physical care</span>
+</aside>
+```
+- **Decoration:** Black rectangle with red warning text, mimic Parental Advisory
+- **Position:** Absolute, bottom-right of jewel case
+
+#### `.disc-art`
+The CD disc face area — a circle inside the jewel case.
+
+```html
+<div class="disc-art">
+  <span class="disc-hole">◉</span>
+</div>
+```
+- **Sizing:** `width: var(--cd-disc-diameter)`; circular via `border-radius: 50%`
+- **Decoration:** Subtle radial gradient for disc sheen
+
+#### `.cd-grid`
+Overlay class for visible tray paper grid on any container.
+
+```html
+<div class="back-tray cd-grid">…</div>
+```
+- **Effect:** `background-image: repeating-linear-gradient` lines
+- **Modifiers:** `.cd-grid--fine` (denser grid for tray), `.cd-grid--coarse` (for leaflet)
+
+### Custom Properties API (customization surface)
+
+Users override these on their `:root` or on a container to theme:
+
+```css
+:root {
+  /* Scale */
+  --cd-scale: 2; /* multiplies physical mm → px. Default 2. */
+
+  /* Override any CD dimension */
+  --cd-jewel-width: 320px;
+  --cd-disc-diameter: 260px;
+
+  /* Theming */
+  --cd-tray-bg: #f5f0e8;          /* warm paper */
+  --cd-grid-color: color-mix(in oklch, var(--gray-3), transparent 60%);
+  --cd-spine-bg: #1a1a1a;
+}
+```
+
+### Data Attributes (JS hook surface)
+
+| Attribute | Target | Values | Purpose |
+|---|---|---|---|
+| `data-leaflet-page` | `.leaflet-page` | `0`, `1`, `2`... | Page index |
+| `data-leaflet-active` | `.leaflet-page` | `true`/`false` | Current visible page |
+| `data-leaflet-direction` | `.leaflet-content` | `"ltr"`, `"rtl"` | Reading direction |
+| `data-jewel-state` | `.cd-jewel-case` | `"closed"`, `"open"` | Open/closed state |
+
+---
+
+## 4. Layout Architecture
+
+```
+┌─────────────────────────────────┐
+│  [SPINE]                        │  ← .cd-spine (14px)
+├─────────────────────────────────┤
+│  ┌─────────────────────────┐    │
+│  │                         │    │
+│  │  [LEAFLET CONTENT]      │    │  ← .leaflet-content (240px²)
+│  │  ┌───────────────────┐  │    │
+│  │  │ ● ● ● ●           │  │    │  ← .disc-art (160px disc)
+│  │  └───────────────────┘  │    │
+│  │                         │    │
+│  └─────────────────────────┘    │
+│  ┌─────── [HUMAN ADVISORY] ──┐  │  ← .human-advisory
+│  └───────────────────────────┘  │
+├─────────────────────────────────┤
+│  [BACK TRAY - TRACKLIST]        │  ← .back-tray (hidden until open)
+└─────────────────────────────────┘
+```
+
+### Spine Placement
+
+- **Default:** Top edge (horizontal spine — reads like a CD top spine)
+- **Variant `.cd-spine--side`:** Right edge (vertical spine — like a book)
+- **Variant `.cd-spine--left`:** Left edge for RTL layouts
+
+### Open / Closed States
+
+| State | `.cd-jewel-case` | `.back-tray` | Effect |
+|---|---|---|---|
+| Closed (default) | 280 × 245 px | Hidden | Front face visible |
+| Open | 560 × 245 px | Visible | Fully splayed jewel case |
+
+Toggle via `data-jewel-state="open"` or class `.cd-jewel-case--open`.
+
+---
+
+## 5. Responsive Strategy
+
+### Breakpoints
+
+| Breakpoint | Behavior |
+|---|---|
+| ≥ 600px | Full jewel case dimensions, grid visible |
+| 400–599px | Shrink grid lines, reduce padding, spine goes horizontal |
+| < 400px | Single column, jewel case fills viewport width, disc art stacks above leaflet |
+
+Uses Open Props `--md-*` breakpoint tokens:
+```css
+@media (--md-ONLY) { /* tablet adjustments */ }
+@media (--sm-ONLY) { /* mobile adjustments */ }
+```
+
+---
+
+## 6. Direction for Face's Recon
+
+Face needs to answer five specific questions before implementation begins:
+
+### Q1: Open Props Token Audit
+- For each token in the mapping table (§2), verify the exact Open Props v2 variable name and value range.
+- Are there newer Open Props tokens (added since README was written) that should be mapped?
+- What is the recommended import path for Open Props v2+? `@import` from CDN vs npm?
+
+### Q2: CD Jewel Case Dimensions
+- Verify the 2× scale factor (142 × 125 mm → 280 × 245 px). Is 2× the right multiplier for web? Should we support a `--cd-scale` variable so users can adjust?
+- Find reference: do jewel cases have ISO standard dimensions? Any regional variations?
+- Document the physical tray paper, leaflet footprint, and CD disc hole diameter (Ø 15 mm center hole).
+
+### Q3: ASW Design Patterns (at `~/releases/asw/`)
+- What semantic HTML patterns does ASW use? Provide specific code examples.
+- How does ASW handle grid overlays? Inspect their grid CSS.
+- Does ASW have a color system we should align with?
+
+### Q4: CD Packaging Design References
+- Find 3–5 strong examples of CD jewel case packaging with distinctive visual elements.
+- What makes a "visible grid" aesthetic work? How fine/coarse should the grid be?
+- Document the Parental Advisory badge exact typography/ratios for the Human Advisory badge.
+
+### Q5: trentuna.com Design Aesthetic
+- Visit trentuna.com if available. Document the current visual direction.
+- Font choices: what typefaces are in use?
+- Color palette: what hues dominate?
+- Grid approach: does trentuna.com use a visible grid?
+
+### Deliverable
+
+Face outputs `RECON.md` in the repo root with:
+- Answers to all five questions above
+- Code snippets / examples from ASW
+- Screenshots or descriptions of references
+- Signed commit
+
+---
+
+## 7. Implementation Sequence
+
+This is the build order once recon is complete:
+
+| Phase | Who | What |
+|-------|-----|------|
+| 1. Recon | Face | `RECON.md` — answers to §6 |
+| 2. Gate Review | Amy | Validate dimension accuracy, token mapping, API surface |
+| 3. Settle variables | Murdock | `_variables.css`, `_reset.css` — all custom properties |
+| 4. Build components | Murdock → B.A. | Each `_*.css` module in dependency order |
+| 5. Templates | Murdock | `templates/*.html` — three complete standalone pages |
+| 6. Integration | B.A. | `opencd.css` entry point, `opencd.min.css` build |
+| 7. Validate | Amy | Visual regression, responsive testing, print preview |
+| 8. Release | Hannibal | Tag, deploy, announce |
+
+---
+
+*"I love it when a plan comes together."*
+— Colonel John H. Smith