zhongwei/gh-sjungling-claude-plugins-plugins-cli-developer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:57:38 +08:00
commit 2c1ab284b7
10 changed files with 961 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,15 @@
{
"name": "cli-developer",
"description": "Expert CLI/TUI design consultant for command structure, visual design, accessibility, and UX patterns",
"version": "1.0.0",
"author": {
"name": "Scott",
"email": "scott.jungling@gmail.com"
},
"skills": [
"./skills"
],
"agents": [
"./agents"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# cli-developer
Expert CLI/TUI design consultant for command structure, visual design, accessibility, and UX patterns

9
agents/cli-ux-designer.md Normal file
View File

@@ -0,0 +1,9 @@
---
name: cli-ux-designer
description: Expert in CLI/TUI design, command structure, visual design (colors, typography, icons), accessibility, and UX patterns. Use when designing new CLI tools, improving command interfaces, or reviewing CLI usability. Examples: <example>user: "Building a CLI for cloud management - help design command structure" assistant: "Let me use the cli-ux-designer agent to help design your CLI architecture" <commentary>Since this involves CLI design from scratch, use the cli-ux-designer agent to apply comprehensive design principles.</commentary></example> <example>user: "My CLI help text is confusing users" assistant: "I'll use the cli-ux-designer agent to review and improve your CLI's UX" <commentary>CLI usability issues require specialized design expertise.</commentary></example>
tools: Read, Write, Edit, Grep, Glob, Skill
model: inherit
color: blue
---
Use the cli-developer:cli-ux-designer skill to help with this CLI design task.

69
plugin.lock.json Normal file
View File

@@ -0,0 +1,69 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:sjungling/claude-plugins:plugins/cli-developer",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "f7f93e642d8917e607ee40e38adb0f2ef43928d5",
"treeHash": "ff6f9b9ebe64ca0ff1e7ac32de77f6dd492a9beea347889bdf1b9bc744235de4",
"generatedAt": "2025-11-28T10:28:22.997973Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "cli-developer",
"description": "Expert CLI/TUI design consultant for command structure, visual design, accessibility, and UX patterns",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "3dc7ab50697af0a17119afe5b909aa8612613f68e7e7a7687f85996151027c2b"
},
{
"path": "agents/cli-ux-designer.md",
"sha256": "fb87cb1a2a0ded4a8d95a331a85f2553583fb7ea606145f0fb74b01770426032"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "0049877ef143ffb80b687216a2576df5083bcfba29465017d6cd10731cc5aa63"
},
{
"path": "skills/cli-ux-designer/SKILL.md",
"sha256": "1cd06f1bdda726e1a354e5bce06a5726a21fb5416033b4b10c04018bdd978b1b"
},
{
"path": "skills/cli-ux-designer/references/ansi-color-reference.md",
"sha256": "fd699d8924e1a43c98504e41429c7d29c27c8bfebe1b1aa39733ad84e5d2a3b4"
},
{
"path": "skills/cli-ux-designer/references/unicode-symbols.md",
"sha256": "d8b5714b8c5c807f148edc936daa114beb0b674c1f19880e152a9d757202188c"
},
{
"path": "skills/cli-ux-designer/assets/examples/help-text-example.txt",
"sha256": "9cf0263750fd2b39e0543dfa48be4cca8e241a36fdeff88d5c9a51a6ef59ef76"
},
{
"path": "skills/cli-ux-designer/assets/examples/interactive-prompt-example.txt",
"sha256": "4ac29ec3c8be8a4a96e4b818c55b9b2db5e31bd4843c030c2ed78391a5a48298"
},
{
"path": "skills/cli-ux-designer/assets/examples/list-view-example.txt",
"sha256": "c31b06e729deabdb3a01a489c50be74627f331931a5e111883a234187e973604"
}
],
"dirSha256": "ff6f9b9ebe64ca0ff1e7ac32de77f6dd492a9beea347889bdf1b9bc744235de4"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

197
skills/cli-ux-designer/SKILL.md Normal file
View File

