Loops Feature Design Handoff Mqo1ynjj

Loops feature — design handoff

Purpose of this file. A cold-start briefing so a new chat with another LLM can continue designing AGH's "Loops" feature screens without re-deriving anything. Paste this whole file into the new conversation as context. It records what was built, what's left, the design system, and the spec model. HTML mockups are the deliverables — this doc only describes them.

Last update: redesign pass complete. The first five screens were rebuilt to match the real AGH operator UI (much quieter, color = state only) and then stripped down to content + header only (the app rail + nav sidebar live in the real app, so the mockups must NOT include them). Read §4 and §10 carefully before building more.

1. Mission

Design all UI screens for AGH's new Loops feature — a mix of the new "loop engineering" paradigm with static DAG workflows. Deliverables are high-fidelity, self-contained HTML mockups (one file per screen, inline CSS/JS).

Scope of each mockup = page CONTENT + its in-page header (topbar) only. The workspace rail (56px) and nav sidebar (244px) already exist in the real app and were intentionally removed from these references. Do NOT re-add them. (See §10.)

Ground truth = the spec only. Do not invent features the spec doesn't describe. Spec folder (this repo is linked read-only in the design project):

/Users/pedronauck/dev/compozy/agh/.compozy/tasks/loops/
  _prd.md  _techspec.md  product-ux.md  use-cases.md  requirements.md
  adrs/adr-001..016   analysis/01..17

