DevRunbook-Public/docs/04-ux-design-system.md

04 — UX and visual design direction

Experience goal

DevRunbook should feel like a premium engineering command center: precise, calm and capable. It must avoid both the sterile appearance of an admin template and the decorative excess of many AI products.

Visual language

• generous spacing and strong typographic hierarchy;
• neutral surfaces with high-contrast technical accents;
• light and dark themes of equal quality;
• restrained category colors used for orientation, never as decoration alone;
• monospaced typography for IDs, versions, commands, paths and prompt blocks;
• humanist sans-serif typography for explanations and controls;
• thin borders, layered surfaces and subtle depth;
• compact density options for library and technical tables.

The final brand should use at most one primary accent plus semantic colors. Do not build a rainbow category system that harms consistency.

Signature interactions

Intent-to-playbook transition

When a user enters an intent, matched playbooks assemble into a ranked operational flow. The animation should demonstrate interpretation, not display generic glowing particles.

Composer pipeline

A subtle horizontal or vertical pipeline shows:

Intent → Context → Guardrails → Workflow → Validation → Export

Selecting a stage highlights the corresponding prompt blocks and form controls.

Autonomy dial

The control has six discrete levels:

1. Observe
2. Diagnose
3. Plan
4. Implement
5. Verify
6. Repair

Each level opens a concise capability sheet showing allowed modifications, expected validation, failure behavior and human checkpoints. It is never represented only by a number.

Provenance highlighting

Hovering or focusing a rendered prompt block highlights its sources:

• playbook base;
• repository profile;
• current user input;
• platform safety policy;
• inferred default.

This is a core trust feature.

Repository topology illustration

On repository workspaces, an interactive but lightweight topology can show applications, services, data stores, build tools and deployment targets. It must have a static accessible alternative and must not pretend to be a complete architecture diagram when evidence is limited.

Core components

• App shell and responsive sidebar
• Command palette
• Universal intent field
• Playbook card and dense row
• Filter drawer and active-filter chips
• Risk badge
• Lifecycle badge
• Quality matrix
• Autonomy dial
• Repository selector
• Scope path picker
• Protected-path callout
• Validation command editor
• Prompt block outline
• Read-only code/Markdown canvas
• Provenance inspector
• Lint issue panel
• Diff viewer
• Run Pack manifest viewer
• Integration health card
• Empty, error and degraded-state panels

Interaction requirements

• Every core action has keyboard access.
• Escape closes transient layers without losing data.
• Autosave state is explicit.
• Copy/export actions provide non-obtrusive confirmation.
• Long-running jobs show stage, last progress and a recoverable failure state.
• Destructive actions describe affected records and retention consequences.
• Advanced controls are progressively disclosed, not hidden behind ambiguous icons.

Responsive strategy

1280–1600 px

Default three-region composer and two-column repository workspace.

Ultrawide

Do not stretch text lines. Use maximum content widths and allow the inspector or history rail to occupy additional space.

900–1279 px

Composer preview and inspector become tabs; configuration remains visible.

Below 900 px

Step-based composer, bottom action bar and filter drawer. Tables become cards or horizontally scrollable only where data comparison requires it.

Accessibility

• visible focus ring on every interactive element;
• semantic heading order;
• labels and descriptions for every input;
• error summary linked to fields;
• accessible live regions for save/export status;
• reduced-motion alternative for every animation;
• text alternatives for topology and pipeline visuals;
• contrast tested in both themes;
• no tooltip-only essential information.

Content tone

• direct and operational;
• avoid anthropomorphizing the platform;
• avoid claims such as “guaranteed” or “perfect prompt”;
• explain risk and evidence plainly;
• use verbs such as Inspect, Compose, Validate, Export and Review;
• reserve “Run” for a generated run record or future direct execution.

Example interface copy

• Hero: What should Codex do?
• Search placeholder: Describe a task, bug, audit or improvement
• Empty repository state: Add a repository profile to reuse real commands, protected paths and stack context.
• Blocking lint state: This task is missing a completion contract. Resolve the highlighted issue before export.
• Gitea degraded state: The repository snapshot remains available, but live refresh is currently unavailable.