Unicode Color Accessibility

Unicode, Color, Accessibility, and Non-TUI Fallbacks

Use this skill when terminal output must be visually correct, readable, inclusive, and robust across fonts, locales, themes, and assistive technologies.

Text correctness rules

• Display width is not byte length, code point count, or user-perceived character count.
• Cursor movement and deletion should operate on grapheme clusters.
• Layout should measure printable text after stripping ANSI control sequences.
• Double-width characters, combining marks, emoji sequences, variation selectors, and zero-width joiners must be tested.
• Treat ambiguous East Asian width as narrow by default unless the target environment explicitly differs.

Visual design rules

• Use semantic roles: error, warning, success, info, muted, selected, focused, disabled.
• Do not encode meaning by color alone; pair color with text, shape, icon, or position.
• Provide ASCII fallback for box drawing, braille charts, block elements, emoji, and private-use icons.
• Avoid assuming Nerd Fonts or patched fonts.
• Support light and dark backgrounds, 16-color, 256-color, truecolor, and no-color modes.

Color preferences

Respect user and environment preferences:

• NO_COLOR disables non-essential color.
• CLICOLOR, CLICOLOR_FORCE, and FORCE_COLOR may force color depending on ecosystem conventions.
• TERM=dumb, non-TTY output, and CI usually imply plain output unless overridden.
• Provide explicit flags such as --color=auto|always|never, --plain, and --ascii.

Accessibility requirements

• All functionality must be keyboard-operable.
• Focus indicators must be visible without relying on color alone.
• Avoid flashing more than three times per second.
• Allow spinner, animation, and live-region suppression for reduced motion, logs, and CI.
• Provide screen-reader friendly alternatives: plain prompts, line-oriented commands, --json, --plain, or documented stdin/stdout workflows.
• Use meaningful labels, stable ordering, and visible status messages.

Failure modes

Reference files

• references/text-measurement.md - Unicode width, graphemes, emoji, BiDi, and ANSI measurement.
• references/accessibility-fallbacks.md - Color policy, screen-reader alternatives, and inclusive UX checklist.

Accessibility and Fallback Reference

Accessible mode patterns

• --no-tui: line-oriented interactive mode or direct CLI subcommands.
• --plain: no cursor control, minimal formatting, stable text order.
• --json: machine-readable state for scripts and assistive workflows.
• --color=never: no color dependency.
• --ascii: no box drawing, emoji, braille, or private-use icons.

Alternate flow contracts

Every full-screen workflow should have an equivalent plain or scriptable contract:

TUI action: select failed job, open detail, retry
Plain flow:
  app jobs list --status failed --plain
  app jobs show JOB_ID --plain
  app jobs retry JOB_ID --confirm
JSON flow:
  app jobs list --status failed --json
  app jobs retry JOB_ID --json --confirm

Output contract examples:

# --plain
STATUS failed
JOB api-17
ERROR timeout waiting for db
NEXT_ACTION app jobs retry api-17 --confirm

# --json
{"status":"failed","job_id":"api-17","error":"timeout waiting for db","actions":[{"name":"retry","command":["app","jobs","retry","api-17","--confirm"]}]}

Plain output should be stable, line-oriented, and free of cursor controls. JSON output should write machine-readable data to stdout and diagnostics to stderr.

Color and contrast

Semantic roles should map to theme-aware palettes. Check contrast for foreground/background pairs and meaningful borders or chart lines. Do not use dim text for required information. In no-color mode, preserve meaning with words, punctuation, alignment, or labels.

When designing custom palettes, perceptual color spaces such as OKLCH can help choose evenly spaced colors, but terminal output ultimately becomes user-theme RGB, 256-color indexes, or 16-color roles. Always test the final mapped colors. High-DPI displays can make glyphs sharper, but terminals still lay out in cells; do not design pixel-dependent UI.

No-color equivalence examples:

Cognitive and motion accessibility

Keep navigation stable, avoid surprise focus jumps, use clear labels, group related actions, and explain destructive consequences in plain language. Avoid flashing more than three times per second and allow spinners, progress animation, and live dashboard updates to be reduced or disabled.

Reduced-motion contract:

