Skip to content

Color Scheme Reference

Jump to bottom
RAprogramm edited this page Oct 20, 2025 · 1 revision

Color Scheme Reference

Complete color mapping for all error components

This reference documents the professional color scheme used for terminal error output, ensuring consistent visual hierarchy and immediate recognition of error severity.

Table of Contents

Color Philosophy

The color scheme follows these principles:

  1. Severity-based hierarchy - Critical issues demand attention (red), warnings are noticeable but less urgent (yellow)
  2. Semantic consistency - Same color always means the same thing
  3. Terminal compatibility - Uses standard ANSI colors supported everywhere
  4. Accessibility - High contrast ratios, doesn't rely solely on color
  5. Professional appearance - Clean, modern CLI aesthetic

Error Severity Colors

Critical Errors (5xx)

Color: Red

Rationale: Server-side failures requiring immediate developer attention.

HTTP Status Codes: 500-599

Visual appearance: High urgency, impossible to miss in terminal output.

Examples:

  • Internal server error (500)
  • Database error (500)
  • Service error (500)
  • Timeout (504)
  • Network error (503)

Client Errors (4xx)

Color: Yellow

Rationale: User-facing issues, often recoverable or actionable by the client.

HTTP Status Codes: 400-499

Visual appearance: Noticeable but less alarming than critical errors.

Examples:

  • Not found (404)
  • Bad request (400)
  • Validation error (422)
  • Unauthorized (401)
  • Forbidden (403)

Component Colors

Error Code

Color: Cyan

Purpose: Easy to scan and reference in documentation.

Component: The error code string (e.g., "INTERNAL", "DATABASE", "NOT_FOUND").

Visual characteristics:

  • Distinct from error messages
  • High contrast on dark backgrounds
  • Professional, technical appearance

Example output:

Code: DATABASE    ← Cyan

Error Message

Color: Bright White

Purpose: Maximum visibility for primary information.

Component: The human-readable error message provided when creating the error.

Visual characteristics:

  • Highest brightness/contrast
  • Primary focus point
  • Clear, readable text

Example output:

Message: Database connection failed    ← Bright white

Source Context Chain

Color: Dimmed (Gray)

Purpose: Important context without visual dominance.

Component: The error chain showing nested causes via with_context().

Visual characteristics:

  • Lower contrast than main error
  • Readable but secondary
  • Shows hierarchical structure

Example output:

  Caused by: Connection timeout    ← Dimmed
  Caused by: Network unreachable   ← Dimmed

Metadata Keys

Color: Green

Purpose: Distinguish structured field names from values.

Component: Keys in the metadata key-value pairs added via with_field().

Visual characteristics:

  • Contrasts with white values
  • Professional structured data appearance
  • Easy to scan for specific fields

Example output:

Context:
  query: SELECT * FROM users        ← Green key, white value
  duration_ms: 5432                 ← Green key, white value
  connection_id: conn_abc123        ← Green key, white value

Error Kind Color Mapping

Complete mapping of all AppErrorKind variants to colors:

Red (Critical 5xx)

Error Kind HTTP Status Label Use Case
Internal 500 Internal server error Unexpected server-side failure
Database 500 Database error Query, connection, migration failures
Service 500 Service error Business logic or orchestration failure
Config 500 Configuration error Missing/invalid environment config
Turnkey 500 Turnkey error Turnkey subsystem integration failure
Timeout 504 Operation timed out Request exceeded time limit
Network 503 Network error DNS, connect, TLS failures
DependencyUnavailable 503 External dependency unavailable Cache down, broker unreachable
Serialization 500 Serialization error Failed to encode data
Deserialization 500 Deserialization error Failed to decode data
ExternalApi 500 External API error Upstream API failure
Queue 500 Queue processing error Publish/consume/ack failure
Cache 500 Cache error Cache read/write failure
NotImplemented 501 Not implemented Feature not supported

Yellow (Client 4xx)

Error Kind HTTP Status Label Use Case
NotFound 404 Not found Resource does not exist
Validation 422 Validation error Input failed validation
Conflict 409 Conflict State conflict or concurrent update
Unauthorized 401 Unauthorized Authentication required or failed
Forbidden 403 Forbidden Authenticated but not allowed
BadRequest 400 Bad request Malformed request
TelegramAuth 401 Telegram authentication error Telegram auth flow failed
InvalidJwt 401 Invalid JWT JWT expired, malformed, or invalid
RateLimited 429 Rate limit exceeded Client exceeded rate limits

Visual Examples

Example 1: Critical Server Error

let err = AppError::database_with_message("Connection pool exhausted")
    .with_field(field::str("pool_size", "20"))
    .with_field(field::u64("active_connections", 20));