@@ -0,0 +1,197 @@
---
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

41
skills/cli-ux-designer/assets/examples/help-text-example.txt Normal file
View File

@@ -0,0 +1,41 @@
gh issue - Manage issues
USAGE
gh issue <command> [flags]
CORE COMMANDS
create: Create a new issue
list: List issues in a repository
view: Display the details of an issue
close: Close an issue
reopen: Reopen a closed issue
comment: Add a comment to an issue
edit: Edit an issue
status: Show status of relevant issues
ADDITIONAL COMMANDS
delete: Delete an issue
lock: Lock issue conversation
pin: Pin an issue
transfer: Transfer issue to another repository
unlock: Unlock issue conversation
unpin: Unpin an issue
FLAGS
-R, --repo [HOST/]OWNER/REPO Select another repository using the [HOST/]OWNER/REPO format
INHERITED FLAGS
--help Show help for command
EXAMPLES
$ gh issue create --title "Bug report" --body "Something is broken"
$ gh issue list --assignee @me --state open
$ gh issue view 123 --web
$ gh issue close 456 --comment "Fixed in PR #789"
LEARN MORE
Use 'gh <command> <subcommand> --help' for more information about a command.
Read the manual at https://cli.github.com/manual
FEEDBACK
Open an issue using 'gh issue create -R cli/cli'

45
skills/cli-ux-designer/assets/examples/interactive-prompt-example.txt Normal file
View File

@@ -0,0 +1,45 @@
Creating a new issue in cli/cli
? Title: Fix color rendering in Windows Terminal
? Body: <Received>
What's the issue?
When running `gh issue list` in Windows Terminal, the ANSI color codes
are not rendering correctly. Text appears with escape sequences visible
instead of colored output.
Steps to reproduce:
1. Open Windows Terminal
2. Run `gh issue list`
3. Observe raw ANSI codes in output
Expected: Colored, formatted output
Actual: Raw escape sequences visible
? What labels should be added? (Press <space> to select, <enter> to submit)
◯ bug
◉ enhancement
◯ documentation
◯ help wanted
◉ windows
◯ good first issue
? What's the next action?
→ Create issue
Create issue and open in browser
Save as draft
Cancel
✓ Created issue #4524: Fix color rendering in Windows Terminal
https://github.com/cli/cli/issues/4524
───────────────────────────────────────────────────────────────────
Note: This example demonstrates:
- Clear question prompts with context
- Multi-line text input (indicated by <Received>)
- Multi-select checkboxes (◯ unchecked, ◉ checked)
- Radio selection menu (→ indicates current selection)
- Success confirmation with symbol and link
- Visual separator for command completion

25
skills/cli-ux-designer/assets/examples/list-view-example.txt Normal file
View File

@@ -0,0 +1,25 @@
Showing 15 of 127 issues in cli/cli
#4523 Fix help text formatting for nested commands (enhancement) 20h
#4521 Add support for GitHub Enterprise Server 3.8 (feature) 1d
#4518 Bug: color output in piped commands (bug) 2d
#4510 Documentation improvements for auth commands (documentation) 4d
#4507 Performance: speed up repository clone operations (enhancement) 5d
#4498 Add interactive mode for issue creation (feature) 1w
#4492 Fix crash when using --web flag without browser (bug) 1w
#4485 Improve error messages for network failures (enhancement) 2w
#4478 Support custom templates for pull requests (feature) 2w
#4471 Update dependencies to latest versions (maintenance) 2w
#4465 Add bash completion for subcommands (enhancement) 3w
#4459 Fix regression in release list command (bug) 3w
#4451 Support for organization-level configurations (feature) 1mo
#4447 Improve accessibility of table output (accessibility) 1mo
#4440 Add support for draft pull requests in list view (enhancement) 1mo
Legend:
• Green = open
• Red = closed
• Yellow = draft
• Gray = secondary information
Note: Times shown are relative to current date

222
skills/cli-ux-designer/references/ansi-color-reference.md Normal file
View File

