From f020b16635491e808c6542f5af68f65d604441c7 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 14 Nov 2026 20:29:49 -0600 Subject: [PATCH 1/2] WRITING(docs[design]) Carry the design system's writing rules why: The libtmux.org design system asks five rules of WRITING.md (12-contract-changes.md) that the site now implements: code frames that state their role, behaviour facts with source lines, equivalence tables that separate a recorded absence from an unmapped port, interface states that say what failed and what still works, and two named language labels. Without them in the writing guide, the next change has no rule to follow. what: - Voice: say "programming language" and "translation language" in interface labels, never the bare "Language" - Who you are writing for: equivalence tables name recorded differences and write "Not mapped" when no mapping exists - Documented examples that run: every code frame states its role (excerpt with file and line range, complete program with files, setup and output) - API documentation: documented completion, ownership, errors, transport and tmux requirements become behaviour facts with their source line - Error messages and help: interface states name what failed, what still works, and the next place to go --- WRITING.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/WRITING.md b/WRITING.md index 6fa352605..377d479dd 100644 --- a/WRITING.md +++ b/WRITING.md @@ -29,6 +29,9 @@ Describe the current behavior. Keep implementation deliberation and branch history in commit messages. Explain tickets and decisions when referring to them; an identifier alone is not context. +Say "programming language" and "translation language" in interface labels, +never the bare word "Language". + ## Who you are writing for The default reader uses libtmux in one language and needs to accomplish a @@ -42,7 +45,10 @@ contributor sections and link to them when needed. - Name tradeoffs in observable terms: blocking, extra commands, cleanup, portability, or latency. Explain what the reader gains for that cost. - Describe each port's actual semantics. Similar names do not prove matching - behavior, defaults, errors, or async guarantees. + behavior, defaults, errors, or async guarantees. Equivalence tables name + recorded differences (async, owner, overloads) and separate a recorded + absence from an unmapped port: write "Not mapped", never "not supported", + when no mapping exists. Use prose for explanations and sections for distinct ideas. Use lists for steps or parallel facts; do not turn paragraphs into oversized bullets. @@ -72,6 +78,10 @@ implementation details only when they affect a reader's choice. ## Documented examples that run +Every code frame states its role. An excerpt names its file and source line +range and links the complete program on the same page; a complete program +shows its files, setup commands and expected output. + Use real public imports, valid names, and explicit prerequisites. Show necessary error handling and cleanup. Avoid placeholders that a reader must decode. Verify example code against the relevant port and version rather @@ -281,6 +291,10 @@ free of routine narration. Verify the rendered link instead of assuming a doc dialect works here. - Keep public examples runnable and preserve their collection markers. +When a declaration's completion, ownership, errors, transport or tmux version +requirement is documented, the extractor records it as a behaviour fact with +its source line, so the reference can show it beside the signature. + ## Source comments Keep a source comment only when it passes all three gates: @@ -318,6 +332,10 @@ Name the failed operation, the relevant input, and a corrective action when one is known. Avoid empty messages such as "an error occurred", blame, and speculative fixes. Keep published examples free of private paths and data. +Interface states name what failed and what still works ("The sidebar did not +load. The page is complete without it.") and link the next-widest place to +go. + Document defaults, units, empty-value semantics, filesystem effects, and exit statuses where they affect using a script. Verify which stream carries results and which carries diagnostics; do not invent a repo-wide convention From 4cc5910e504e25410deb2bf5a8f1cedca73801a7 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 14 Nov 2026 20:29:50 -0600 Subject: [PATCH 2/2] AGENTS(docs[design]) Point agents at the design system and its checks why: The libtmux.org design system asks three additions to AGENTS.md (12-contract-changes.md): where visual tokens and component anatomy are defined, that values become named custom properties, and which checks cover badge colour and layout changes. what: - Which policy applies: name the design system (libtmux/design) for visual tokens, component anatomy and page-family rules - Change discipline: add values as named custom properties, never literal colours in component styles - Change discipline: run check-style-parity for badge, signature and kind colours, and the layout-shift probe for player, tab, filter and pane layout changes --- AGENTS.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 9f41e98e0..301e38dba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,6 +12,9 @@ requested work. - Environment, Oxlint, formatting, tests, and pull requests: [CONTRIBUTING.md](.github/CONTRIBUTING.md). - Documentation, user-facing text, comments, and commits: [WRITING.md](WRITING.md). +- Visual tokens, component anatomy, and page-family rules: the libtmux.org + design system ([libtmux/design](https://github.com/libtmux/design)), + implemented in `site/src/styles` and `site/src/components`. Each guide is the single home for its subject. @@ -44,6 +47,11 @@ facts come from the code. `site/src/integrations/pagefind.ts`. - Keep TypeScript on the workspace's 6.x catalog entry; do not bump it to 7. See [Toolchain constraints](.github/CONTRIBUTING.md#toolchain-constraints). +- Add colour, spacing, and size values as named custom properties beside the + existing ones; do not introduce literal colours in component styles. +- Run `site/scripts/check-style-parity.mjs` for badge, signature, and kind + colour changes, and the layout-shift probe (`site/scripts/check-page-readiness.mjs`) + for layout changes to players, tabs, filters, or panes. ## Repository boundaries