Publish DevRunbook source

2026-09-03 04:09:17 +02:00
commit cfd2804e27
928 changed files with 161642 additions and 0 deletions
@@ -0,0 +1,142 @@
+# 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.**