cad-atlas/docs/UX-REVIEW-2.md

CAD Atlas — Fresh-Eyes UX Review, Lap 2

Reviewer role: fresh-eyes UX (not implementer). Second pass, judging the shipped progressive-disclosure sprint against the goal set in UX-REVIEW.md. This document critiques; it does not change code.

Sources reviewed:

• docs/UX-REVIEW.md (the spec that was implemented — lap 1)
• internal/atlas/atlas.json (authored data: plain_title, plain, trans_label, trans per stage; plain per node)
• internal/web/static/cad-atlas.html (the renderer: Plain⇄Technical toggle, spine transition labels, legend, substrate/footer hidden in Plain)
• /tmp/ux5/home.png (deployed Plain view, stages 00–04 in frame)

---

1. Verdict

The sprint largely achieved the phase half of the success criterion and made a real dent in the transition half — but it does not fully clear the bar. Grade for a naive viewer: B / B+.

Success criterion was: a viewer with no briefing can explain every phase AND what advances work across every transition.

• Phases: pass. This is the big win. The headline hierarchy works — big plain_title ("Notice what's happening", "Why we're here", "Agents do the work"), a dim technical subtitle, and a jargon-free "what happens" sentence. A cold stakeholder can now narrate every column. This is a genuine, measurable improvement over lap 1, where every column was a mechanism name. Full marks here.

• Transitions: partial. The short spine labels ("Does it matter to us?", "Worth a session?", "Decision reached", "Sealed & agent-ready") convey the gist of each hop, which is a step-change from the blank arrows of lap 1. But three things hold it back from "can explain what advances work":

  1. The actual "what must be true to advance" sentence (trans) is hover-only (an SVG <title> tooltip). That is undiscoverable — nothing signals it's hoverable — and dead on touch devices. So the naive viewer gets the one-line theme, not the gate logic.
  2. The labels are terse and grammatically mixed: some are questions ("Does it matter to us?"), some are achieved-states ("Decision reached", "It's live"). A first-timer builds two different mental models — "is this the question asked here, or the answer reached?" — from one row.
  3. They vanish on narrow screens. All transition labels live inside svg.spine, which is display:none under 820px, and the stacked mobile layout renders no HTML fallback. The single biggest comprehension win of the sprint is absent on a phone.

• The viewport undermines both. The atlas is a 9-column horizontal scroll and a laptop shows ~stages 00–03. That means stage 04, the one human gate — the thing the header literally advertises ("one human gate") — is off-screen on load, along with execution, CI, deploy, and the loop. A first-timer cannot see the shape of the gated flow, cannot see that a human checkpoint exists, and gets no affordance that five more stages are to the right. The atlas's whole payoff — "see the auditable flow from signal to pod at a glance" — is not deliverable in the default viewport.

