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
 
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