ape-cli-terminal-experience

# CLI Terminal Experience A terminal UI that reads like Claude Code: mostly grey, a few deliberate accents, one line per fact, animation only while something is actually happening, and a plain-text fallback the moment the output stops being a terminal. Every rule below is enforceable and testable. Follow them exactly rather than approximating the vibe. --- ## 1. The two laws **Subtle by default.** Colour marks meaning -- a failure, a value the user will act on -- and nothing else. Labels, units, paths, and chrome are dim; values are plain. A full screen of output should read as mostly grey with a handful of accents, never as a colour test page. If you cannot say what a colour *means*, remove it. **Plain when not a terminal.** Pipe the program anywhere and every escape sequence disappears, glyphs fall back to bracketed ASCII, rules vanish, and the spinner goes silent. Output stays greppable; a script parsing it never sees a byte of styling. Three consequences that people get wrong: - Colour detection and terminal detection are **different questions**. `FORCE_COLOR` should add colour to piped output, but carriage-return redraws still make no sense there. Gate colour on `color_enabled()`, gate animation on `is_tty()`. - **Only colour is a colour question.** Glyph shape, rules, and the spinner are terminal questions -- they gate on `is_tty()`. Conflating the two is the single most common bug in this module: `NO_COLOR=1` in a real terminal then degrades `✓` to `[OK...