gh-sjungling-claude-plugins-plugins-cli-developer/skills/cli-ux-designer/references/ansi-color-reference.md

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

# 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:

# 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

# 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

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:

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