@@ -0,0 +1,222 @@
# ANSI Color Reference for CLI Design
This reference provides comprehensive ANSI color codes for terminal styling in CLI applications.
## Basic 16 Colors (3/4-bit)
### Standard Colors
| Color | Foreground | Background | Use Cases |
|---------|-----------|-----------|----------------------------------------|
| Black | `\033[30m` | `\033[40m` | Default text, dividers |
| Red | `\033[31m` | `\033[41m` | Errors, failures, closed states |
| Green | `\033[32m` | `\033[42m` | Success, open states, confirmations |
| Yellow | `\033[33m` | `\033[43m` | Warnings, draft states, caution |
| Blue | `\033[34m` | `\033[44m` | Information, links, metadata |
| Magenta | `\033[35m` | `\033[45m` | Special highlights, tags |
| Cyan | `\033[36m` | `\033[46m` | Branch names, identifiers, emphasis |
| White | `\033[37m` | `\033[47m` | Primary text, headings |
### Bright/Bold Variants
| Color | Foreground | Background | Use Cases |
|--------------|-----------|-----------|----------------------------------|
| Bright Black (Gray) | `\033[90m` | `\033[100m` | Secondary text, labels, timestamps |
| Bright Red | `\033[91m` | `\033[101m` | Critical errors, destructive actions |
| Bright Green | `\033[92m` | `\033[102m` | Strong success indicators |
| Bright Yellow | `\033[93m` | `\033[103m` | Important warnings |
| Bright Blue | `\033[94m` | `\033[104m` | Highlighted information |
| Bright Magenta | `\033[95m` | `\033[105m` | Special status indicators |
| Bright Cyan | `\033[96m` | `\033[106m` | Emphasized identifiers |
| Bright White | `\033[97m` | `\033[107m` | Maximum emphasis, alerts |
## Text Styling
| Style | Code | Reset | Use Cases |
|----------------|-----------|-----------|------------------------------|
| Bold | `\033[1m` | `\033[22m` | Headers, emphasis |
| Dim | `\033[2m` | `\033[22m` | Secondary info, deprecation |
| Italic | `\033[3m` | `\033[23m` | Not recommended (poor support) |
| Underline | `\033[4m` | `\033[24m` | Links, emphasis |
| Blink | `\033[5m` | `\033[25m` | Avoid (accessibility issue) |
| Reverse | `\033[7m` | `\033[27m` | Selection, current item |
| Strikethrough | `\033[9m` | `\033[29m` | Deprecated, removed items |
## Reset Codes
| Reset Type | Code | Description |
|---------------|-----------|-------------------------------------|
| All attributes | `\033[0m` | Clear all styling and colors |
| Foreground | `\033[39m` | Reset to default text color |
| Background | `\033[49m` | Reset to default background |
## 256 Color Palette (8-bit)
### Syntax
- **Foreground**: `\033[38;5;<n>m` where `<n>` is 0-255
- **Background**: `\033[48;5;<n>m` where `<n>` is 0-255
### Color Ranges
**0-15**: Standard and bright colors (same as 16-color palette above)
**16-231**: 6×6×6 RGB color cube
- Formula: `16 + 36×r + 6×g + b` where r,g,b are 0-5
- Example: `\033[38;5;196m` = bright red (r=5, g=0, b=0)
**232-255**: Grayscale ramp (24 shades from dark to light)
- Example: `\033[38;5;240m` = dark gray
- Example: `\033[38;5;250m` = light gray
### Common 256 Colors
| Color Description | Code (FG) | Hex Approximation |
|------------------|----------------|-------------------|
| Dark Red | `\033[38;5;88m` | `#870000` |
| Orange | `\033[38;5;208m`| `#ff8700` |
| Dark Green | `\033[38;5;28m` | `#008700` |
| Teal | `\033[38;5;30m` | `#008787` |
| Navy Blue | `\033[38;5;18m` | `#000087` |
| Purple | `\033[38;5;93m` | `#8700ff` |
| Dark Gray | `\033[38;5;240m`| `#585858` |
| Light Gray | `\033[38;5;250m`| `#bcbcbc` |
## RGB True Color (24-bit)
### Syntax
- **Foreground**: `\033[38;2;<r>;<g>;<b>m` where r,g,b are 0-255
- **Background**: `\033[48;2;<r>;<g>;<b>m` where r,g,b are 0-255
### Examples
```bash
# Brand-specific red (RGB: 255, 59, 48)
\033[38;2;255;59;48m
# Brand-specific blue (RGB: 0, 122, 255)
\033[38;2;0;122;255m
# Custom gray (RGB: 142, 142, 147)
\033[38;2;142;142;147m
```
## Combining Codes
Multiple styles can be combined using semicolons:
```bash
# Bold red text
\033[1;31m
# Underlined bright green
\033[4;92m
# Bold, underlined cyan on dark gray background
\033[1;4;36;100m
# 256-color bold blue
\033[1;38;5;27m
# RGB true color bold
\033[1;38;2;255;59;48m
```
## Compatibility Notes
### Terminal Support
| Feature | Support Level | Notes |
|---------------|--------------|--------------------------------------|
| 16 colors | Universal | Safe to use everywhere |
| Bold/Dim | Universal | Widely supported |
| Underline | Universal | Widely supported |
| Italic | Limited | Unreliable, avoid in production |
| Blink | Limited | Accessibility issue, avoid |
| 256 colors | Good | Most modern terminals, test first |
| RGB colors | Moderate | Many modern terminals, fallback needed |
### Detection Strategy
```bash
# Check COLORTERM environment variable
if [ "$COLORTERM" = "truecolor" ] || [ "$COLORTERM" = "24bit" ]; then
# RGB true color supported
elif [ "$TERM" = "xterm-256color" ]; then
# 256 colors supported
else
# Use basic 16 colors only
fi
```
## Best Practices
### 1. Stick to Basic Colors for Maximum Compatibility
Use the 16 basic colors for critical information. Reserve 256/RGB for branding or progressive enhancement.
### 2. Always Reset After Styling
```bash
echo "\033[32mSuccess!\033[0m" # Good
echo "\033[32mSuccess!" # Bad - affects subsequent output
```
### 3. Provide Monochrome Fallback
Ensure meaning isn't conveyed through color alone. Use symbols and text:
```bash
echo "✓ \033[32mSuccess\033[0m" # Good - symbol + color
echo "\033[32mSuccess\033[0m" # Risky - color only
```
### 4. Respect User Preferences
- Check `NO_COLOR` environment variable
- Detect if output is piped/redirected
- Support `--no-color` flag
### 5. Test in Multiple Terminals
- macOS Terminal
- iTerm2
- Windows Terminal
- VS Code integrated terminal
- Linux terminals (GNOME Terminal, Konsole, etc.)
## Quick Reference: Semantic Color Usage
| Meaning | Recommended Color | Code |
|--------------|------------------|------------|
| Success | Green | `\033[32m` |
| Error | Red | `\033[31m` |
| Warning | Yellow | `\033[33m` |
| Info | Blue | `\033[34m` |
| Highlight | Cyan | `\033[36m` |
| Subtle | Bright Black (Gray) | `\033[90m` |
| Emphasis | Bold | `\033[1m` |
| Link | Blue Underline | `\033[4;34m` |
## Language-Specific Libraries
### JavaScript/Node.js
- `chalk` - Terminal string styling
- `kleur` - Lightweight alternative to chalk
- `picocolors` - Minimal ANSI color library
### Python
- `colorama` - Cross-platform colored terminal text
- `termcolor` - ANSI color formatting
- `rich` - Advanced terminal formatting
### Go
- `fatih/color` - Color package for Go
- `charmbracelet/lipgloss` - Style definitions for TUI
### Rust
- `colored` - Coloring terminal
- `ansi_term` - ANSI terminal colors and styles
### Ruby
- `colorize` - String coloring
- `tty-color` - Terminal color capabilities detection
## Additional Resources
- ANSI Escape Codes Standard: ECMA-48
- Terminal emulator test suite: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
- Color testing tool: https://github.com/termstandard/colors

