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).

: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

: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

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

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

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

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

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

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

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

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

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

@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