DevRunbook-Public/docs/30-screen-state-specification.md

30 — Screen and state specification

Purpose

This document supplements the information architecture with mandatory screen behavior. Codex may exercise visual creativity, but it must not omit state handling, provenance, keyboard access or risk communication.

Global application shell

Persistent elements:

• product navigation;
• workspace switcher, even when only one personal workspace exists;
• command palette;
• theme control;
• actor menu;
• integration/job problem indicator only when action is required.

Global states:

• authenticated normal;
• first-run setup;
• database not ready;
• worker degraded;
• storage degraded;
• session expired with draft preservation;
• global authorization denied;
• offline or failed network request with retry.

Never replace the entire application with a generic spinner. Retain stable navigation and show skeletons or localized progress.

Command Center

Required sections:

1. intent entry;
2. ranked playbook matches with explanation;
3. continue-draft card;
4. repository recommendations/findings;
5. recently generated tasks;
6. integration or job attention items.

States:

• empty new user;
• no repositories yet;
• typed intent with no matches;
• matches requiring repository context;
• stale repository snapshot;
• all healthy with no attention panel.

The intent field searches deterministic indexed content. It must not imply that an AI has already generated a safe executable task.

Library

Required behavior:

• card and dense modes;
• URL-backed query, filters, sort and page cursor;
• filter count and clear-all action;
• quality/lifecycle explanation;
• built-in/private/imported source label;
• deprecated replacement link;
• favorite action with optimistic UI and rollback.

States:

• initial loading;
• no accessible content;
• zero results with recovery suggestions;
• invalid URL filter ignored with warning;
• partial search degradation;
• stale search projection admin warning.

Playbook detail

Mandatory panels:

• outcome and compose action;
• use and non-use cases;
• risk/autonomy/mode summary;
• inputs;
• workflow;
• guardrails;
• validation and completion;
• compatibility and limitations;
• quality evidence;
• package files/version history;
• deterministic example preview.

A draft or deprecated version cannot visually resemble a validated current recommendation.

Repository list and workspace

List supports manual and Gitea sources, stale/degraded status and last evidence timestamp.

Repository workspace tabs:

• Overview
• Profile
• Commands
• Paths & Policies
• Evidence
• Findings
• Recommended Playbooks
• Generated Tasks

States:

• manual profile only;
• connected and healthy;
• token invalid;
• permission-limited;
• Gitea unavailable with last snapshot retained;
• snapshot collecting;
• snapshot partially failed;
• archived repository.

Source facts and manual overrides must be visually distinct.

Repository profile editor

Sections:

• identity and repository type;
• stack;
• commands;
• path classes;
• policies;
• source evidence and overrides;
• import/export.

Behavior:

• changes create a new revision only after save;
• show unresolved inferred commands;
• require confirmation before marking a command safe for agent suggestion;
• detect protected/generated/excluded path overlap;
• preview capabilities satisfied by the profile;
• compare against prior revision before saving.

Composer

Desktop regions:

• configuration rail;
• prompt preview;
• issue/provenance inspector.

Mandatory steps:

1. playbook and version;
2. repository/profile;
3. task inputs;
4. scope and protected paths;
5. work mode and autonomy;
6. validation;
7. review/export.

States:

• autosaving;
• saved;
• local unsaved changes;
• required input missing;
• profile incompatible;
• compatibility unknown;
• blocking lint;
• warnings only;
• deterministic preview ready;
• profile revision changed elsewhere;
• historical playbook version selected;
• session expires during editing.

The export bar must state exactly what will be produced and why export is blocked.

Generated task detail

UI title: Generated task, not “execution run”.

Display:

• exact playbook version and package digest;
• exact profile revision/digest;
• work mode and autonomy;
• normalized inputs;
• prompt and render digest;
• lint findings;
• provenance;
• artifacts;
• feedback/notes;
• create-variation action.

Everything except feedback/notes is read-only.

Prompt Lab

Required views:

• package editor tree;
• schema and semantic problems;
• prompt preview;
• package file inventory;
• example cases;
• evaluation results;
• version diff;
• changelog and publish panel.

States:

• imported invalid archive;
• valid draft;
• dirty draft;
• publish conflict;
• digest duplicate;
• missing changelog;
• quality claim exceeds evidence;
• evaluation stale;
• deprecated with replacement.

Settings and administration

Settings:

• profile and sessions;
• users/invitations for administrators;
• integrations;
• retention/storage;
• security and encryption-key status;
• export/delete personal data.

Administration:

• jobs;
• health/readiness;
• catalog import errors;
• migration version;
• audit events;
• support bundle.

Sensitive settings never display complete secrets. Destructive actions provide impact, retention consequences and confirmation.

Responsive and accessibility verification

For every core screen verify:

• 390 px mobile;
• 768 px tablet;
• 1024 px compact laptop;
• 1440 px desktop;
• 2560 px ultrawide.

Core flows must be keyboard-complete. Focus order follows visual order. Drawers and dialogs trap focus correctly, restore focus on close and provide an escape path without data loss. Reduced motion disables topology and pipeline transitions rather than merely shortening them.