The AGH design system is the other source of truth: /Users/pedronauck/dev/compozy/agh/DESIGN.md + PRODUCT.md (token source: packages/ui/src/tokens.css). Real UI patterns to copy live in web/src/systems/* and packages/ui/src/components/*.

2. Where the artifacts live

The mockups are in the Open Design project workspace (NOT in the agh repo):

/Users/pedronauck/Library/Application Support/Open Design/namespaces/release-stable/data/projects/bb1d96e1-f5c1-4478-a88b-10abd624f30a/

Each screen is one standalone .html, previewable on its own. (loops-index-2.html — the old phantom duplicate — has been deleted.)

3. Product model (keep this accurate — verified against the spec)

• Two nouns only: Loops (the catalog) and Runs (the executions). No third noun — no "ready to run", "spec", or "workflow" screens.
• A Loop = a contract (goal → verify → stop) + a body (a static DAG of steps) + typed declared inputs. It runs on AGH's autonomy kernel (not a 2nd executor).
• Arrive-and-use is the hero path: pick a Loop → fill an auto-generated input form → Run → watch it iterate live. Built-ins run with zero authoring.
• Runs iterate across generations. Re-attempt strategy: failed-only (default — re-runs failed/pending nodes plus their transitive downstream dependents; carries succeeded node outputs forward as read-only) | full-body.
• Terminal outcomes — always explicit & honest: done · failed · exhausted · stalled. needs-approval is a LIVE pause, not terminal. Other live states: queued / ready / running / paused / watching.
• Node classes: action (run-agent, call-tool, channel-post / converse-and-decide) · control (fan-out, collect, branch, gate, sub-loop) · source (watch-source, file-import, input).
• Verification kinds: command (exit code/stdout) · agent-judge (rubric → revise/approve) · human (approval gate) · (extension via tool registry).
• Limits & daemon ceilings (per-loop default / hard ceiling): iteration_cap 10/100 · budget.tokens 2M/20M (0 = unlimited; opt-in) · budget.wall_clock_sec 30m/7d (opt-in) · budget.usd unset · no_progress.window 3/10 · fan_out_ceiling 4/64 · gate.max_revisions 3/10. Ceilings are hard backstops — never editable in the UI. Watch loops default to iteration_cap 0 (unbounded).
• DSL agh.loop/v1: meta, inputs, contract { goal, definition_of_done, verification[], terminal_states, iteration_cap, no_progress, budget, fan_out_ceiling }, graph { nodes[], edges[] }, start[]. Declared-input types: string/number/bool/file/agent/ref.
• Linter invariants (the builder surfaces them, never re-implements): acyclicity · reachability · termination · fan-out finiteness. Publish returns 422 with per-node errors.

4. Design system — REBUILT to match real AGH (read before coding)

The screens now mirror the real AGH operator UI (web/ + packages/ui), per DESIGN.md. The atmosphere: warm near-black canvas, quiet/dense/intentional, flat depth, a single accent, signal colors as desaturated tint + text (never solid banners).

The golden rule: color carries STATE, not category. This was the #1 problem with the first draft. Node type (action/control/source) is a neutral mono label — it is NOT color-coded. Only run/node state gets color (success/warning/danger/accent/info), and even then as a small dot or a tint pill.

Tokens (these are the AGH tokens — copy verbatim into every screen's :root):

surfaces  --rail #0c0b0b · --canvas #131211 · --canvas-soft #1a1918 · --canvas-tint #1c1b1a · --elevated #232220
text      --fg #ececef · --fg-strong #f6f6f8 · --muted #9a9a9f · --subtle #76767c · --faint #545458
lines     --line rgba(255,255,255,.055) · --line-soft .03 · --line-strong .09
accent    --accent #e8572a · --accent-hover #d14e25 · --accent-strong #f6874f · --accent-ink #17110f · --accent-tint .10
          (SCARCE — primary CTA, active nav icon, running/active state, brand mark only)
status    success #5fbf85/.08 · warning #d6a647/.08 · danger #e0635a/.09 · info #8e8eb5/.12 · neutral #7a7a80/.06
          (always tint-bg + saturated text; NEVER solid fills)
glaze     --row-hover .022 · --row-selected .03 · --input-fill .025 · --badge-fill .05 · --btn-fill .04 · --bar-fill .18
type      Inter Variable (font-feature cv01,ss03) + JetBrains Mono
scale     body 13.5px · detail-h1 22px/-.028em · section label 10.5-11px uppercase · mono ids ~11px
radii     4/5/6/8/10/14 · pill 9999 · motion 140ms cubic-bezier(.2,0,0,1)

• Layout = content + header only. Each file is .shell{height:100vh} → .main (flex column: a 48px .topbar header that's flex:none + a scrolling region flex:1;min-height:0). NO workspace rail, NO nav panel. The in-page right rails that carry per-loop/per-run info (run-detail events/facts column, loop-detail inputs/limits column) ARE content — keep them.
• Header (topbar): 48px, border-bottom:1px solid --line, holds a breadcrumb on the left (e.g. Loops › software-delivery) and trailing actions/search on the right.
• Page head (in body): H1 at detail-h1 (22px, weight 560), a mono count-chip, and a thin muted meta line. No marketing lead paragraphs, no glowing eyebrow dots.
• Status → visual (shared .pill--* vocabulary, tint + text): running = accent + pulse · watching = info + pulse · needs-approval = info · done = success · failed = danger · exhausted = warning · stalled = neutral. In dense tables a 6px state dot inside the pill is enough; reserve the pulse for live states only (wrap pulses in prefers-reduced-motion).
• DAG / nodes: neutral surfaces (--canvas-tint), node class shown as a small mono uppercase label (--faint/--subtle); gates may tint their verdict text by tone. Build with positioned divs/SVG (ReactFlow-style), not a real graph library.

Hard rules (impeccable — these were violated in the first draft, do not repeat):

• One accent, used sparingly. No rainbow category colors. Color = state only.
• No side-stripe borders (border-left/right > 1px as accent). Use full borders + tint.
• No gradients (no radial hero glows, no gradient card/gate/header backgrounds).
• Flat depth — no shadows on content cards; only overlays/modals may use --shadow-overlay.
• No em dashes in copy — use commas/colons/periods/parens. (— as a "no value" placeholder, e.g. Cost — unset, is fine.)
• Real product UI only — no demo/viewport/theme/platform toggles, no metadata/process cards ("Ready/Next", "the screenshot that sells the product", etc.). No AI-slop emoji rows. Honest placeholders over invented stats.

5. DONE (all rebuilt this session: quiet AGH pattern + content-only)

Cross-screen consistency is locked: identical :root token block, shell, .pill--* vocabulary, type scale. Spec numbers fact-checked (limits, states, node count = 6 for software-delivery, sidebar "Runs" count = 3 active).

6. REMAINING (priority order — build content + header only, same tokens/shell)

1. loop-editor.html — Visual DAG builder (fork & edit; the other heavy screen). Canvas of action/control/source nodes (neutral, class as mono label) + edges; node palette; right node-inspector with per-class config (action: action_ref/inputs/timeout_sec/session_mode; gate: verification[]/verdict_policy/max_revisions/verdict_source; fan-out: collection_ref/max_fan_out; branch: condition AST); inline linter panel (acyclicity/reachability/termination/fan-out finiteness) with per-node error highlight; toolbar (add/validate/publish); version sidebar. Positioned divs/SVG, not a graph library. A read-only viewer variant is reused on the detail/run pages. NB: opens EXISTING loops only (fork-and-edit) — ADR-008 forbids a blank-canvas from-scratch builder.
2. loop-run-form.html — Run a loop (hero path). Auto-generated input form from the Loop's declared inputs (typed fields: string/number/bool/file/agent/ref) with required validation; Advanced panel = per-run limit overrides bounded by the daemon ceiling (greyed at ceiling); live contract/preview pane. Two-column form+preview, matching the create-trigger-redesign.html / create-task-redesign.html / create-job-redesign.html pattern (but content-only). Run + Dry-run.
3. loop-configure.html — Configure (light; power ceiling, never the hero). No-fork tweaks: verification-check select, human-approval gate toggle, re-attempt granularity (failed-only | full-body), per-loop limit overrides. Sheet/modal; no structural change; Save / Reset to defaults.

Optional later: version diff, node-run drilldown modal, watch-source quiet/stall state, empty states.

7. How to continue (workflow)

1. Read this file + DESIGN.md/PRODUCT.md + the spec folder. Don't invent — every term/limit must trace to the spec. Use the impeccable skill (it loads the AGH register + rules); the user expects it applied extensively.
2. Copy the :root token block + the content-only shell (.shell{height:100vh} + .main topbar/scroll) from loop-detail.html or run-detail.html. Keep each file fully self-contained (inline CSS/JS). Do NOT add a workspace rail or nav panel.
3. Build the screen, grounding all data in §3 and reusing the .pill--* status vocabulary.
4. Flip its card on loops-index.html from "Planned" → "Built".
5. Self-check against §4's hard rules (color=state, no side-stripe/gradient/em-dash, flat, one accent), then a quick 5-dim critique (philosophy/hierarchy/execution/specificity/ restraint) before shipping.

8. Open decisions / flags

• Global Runs route: product-ux.md puts run history under each Loop and says there is no separate global Runs nav route. runs.html was kept as an operator convenience (and as the run-detail "All runs" target). If strict spec-IA is wanted, fold it into the catalog/loop-detail instead. (Decision pending the user.)
• Palette: AGH operator (warm-dark + orange), matching the real app. A Linear-indigo reskin would be a pure token swap.
• App shell removed by request: mockups are content + header only; the real app supplies the rail/sidebar. New screens must follow suit.

9. Suggested skills (for the next session)

• impeccable — UI quality (hierarchy, states, accessibility, anti-slop). Use it.
• agh-design — AGH branded UI/asset generation.
• agh-ui-screenshot — deterministic PNGs for visual-parity checks.
• compozy — repo conventions, for when this moves to real implementation.

10. Key lessons from the redesign pass (don't regress)

• Color = state, never category. The first draft rainbow-coded node classes (action=blue, control=amber/purple, source=green) and per-category catalog icons. All neutralized. Keep nodes/icons neutral; let success/warning/danger/accent/info mark state only.
• Quiet > dense-and-loud. Dropped marketing-scale headlines (34–58px → 22px), glowing eyebrow dots, marketing lead paragraphs, hover-lift transforms, and nested bordered cards. Prefer the Section pattern (uppercase label + hairline-separated rows) over stacked cards.
• Banned and removed: side-stripe borders, gradient backgrounds (incl. the launcher's radial glow), peach/off-palette inline-code colors, em dashes in copy.
• Content + header only: no workspace rail, no nav panel. In-page info rails are content.
• These screens are the reference for the real web/ implementation, so they must look like AGH already — earned familiarity, the tool disappearing into the task.

Provenance

Formalized by Open Design from candidate 51782ac8-6dff-4bfe-bd19-8cc756e64af8.