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

Symptom	Likely cause	Fix
Misaligned tables	byte length or ANSI counted as visible width	use ANSI-aware wcwidth/grapheme measurement
Cursor splits emoji	movement by code point	move by grapheme cluster
Borders look broken	font or width mismatch	provide ASCII mode and test common fonts
Error only shown in red	color-only meaning	add text/icon/label and contrast check
Screen reader unusable	full-screen repaint grid	provide non-TUI mode and line-oriented flows

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.