WDP Part 10: Visual Presentation Guidelines

Abstract#

This document provides INFORMATIVE (non-normative) guidance on visual presentation for the Waddling Diagnostic Protocol (WDP). It recommends emoji mappings, terminal colors, web colors (light and dark mode), and accessibility considerations for displaying WDP diagnostics in user interfaces.

Specification Navigation: See STRUCTURE.md for an overview of all WDP specification parts.

Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Introduction#

1.1 Purpose

This document provides recommended visual presentation guidelines for WDP diagnostic severities. These recommendations help create consistent, accessible user experiences across different platforms and interfaces.

1.2 Scope

This specification covers visual presentation for:

• Terminal/CLI applications (emoji + ANSI colors)
• Web interfaces (hex colors + backgrounds)
• IDEs and text editors
• Log viewers and monitoring dashboards
• Documentation and reports

1.3 Design Goals

1. Consistency - Same severity should look similar across platforms
2. Accessibility - Colors should work for colorblind users
3. Clarity - Visual distinction between severity levels
4. Cultural Sensitivity - Emoji work across cultures
5. Backwards Compatibility - Degrade gracefully without color support

2. Emoji Mapping#

2.1 Recommended Emoji

2.2 Rationale

Error (❌) vs Blocked (🚫):

• ❌ indicates something went wrong (failure state)
• 🚫 indicates something is preventing progress (blocked state)

Success (✅) vs Completed (✔️):

• ✅ for primary success outcomes (bold, prominent)
• ✔️ for completion markers (subtler)

Critical (🔥):

• Fire emoji conveys urgency and severity
• Stands out visually without implying blocking

Help (💡):

• Light bulb is universally understood as "helpful suggestion"
• Positive, constructive tone

2.3 Alternative Emoji

If the recommended emoji are not available or don't render well, implementations MAY use:

2.4 Terminal Considerations

Emoji Rendering:

• Modern terminals (Windows Terminal, iTerm2, Kitty) render emoji well
• Older terminals may show emoji as boxes or double-width characters
• Implementations SHOULD provide a --no-emoji or --plain flag

Width Handling:

• Most emoji are double-width characters
• Use padding/spacing to align text properly
• Consider using ASCII alternatives for strict column alignment

3. Terminal Colors (ANSI)#

3.1 ANSI Color Codes

