CLI Color Strategy¶

Reference for all ANSI color usage in tx. Read this before adding or changing colored output.

Palette¶

Every role keeps at least ~3.3:1 contrast on both dark (#1E1E1E) and light (#FFFFFF) terminal backgrounds — the practical ceiling for a single palette, since 4.5:1 (WCAG normal text) on both is mathematically impossible: it would require every color's luminance to sit in a near-zero-width band. Roles that appear in the same view are separated by lightness as well as hue, so the distinction survives for red-green color-blind readers (see Palette construction). The guarantees are enforced by PaletteTests.

Palette Implementation¶

Defined in src/Tomix.Cli/Output/Styling.cs:

using Spectre.Console;

namespace Tomix.Cli.Output;

internal static class Palette
{
    public static readonly Color Sage   = new(0x34, 0x89, 0x7E);
    public static readonly Color Lav    = new(0x85, 0x72, 0xAF);
    public static readonly Color Terra  = new(0x96, 0x64, 0x42);
    public static readonly Color Harbor = new(0x45, 0x82, 0xAC);
    public static readonly Color Moss   = new(0x40, 0x81, 0x39);
    public static readonly Color Amber  = new(0xB0, 0x7E, 0x2A);
    public static readonly Color Rose   = new(0xCC, 0x67, 0x66);
    public static readonly Color Orchid = new(0xCF, 0x67, 0xAC);
    public static readonly Color Slate  = new(0x75, 0x7F, 0x88);
}

Use Palette.Sage for Spectre widget styling (table borders, panel borders). Use the markup helpers below for inline text.

Palette Construction¶

The palette is derived, not hand-picked: hues and chroma come from the original design, and each color's CIELAB lightness is set deliberately.

• Contrast first. Lightness targets pull every role toward the luminance that maximizes its worst-case contrast against dark and light backgrounds, so no role drops below ~3.3:1 on either.
• Lightness as a second channel. Roles that appear side by side get a deliberate lightness gap in addition to their hue difference (columns darker than measures, variables darker than literals). Under red-green color vision deficiency the hue difference vanishes and the lightness gap carries the distinction: the columns/measures pair improves from ΔE 13 to 29 under deuteranopia simulation, variables/literals from 13 to 16.
• Enforced by tests. PaletteTests computes WCAG contrast ratios and CIELAB ΔE76 for every role and fails when a color falls below 3.2:1 on either background or a same-view pair drifts under ΔE 25.

When changing a palette color, keep this contract: adjust lightness before hue, and let PaletteTests arbitrate.

Message Categories¶

NO_COLOR Compliance¶

tx follows the NO_COLOR convention:

1. Environment variable. When NO_COLOR is set (any non-empty value), tx suppresses all ANSI color codes.
2. Config override. noColor: true in ~/.tomix/config.json also disables color.
3. Implementation. Both mechanisms set AnsiConsole.Profile.Capabilities.ColorSystem = ColorSystem.NoColors at startup (see Program.cs). Spectre.Console automatically strips all markup and color from output when this is set.
4. Piped output. Spectre.Console also detects Console.IsOutputRedirected and degrades gracefully.

Do not bypass this by writing raw ANSI escape codes. Always use Spectre.Console APIs or the Styling helpers.

Styling Helpers¶

All output helpers live in src/Tomix.Cli/Output/Styling.cs. Use these instead of raw markup strings.

What NOT to Color¶

• JSON output (--format json) — raw JSON, no markup.
• CSV output (--format csv) — raw CSV, no markup.
• TMDL/BIM raw output (--format tmdl, --format bim) — raw syntax.
• CI annotations (::error::, ##vso[task.logissue...]) — plain-text CI protocols.
• Completion scripts (completion bash/zsh/fish) — shell script output.