# 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.**