Design specification for Cadora's human-in-the-loop review panel: color and type tokens, the panel's anatomy, its states, and interaction rules.

Cadora · design spec

The review gate, by the numbers

Everything needed to rebuild or extend the human review surface — the exact tokens, the panel's anatomy, its states, and how it behaves. The rendered components are live HTML; edit them here or lift the specs into Figma.

Palette

Dark instrument surface · amber signals a human is needed

Amber--amber · #ffd08aReview-gate accent
Green--green · #16c784Approve · gate pass
Red--red · #fb7185Abort · failure
Blue--blue · #3b82f6Document links
Ink--bg · #0f172aPage ground
Canvas--canvas · #111c2fInset · doc rows
Panel--panel-2 · #162237Callout surface
Line--line · #334158Borders
Text--text · #f5f7fbPrimary
Muted--muted · #9aa8bcSecondary · captions

Type & metrics

System sans for reading · monospace for the instrument voice

RoleFamilySize / weightNotes
Node / doc titlesystem-ui15px / 500Run and node names
Body · doc linksystem-ui13px / 400Link color --blue, underline on hover
Label · badge · kindmono10–11px / 600Uppercase, letter-spacing .05em
Time · durationsystem-ui13pxHH:MM:SS · 2m 30s — never raw ISO
MetricValueMetricValue
Card radius12pxControl radius8px
Pill radius999pxCallout border1px var(--amber)
Panel padding12–14pxRow gap6px
Button padding7px 15pxDoc row padding8px 10px

Anatomy — the review panel

The one component the whole journey turns on

1
Review requiredrequirements is waiting for your decision
2
aidlc-docs/inception/requirements/requirements.mdNEWpreview
aidlc-docs/inception/plans/execution-plan.mdNEWpreview
3
Comments — required to request changes
4
ApproveRequest changesAbort
1Gate header — an amber flag plus the waiting node's name. Amber is reserved: it means only one thing, a human is needed.
2Document list — each changed file this stage produced, as a link (opens the rendered doc) with a NEW/MODIFIED kind and an inline preview.
3Comments — free text; required before Request changes, optional otherwise. Travels with the decision into the agent's next prompt.
4Decision row — Approve (green), Request changes (neutral), Abort (red). Semantic color, left-to-right by increasing consequence.
execution-plan.md ▾Ask about this document, or describe a revision…Ask ↩Revise ↩
The run's answer renders here — a question answered inline, or the revised draft shown before you accept it.

The conversation row sits between the documents and the comments: a document picker, one input, and Ask / Revise. Ask answers in place; Revise rewrites the chosen document and re-surfaces it. Each is a real executor turn — style the reply area for streamed text and rendered markdown.

States

Every condition the panel must render

Default · gate open

Review requiredrequirements
requirements.mdNEWpreview
ApproveRequest changesAbort

Preview open

requirements.mdpreview
ApproveRequest changes

Submitting

ApproveRequest changesAbortsubmitting…

Error · fail-soft

(empty)
Request changesrequest_changes requires reviewer comments

No changed documents

Review requireddesign

No changed documents surfaced

ApproveAbort

Resolved · advances

approvednext: design

Asking · awaiting reply

plan.md ▾Why step 2?Ask ↩
thinking…

Answered / revised

Revised in place — approve to keep it.
Step 2 pauses for human review when the node is marked review: true…

Interaction & behavior

What each control does, and the rules that protect the reviewer

ControlActionResult on the run
ApprovePOST decision approveNode passes; run continues to the next gate. Comments (if any) pass downstream.
Request changesPOST request_changes + commentsSame stage re-runs with the comments in its prompt (up to 3 revisions).
AbortPOST abortRun stops, recorded in the evidence pack.
Document linkOpen the rendered fileServes the live under-review doc from the run workspace.
PreviewRender the doc inlineNo navigation; markdown rendered in the panel.
AskPOST a question messageThe parked run runs the executor scoped to the doc; the answer renders in the reply area.
RevisePOST a revision messageThe executor rewrites the doc in place; the new draft is shown and re-surfaced for a decision.
RuleWhy
Auto-refresh pauses during reviewThe 5s poll never rebuilds the panel under the reviewer — no wiped comment, no missed click.
Fail-soft submissionA bad decision or empty required-comment returns a message in place; the gate stays open to retry.
Indefinite wait (--review-timeout 0)An async reviewer can step away; the gate holds rather than failing closed.
Loopback + JSON-only POSTThe write path is local and guarded; the surface is unauthenticated by design.

Voice

Words are part of the design

DoNot
Sentence case — “Request changes”Title Case — “Request Changes”
Name the outcome — “submitted: approve”“Success!”
Say what to do — “Comments required to request changes”“Invalid input”
09:34:06 · 2m 30s2026-07-17T07:34:06.215495+00:00
Tokens and metrics are taken verbatim from cadora/dashboard/static/style.css. Edit the rendered components in place, or hand the palette and metrics tables to a Figma library.