if --reduced-motion or CI or non-TTY:
  spinner -> static "Loading..."
  animated progress -> periodic line updates or final summary
  live dashboard -> slower refresh or manual refresh

Screen-reader reality

Many full-screen TUIs repaint a visual grid that screen readers cannot interpret well. The accessible solution is usually not more escape sequences; it is a parallel plain interface with the same core functionality.

Document discoverability in --help:

Accessibility:
  --no-tui          Use line-oriented prompts instead of full-screen UI.
  --plain          Print stable plain text with no cursor control.
  --json           Print machine-readable output for scripts.
  --color=never    Disable color.
  --ascii          Avoid Unicode drawing characters and emoji.

Inclusive interaction checklist

• All actions reachable from keyboard.
• Help lists keybindings and non-TUI alternatives.
• Focus state is visible and textual where possible.
• Status and errors are announced in stable text regions or plain output.
• Animation can be disabled.
• Timeouts are avoidable or configurable.
• Destructive actions require confirmation that does not depend on color.
• Copy/export actions exist for content that may be hard to select from an alternate screen.

Text Measurement Reference

Width concepts

• Bytes: storage encoding, not visual width.
• Code points: Unicode scalar values, still not visual width.
• Grapheme clusters: user-perceived characters, useful for cursor movement and deletion.
• Cell width: terminal display columns, needed for layout.

A renderer usually needs both grapheme segmentation and width calculation.

UAX-to-implementation mapping

Implementation pipeline:

input string
  -> parse/remove ANSI controls into style spans
  -> segment grapheme clusters (UAX #29)
  -> assign display cell width per cluster (wcwidth/EAW/emoji policy)
  -> wrap/truncate by accumulated cells (UAX #14 where wrapping prose)
  -> render cells with style metadata, never counting escape bytes

ANSI-aware measurement

Strip or parse ANSI escape sequences before measuring visible text. Styled strings should preserve metadata separately where possible. Never let escape bytes contribute to table width, wrapping, truncation, or cursor position.

Styled truncation example:

input spans: [red "ERROR"], [plain ": database unavailable"]
limit: 12 cells
visible: "ERROR: datab"
output: SGR(red) "ERROR" SGR(reset) ": datab" SGR(reset)

If truncating inside a styled span, close/reset the active style. If the parent style must continue after the truncated fragment, reset then reapply the parent style explicitly.

Test strings

Use these in unit, snapshot, and manual tests:

Double-width and zero-width cases

Test CJK ideographs, Hangul, fullwidth punctuation, combining accents, emoji with skin tone modifiers, zero-width joiner sequences, flag sequences, variation selectors, and private-use glyphs. Different terminals and fonts can disagree; keep fallbacks practical.

Truncation and wrapping

Truncate by grapheme and cell width, not bytes. Do not split a double-width glyph at the final column. When a styled string is truncated, close/reset styles safely. Wrapping should account for wide characters and preserve indentation semantics.

Pseudo-code:

truncate_to_cells(spans, limit):
  out = []
  used = 0
  for span in spans:
    for cluster in graphemes(span.text):
      w = cell_width(cluster)
      if used + w > limit: return close_styles(out)
      out.append(cluster with span.style)
      used += w
  return close_styles(out)

Line breaking and shaping

Unicode line breaking, grapheme segmentation, and terminal cell width are related but different. Wrapping should follow grapheme boundaries and avoid splitting combining sequences, emoji ZWJ sequences, flags, and double-width cells. Terminals generally do not expose full font shaping decisions to applications; ligatures and font-specific glyph substitution can change appearance without changing cell counts.

BiDi text

Keep text in logical order when possible and let terminal display behavior handle ordering. For full-screen cell renderers, test mixed LTR/RTL content and avoid manual reordering unless the application intentionally owns a BiDi strategy. If precise BiDi layout is required, document the strategy and test with UAX #9-style cases.

Symbol sets and fonts

Box drawing, block elements, braille patterns, powerline glyphs, Nerd Font icons, emoji presentation sequences, variation selectors, and private-use characters can render differently across fonts and terminals. Provide ASCII mode, avoid private-use icons for essential meaning, and test with common monospace fonts.