Initial commit

2025-11-30 08:57:38 +08:00
commit 2c1ab284b7
10 changed files with 961 additions and 0 deletions
--- a/skills/cli-ux-designer/SKILL.md
+++ 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 | `<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
--- a/skills/cli-ux-designer/assets/examples/help-text-example.txt
+++ b/skills/cli-ux-designer/assets/examples/help-text-example.txt
@@ -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'
--- a/skills/cli-ux-designer/assets/examples/interactive-prompt-example.txt
+++ 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: <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
--- a/skills/cli-ux-designer/assets/examples/list-view-example.txt
+++ 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
--- a/skills/cli-ux-designer/references/ansi-color-reference.md
+++ 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;<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
--- a/skills/cli-ux-designer/references/unicode-symbols.md
+++ 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