Visual Language Spec · v1
Tepna — Disclosure & Evidence
Two independent axes that solve feature-saturation and trust: depth (how much you see) and evidence (how much to trust it). Reference for the metric-registry rollout.
SYSTEM-COHESION-BRIEF.md
concern #1 · #2
ref impl → OxyDex
01 — COGNITIVE LOAD
Depth selector ● already in ans-design.css
The segmented control and tiering mechanism already exist.mode-bar / .mode-btn drive body[data-mode], and [data-tier] attributes gate visibility. The registry's depth field simply emits these existing attributes. Default Core; the expert opts up. Nothing is invented here — it's documented so the rollout reuses it.
click to preview tier filtering below ↓
Core
depth:'basic' → (no data-tier)
Readiness hero, 4–5 headline KPIs, one plain-language line. The default a normal user meets.
Advanced
depth:'advanced' → data-tier="secondary"
Full metric tables, charts, morphology, CVHR, validation lanes. Adds onto Core.
Research
depth:'research' → data-tier="research"
Experimental composites, DFA/SampEn, the full dump. The "everything" tier = today's UI.
02 — CLINICAL / EPISTEMIC HIERARCHY
Evidence badges ◆ net-new visual language
A metric's trustworthiness, encoded in a fill ladder on one neutral META ink — never a hue, because green/amber/red already mean status and teal/blue mean brand. Fill goes solid → half → hollow → dashed as confidence drops: an intuitive gradient that survives color-blindness and never collides with status color.
Measured
bullseye
Direct sensor reading — the strongest evidence, not computed. A raw statistic of the recorded signal (mean / min / max / nadir / duration / coverage).
Mean SpO₂ · Mean HR · duration · % recorded
Validated
solid fill
Established, externally validated, clinically meaningful derived metric. The gold standard of computed measures.
ODI-4 · T90 · hypoxic burden · RMSSD
Emerging
half fill
Published and promising, but less standardized or device-dependent. Use with context.
DFA α1 · CVHR screen · augmentation idx
Experimental
hollow ring
Plausible, node-computed composites without external validation. Directional only.
NSI · sleep-stability · SBII
Heuristic
dashed ring
Convenience estimates / population proxies. Useful as a trend, not a measurement.
ANS-age · VO₂max est · BP projection
Evidence Measured Validated Emerging Experimental Heuristic one strip per view · cite on hover
03 — APPLIED TO OXYDEX
Both axes, composed
Status hue lives in the value + top-bar; evidence lives in a quiet badge in the card's bottom-right corner (inline + leading in dense tables; after the value on chips). They never touch. Toggle the depth selector above — KPIs gated above the current tier dim out. This is exactly how a node renders once the registry drives it.
Recovery Readiness · KPI strip oxydex-render.js → renderAll
ODI-4
3.1/hr
normal · <5
Mean SpO₂
95%
healthy
Hypoxic burden
42%min/h
mild elevation
CVHR index
8.4/hr
screen, not Dx
NSI
46
composite
Sleep-stability
61
0–100
ANS-age
34yr
proxy
VO₂max est
47ml/kg
estimate
MetricValueEvidenceProvenance (cite)Tier
ODI-43.1 /hrValidatedAASM 4% desaturation indexcore
Hypoxic burden42 %min/hValidatedAzarbarzin 2019, SHHS/MrOSadvanced
DFA α11.08Emergingdetrended fluctuation, short-windowadvanced
NSI46ExperimentalOxyDex composite — internal, unvalidatedresearch
ANS-age34 yrHeuristicHRV→population-norm projectionresearch
04 — WHY TWO AXES, NOT ONE "MODE"
Depth and evidence are orthogonal
The common trap is collapsing complexity and trust into one slider. They're independent: a Core metric can be Validated (ODI-4); a Research metric is usually Experimental — but not always. Keeping two fields is what lets an expert in Research mode still instantly see what's gold vs speculative.
depth ↓ / evidence →Measured ◉Validated ●Emerging ◐Experimental ○Heuristic ◌
Core Mean SpO₂ ODI-4 Mean-HR dip — rare — Readiness
Advanced Mean HR · min HR Hypoxic burden CVHR · DFA α1 SBII VO₂max est
Research — rare — — rare — SampEn NSI · stability BP projection
Both fields live in the registry and travel with the metric — into the screen, the crossnight envelope, and the Integrator longitudinal view. One declaration, three surfaces, zero drift. The badge renderer (MetricRegistry.badge) is shared so a Validated dot looks identical in every node.
Encoding rules (carry into the brief verbatim):
1 — Evidence uses fill/shape on ONE neutral ink (--ev-ink #aab8cc); never green/amber/red (status) or teal/blue (brand).
2 — Fill ladder = confidence ladder: bullseye ◉ (measured) → solid ● → half ◐ → hollow ○ → dashed ◌.
3 — Status hue stays on the value + KPI top-bar; evidence badge sits in the card's bottom-right corner (inline + leading in dense tables; after the value on chips). They never share a channel.
4 — depth → existing [data-tier] + body[data-mode]; evidence → new MetricRegistry.badge(). Two fields, one registry entry.
5 — Legend: one strip per view; cite string on hover/title of each badge.