opencd/DESIGN.md

# 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