opencd: plan framework architecture — DESIGN.md
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
This commit is contained in:
parent
1ae235fd61
commit
0be1681da2
1 changed files with 402 additions and 0 deletions
402
DESIGN.md
Normal file
402
DESIGN.md
Normal file
|
|
@ -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
|
||||||
Loading…
Add table
Add a link
Reference in a new issue