Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Display Issues

Solving color, rendering, and visual problems.

Color Problems

Colors Don’t Appear

Symptom: Everything is monochrome

Causes:

  1. Terminal doesn’t support colors
  2. TERM variable incorrect
  3. Color disabled in config

Solutions:

  1. Check terminal support:

    # Check TERM
echo $TERM
# Should be xterm-256color, screen-256color, etc.

# Check color count
tput colors
# Should be 256 or higher

  2. Set correct TERM:

    export TERM=xterm-256color

  3. Enable colors in config:

    [display]
colors = true
color_mode = "truecolor"  # or "256" or "16"

Wrong Colors

Symptom: Colors look different than expected

Causes:

  1. Terminal color scheme conflicts
  2. True color vs 256-color mismatch
  3. Theme file issues

Solutions:

  1. Match color modes:

    # For terminals with true color (24-bit)
[display]
color_mode = "truecolor"

# For older terminals
[display]
color_mode = "256"

  2. Check terminal palette:

    • Terminal color scheme affects named colors
    • Try built-in “Dark” or “Light” preset
    • Use hex colors for consistency: 
      [theme]
background = "#1a1a1a"  # Explicit hex

  3. Test colors:

    # Print color test
for i in {0..255}; do
  printf "\e[48;5;${i}m %3d \e[0m" $i
  [ $((($i + 1) % 16)) -eq 0 ] && echo
done

Washed Out Colors

Symptom: Colors look pale or desaturated

Causes:

  1. Terminal transparency
  2. Bold-as-bright setting
  3. Theme choices

Solutions:

  1. Disable terminal transparency for accurate colors

  2. Adjust terminal settings:

    • Disable “Bold as bright” if colors seem too bright
    • Enable “Bold as bright” if bold text is invisible

  3. Increase color saturation in theme:

    [theme]
# Use more saturated colors
health = "#00ff00"    # Bright green
mana = "#0080ff"      # Bright blue

High Contrast / Low Visibility

Symptom: Some text hard to read

Solutions:

[theme]
# Increase contrast
background = "#000000"
text = "#ffffff"
text_dim = "#b0b0b0"  # Brighter dim text

# Use accessible color combinations
# Background: #000000, Text: #ffffff (21:1 contrast)
# Background: #1a1a1a, Text: #e0e0e0 (13:1 contrast)

Character Rendering

Missing Characters (Boxes)

Symptom: Characters display as □, ?, or empty boxes

Cause: Font missing required glyphs

Solutions:

  1. Install complete font:

    • JetBrains Mono
    • Fira Code
    • Cascadia Code
    • Nerd Font variants (include many symbols)

  2. Set fallback font in terminal settings

  3. Disable Unicode:

    [display]
unicode = false
ascii_borders = true

Wrong Box Drawing Characters

Symptom: Borders look wrong or misaligned

Causes:

  1. Font substitution
  2. Line height issues
  3. Unicode normalization

Solutions:

  1. Use monospace font designed for terminals

  2. Adjust line spacing:

    # Alacritty example
font:
  offset:
    y: 0  # May need adjustment

  3. Use ASCII borders:

    [display]
border_style = "ascii"
# Uses +--+ instead of ╔══╗

Emoji Display Issues

Symptom: Emoji not rendering or wrong width

Solutions:

  1. Ensure emoji font installed:

    • Noto Color Emoji (Linux)
    • Apple Color Emoji (macOS)
    • Segoe UI Emoji (Windows)

  2. Configure terminal:

    # Alacritty
font:
  builtin_box_drawing: true

  3. Avoid emoji in critical areas:

    [display]
emoji_support = false  # Use text instead

Layout Problems

Widget Overlap

Symptom: Widgets draw over each other

Diagnosis:

# Start with layout debug
two-face --debug-layout

Solutions:

  1. Check coordinates:

    [[widgets]]
type = "text"
name = "main"
x = 0
y = 0
width = 70
height = 85  # Ends at y=85

[[widgets]]
type = "progress"
name = "health"
x = 0
y = 86       # Start after main ends

  2. Use percentage positioning:

    [[widgets]]
type = "text"
x = "0%"
y = "0%"
width = "70%"
height = "85%"

