Skip to content

STYLE.md

Latest commit

 

History

History
113 lines (88 loc) · 5.76 KB

STYLE.md

File metadata and controls

113 lines (88 loc) · 5.76 KB
Raw

Terminal output style

The tracebloc CLI and the installer share one terminal style system. This is the reference; scripts/check-style.sh enforces the mechanical parts in CI.

The idea

From the tracebloc.io homepage gradient — cyan orients, lime moves:

  • cyan #01a5cc = structure — headings, step titles, links, "where you are"
  • lime #91e947 = action — commands, the primary CTA, "what to do next"

Everything else stays quiet (dim neutral). Colour is never load-bearing: headings and commands also carry bold, and alerts carry a distinct glyph, so the output still reads under NO_COLOR, in a pipe, or for a colour-blind reader.

Roles → tones

All colour goes through the Printer in internal/ui — never inline an escape or hex elsewhere. The tone table (internal/ui/ui.go) maps each role:

Role Printer method / tone Colour Weight / glyph
Heading / section / step Section, Step, Banner (toneHeading) cyan #01a5cc bold
Command (to run) Command, MenuRow cmd (toneCommand) lime #91e947 bold
Description / supporting MenuRow desc (toneDesc) soft lime #a7ed6c —
Link / URL toneLink cyan #01a5cc underline
Success ✔ / online ● Successf, CheckLine (toneGo) lime #91e947 glyph
Warning ⚠ Warnf, WarnLine (toneWarn) amber #ffc62b glyph
Error ✖ Errorf (toneErr) red #f64c4c bold glyph
Label : value Field, Stat (toneLabel) dim neutral —

Emoji are welcome — used with intent, for warmth (👋 greeting, 💚 sign-off, 🚀 sent) and for status (🟢 online, 🟡 starting, 🔴 offline, ⚠ caution). They're a brand touch, not policed by the guard — just don't overuse them.

The engine renders exact 24-bit hex on truecolor terminals, the deep shade (#01637a / #578c2b) on light backgrounds, the nearest ANSI-16 otherwise, and nothing when colour is off (NO_COLOR / non-TTY / TERM=dumb / --plain). The exact brand SGR is pinned by internal/ui/brand_tones_test.go, so a drift in the tone table fails CI. The installer mirrors this in scripts/lib/common.sh.

Guided-prompt spacing

Interactive flows (the tb data ingest questionnaire, and any future guided flow) use one uniform rhythm so every question reads the same:

  • One blank line before each question header — a Step N of M · <question> (PromptStep) or an unnumbered refinement/confirm header (Section). The header method emits this leading blank itself.
  • One blank line between the header and its supporting text (the hint / examples / option list), when there is any.
  • One blank line before the ? prompt line. With no supporting text, that single blank sits directly between the header and the prompt.
  • A result that belongs to an answer attaches to it with no blank — e.g. the ✔ Found a CSV table … sniff echo sits directly under the path answer.

So: header → blank → [supporting text → blank] → ? prompt. Keep it uniform — don't hand-tune the spacing of individual questions.

Guided-prompt labels

The ? line carries a short noun label, not the question: ? Path: ~/mydata, ? Task: tabular_classification. The question lives in the header and is never repeated on the ? line; the label says what you are typing into.

  • The label is the shortest noun phrase that names the answer, with a trailing colon — Split:, Name:, Path:, Task:, Data type:, Label: / Target:, Keypoints:, Resolution:, Column types:, Label policy:, Time column:.
  • A prompt never goes label-less. The guided flow used to blank survey's Message (a bare mode), which rendered a lone ? — and once answers were pre-filled, ? [~/mydata]: a question mark, a bracket and a path, with no verb (cli#504). internal/cli/interactive_test.go asserts the property — non-empty, ends in :, no ?, within a length budget — against whatever the real flow asks, so a new question is covered without editing the test.
  • A confirm is the exception: it carries the whole question (? Proceed with the ingest? (y/N)). A y/N prompt has no header of its own, and the overwrite-replace confirm fires with nothing printed before it — a noun there would name the object and hide the stakes.
  • Flows with no step headers of their own (client create, delete, resources set) pass the whole question as the label. The register follows the header, not the prompter.

Terminology

Source of truth: the docs repo TERMINOLOGY.md. In user-facing output:

Use Not
secure environment workspace, hub, client (as a noun for the environment)
ingest upload, import
delete remove, uninstall (for offboarding)
Online / Offline connected / disconnected, up / down
collaborators users, members
task job, experiment type

client stays valid as the CLI verb (tracebloc client create) and in code identifiers (exitNoWorkspace, etc.) — the guard matches workspace as a whole word in output text only.

What's enforced vs reviewed

scripts/check-style.sh (CI Lint job, blocking) catches the mechanical violations: hardcoded brand colour outside internal/ui, and workspace in user-facing text. Run it locally with make check-style (also part of make ci) or directly: bash scripts/check-style.sh.

It can't police judgement — using the right role for a token (a command in the command tone, not the heading tone), or the softer terminology calls. Those stay with review; STYLE.md and scripts/check-style.sh are CODEOWNER-gated so the rules can't be quietly weakened.

To intentionally exempt a line, append // style-guard: allow with a reason.