commit 2c1ab284b7ff6cee66a842339917e0a7f9b731b3 Author: Zhongwei Li Date: Sun Nov 30 08:57:38 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..da5d8c5 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -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" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..5d04d0b --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# cli-developer + +Expert CLI/TUI design consultant for command structure, visual design, accessibility, and UX patterns diff --git a/agents/cli-ux-designer.md b/agents/cli-ux-designer.md new file mode 100644 index 0000000..4e059db --- /dev/null +++ b/agents/cli-ux-designer.md @@ -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: 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" Since this involves CLI design from scratch, use the cli-ux-designer agent to apply comprehensive design principles. 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" CLI usability issues require specialized design expertise. +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. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..be97257 --- /dev/null +++ b/plugin.lock.json @@ -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": [] + } +} \ No newline at end of file diff --git a/skills/cli-ux-designer/SKILL.md b/skills/cli-ux-designer/SKILL.md new file mode 100644 index 0000000..08ec7fd --- /dev/null +++ b/skills/cli-ux-designer/SKILL.md @@ -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 | `` | `` | [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 + +- `` 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 diff --git a/skills/cli-ux-designer/assets/examples/help-text-example.txt b/skills/cli-ux-designer/assets/examples/help-text-example.txt new file mode 100644 index 0000000..a74ad5e --- /dev/null +++ b/skills/cli-ux-designer/assets/examples/help-text-example.txt @@ -0,0 +1,41 @@ +gh issue - Manage issues + +USAGE + gh issue [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 --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' diff --git a/skills/cli-ux-designer/assets/examples/interactive-prompt-example.txt b/skills/cli-ux-designer/assets/examples/interactive-prompt-example.txt new file mode 100644 index 0000000..cc20fb8 --- /dev/null +++ b/skills/cli-ux-designer/assets/examples/interactive-prompt-example.txt @@ -0,0 +1,45 @@ +Creating a new issue in cli/cli + +? Title: Fix color rendering in Windows Terminal + +? Body: + 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 to select, 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 ) +- Multi-select checkboxes (◯ unchecked, ◉ checked) +- Radio selection menu (→ indicates current selection) +- Success confirmation with symbol and link +- Visual separator for command completion diff --git a/skills/cli-ux-designer/assets/examples/list-view-example.txt b/skills/cli-ux-designer/assets/examples/list-view-example.txt new file mode 100644 index 0000000..dde28e4 --- /dev/null +++ b/skills/cli-ux-designer/assets/examples/list-view-example.txt @@ -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 diff --git a/skills/cli-ux-designer/references/ansi-color-reference.md b/skills/cli-ux-designer/references/ansi-color-reference.md new file mode 100644 index 0000000..a67b29b --- /dev/null +++ b/skills/cli-ux-designer/references/ansi-color-reference.md @@ -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;m` where `` is 0-255 +- **Background**: `\033[48;5;m` where `` 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;;;m` where r,g,b are 0-255 +- **Background**: `\033[48;2;;;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 diff --git a/skills/cli-ux-designer/references/unicode-symbols.md b/skills/cli-ux-designer/references/unicode-symbols.md new file mode 100644 index 0000000..791951e --- /dev/null +++ b/skills/cli-ux-designer/references/unicode-symbols.md @@ -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