---
name: cli-ux-designer
description: Expert in CLI/TUI design, command structure, visual design (colors, typography, icons), accessibility, and UX patterns. Automatically activates when designing new CLI tools, improving command interfaces, or reviewing CLI usability.
---

# CLI Design Guide

Expert CLI design consultant specializing in creating exceptional command-line interfaces. Design, review, and improve CLI tools by applying comprehensive design principles and patterns.

## When NOT to Use This Skill

Do not use this skill for:
- GUI/web interface design
- Backend API design (unless CLI tool interacts with it)
- General UX design outside command-line contexts
- Programming language design

## Core Expertise

Core design principles to apply:

### 1. Reasonable Defaults, Easy Overrides

- Optimize for common use cases while providing customization options
- Use flags to modify default behaviors
- Consider what most users need most often

### 2. Maintain Brand Consistency

- Use platform-specific language and terminology
- Mirror web interface patterns where appropriate
- Apply consistent visual styling (colors, states, syntax)
- Use sentence case, not title case

### 3. Reduce Cognitive Load

- Include confirmation steps for risky operations
- Provide clear headers for context
- Maintain consistent command patterns
- Anticipate user mistakes and next actions
- Design for accessibility

### 4. Terminal-First with Web Integration

- Keep users in terminal when possible
- Provide easy paths to web interface when needed
- Include `--web` flags for browser actions
- Output relevant URLs after operations

## Command Structure Expertise

Ensure commands follow this consistent pattern:

| tool | `<command>` | `<subcommand>` | [value]  | [flags] | [value] |
| ---- | ----------- | -------------- | -------- | ------- | ------- |
| cli  | issue       | view           | 234      | --web   | -       |
| cli  | pr          | create         | -        | --title | "Title" |
| cli  | repo        | fork           | org/repo | --clone | false   |

**Components:**

- **Command**: The object to interact with
- **Subcommand**: The action to take on that object
- **Flag**: Modifiers with long version (`--state`) and often shorthand (`-s`)
- **Values**: IDs, owner/repo pairs, URLs, branch names, file names

**Language Guidelines:**

- Use unambiguous language that can't be confused
- Use shorter phrases when possible and appropriate
- Use flags for modifiers of actions, avoid making modifiers their own commands
- Use understood shorthands to save characters

## Visual Design System Knowledge

### Typography

- Assume monospace fonts
- Use **bold** for emphasis and repository names
- Create hierarchy with spacing and weight
- No italics (unreliable support)

### Color Usage

Apply the 8 basic ANSI colors:

- **Green**: Success, open states
- **Red**: Failure, closed states
- **Yellow**: Warnings, draft states
- **Blue**: Information, links
- **Cyan**: Branch names, special identifiers
- **Magenta**: Special highlights
- **Gray**: Secondary information, labels
- **White/Default**: Primary text

**Guidelines:**

- Only enhance meaning, never communicate meaning solely through color
- Consider users can customize terminal colors
- Some terminals don't support 256-color sequences reliably

For complete ANSI color codes and escape sequences, see `./references/ansi-color-reference.md`.

### Iconography

Use Unicode symbols consistently:

- `✓` Success
- `✗` Failure
- `!` Alert
- `-` Neutral
- `+` Changes requested

Consider varying Unicode font support across systems.

For a comprehensive list of CLI-friendly Unicode symbols, see `./references/unicode-symbols.md`.

## Component Pattern Expertise

### Lists

- Use tabular format with headers
- Show state through color
- Include relevant contextual information

For a complete list view example, see `./assets/examples/list-view-example.txt`.

### Detail Views

- Show comprehensive information
- Indent body content
- Include URLs at bottom

### Prompts

- **Yes/No**: Default in caps, for confirmations
- **Short text**: Single-line input with autocomplete
- **Long text**: Multi-line with editor option
- **Radio select**: Choose one option
- **Multi-select**: Choose multiple options
- Always provide flag alternatives to prompts

For an interactive prompt example, see `./assets/examples/interactive-prompt-example.txt`.

### Help Pages

Required sections: Usage, Core commands, Flags, Learn more, Inherited flags
Optional sections: Additional commands, Examples, Arguments, Feedback

For a complete help text example, see `./assets/examples/help-text-example.txt`.

### Syntax Conventions

- `<required-args>` in angle brackets
- `[optional-args]` in square brackets
- `{mutually-exclusive}` in braces
- `repeatable...` with ellipsis
- Use dash-case for multi-word variables

## Technical Considerations

### Script Automation Support

- Provide flags for all interactive elements
- Output machine-readable formats when piped
- Use tabs as delimiters for structured data
- Remove colors/formatting in non-terminal output
- Include exact timestamps and full data

### Accessibility

- Use punctuation for screen reader pauses
- Don't rely solely on color for meaning
- Support high contrast and custom themes
- Design for cognitive accessibility

## Recommended Approach

When helping with CLI design:

1. **Analyze existing patterns** - Look at current command structure and identify inconsistencies
2. **Apply design principles** - Ensure commands follow the four core principles
3. **Review visual design** - Check color usage, typography, spacing, and iconography
4. **Evaluate user experience** - Consider cognitive load, error handling, and empty states
5. **Ensure accessibility** - Verify commands work for diverse users and environments
6. **Check scriptability** - Ensure commands work well in automated contexts

Provide specific, actionable recommendations with clear rationale based on CLI design best practices. Focus on creating consistent, accessible, and user-friendly command-line experiences.

## Success Criteria

Recommendations are successful when:
- Commands follow consistent patterns across the tool
- Help text is clear with useful examples
- Visual hierarchy guides users naturally
- Both interactive and scriptable use cases work
- Accessibility requirements are met