roboco/docs/ux_ui/design/content-readability-spec.md

Content-readability spec: markdown, collapsible sections, timestamps

Status: proposed Owner: ux-dev-1 Surface: task detail panel (panel/src/components/tasks/task-detail/) and any other view that renders task-authored markdown or an activity/notes feed (journals, A2A transcript).

Dial read

Per the team design bar, this is dense product UI (task detail / admin panel), not a marketing surface:

• DESIGN_VARIANCE: 2 — predictable, symmetric card layout. Collapsing content changes height, not position; no asymmetric grid.
• MOTION_INTENSITY: 2 — a single transform/opacity/grid-template-rows expand-collapse transition on the section body, nothing else animates.
• VISUAL_DENSITY: 8 — tight padding, no added chrome beyond what already exists in Card, tabular timestamps in list contexts.

Problem

Long task bodies (descriptions, dev/QA/PR-reviewer notes, journal entries) render in full with no way to collapse them, so a task with a large plan or a long QA note pushes the rest of the tab below the fold — this is the "scrolling fatigue" the acceptance criteria name. Separately, the panel currently renders timestamps three different ways depending on which component you're looking at:

Component	Format	Example
progress-timeline.tsx formatTime()	relative bucket, falls back to short absolute past 7 days	"3h ago" / "Jul 3, 02:14 PM"
tab-notes.tsx writtenAt()	always absolute, no time-of-day granularity beyond minutes	"Jul 10, 04:41 AM"
a2a-transcript.tsx	date-fns formatDistanceToNow, always relative, no absolute fallback	"3 hours ago"

Three renderers means three different date-math implementations to keep correct and three different reading experiences in the same activity feed. This spec fixes both problems without introducing a new dependency — date-fns is already installed and used by a2a-transcript.tsx.

1. Collapsible-section pattern

Use the existing Radix wrapper (panel/src/components/ui/collapsible.tsx, Collapsible/CollapsibleTrigger/CollapsibleContent) — do not add a new library or hand-roll a useState show/hide toggle for this; the primitive already handles the data-state/animation attributes lint components key off.

Trigger condition. A markdown body collapses when its rendered content would exceed ~10 lines or ~640 characters of source markdown, whichever comes first — measured on the raw markdown string before render, not the rendered DOM height, so the decision is synchronous and doesn't require a layout pass. Content under that threshold renders inline with no trigger/affordance at all (a collapse control on a 2-line note is chrome for its own sake).

Default state by field, not a single global rule — a reader's expectation of "do I need this right now" differs per field:

Field / feed	Default state	Rationale
Task description	open	The task's own brief — the reason the reader opened the task.
dev_notes / qa_notes / pr_reviewer_notes / auditor_notes / doc_notes	collapsed if over threshold	Historical record; opened on demand while triaging or auditing, not on first load.
quick_context (resumption)	open	Explicitly the field a resuming agent/PM needs first.
Progress-timeline / journal entries (list items)	collapsed, most recent 2 entries open	Matches "activity feed" convention — recent items visible, older ones summarized.
Task constraints	collapsed	Read-only, project-wide, rarely the thing a reader is here for.