Reset: \x1b[0m (always reset after colored text)

3.2 Color Scheme Rationale

Red Family (Error, Blocked):

• Error: Bold red for maximum attention
• Blocked: Regular red (slightly less urgent than error)

Yellow Family (Critical, Warning):

• Critical: Bold yellow/orange (severe but not blocking)
• Warning: Regular yellow (caution)

Green Family (Success, Completed, Help):

• Success: Bold green (positive outcome emphasis)
• Completed: Regular green (quiet completion)
• Help: Regular green (helpful, constructive)

Blue/Cyan (Info, Trace):

• Info: Cyan (neutral, informational)
• Trace: Dim blue (low-priority, debugging)

3.3 Colorblind Considerations

This color scheme has been tested for:

• Protanopia (red-blind) - Bold/dim styles help distinguish
• Deuteranopia (green-blind) - Yellow/cyan/blue remain distinct
• Tritanopia (blue-blind) - Red/yellow/green remain distinct

Additional Recommendations:

• Always include emoji or text labels, not just color
• Use bold/dim styles to add contrast
• Provide --no-color flag for terminals without color support

3.4 Example ANSI Usage

# Error (bold red)
echo -e "\x1b[1;31m❌ Error:\x1b[0m Operation failed"

# Warning (yellow)
echo -e "\x1b[33m⚠️  Warning:\x1b[0m Quota at 85%"

# Success (bold green)
echo -e "\x1b[1;32m✅ Success:\x1b[0m Build complete"

# Info (cyan)
echo -e "\x1b[36mℹ️  Info:\x1b[0m Server started on port 8080"

4. Web Colors (Hex)#

4.1 Foreground Colors (Light Mode)

These hex colors are designed for text and icons in web interfaces:

4.2 Color Palette Rationale

This palette is inspired by the Flat UI color scheme, chosen for:

• Modern, clean appearance
• Good contrast on white backgrounds
• Works well in both light and dark themes
• Professional and accessible

Color Temperature:

• Warm colors (red, orange, yellow) for problems/attention
• Cool colors (green, teal, cyan, blue) for positive/neutral states
• Gray for low-priority trace information

4.3 CSS Examples (Light Mode)

/* Severity text colors - Light Mode */
.severity-error { color: #c0392b; }
.severity-blocked { color: #e74c3c; }
.severity-critical { color: #e67e22; }
.severity-warning { color: #f39c12; }
.severity-help { color: #27ae60; }
.severity-success { color: #2ecc71; }
.severity-completed { color: #16a085; }
.severity-info { color: #3498db; }
.severity-trace { color: #95a5a6; }

4.4 Dark Mode Foreground Colors

For dark backgrounds, use brighter/lighter variants for better contrast:

4.5 CSS Examples (Dark Mode)

/* Severity text colors - Dark Mode */
@media (prefers-color-scheme: dark) {
  .severity-error { color: #e74c3c; }
  .severity-blocked { color: #ff6b6b; }
  .severity-critical { color: #f39c12; }
  .severity-warning { color: #f1c40f; }
  .severity-help { color: #2ecc71; }
  .severity-success { color: #58d68d; }
  .severity-completed { color: #1abc9c; }
  .severity-info { color: #5dade2; }
  .severity-trace { color: #bdc3c7; }
}

4.6 CSS Custom Properties (Recommended)

Using CSS custom properties enables easy theme switching:

:root {
  /* Light mode (default) */
  --severity-error: #c0392b;
  --severity-blocked: #e74c3c;
  --severity-critical: #e67e22;
  --severity-warning: #f39c12;
  --severity-help: #27ae60;
  --severity-success: #2ecc71;
  --severity-completed: #16a085;
  --severity-info: #3498db;
  --severity-trace: #95a5a6;
}

@media (prefers-color-scheme: dark) {
  :root {
    --severity-error: #e74c3c;
    --severity-blocked: #ff6b6b;
    --severity-critical: #f39c12;
    --severity-warning: #f1c40f;
    --severity-help: #2ecc71;
    --severity-success: #58d68d;
    --severity-completed: #1abc9c;
    --severity-info: #5dade2;
    --severity-trace: #bdc3c7;
  }
}

/* Usage */
.severity-error { color: var(--severity-error); }
.severity-warning { color: var(--severity-warning); }
/* ... etc */

5. Background Colors#

5.1 Light Mode Background Palette

Light, subtle backgrounds for badges, chips, and callout boxes on light themes:

5.2 Dark Mode Background Palette

Dark, muted backgrounds for badges, chips, and callout boxes on dark themes:

5.3 Background Usage (Light Mode)

Badges/Chips:

/* Light Mode Badges/Chips */
.badge-error {
  color: #c0392b;
  background-color: #fee;
  border: 1px solid #f5c6cb;
}

.badge-success {
  color: #27ae60;
  background-color: #dcfce7;
  border: 1px solid #c3e6cb;
}

Callout Boxes:

/* Light Mode Callout Box */
.alert-warning {
  color: #856404;
  background-color: #fef3cd;
  border-left: 4px solid #f39c12;
  padding: 1rem;
}

5.4 Background Usage (Dark Mode)

Badges/Chips:

/* Dark Mode Badges/Chips */
@media (prefers-color-scheme: dark) {
  .badge-error {
    color: #e74c3c;
    background-color: #3d1f1f;
    border: 1px solid #5c2a2a;
  }

  .badge-success {
    color: #58d68d;
    background-color: #1a3d26;
    border: 1px solid #2a5c3a;
  }
}

Callout Boxes:

/* Dark Mode Callout Box */
@media (prefers-color-scheme: dark) {
  .alert-warning {
    color: #f1c40f;
    background-color: #3d3520;
    border-left: 4px solid #f39c12;
    padding: 1rem;
  }
}

5.5 Background CSS Custom Properties

:root {
  /* Light mode backgrounds (default) */
  --bg-error: #fee;
  --bg-blocked: #fdd;
  --bg-critical: #ffe5cc;
  --bg-warning: #fef3cd;
  --bg-help: #d4edda;
  --bg-success: #dcfce7;
  --bg-completed: #d1f2eb;
  --bg-info: #d1ecf1;
  --bg-trace: #e2e3e5;
}

@media (prefers-color-scheme: dark) {
  :root {
    /* Dark mode backgrounds */
    --bg-error: #3d1f1f;
    --bg-blocked: #4a2020;
    --bg-critical: #3d2e1a;
    --bg-warning: #3d3520;
    --bg-help: #1e3d2a;
    --bg-success: #1a3d26;
    --bg-completed: #1a3d36;
    --bg-info: #1a2d3d;
    --bg-trace: #2d2d2d;
  }
}

5.6 Contrast Requirements

Light Mode: All foreground/background combinations meet WCAG AA standards (4.5:1 minimum contrast ratio for normal text):

Dark Mode: All foreground/background combinations meet WCAG AA standards:

WCAG Guidelines:

• AA Normal Text: 4.5:1 minimum
• AA Large Text: 3:1 minimum (18pt+ or 14pt+ bold)
• AAA Normal Text: 7:1 minimum

Note: For small text (below 14px) or UI elements requiring AAA compliance, consider using bolder weights or adjusting foreground colors for higher contrast.

6. Implementation Examples#

6.1 Terminal (Rust)

pub enum Severity {
    Error, Warning, Critical, Blocked,
    Success, Completed, Help, Info, Trace,
}

impl Severity {
    pub const fn emoji(&self) -> &'static str {
        match self {
            Self::Error => "❌",
            Self::Blocked => "🚫",
            Self::Critical => "🔥",
            Self::Warning => "⚠️",
            Self::Help => "💡",
            Self::Success => "✅",
            Self::Completed => "✔️",
            Self::Info => "ℹ️",
            Self::Trace => "🔍",
        }
    }

    pub const fn ansi_color(&self) -> &'static str {
        match self {
            Self::Error => "\x1b[1;31m",
            Self::Blocked => "\x1b[31m",
            Self::Critical => "\x1b[1;33m",
            Self::Warning => "\x1b[33m",
            Self::Help => "\x1b[32m",
            Self::Success => "\x1b[1;32m",
            Self::Completed => "\x1b[32m",
            Self::Info => "\x1b[36m",
            Self::Trace => "\x1b[2;34m",
        }
    }

    pub const ANSI_RESET: &'static str = "\x1b[0m";
}

// Usage
println!("{} {}{}{} Operation failed",
    Severity::Error.emoji(),
    Severity::Error.ansi_color(),
    "Error:",
    Severity::ANSI_RESET
);

6.2 Web (TypeScript/React)

interface SeverityStyle {
  emoji: string;
  color: string;
  bgColor: string;
}

const SEVERITY_STYLES: Record<string, SeverityStyle> = {
  E: { emoji: '❌', color: '#c0392b', bgColor: '#fee' },
  W: { emoji: '⚠️', color: '#f39c12', bgColor: '#fef3cd' },
  C: { emoji: '🔥', color: '#e67e22', bgColor: '#ffe5cc' },
  B: { emoji: '🚫', color: '#e74c3c', bgColor: '#fdd' },
  S: { emoji: '✅', color: '#2ecc71', bgColor: '#dcfce7' },
  K: { emoji: '✔️', color: '#16a085', bgColor: '#d1f2eb' },
  H: { emoji: '💡', color: '#27ae60', bgColor: '#d4edda' },
  I: { emoji: 'ℹ️', color: '#3498db', bgColor: '#d1ecf1' },
  T: { emoji: '🔍', color: '#95a5a6', bgColor: '#e2e3e5' },
};

// React component
function DiagnosticBadge({ severity }: { severity: string }) {
  const style = SEVERITY_STYLES[severity];
  return (
    <span style={{
      color: style.color,
      backgroundColor: style.bgColor,
      padding: '0.25rem 0.5rem',
      borderRadius: '0.25rem',
      fontSize: '0.875rem',
      fontWeight: 500,
    }}>
      {style.emoji} {severity}
    </span>
  );
}

6.3 CLI (Python)

from enum import Enum

class Severity(Enum):
    ERROR = 'E'
    WARNING = 'W'
    CRITICAL = 'C'
    BLOCKED = 'B'
    SUCCESS = 'S'
    COMPLETED = 'K'
    HELP = 'H'
    INFO = 'I'
    TRACE = 'T'

    def emoji(self) -> str:
        return {
            'E': '❌', 'W': '⚠️', 'C': '🔥', 'B': '🚫',
            'S': '✅', 'K': '✔️', 'H': '💡', 'I': 'ℹ️', 'T': '🔍',
        }[self.value]

    def ansi_color(self) -> str:
        return {
            'E': '\x1b[1;31m', 'W': '\x1b[33m', 'C': '\x1b[1;33m',
            'B': '\x1b[31m', 'S': '\x1b[1;32m', 'K': '\x1b[32m',
            'H': '\x1b[32m', 'I': '\x1b[36m', 'T': '\x1b[2;34m',
        }[self.value]

    @staticmethod
    def reset() -> str:
        return '\x1b[0m'

    def format_message(self, message: str) -> str:
        return f"{self.emoji()} {self.ansi_color()}{self.name}:{self.reset()} {message}"

# Usage
print(Severity.ERROR.format_message("Operation failed"))
print(Severity.SUCCESS.format_message("Build complete"))

7. Accessibility Considerations#

7.1 Color Blindness

Recommendations:

1. Never rely solely on color - Always include emoji, text labels, or icons
2. Test with colorblind simulators - Use tools like Coblis or Chrome DevTools
3. Use multiple visual cues - Combine color + emoji + text + position
4. Provide alternatives - Offer --no-color and --no-emoji flags

Color Combinations to Avoid:

• Red/green only (protanopia/deuteranopia)
• Blue/yellow only (tritanopia)

7.2 Screen Readers

Best Practices:

<!-- Good: Semantic HTML with ARIA -->
<div role="alert" aria-live="polite">
  <span class="severity-icon" aria-label="Error">❌</span>
  <span class="severity-text">Error:</span>
  <span class="diagnostic-message">Operation failed</span>
</div>

<!-- Better: Use visually-hidden text -->
<div role="alert">
  <span class="sr-only">Error severity:</span>
  <span aria-hidden="true">❌</span>
  <strong>Error:</strong> Operation failed
</div>

7.3 High Contrast Mode

Windows High Contrast:

• Emoji may render as outlines
• ANSI colors are overridden by system theme
• Ensure text labels are always present

CSS for High Contrast:

@media (prefers-contrast: high) {
  .severity-error {
    border: 2px solid currentColor;
    font-weight: bold;
  }
}

8. Best Practices#

8.1 Consistency

DO:

• Use the same emoji/color for a severity across your entire application
• Document your chosen palette in your style guide
• Maintain consistent spacing and formatting

DON'T:

• Mix different emoji sets (e.g., ❌ and ✖️ for errors)
• Change colors based on context (error is always red)
• Use custom emoji without fallbacks

8.2 Progressive Enhancement

Fallback Strategy:

1. Full experience: Emoji + Color + Formatting
2. No emoji: ASCII + Color + Formatting
3. No color: ASCII + Text labels
4. Plain text: Severity code + Message

Example:

Level 1: ❌ Error: Operation failed
Level 2: [E] Error: Operation failed (in red)
Level 3: [E] Error: Operation failed
Level 4: E.AUTH.TOKEN.001: Operation failed

8.3 Terminal Detection

Detect capabilities:

// Check for color support
fn supports_color() -> bool {
    std::env::var("NO_COLOR").is_err()
        && (atty::is(atty::Stream::Stdout)
            || std::env::var("FORCE_COLOR").is_ok())
}

// Check for emoji support
fn supports_emoji() -> bool {
    std::env::var("NO_EMOJI").is_err()
        && !cfg!(target_os = "windows") // Or check Windows version
}

8.4 Configuration

Allow users to customize:

# .wdpconfig
[display]
emoji = true
color = "auto"  # auto, always, never
style = "default"  # default, minimal, verbose

[colors]
error = "#c0392b"
warning = "#f39c12"
success = "#2ecc71"

8.5 Testing

Test your presentation:

1. Light theme vs dark theme
2. Different terminal emulators
3. Colorblind simulators
4. Screen readers
5. High contrast mode
6. CI/CD environments (often no color/emoji)

Appendix A: Complete Reference Table#

Light Mode

Dark Mode

Note: ANSI codes are the same for both themes as terminal colors are typically managed by the terminal emulator's theme settings.

Appendix B: Color Swatches#

Light Mode

Error Family (Red)

█ #c0392b  Error foreground (dark red)
█ #e74c3c  Blocked foreground (red)
█ #fee     Error background
█ #fdd     Blocked background

Warning Family (Yellow/Orange)

█ #e67e22  Critical foreground (orange)
█ #f39c12  Warning foreground (yellow/orange)
█ #ffe5cc  Critical background
█ #fef3cd  Warning background

Success Family (Green)

█ #2ecc71  Success foreground (bright green)
█ #27ae60  Help foreground (green)
█ #16a085  Completed foreground (teal)
█ #dcfce7  Success background
█ #d4edda  Help background
█ #d1f2eb  Completed background

Neutral Family (Blue/Gray)

█ #3498db  Info foreground (blue)
█ #95a5a6  Trace foreground (gray)
█ #d1ecf1  Info background
█ #e2e3e5  Trace background

Dark Mode

Error Family (Red)

█ #e74c3c  Error foreground (bright red)
█ #ff6b6b  Blocked foreground (light red)
█ #3d1f1f  Error background (dark red)
█ #4a2020  Blocked background (dark maroon)

Warning Family (Yellow/Orange)

█ #f39c12  Critical foreground (bright orange)
█ #f1c40f  Warning foreground (bright yellow)
█ #3d2e1a  Critical background (dark brown)
█ #3d3520  Warning background (dark olive)

Success Family (Green)

█ #58d68d  Success foreground (light green)
█ #2ecc71  Help foreground (bright green)
█ #1abc9c  Completed foreground (bright teal)
█ #1a3d26  Success background (dark green)
█ #1e3d2a  Help background (dark green)
█ #1a3d36  Completed background (dark teal)

Neutral Family (Blue/Gray)

█ #5dade2  Info foreground (light blue)
█ #bdc3c7  Trace foreground (light gray)
█ #1a2d3d  Info background (dark blue)
█ #2d2d2d  Trace background (dark gray)

References#

• Flat UI Colors: https://flatuicolors.com/
• WCAG Contrast Guidelines: https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html
• ANSI Escape Codes: https://en.wikipedia.org/wiki/ANSI_escape_code
• Emoji Unicode Standard: https://unicode.org/emoji/charts/full-emoji-list.html
• Colorblind Testing: https://www.color-blindness.com/coblis-color-blindness-simulator/