DESIGN.md
Guidelines for UI design, covering GUI, CLI, documentation, log messages, etc
Short, single-sentence text do NOT end in a period in the UI.
Multi-sentence text ALWAYS ends in a period.
We prefer normal casing, and avoid Title Casing.
We only use Title Casing for company and product names (Rerun, Rerun Viewer, Discord, …), but NOT for concepts like “container”, “view”, etc.
Good: log("File saved")
Bad: log("file saved.")
Use a spaced em dash (—) for parenthetical breaks in prose (docs, comments, log messages, UI text).
Avoid:
word—word) — add spaces around the em dash. <!-- NOLINT -->–) used as sentence punctuation — use an em dash instead.En dashes are reserved for numeric/range expressions (2020–2025, pp. 10–15, ~3–4 GB).
Write one sentence per line in markdown files (.md, docs, READMEs, agent guides).
Markdown joins consecutive non-empty lines into a single paragraph, so this does not affect rendering — but it produces much cleaner diffs.
Each edited sentence shows up as a single changed line, instead of reflowing an entire paragraph.
Use a blank line between paragraphs as usual.
When a button action requires more input after pressing, suffix it with ….
Good: Save recording… (leads to a save-dialog)
We do not use a colon suffix for labels in front of a value.
Good: Color 🔴
Bad: Color: 🔴