Affordance. The CollapsibleTrigger wraps a text button reading Show more (N lines) / Show less, right-aligned in the existing CardHeader row those components already use (see tab-notes.tsx's header flex items-center justify-between) — no new header layout. Use a ChevronDown (lucide-react, already a dependency) that rotates 180° on open via data-[state=open]:rotate-180 transition-transform, matching the MOTION_INTENSITY: 2 budget (transform only, no scroll listener).

Persistence. Collapse state is component-local (useState), not persisted to the task record or localStorage — a reader re-opening the tab should see the field-default state again, not their last session's toggle. This keeps the change purely presentational with zero backend/schema touch.

Accessibility. CollapsibleTrigger already renders aria-expanded via the Radix primitive; keep the visible label text in sync with that state ("Show more" / "Show less", not just an icon) so screen readers get the same information sighted users do.

2. Markdown rendering treatment

The existing Markdown component (panel/src/components/ui/markdown.tsx) already defines the full token set — this spec does not introduce a second markdown renderer or a competing prose scale. It formalizes which of its two existing modes (compact vs. default) each surface should use, since that choice is currently made ad hoc per call site:

• Default mode (prose-headings:font-bold, h1 2xl / h2 xl with a bottom border / h3 lg / h4 base, prose-pre:bg-muted prose-pre:border prose-pre:rounded-lg) is for content the reader is reading top-to-bottom as a document: task description, dev_notes/qa_notes/etc. bodies, journal entries, constraints.
• compact mode (uniform text-xs headings, hidden pre blocks, tight list/paragraph spacing) is for anything rendered inside a list row or card summary where markdown is secondary to the surrounding metadata — e.g. a one-line progress-update message or an A2A transcript bubble. Do not disable compact's prose-pre:hidden for these contexts: a code block inside a chat bubble already breaks density, and this spec's threshold-based collapse (§1) is the mechanism for anyone who needs the full content, not an inline fenced-block render.
• Code blocks (default mode only, since compact hides them): rely on the existing prose-pre:bg-muted prose-pre:border prose-pre:rounded-lg plus inline-code's prose-code:bg-muted prose-code:rounded prose-code:font-mono — this already matches the panel's card/muted tokens, so no new color is introduced. No syntax highlighting — out of scope; a highlighter is a new dependency this spec's content doesn't justify (ponytail: revisit only if a future task specifically needs highlighted diffs/code review inline).
• Lists: GFM task-list checkboxes already render via the Checkbox component when onCheckboxChange is supplied (editable contexts: description, notes) and as a plain styled input[type=checkbox] otherwise (read-only contexts: journals, PR bodies) — keep that split; do not force every consumer to wire up onCheckboxChange.

No changes to markdown.tsx's Tailwind token classes are proposed — they already satisfy this criterion. What was missing was a documented rule for which mode a new call site should pick, captured above.

3. Timestamp presentation format

One format, applied everywhere a note or progress/journal entry shows a timestamp: a relative bucket for anything within the last 7 days, an absolute short date+time beyond that — this is progress-timeline.tsx's existing formatTime() behavior, and it becomes the canonical implementation the other two call sites adopt instead of maintaining their own date math:

< 1 min        "Just now"
< 60 min       "{n}m ago"
< 24 h         "{n}h ago"
< 7 d          "{n}d ago"
>= 7 d         "Jul 3, 2:14 PM"   (Intl "MMM d, h:mm a", locale en-US)

Always-visible absolute timestamp on hover/focus. Every timestamp element carries a title attribute with the full ISO-derived absolute stamp ("Jul 3, 2026, 2:14:32 PM"), so a relative bucket never fully hides the precise time — this is a one-line addition to each call site, no new component required beyond the shared formatter.

Consolidation, not three rules. Extract progress-timeline.tsx's formatTime() into a shared helper (e.g. panel/src/lib/format-timestamp.ts, matching where other date/agent-name helpers already live like lib/agent-utils.ts) and have tab-notes.tsx's writtenAt() and a2a-transcript.tsx's formatDistanceToNow(...) call replaced with it. This removes two of the three divergent implementations rather than adding a fourth. date-fns stays a dependency (already used elsewhere in the panel) but this specific formatter does not need it — the bucket math is short enough to stay plain Date arithmetic, consistent with formatTime()'s current implementation, so format-timestamp.ts has no new dependency to justify.

Where this applies: progress updates, journal/note entries in every task-detail tab (quick_context/dev_notes/qa_notes/pr_reviewer_notes/ auditor_notes/doc_notes "written at" stamps), and the A2A transcript. Any future feed showing a note/progress entry should reuse the same helper rather than writing a fourth formatter.

Non-goals

• No new component library or animation dependency — everything above composes Collapsible, Markdown, and date-fns/plain Date, all already in the panel's dependency tree.
• No change to how markdown is stored or how notes are written (backend, notes_structured, gateway verbs) — this is purely a rendering-layer spec.
• Syntax highlighting, persisted collapse-state, and a global "collapse all" control are explicitly out of scope for this pass.