roundel

chalk gives you red; picocolors gives you red for fewer bytes. Neither gives you error, and each decides on its own whether the terminal has colour — which is why a program's spinner, prompt and help so often disagree. roundel is the colours a CLI carries: one output policy decided once from the runtime, nine semantic tokens over util.styleText, and a theme that changes them all together, contrast-checked before it flies — plus chalk's API over the same tokens, for the program that is not ready to give chalk up. Zero dependencies, five subpaths, each costing only itself.

For an agent, the policy is the point: under --json, NO_COLOR or a pipe nobody asked to colour, every token returns its input unchanged, so captured output never carries an escape.

A roundel is a flag's colours carried onto another surface — the rings on an aircraft's wing, the London Underground sign. Identity, expressed purely in colour, on something that is not a flag. That is what this package is for a command-line program: not red and blue, but error, hint, command and flag, the colours that mean you, carried onto the terminal as a theme.

Start here

npm install roundel

import { fly } from 'roundel/theme';
import { command, error, hint } from 'roundel/tokens';

// Once, at startup. The runtime is yours to describe; nothing here reads `process`.
fly({}, { env: process.env, isTTY: { stdout: Boolean(process.stdout.isTTY) } });

console.error(`${error('missing --name')}  ${hint('try')} ${command('greet --name ada')}`);

Through a pipe with nothing asked, under NO_COLOR, or with --json, every token returns its input unchanged. On a terminal it styles, at the level the terminal has — and on a pipe too when the user said so with FORCE_COLOR or --color.

What is here

The policy

First match wins: json if the run asked for it; accessible if CLI_ACCESSIBLE; ci if CI and not a TTY; pipe if not a TTY; else tty. The mode decides redraws — spinners, progress, anything that rewrites a line — and never the colour level.

The level is chalk's, and it obeys the user's explicit instruction in any mode: NO_COLOR wins outright; then FORCE_COLOR=0, which supports-color settles before it reads any flag, so an explicit "colour off" is never overridden into colour on — FORCE_COLOR=0 with --color=256 is 0, not 2; then the --color flags (--color=256, --color=16m, --no-color, --no-colors, --color=never… both spellings, as has-flag has them) when the caller hands the policy its argv; then FORCE_COLOR, which names an exact level (FORCE_COLOR=2 is 2, not "2 or better") or, as true or empty, only turns colour on and lets the environment decide it. --json is the one output the level never enters: structured text carries no escapes.

With no instruction at all the order is supports-color's own, deliberately: a pipe is 0 — a pipe nobody asked to colour is a file or another program's stdin — and accessible mode is 0 too, because CLI_ACCESSIBLE is itself an instruction from a human and ANSI colour is noise to a screen reader; an explicit ask still colours either of them. Azure Pipelines (TF_BUILD and AGENT_NAME) is the single exception on a pipe, exactly where chalk puts it. Once colour is being detected, on a terminal or because the run asked, TERM=dumb is the floor, a CI run gets its vendor's level (GitHub and Gitea Actions and CircleCI at truecolor; Travis, AppVeyor, GitLab, Buildkite, Drone and Codeship at 16), and anything else is what TERM and COLORTERM report. So FORCE_COLOR=true on GitHub Actions gives you truecolor logs, and nobody else's pipe changes.

One policy, one answer: no two components in a program can reach different conclusions, which is the whole point (clack #286).

The theme

fly(
  {
    ground: '#0a0a0a', // what the hex tokens are checked against; near-black by default
    error: '#f4794a', // truecolor, checked at 4.5:1 against the ground, or fly() throws
    heading: ['bold', 'underline'], // the terminal's own palette — never checked or claimed
  },
  runtime,
);

The defaults carry the burgee brand — rock for error, juniper for ok, each in whichever of its deep or lifted variants reads better on the declared ground — and format names for the other seven. A hex token below 4.5:1 is refused at every level, not only on truecolor terminals, so a theme that would not read fails in CI rather than on one laptop. The 16- and 256-colour fallbacks are the user's terminal palette and are not checked: a number there would be invented.

Migrating from chalk

- import chalk from 'chalk';
+ import chalk from 'roundel/chalk';

Identical. The chain (chalk.red.bold.underline(s), every modifier, the sixteen colours and their Bright variants, backgrounds, chalk 6's underline styles and colours), rgb/hex/ansi256 and their bg/underline forms with chalk's own downsampling at levels 2 and 1, nesting and line-break handling byte for byte, chalk.level (get and set, validated), new Chalk({ level }), chalkStderr, supportsColor / supportsColorStderr, modifierNames / foregroundColorNames / backgroundColorNames / underlineColorNames / colorNames, visible, reset, and Function.prototype on every link. ESM with a default condition, so require('roundel/chalk') works too.

Different.

• The level is per façade. chalk.level = 0 silences roundel/chalk and nothing else; the tokens and the theme keep reading the policy. chalk's global mutable level is why chalk and ora disagree about the same terminal, and it stops at this door.
• The policy decides colour. The level is detected once at import through colorLevel(), reading the same NO_COLOR, FORCE_COLOR, --color, CI-vendor, TERM and COLORTERM rules chalk does — see The policy. Every other package in the family reads the same answer, so roundel/chalk and a spinner cannot disagree about the terminal the way chalk and ora do.
• No template literal. chalk\{red x}`` was removed in chalk 5 and is not resurrected.
• No emulator allow-list. chalk's per-terminal-program detection (TERM_PROGRAM, kitty, ghostty, wezterm, TeamCity, the Windows build number) is not reproduced; a program on one of those terminals that wants colour asks for it with FORCE_COLOR or --color.

Graded by chalk's own suite, vendored at 6.0.0 into compat-oracle and run unedited through a generated shim: 58 of 58 tests (100.0%) on 2026-09-08, alongside the same suite scoring 58 / 58 against real chalk in the same run.

Weight

Every subpath is a lock, not a convention. roundel/tokens reaches 3,258 bytes on disk (its ceiling is picocolors, 3.3 KB); roundel/policy 1,972; roundel/theme 6,271; roundel/plugin 2,812 and reaching no module at all; roundel/contrast 1,250; roundel/chalk 9,311 (its ceiling is chalk 6.0.0's own 9,370, before the ansi-styles and supports-color chalk also ships). Importing one never loads another — the tokens never carry the theme, the theme never carries the tokens, chalk carries neither — and sideEffects: false lets a bundler drop what a program does not use. ESM with a default condition, so require('roundel/tokens') works from CommonJS on Node ≥ 24.

What is next

• roundel/import — fromBase16(scheme) and fromITerm(plist): a theme from the two largest corpora of terminal palettes, contrast-checked on the way in.

Part of the burgee family: a CLI on burgee declares what it is, roundel carries its colours, flagstaff flies it, and caique answers back. Each is an independent package; none requires the others.

MIT © Ofri Peretz — see LICENSE.

Benchmarks

Every number here is produced by npm run bench and published at /docs/benchmarks.

Graded by the incumbent's own test suite:

Where it sits

Plugins register under the tokens key, against the one schema the whole family shares.

burgee and flagstaff build on it, and it builds on nothing in this family.