| name | console-ux-design |
| description | Create or improve usable command-line and console commands or apps, including Laravel Artisan, Symfony Console, and similar frameworks. Use for command structure, signatures, help, prompts, progress, errors, output, machine formats, automation behavior, and implementation-ready CLI UX. Do not use for web, mobile, native GUI, shell scripting without UX changes, terminal themes, full-screen TUIs, or report-only audits. |
Console UX Design
Design a predictable console interface for people at a terminal and callers in automation.
Stay inside the console boundary
- Create or improve ordinary commands, subcommands, and line-oriented console applications.
- Treat Laravel Artisan, Symfony Console, and similar frameworks as examples, not as universal APIs.
- Analyze an existing command when that analysis leads to a redesign or implementation-ready change.
- Do not turn a report-only audit into a redesign. Do not cover web, mobile, native GUI, terminal-emulator themes, or full-screen terminal user interfaces.
- Do not treat shell implementation alone as UX work. Activate only when the command's contract or user experience changes.
Establish the operating context
Before designing, determine:
- the user's task, domain vocabulary, command frequency, and cost of mistakes;
- novice, expert, and automation journeys;
- current command names, signatures, help, output, exit codes, compatibility promises, and tests;
- supported platforms, shells, console framework, terminal widths, locales, and character encodings;
- TTY and redirected behavior for standard input, output, and error;
- interactive, non-interactive, quiet, verbose, color-disabled, and machine-readable modes;
- destructive effects, secrets, cancellation, partial work, retries, and cleanup obligations.
Mark missing facts and compatibility constraints instead of inventing them.
Read only the references the task needs
- Read references/command-contract.md when defining taxonomy, names, signatures, discoverability, automation behavior, streams, formats, exit codes, aliases, or deprecation.
- Read references/runtime-interaction-and-output.md when defining prompts, confirmation, progress, errors, recovery, text layout, color, verbosity, localization, accessibility, or cancellation.
- Read references/validation.md when planning implementation handoff, acceptance criteria, transcripts, tests, or final verification.
Read all three for a new command family or an end-to-end redesign. Keep framework-specific syntax in examples and map the resulting contract to the project's actual framework only after inspecting its version and conventions.
Produce a reviewable design
Deliver the smallest artifact that makes implementation unambiguous. Include, as applicable:
- user tasks and operating contexts;
- proposed command tree and signatures;
- help and completion behavior;
- interaction states and recovery paths;
- stream, format, verbosity, color, and terminal-layout rules;
- exit-code and automation contract;
- compatibility, migration, and deprecation decisions;
- implementation notes and acceptance tests.
Show before-and-after transcripts for material changes. Separate required behavior from illustrative wording so reviewers can approve the contract without freezing every sentence.
Preserve safety and composability
- Never make an interactive prompt the only way to complete a command that is expected to run in automation.
- Never print secrets or mix diagnostics into machine-readable standard output.
- Never rely on color, animation, or cursor control as the sole carrier of meaning.
- Never treat missing input, EOF, ambiguous confirmation, or an unavailable TTY as consent. Permit non-interactive destructive execution only with fully explicit, validated targets and a documented pre-authorized override.
- Define stable success and failure signals before polishing presentation.
- Preserve user data and describe partial-work and cancellation behavior before implementation.