335
skills/cli-ux-designer/references/unicode-symbols.md Normal file
View File

@@ -0,0 +1,335 @@
# Unicode Symbols Reference for CLI Design
This reference provides CLI-safe Unicode symbols with platform compatibility notes and usage recommendations.
## Status Indicators
### Success/Completion
| Symbol | Unicode | Description | macOS | Linux | Windows | Notes |
|--------|---------|-------------|-------|-------|---------|-------|
| ✓ | U+2713 | Check Mark | ✓ | ✓ | ✓ | Universal, highly recommended |
| ✔ | U+2714 | Heavy Check | ✓ | ✓ | ✓ | Bolder variant |
| ✅ | U+2705 | Check Button| ✓ | ✓ | Windows 10+ | Emoji, may render large |
| ◉ | U+25C9 | Fisheye | ✓ | ✓ | ✓ | Alternative indicator |
| ● | U+25CF | Black Circle| ✓ | ✓ | ✓ | Simple, safe |
### Failure/Error
| Symbol | Unicode | Description | macOS | Linux | Windows | Notes |
|--------|---------|-------------|-------|-------|---------|-------|
| ✗ | U+2717 | Ballot X | ✓ | ✓ | ✓ | Universal, highly recommended |
| ✘ | U+2718 | Heavy Ballot X | ✓ | ✓ | ✓ | Bolder variant |
| ❌ | U+274C | Cross Mark | ✓ | ✓ | Windows 10+ | Emoji, may render large |
| ⨯ | U+2A2F | Vector Cross| ✓ | ✓ | Limited | Mathematical, less support |
| × | U+00D7 | Multiplication | ✓ | ✓ | ✓ | Very safe fallback |
### Warning/Alert
| Symbol | Unicode | Description | macOS | Linux | Windows | Notes |
|--------|---------|-------------|-------|-------|---------|-------|
| ! | U+0021 | Exclamation | ✓ | ✓ | ✓ | ASCII, universal |
| ⚠ | U+26A0 | Warning Sign| ✓ | ✓ | ✓ | Good support |
| ⚠️ | U+26A0 U+FE0F | Warning (Emoji) | ✓ | ✓ | Windows 10+ | May render colorful |
| ⚡ | U+26A1 | High Voltage| ✓ | ✓ | ✓ | Alternative attention |
| ⓘ | U+24D8 | Info Circle | ✓ | ✓ | Limited | Less common |
### Neutral/In Progress
| Symbol | Unicode | Description | macOS | Linux | Windows | Notes |
|--------|---------|-------------|-------|-------|---------|-------|
| - | U+002D | Hyphen | ✓ | ✓ | ✓ | ASCII, universal |
| • | U+2022 | Bullet | ✓ | ✓ | ✓ | Good for lists |
| ○ | U+25CB | White Circle| ✓ | ✓ | ✓ | Hollow indicator |
| ◦ | U+25E6 | Small Circle| ✓ | ✓ | ✓ | Smaller variant |
| ⋯ | U+22EF | Midline Ellipsis | ✓ | ✓ | ✓ | Indicates processing |
## Directional Arrows
### Basic Arrows
| Symbol | Unicode | Description | macOS | Linux | Windows | Notes |
|--------|---------|-------------|-------|-------|---------|-------|
| → | U+2192 | Rightwards | ✓ | ✓ | ✓ | Universal, highly recommended |
| ← | U+2190 | Leftwards | ✓ | ✓ | ✓ | Universal |
| ↑ | U+2191 | Upwards | ✓ | ✓ | ✓ | Universal |
| ↓ | U+2193 | Downwards | ✓ | ✓ | ✓ | Universal |
| ↔ | U+2194 | Left-Right | ✓ | ✓ | ✓ | Bidirectional |
| ⇄ | U+21C4 | Right-Left | ✓ | ✓ | ✓ | Over arrows |
### Special Arrows
| Symbol | Unicode | Description | macOS | Linux | Windows | Notes |
|--------|---------|-------------|-------|-------|---------|-------|
| ➜ | U+279C | Heavy Arrow | ✓ | ✓ | Limited | Prompt indicator |
| ⟹ | U+27F9 | Long Right | ✓ | ✓ | Limited | Implications |
| ↩ | U+21A9 | Left Hook | ✓ | ✓ | ✓ | Return, undo |
| ↪ | U+21AA | Right Hook | ✓ | ✓ | ✓ | Forward, redo |
| ⤴ | U+2934 | Up-Right | ✓ | ✓ | Limited | External link |
| ⤵ | U+2935 | Down-Right | ✓ | ✓ | Limited | Nested content |
## Tree/Hierarchy Symbols
### Box Drawing Characters
| Symbol | Unicode | Description | macOS | Linux | Windows | Notes |
|--------|---------|-------------|-------|-------|---------|-------|
| │ | U+2502 | Vertical | ✓ | ✓ | ✓ | Tree lines |
| ─ | U+2500 | Horizontal | ✓ | ✓ | ✓ | Tree branches |
| ├ | U+251C | Middle Node | ✓ | ✓ | ✓ | Tree connector |
| └ | U+2514 | Last Node | ✓ | ✓ | ✓ | Tree terminal |
| ┌ | U+250C | Top-Left | ✓ | ✓ | ✓ | Box corners |
| ┐ | U+2510 | Top-Right | ✓ | ✓ | ✓ | Box corners |
| ┘ | U+2518 | Bottom-Right| ✓ | ✓ | ✓ | Box corners |
| ┤ | U+2524 | Right T | ✓ | ✓ | ✓ | Box connectors |
| ┬ | U+252C | Top T | ✓ | ✓ | ✓ | Box connectors |
### Tree Connectors (Heavy)
| Symbol | Unicode | Description | macOS | Linux | Windows | Notes |
|--------|---------|-------------|-------|-------|---------|-------|
| ┃ | U+2503 | Heavy Vertical | ✓ | ✓ | ✓ | Emphasis |
| ━ | U+2501 | Heavy Horizontal | ✓ | ✓ | ✓ | Emphasis |
| ┣ | U+2523 | Heavy Middle | ✓ | ✓ | ✓ | Emphasis |
| ┗ | U+2517 | Heavy Last | ✓ | ✓ | ✓ | Emphasis |
## List Markers
### Bullets
| Symbol | Unicode | Description | macOS | Linux | Windows | Notes |
|--------|---------|-------------|-------|-------|---------|-------|
| • | U+2022 | Bullet | ✓ | ✓ | ✓ | Standard list |
| ◦ | U+25E6 | White Bullet| ✓ | ✓ | ✓ | Nested lists |
| ▪ | U+25AA | Black Square| ✓ | ✓ | ✓ | Alternative |
| ▸ | U+25B8 | Right Tri | ✓ | ✓ | ✓ | Collapsible |
| ▾ | U+25BE | Down Tri | ✓ | ✓ | ✓ | Expanded |
| ‣ | U+2023 | Triangular | ✓ | ✓ | ✓ | Alternative |
### Numbered Alternatives
| Symbol | Unicode | Description | macOS | Linux | Windows | Notes |
|--------|---------|-------------|-------|-------|---------|-------|
| ①②③ | U+2460+ | Circled Digits | ✓ | ✓ | ✓ | 1-20 available |
| ⑴⑵⑶ | U+2474+ | Parenthesized | ✓ | ✓ | ✓ | 1-20 available |
| ➀➁➂ | U+2780+ | Sans-Serif | ✓ | ✓ | Limited | Less support |
## Shapes & Indicators
### Geometric Shapes
| Symbol | Unicode | Description | macOS | Linux | Windows | Notes |
|--------|---------|-------------|-------|-------|---------|-------|
| ■ | U+25A0 | Black Square| ✓ | ✓ | ✓ | Filled indicator |
| □ | U+25A1 | White Square| ✓ | ✓ | ✓ | Hollow indicator |
| ▪ | U+25AA | Small Square| ✓ | ✓ | ✓ | Compact |
| ▫ | U+25AB | Small White | ✓ | ✓ | ✓ | Compact hollow |
| ▲ | U+25B2 | Black Triangle | ✓ | ✓ | ✓ | Up indicator |
| △ | U+25B3 | White Triangle | ✓ | ✓ | ✓ | Up hollow |
| ▼ | U+25BC | Down Triangle | ✓ | ✓ | ✓ | Down indicator |
| ▽ | U+25BD | Down White | ✓ | ✓ | ✓ | Down hollow |
### Progress Indicators
| Symbol | Unicode | Description | macOS | Linux | Windows | Notes |
|--------|---------|-------------|-------|-------|---------|-------|
| ░ | U+2591 | Light Shade | ✓ | ✓ | ✓ | Progress bar empty |
| ▒ | U+2592 | Medium Shade| ✓ | ✓ | ✓ | Progress bar partial |
| ▓ | U+2593 | Dark Shade | ✓ | ✓ | ✓ | Progress bar almost |
| █ | U+2588 | Full Block | ✓ | ✓ | ✓ | Progress bar filled |
| ▌ | U+258C | Left Half | ✓ | ✓ | ✓ | Partial progress |
| ▐ | U+2590 | Right Half | ✓ | ✓ | ✓ | Partial progress |
## Spinners & Animations
### Rotating Indicators
| Sequence | Unicode | Description | Notes |
|----------|---------|-------------|-------|
| ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ | U+280B+ | Braille Dots | Smooth spinner |
| ◐◓◑◒ | U+25D0-U+25D2 | Circles | Simple rotation |
| ◴◷◶◵ | U+25F4-U+25F7 | Quadrants | Rotating |
| ⣾⣽⣻⢿⡿⣟⣯⣷ | U+28BE+ | Braille Heavy | Heavy spinner |
| ▁▂▃▄▅▆▇█▇▆▅▄▃▂ | U+2581+ | Bars | Growing/shrinking |
### Discrete States
| Symbol | Unicode | Description | macOS | Linux | Windows | Notes |
|--------|---------|-------------|-------|-------|---------|-------|
| ◜◝◞◟ | U+25DC+ | Quarter Circles | ✓ | ✓ | Limited | 4-state indicator |
| ▖▘▝▗ | U+2596+ | Quarter Blocks | ✓ | ✓ | ✓ | 4-state |
## Special Purpose
### Git/Version Control
| Symbol | Unicode | Description | macOS | Linux | Windows | Notes |
|--------|---------|-------------|-------|-------|---------|-------|
| + | U+002B | Addition | ✓ | ✓ | ✓ | ASCII, additions |
| - | U+002D | Deletion | ✓ | ✓ | ✓ | ASCII, deletions |
| ± | U+00B1 | Plus-Minus | ✓ | ✓ | ✓ | Changes |
| ≠ | U+2260 | Not Equal | ✓ | ✓ | ✓ | Conflicts |
| ∼ | U+223C | Tilde | ✓ | ✓ | ✓ | Modified |
| ⎇ | U+2387 | Alternative | ✓ | ✓ | Limited | Branch symbol |
### File Operations
| Symbol | Unicode | Description | macOS | Linux | Windows | Notes |
|--------|---------|-------------|-------|-------|---------|-------|
| 📁 | U+1F4C1 | Folder | ✓ | ✓ | Windows 10+ | Emoji |
| 📄 | U+1F4C4 | Document | ✓ | ✓ | Windows 10+ | Emoji |
| 🔗 | U+1F517 | Link | ✓ | ✓ | Windows 10+ | Emoji |
| 🗑 | U+1F5D1 | Trash | ✓ | ✓ | Windows 10+ | Emoji |
| ∅ | U+2205 | Empty Set | ✓ | ✓ | ✓ | No files |
### Time & Duration
| Symbol | Unicode | Description | macOS | Linux | Windows | Notes |
|--------|---------|-------------|-------|-------|---------|-------|
| ⏱ | U+23F1 | Stopwatch | ✓ | ✓ | Limited | Timing |
| ⌛ | U+231B | Hourglass | ✓ | ✓ | ✓ | Waiting |
| ⏳ | U+23F3 | Flowing Sand| ✓ | ✓ | Limited | Processing |
| 🕐 | U+1F550 | Clock | ✓ | ✓ | Windows 10+ | Emoji |
## Platform Compatibility Guide
### Universal (Safe Everywhere)
These work reliably across all platforms:
- ASCII characters (`!`, `-`, `+`, `*`, `|`)
- Basic arrows (`→`, `←`, `↑`, `↓`)
- Check/X marks (`✓`, `✗`)
- Box drawing (`│`, `─`, `├`, `└`)
- Basic bullets (`•`, `○`)
- Basic shapes (`■`, `□`, `▲`, `▼`)
### Good Support (Modern Terminals)
Works on macOS, Linux, and Windows 10+:
- Warning symbols (`⚠`)
- Extended arrows (`➜`, `↩`, `↪`)
- Progress blocks (`░`, `▒`, `▓`, `█`)
- Braille spinners (`⠋`, `⠙`, `⠹`, etc.)
### Limited Support (Use with Caution)
May not render on older systems or all terminals:
- Emoji (`✅`, `❌`, `📁`, `📄`, `🕐`)
- Specialized math symbols (`⟹`, `⨯`)
- Advanced geometric shapes (`◴`, `◷`, `◜`, `◝`)
### Windows Considerations
- Windows 10+ has much better Unicode support than earlier versions
- Windows Terminal supports more symbols than legacy cmd.exe
- PowerShell 7+ has improved rendering
- Consider providing `-UseAscii` flag for older systems
## Usage Recommendations
### 1. Semantic Consistency
Use the same symbol for the same meaning throughout your CLI:
```
✓ Operation completed successfully
✗ Operation failed
⚠ Warning: destructive action
→ Navigate to next step
```
### 2. Provide ASCII Fallbacks
For critical information, offer ASCII alternatives:
```bash
if supports_unicode; then
echo "✓ Success"
else
echo "[OK] Success"
fi
```
### 3. Test Rendering
Always test symbols in:
- macOS Terminal
- iTerm2
- Windows Terminal
- PowerShell
- VS Code integrated terminal
- Linux GNOME Terminal
### 4. Avoid Emoji in Production CLIs
Emoji can:
- Render at different sizes
- Display in color (disrupting design)
- Fail on older systems
- Be inconsistent across fonts
Use simple Unicode symbols instead.
### 5. Consider Accessibility
- Screen readers handle ASCII better than Unicode
- Provide text alternatives
- Don't rely solely on symbols for meaning
## Quick Reference: Common Patterns
### Status Line
```
✓ Task completed
✗ Task failed
⚠ Task needs attention
- Task pending
```
### File Tree
```
project/
├── src/
│ ├── main.rs
│ └── lib.rs
├── tests/
│ └── test.rs
└── Cargo.toml
```
### Progress Bar
```
[████████░░] 80%
[▓▓▓▓▓▓▓▓▒▒] 8/10 complete
```
### List Navigation
```
→ Selected item
Other item
Another item
```
### Spinner States
```
⠋ Loading...
⠙ Loading...
⠹ Loading...
⠸ Loading...
```
## Testing Utilities
### Environment Detection
```bash
# Check Unicode support
locale | grep -i utf
# Check terminal capabilities
echo $TERM
# Test symbol rendering
echo "✓ ✗ ⚠ → ├ ▓"
```
### Manual Test String
Copy this string to test symbol support:
```
✓✗⚠!•→←↑↓│─├└■□▲▼░▒▓█⠋⠙⠹⠸
```
## Additional Resources
- Unicode Character Database: https://unicode.org/charts/
- Terminal compatibility: https://github.com/sindresorhus/figures
- Box drawing: https://en.wikipedia.org/wiki/Box-drawing_character
- Braille patterns: https://en.wikipedia.org/wiki/Braille_Patterns