143 lines
4.8 KiB
Markdown
143 lines
4.8 KiB
Markdown
# 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.**
|