console-ux-design

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,

SKILL.md

GitHub

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 references/go-cli-contracts.md only when the project actually uses Cobra or Viper; detect the installed version before translating the console contract into its APIs.

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:

  1. user tasks and operating contexts;
  2. proposed command tree and signatures;
  3. help and completion behavior;
  4. interaction states and recovery paths;
  5. stream, format, verbosity, color, and terminal-layout rules;
  6. exit-code and automation contract;
  7. compatibility, migration, and deprecation decisions;
  8. 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.