Widgets Outside Screen

Symptom: Widgets cut off or invisible

Causes:

  1. Fixed positions larger than terminal
  2. Percentage math errors

Solutions:

  1. Use percentages for flexible layouts:

    [[widgets]]
width = "25%"   # Always fits

  2. Handle resize:

    [layout]
resize_behavior = "scale"  # Rescale widgets

  3. Check terminal size:

    echo "Columns: $(tput cols) Rows: $(tput lines)"

Wrong Z-Order

Symptom: Popup appears behind other widgets

Solution:

[[widgets]]
type = "text"
name = "popup"
z_index = 100  # Higher = on top

Border Issues

Borders Not Aligned

Symptom: Border corners don’t meet, gaps appear

Causes:

  1. Font character width inconsistency
  2. Terminal cell size
  3. Unicode width calculation

Solutions:

  1. Use consistent font:

    • Pure monospace font
    • Same font for all text

  2. ASCII fallback:

    [display]
border_style = "ascii"

  3. Adjust border characters:

    [theme.borders]
horizontal = "─"
vertical = "│"
top_left = "┌"
top_right = "┐"
bottom_left = "└"
bottom_right = "┘"

Double-Width Character Issues

Symptom: CJK characters or emoji break alignment

Solution:

[display]
wide_character_support = true
wcwidth_version = "unicode_15"

Refresh Issues

Partial Redraws

Symptom: Parts of screen don’t update

Causes:

  1. Optimization too aggressive
  2. Terminal damage tracking
  3. SSH/tmux issues

Solutions:

  1. Force full refresh:

    # In Two-Face
.refresh

    Or keybind:

    [keybinds."ctrl+l"]
action = "refresh_screen"

  2. Disable lazy rendering:

    [performance]
lazy_render = false

  3. tmux settings:

    # In .tmux.conf
set -g default-terminal "screen-256color"
set -ag terminal-overrides ",xterm-256color:RGB"

Screen Flicker

Symptom: Screen flashes during updates

Solutions:

  1. Enable double buffering:

    [display]
double_buffer = true

  2. Batch updates:

    [performance]
batch_updates = true

  3. Check terminal:

    • Some terminals handle rapid updates poorly
    • Try Alacritty, Kitty, or WezTerm

Ghost Characters

Symptom: Old characters remain after widget moves

Solution:

[display]
clear_on_move = true
full_redraw_on_resize = true

Terminal-Specific Issues

SSH Display Problems

Symptom: Display corrupted over SSH

Solutions:

  1. Set TERM correctly:

    ssh -t user@host "TERM=xterm-256color two-face"

  2. Enable compression:

    ssh -C user@host

  3. Reduce color depth:

    [display]
color_mode = "256"  # More compatible

tmux Display Problems

Symptom: Colors or characters wrong in tmux

Solutions:

  1. Configure tmux:

    # .tmux.conf
set -g default-terminal "tmux-256color"
set -as terminal-features ",xterm-256color:RGB"

  2. Start Two-Face correctly:

    TERM=tmux-256color two-face

Screen Display Problems

Symptom: Issues in GNU Screen

Solutions:

# .screenrc
term screen-256color
defutf8 on

Accessibility

High Contrast Mode

[theme]
name = "high_contrast"
background = "#000000"
text = "#ffffff"
border = "#ffffff"
border_focused = "#ffff00"

health = "#00ff00"
health_low = "#ffff00"
health_critical = "#ff0000"

Large Text

Configure in terminal settings, not Two-Face:

  • Increase font size to 14pt+
  • Two-Face will adapt to available space

Screen Reader Hints

[accessibility]
screen_reader_hints = true
announce_focus_changes = true

Diagnostic Commands

Test Display Capabilities

# Color test
printf "\e[38;2;255;0;0mTrue Color Red\e[0m\n"

# Unicode test
echo "╔═══════╗"
echo "║ Test  ║"
echo "╚═══════╝"

# Box drawing test
echo "┌─┬─┐"
echo "├─┼─┤"
echo "└─┴─┘"

Debug Mode

# Start with display debugging
two-face --debug-display

# Log display operations
TF_LOG_DISPLAY=1 two-face

See Also