eprintln!("{}", err);

Terminal output (with colors):

Error: Database error                      ← Red
Code: DATABASE                             ← Cyan
Message: Connection pool exhausted         ← Bright white

Context:
  pool_size: 20                            ← Green key, white value
  active_connections: 20                   ← Green key, white value

Example 2: Client Error with Context

let io_err = IoError::other("File not found");
let err = AppError::not_found("User configuration missing")
    .with_context(io_err)
    .with_field(field::str("path", "/etc/app/user.toml"));

eprintln!("{}", err);

Terminal output (with colors):

Error: Not found                           ← Yellow
Code: NOT_FOUND                            ← Cyan
Message: User configuration missing        ← Bright white

  Caused by: File not found                ← Dimmed

Context:
  path: /etc/app/user.toml                 ← Green key, white value

Example 3: Deep Error Chain

let root = IoError::other("Connection reset by peer");
let mid_err = AppError::network("Failed to fetch data")
    .with_context(root);
let top_err = AppError::timeout("API request timeout")
    .with_context(mid_err)
    .with_field(field::u64("timeout_ms", 30000));

eprintln!("{}", top_err);

Terminal output (with colors):

Error: Operation timed out                 ← Red (504 is 5xx)
Code: TIMEOUT                              ← Cyan
Message: API request timeout               ← Bright white

  Caused by: Network error                 ← Dimmed (shows nested error kind)
  Caused by: Failed to fetch data          ← Dimmed
  Caused by: Connection reset by peer      ← Dimmed

Context:
  timeout_ms: 30000                        ← Green key, white value

Example 4: Multiple Client Errors

let errors = vec![
    AppError::validation("Email format invalid"),
    AppError::unauthorized("Missing authentication token"),
    AppError::forbidden("Insufficient permissions"),
    AppError::rate_limited("Too many requests"),
];

for err in errors {
    eprintln!("{}\n", err);
}

Terminal output (with colors):

Error: Validation error                    ← Yellow
Code: VALIDATION                           ← Cyan
Message: Email format invalid              ← Bright white

Error: Unauthorized                        ← Yellow
Code: UNAUTHORIZED                         ← Cyan
Message: Missing authentication token      ← Bright white

Error: Forbidden                           ← Yellow
Code: FORBIDDEN                            ← Cyan
Message: Insufficient permissions          ← Bright white

Error: Rate limit exceeded                 ← Yellow
Code: RATE_LIMITED                         ← Cyan
Message: Too many requests                 ← Bright white

Accessibility Considerations

Color Blindness

Protanopia/Deuteranopia (Red-Green):

  • Red and green are never used adjacently
  • Red (critical) vs Yellow (client) still distinguishable by brightness
  • Cyan and green metadata keys have distinct purposes

Tritanopia (Blue-Yellow):

  • Cyan codes remain distinct from yellow client errors
  • Bright white messages provide non-color differentiation

High Contrast

All colors maintain high contrast ratios:

  • Bright white: Maximum contrast
  • Red/Yellow: High luminance for visibility
  • Cyan: Distinct hue with good contrast
  • Dimmed: Still readable but clearly secondary

Text-Only Fallback

Colors enhance but don't replace textual information:

  • Error kind labels: "Internal server error", "Not found"
  • Error codes: "INTERNAL", "NOT_FOUND"
  • Structured prefixes: "Error:", "Code:", "Message:", "Context:", "Caused by:"

When colors are disabled, the output remains fully functional:

Error: Database error
Code: DATABASE
Message: Connection pool exhausted

Context:
  pool_size: 20
  active_connections: 20

Terminal Emulator Compatibility

Colors are chosen from the standard ANSI palette (16 basic colors):

  • Red: ANSI 31 (standard red)
  • Yellow: ANSI 33 (standard yellow)
  • Cyan: ANSI 36 (standard cyan)
  • Bright White: ANSI 97 (bright white, 256-color mode)
  • Dimmed: ANSI 2 (dim attribute)
  • Green: ANSI 32 (standard green)

All modern terminal emulators support these colors, including:

  • iTerm2, Terminal.app (macOS)
  • GNOME Terminal, Konsole, Alacritty (Linux)
  • Windows Terminal, ConEmu (Windows 10+)
  • SSH terminals (xterm-256color)

Testing Your Terminal

Run the example to see all colors:

cargo run --example colored_cli --features colored

If colors don't appear, check:

  1. TERM environment variable: echo $TERM
  2. NO_COLOR variable: echo $NO_COLOR
  3. Terminal emulator color support

See Troubleshooting Guide for detailed diagnostics.

Related Pages:

Previous: Terminal Detection Guide | Next: Integration Guide →

Clone this wiki locally