198 lines
6.2 KiB
Markdown
198 lines
6.2 KiB
Markdown
---
|
|
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
|