Decision D019 · accepted as a goal; details proposed
Terminal output is colored and carefully designed
A record of the language's design, as it stood on 2026-11-18: written for the people who build Diaspar, and kept as it was written. Its code is a sketch, not a program of the site, and an older record may show syntax that a later one changed. It names files of the language's source, which is not public yet.
Status: accepted (2026-11-15) as a goal; proposed for the details
Decision
Everything Diaspar's tools print to a terminal is designed, not incidental: diagnostics (D014), the REPL and the debugger (D017), test and benchmark results (D016), and build output. One shared style and one implementation serve all of them, as Rust's diagnostics look the same across cargo's commands.
Principles (proposed)
-
Meaning, not raw colors, in the toolchain. The tools' output names what a piece is (error, warning, help, location, code, value, success, muted) through the fields of component themes, and one theme file configures every tool.
-
The terminal's palette by default. Default theme styles use the 16 ANSI colors, so the user's terminal theme decides the actual colors and Diaspar looks native in any theme. 24-bit colors only when a theme asks for them.
-
Never color alone. Every meaning also has a word or a symbol (
error:,✓,✗), for color-blind users, logs, and screenshots in black and white. -
The standard switches. Color only when the output is a terminal;
--color=auto|always|never; theNO_COLORandFORCE_COLOR/CLICOLOR_FORCEenvironment variables; no color whenTERM=dumb. When bothNO_COLORandFORCE_COLORare set,NO_COLORwins: it is the user's request. UnderNO_COLORon a terminal, bold and underline stay, as no-color.org advises (accepted). -
Styled output is Rich markup inside an f-string (accepted).
term.printis a macro over the f-string (D022), so it sees the literal parts and the interpolated values separately, as Python 3.14's t-strings (PEP 750) do:(term.print f"[bold red]error:[/] cannot read {path}")- Markup comes only from the literal parts and is parsed at compile time:
[bold rde]or an unclosed tag is a compile error with a suggestion. - Interpolated values are never markup: a file name containing
[blink]prints as it is, escaped automatically. In Rich and Spectre.Console the f-string is joined before the markup parser sees it, so text from data can restyle the output unless the caller escapes it by hand; this closes that hole. - The tag syntax is Rich's, known from Rich, Textual, and Spectre.Console:
[bold red],[on #ff8000],[color(208)],[/]closes the last tag. - Stricter than Rich (accepted, 2026-11-16):
[/name]must close the innermost open tag, and a tag left open at the end is a compile error; Rich repairs both silently.[[and]]write brackets. - The result is styled text as data, rendered once at the stream with its capabilities (D024); in a pipe or under
NO_COLORthe markup disappears.
- Markup comes only from the literal parts and is parsed at compile time:
-
Themes are records per component (accepted). Each component that prints (diagnostics,
clihelp, the test runner, the REPL) has its own theme, a record whose fields are styles with defaults, as clap'sStylesand miette'sThemeStyles:;; std.diagnostic (deftype Theme [(error default: (style.parse "bold red")) (warning default: (style.parse "bold yellow")) (help default: (style.parse "cyan")) (location default: (style.parse "blue")) (line-num default: (style.parse "dim"))])Markup tags may name the theme's fields, checked at compile time against the theme's type:
(term.print theme f"[error]error:[/] {message}"). A package that prints its own output (adiff, say) declares its own theme record; nothing is registered globally. The user's theme file sets fields per component, decoded into the records, so a misspelled field is a decoding error with a suggestion (D010):;; ~/.config/diaspar/theme.dias #{:diagnostic #{:error "bold bright-red" :help "bright-cyan"} :cli #{:header "bold green"}} -
Styles are built in code with a builder (accepted as the direction; the names are proposed), following Ferron's
Style.new().fg(Red).bold()and ratatui'sStyleandStylize. The builder functions live instd.term.styleand thread with->; colors are variants ofColor(the 16 ANSI colors,(Indexed n),(Rgb r g b),(Default)):(use std.term.style) (use std.term.color [Color]) (def error-style (-> style.plain (style.fg (Color.Red)) style.bold)) (def squiggle (-> style.plain (style.underline :curly) (style.underline-color (Color.Red)))) ;; the same functions style text directly, as ratatui's Stylize: the result is a styled span (-> "error:" (style.fg (Color.Red)) style.bold) (term.styled "error:" error-style)style.parsereads the text form ("bold red on #ff8000"), used by theme files and configuration; literal strings are parsed at compile time. Styles combine withstyle.patch, where later attributes win, as ratatui'spatch. -
No global roles and no function per color (accepted). There is no language-wide list of roles (
role.error): its names collided with other concepts such as theErrorprotocol, it needed an extension mechanism for packages, and one list fits no component well; meaning lives in component themes instead. There are no top-level functions such asterm.redorterm.bold: dozens of names in a module for what one markup tag or one builder call says. Also rejected: keyword roles (misspellings found only by a check against a set), adefenumof roles (heavy to write, closed to packages), and Rich's names-as-strings in one shared theme (the same global registry, without checks). -
Unicode with a fallback. Box-drawing characters and symbols (
─,│,✓), with an ASCII fallback when the locale or terminal cannot show them. -
Code is highlighted. Source excerpts in diagnostics, REPL input, and printed values use syntax highlighting with the same theme.
-
Curly underlines in diagnostics. Where the terminal supports extended underlines (kitty, Ghostty, WezTerm, and others), the span of an error is underlined with a red curly line and a warning with a yellow one, as editors do; elsewhere the
━/^underline stays (accepted). -
Theme files are data mapping component theme fields to styles written as text (
#{:diagnostic #{:error "bold bright-red"}}), with automatic color downgrade (D024) (accepted). -
Locations are links.
file:line:colis printed as an OSC 8 hyperlink where the terminal supports it, so a click opens the file in the editor. -
The width is respected. Output wraps or truncates to the terminal width; long values are abbreviated with a way to see them in full.
-
Motion only on a terminal. Progress counters and spinners appear only when the output is interactive; piped and CI output stays plain, stable, and line-based.
-
Machine-readable output is separate.
--json(D014) never contains color codes.
Why
Output is the language's face: a new user meets the diagnostics, the REPL, and the test runner before anything else. Rust, Elm, and modern tools such as uv and bun show that careful output is part of why a tool feels good to use.