Net: the copy layer is excellent and the toggle is the right architecture. The remaining gap is structural (what's visible, and where the transition rationale lives), plus one stubborn copy residue (node titles). A naive viewer can explain the phases unprompted; they can explain the transitions only at a slogan level, and only for the half of the pipeline they happen to scroll to.

---

2. What works (the genuine wins)

• Plain default + persisted toggle. Right call, right default. Nothing was thrown away; Technical is the old atlas verbatim. Architecture matches the spec.
• Stage headline hierarchy. plain_title dominant, technical title demoted to a dim mono subtitle, plain sentence underneath. Clean, scannable, correct visual weight.
• Transitions exist at all. Even terse, the labelled arrows turn a row of boxes into a narrated flow. This was the #1 lap-1 miss and it shipped in the default layer.
• Density dropped in Plain. Tags, risk chips, host ribbon and footer are all suppressed in Plain (body.plain), so the reading surface is airy and calm — a real contrast to the lap-1 wall of pills.
• Stage 06 no longer reads as empty. An authored "Automated checks" node with plain copy now backstops the live CI generation, so the CI gate never looks like a no-op on a cold load. Directly fixes lap-1 punch-item 7.
• Feedback bus is honestly hedged. Dashed violet + "partly manual today" in both the loop label and the legend. Matches the dogfooding-honesty discipline.
• The pulse gives direction. The travelling dot is a low-cost "this flows left-to-right, then loops back" cue — helpful for orientation.

---

3. What's still weak (shipped Plain view)

a. Node titles are still pure mechanism-jargon — the exact lap-1 disease, one level down. The node body is now plain, but the node title — the first, boldest thing the eye lands on in a card — is untouched: "Applied AI Radar", "Intention substrate", "Admission controller", "var-go Oath", "Session-Dispatch bridge", "Executor + reviewer loop", "dma-cli · routing + scope", "assessor-loop ledger". The plain body can't fully rescue a card whose title already framed it as a mechanism. The stage head got the plain-title/tech- subtitle treatment; the node did not — an inconsistency that leaves each column half- translated. See §4.

b. The transition rationale is hidden and fragile. As in §1: trans is hover-only (undiscoverable, touch-dead) and the whole label layer disappears under 820px. The "what must be true to advance" — the governance content the atlas exists to show — is the least robustly delivered part of the whole thing.

c. Horizontal scroll with no affordance = half the pipeline is invisible. Nothing at the right edge signals "more stages this way" — no fade, no scrollbar cue, no "→ 04–08", no overview. A first-timer may reasonably believe the pipeline is five stages that end at "Write the work order". The marquee human gate and the entire execute→ship→loop arc are off-frame by default. This is the single largest comprehension barrier remaining.

d. Transition-label attachment is weaker than specced. Lap-1 §5 asked for label chips sitting on the spine; what shipped is floating 10px mono text ~9px above the arrow with no background. On the dark grid it reads, but it floats — the viewer has to mentally bind the text to the arrow beneath it. A chip (or a short leader) would make the label read as of the arrow, not near it.

e. Gate treatment is cryptic. Lap-1 §5 asked for a lock/shield glyph + stronger colour on the two real gates (04 human, 06 CI). What shipped is a "▸ " prefix + gold + bold on those two labels. A naive viewer will not read "▸" as "governance checkpoint"; the only real cue is "one of these labels is gold", which leans entirely on the legend. The two most important hops in the whole atlas deserve a glyph that says stop / check, not an arrowhead character.

f. The legend doesn't match the colours actually on screen. The KEY decodes green/amber/ coral as CI run-states plus gold=gate + dashed=feedback. But in Plain the cards show violet, blue, and coral pills and coloured/dashed borders (council=violet, bridge=dashed-blue, oath=dashed-gold, executor=coral) that the KEY never explains — while the green/amber/coral CI states the KEY does explain are barely present in Plain. So the viewer sees a violet dot on "Intention substrate" and a dashed-gold box on "var-go Oath" with no way to decode them, and a legend describing states they can't see. Colour is carrying two unrelated meanings (authored semantics vs. live CI status) under one key. Either key every colour/border shown in Plain, or strip the decorative pills/borders in Plain so colour means only what the legend says.

g. The technical subtitle is a wash — mild noise, mild help. Under the plain_title sits s.title: sometimes near-plain ("Signals", "Strategic session"), sometimes pure jargon ("TELOS", "Spec → Gitea issue", "PR → CI", "Execute · agentsquad"). For a naive viewer roughly half of these subtitles are undecodable filler directly under the headline; for a new engineer they're a useful canonical-name bridge without a mode-switch. Because it's dim and small the noise cost is low, so keep it — but note the inconsistency: the stage trusts the reader with a dim technical name under a plain headline, yet the node doesn't extend that same courtesy (§4). Apply the pattern uniformly.

h. Unexplained accent colours on headlines. plain_title is violet for TELOS/Loop and amber for the gate. Meaningful to the author, unkeyed for the viewer — a minor echo of problem (f).

i. The feedback bus reads as a mystery line in-viewport. The dashed violet return leg drops straight down out of the TELOS column, but its label ("What did we learn? · feedback bus") sits at the very bottom of a 9-column-wide canvas — off-screen for anyone who hasn't scrolled down and right. In the default view you see an unexplained dashed vertical line and no origin (stage 08 is off-frame right). The honesty hedge is good; the legibility of the loop in the first screen is poor.

---

4. Node-title question — recommendation: add plain node titles; keep the technical name as a dim subtitle inside the card.

Do not keep titles as-is, and do not simply swap in plain titles and delete the technical ones. Mirror the pattern the stage head already uses, one level down:

[pill] Marks its own homework? No.          ← plain_t  (bold, primary)
       Executor + reviewer loop             ← t        (dim mono subtitle)
       One agent does the work; a second,   ← plain    (body, already shipped)
       independent agent reviews it …

Reasoning for the mixed audience:

• The title is the frame. The eye reads title → body. A jargon title ("Admission controller", "var-go Oath") sets a mechanism frame that a plain body then fights against. This is precisely the lap-1 diagnosis ("every node names a mechanism rather than the thing that happens to the work") — it was fixed for stages and bodies but left standing in node titles. The job is half-done until titles get the same treatment.
• A naive viewer needs the plain title. "Marks its own homework? No.", "Signed so tampering shows", "The one human yes/no", "A machine-checkable definition of done" — these are explainable at a glance; "dma-cli · routing + scope" is not.
• A new engineer still needs the canonical name. "var-go Oath", "Ed25519 admission controller", "assessor-loop ledger" are the searchable terms that connect the picture to the code and the brain. Deleting them would help the stakeholder and hurt the engineer — the wrong trade for a "everyone" audience.
• Consistency is its own win. Right now stage heads say "plain big / technical small" and nodes say "technical only". Two rules for the same card type is friction. One rule, applied at both levels, makes the whole atlas feel like one designed system and makes the toggle's mental model ("plain names up front, mechanisms one layer in") coherent.

Concretely: add an optional plain_t per node in atlas.json; in Plain render plain_t as the title and t as a tech-sub-style dim line (reuse the existing class); in Technical keep today's behaviour (t as title). Nodes without a plain_t fall back to t, so it's an incremental authoring task, not a big-bang rewrite.

---

5. Prioritized next punch list (top 6 by comprehension impact)

1. Add plain node titles (plain_t), technical name demoted to a dim in-card subtitle. Highest impact: the title is the first thing read and it's still the lap-1 jargon disease. Finishes the progressive-disclosure job the stages already got. (§3a, §4)

2. Solve the horizontal-scroll blindness. A first-timer must be able to tell the pipeline is nine stages and reach the human gate and the loop. Ship at least a right-edge fade + "→ stages 04–08" hint; ideally a "fit to width / overview" zoom toggle so the whole gated shape (and the one human gate the header promises) is visible at a glance. (§3c)

3. Render transition labels in the stacked/narrow layout, and surface the trans sentence without a hover. The labels currently die under 820px (they live only in the SVG) and the gate rationale is hover-only/touch-dead. Emit trans_label as an HTML element between stacked stages, and make the full trans reachable by click/tap (expandable), not just desktop hover. This is the "explain every transition" half of the success criterion. (§1, §3b)

4. Give the two governance gates (04 human, 06 CI) a real glyph and make the feedback loop legible in-viewport. Replace the "▸" prefix with a lock/shield on the gold gate labels so the checkpoints read as checkpoints; and attach a visible "What did we learn?" chip to the top of the feedback return leg near TELOS so the dashed line isn't a mystery in the first screen. (§3e, §3i)

5. Reconcile the legend with the colours on screen in Plain. Either key every pill/border meaning the Plain view shows (violet/blue/coral pills; council/bridge/oath borders) or drop the decorative pills/borders in Plain so colour means only the CI states the KEY describes. Today the legend and the canvas disagree. (§3f, §3h)

6. Turn floating transition text into attached chips and normalise the grammar. Give each label a small chip background so it reads as on the arrow, and pick one voice — all "what-must-be-true" states ("Mattered to us", "Decision reached", "Human said go", "All checks green", "It's live") reads more consistently than mixing questions and states. (§3d)

---

Scorecard vs. lap-1 punch list

Lap-1 item	Status
1. Label every arrow	Shipped (desktop only; hover-only rationale; dies on mobile)
2. plain_what per stage + demoted title	Shipped — clean
3. Plain⇄Technical toggle, default Plain, persisted	Shipped — correct
4. Plain node primary text, d on demand	Half — bodies plain, titles still jargon (§4)
5. Distinguish the two gates (lock/shield)	Weak — "▸"+gold, no glyph
6. Legend keying colours + gate types	Partial — legend exists but doesn't match Plain colours
7. Fix stage-06 empty column	Shipped — authored fallback node
8. Honest feedback bus + suppress proper nouns in Plain	Half — bus honest; proper nouns still leak via node titles + tech-subs