Version: 1.3.0 Last updated: 2026-07-27 Status: design authority for the shipped product. Where this document and the product spec disagree on how something looks, this document wins; where they disagree on scope, the spec wins.
1. The one-line idea
Encoded musical cartography: deep navy ink on white paper, where every mark is a measurement and color means only one thing — which layer of intelligence a value came from.
2. Paper and ink
- Background is paper white. Foreground, borders, axes, table rules, chart lines and typography are deep navy ink
#1F2A44. - All structure is ink. Color never carries structure.
- Dark mode is a non-goal for this release. The
.darkblock is kept in sync with the paper values so no surface can render unreadable.
3. The color system
| Token | Hex | Meaning |
|---|---|---|
--measured | #3B82F6 blue | Layer 1 — measured by a provider or by audio analysis |
--derived | #D99A2B amber | Layer 2 — computed from measurements |
--interpreted | #7E3B5C wine | Layer 3 — model interpretation, always evidence-backed |
--creative | #159C8C teal | Layer 4 — generative and creative output |
--intensity | #D85C5C coral | peaks, drivers, tension — emphasis, never a layer |
--uncertain | #A7AFBA gray | missing, unmeasured, low confidence |
Memory rule: blue measures · amber derives · wine explains · teal creates · coral intensifies · gray admits uncertainty.
Each token has a -strong variant that is contrast-safe for text on paper. The base value is for strokes, fills and accents. Components never hardcode hex or utility colors such as text-white; everything routes through tokens in src/styles.css.
4. Confidence is line style, never color
| Band | Threshold | Treatment |
|---|---|---|
| High | ≥ 0.90 | solid border, full opacity |
| Moderate | ≥ 0.60 | dashed border, 92% opacity |
| Low | < 0.60 | dotted border, 75% opacity |
SVG elements use the stroke-side equivalents (stroke-conf-high/moderate/low). Because confidence never touches hue, a color-blind reader and a grayscale printout both read the same epistemic story.
5. The coverage rule
Outside the Genome Spiral, color touches at most roughly 10% of any screen. Color appears at sanctioned touchpoints only: layer chips, data strokes, peak/driver marks, and the interpreted rule beside a claim. Backgrounds, cards, headers and body text stay ink on paper.
6. The grayscale test
Every zone must remain fully meaningful with a CSS grayscale filter applied. If information disappears in grayscale, the encoding was leaning on hue and must be re-expressed as line style, weight, position, or label. This runs as a Playwright pass per zone before release.
7. Visual encodings
Genome Spiral
Vertical axis is time. One rung per measured section, or per four bars derived from BPM and meter when no sections exist. Strand separation is section-to-section energy contrast; thickness is section loudness; coral marks the top two energy peaks; wine marks borrowed or non-diatonic harmony; the twist paces to BPM and stops under prefers-reduced-motion. Exempt from the coverage rule. A compact variant sits beside the track title.
Energy Ribbon
Mirror-path ribbon along the time axis. Measured loudness in blue, derived energy in amber, coral markers at peaks, named section boundaries in ink, live playhead, click anywhere to seek.
Chord Constellation
The measured tonic is HOME at the center. Node size is frequency and dwell time; path weight is transition frequency; coral marks tension paths; wine marks borrowed harmony; the active chord highlights with the playhead. Filterable by section, clickable to inspect.
Chorus Lift
Aligned ink bars, before above after, across one section boundary. Coral marks the driving delta. Dimensions are section loudness, section energy, harmonic tension (borrowed-chord share) and harmonic rhythm (chords per minute). Vocal presence and stereo width are track-level measurements today and are labelled as track context, never rendered as per-section values.
8. Honest uncertainty
A visual with no data says so in plain language and names what would fix it. Nothing is invented to fill a frame: where section detection returns a single whole-track span, section-dependent visuals refuse to draw rather than draw one fake section. Unmeasured fields show an em dash with the reason.
9. Evidence in two interactions or fewer
Every interpreted claim carries evidence chips. Hovering a chip explains the tag and its confidence; clicking it scrolls to the measurement and flashes it. No claim is more than two interactions from the number behind it.
10. Motion and accessibility
- One playhead drives every time-based visual; motion exists to show time passing, never for decoration.
prefers-reduced-motiondisables animation app-wide.- Every chart carries a plain-language text summary that stands alone for screen readers.
- Focus states are visible on every interactive element; touch targets meet 44px on mobile.
- Zones stack on small screens; wide data keeps its own horizontal scroller.
11. Out of scope for v1.2
Dark mode, 3D genomes, chart gradients and glows, any electric-violet hue, a global similarity score, and any decoration that does not encode a measurement.