<!-- SYNCED COPY — do not edit here. Canonical: common-docs/skills/interface-text/SKILL.md This file is distributed to every consuming repo by common-docs/meta/scripts/sync_skills.py. Edit the canonical, run the sync, and commit each repo. Edits made here are overwritten and lost. -->

interface-text — in-app text is layout

Doctrine (read once): common-docs/policies/interface-text-is-layout.md.

You are writing interface text, not prose. Every string the app renders sits in a slot owned by a component, has a character budget, and has siblings that must match. The screen is not where you explain, justify, or prove anything — that is what the commit message, the code comment and FEATURE.md are for.

The card — apply to every string you write or touch

1. Who is this sentence for? If it helps someone reading the diff — a formula, a function or table name, where the number comes from, what changed, what is not built yet, which other page agrees with it — it is author-facing. Put it in a code comment or the commit. It never renders.
2. Label first, tooltip always. Make the label carry the meaning (Batch savings (7d)). Then give every label, icon button, abbreviation or number a newcomer might not understand a one-sentence tooltip: title= on KpiTile, components/official/InfoHint everywhere else (hover, keyboard and touch — a native title= attribute is unreachable on phones). A complex thing gets a help popover (FieldHelp from @ai-matrx/design-system/controls; a Field's string help and a settings row's helpText already render one). When you delete prose, ask what a newcomer loses and move that into a tooltip — never just delete (Arman, 2026-10-10: "our changes need to push for ALWAYS tooltips").
3. Fit the slot. Secondary text ≤ 60 chars, one line, never two sentences. Tooltip ≤ 140, one sentence. Placeholder ≤ 60, an example value. Dialog description / empty / error state ≤ 140, at most two sentences: what happened, what to do. No sentence under a page or section title — ever.
4. Look at the row and the column. Your text sets the height of every tile in its row and the width of every cell in its column. Fill a visible slot on all siblings, at similar length and in the same shape, or on none. Tooltips are hidden and per need — never add one to a sibling just to match.
5. Use the primitive that enforces the budget. components/official/kpi/KpiTile + KpiGrid for KPI rows (one-line hint, title tooltip). If the official primitive "cuts off" your text, your text is too long — shorten it; never hand-roll a component to escape the limit. A local component that renders unbounded secondary text is itself a finding.
6. A tooltip states only what you verified in the code or the data contract. Cannot prove the definition ("since midnight", "today's budget")? Write no tooltip — a wrong definition is worse than none.
7. Honesty is state, not prose. Unmeasured → — with the reason in the tooltip. Partial feature → the Coming Soon registry. Never "not yet reported by the backend", never "Backfill brings this up to 100%".
8. Text has three colours — never a fainter one. Content and actions text-foreground; labels, meta, menu group labels, placeholders text-muted-foreground; a disabled control text-disabled-foreground (its disabled prop paints it). Never /60, opacity-* on text, or text-gray-*: a label must look different from the action it names, in light AND dark (the 2026-10-14 "gray on gray on gray" menu). Table: the style guide's Colour section.
9. See it rendered, then check it. In matrx-frontend run pnpm check:interface-text --changed before committing; any other repo: node ../matrx-frontend/scripts/interface-text/check-interface-text.mjs --root=. --changed. Every NOVEL line on your diff is fixed before commit.

Rationalizations

From the 2026-09-30 baseline runs (evals.md) — each one produced a defect.

Excuse (verbatim)	Reality
"the shared tile cuts off long hints"	That is the budget working. Shorten the text; keep the primitive.
"swapping only this row would make one page look two ways… should be its own change"	Adopt the primitive for the whole page in this change; it is a few lines.
"the rule that every number names its window and item count"	The label (7d) names the window; a count fits a 60-char hint. A sentence is not required.
"Both are a screen lying." → adds a sentence	Honesty is — + tooltip, a badge, or a registry entry.
"in the same words the Platform Spend 'Saved by batching' headline uses"	Consistency means the same label, not the same paragraph copied to two pages.
(with the skill) tooltips added to all six tiles "so the row matches" — two invented "since midnight" / "today's budget"	Parity is for visible slots. An unverified definition is fabrication; leave the tooltip out.

Red flags — stop and re-read the card

• You are about to paste words from your commit message, FEATURE.md or a code comment into JSX.
• Your string contains a dot-separated or snake_case name, a backtick, "backend", "server", or "not yet".
• One sibling gets a hint and the others do not.
• You are writing a second sentence in a hint or description.
• You are choosing a local component over components/official/* because of text length.
• You are writing a tooltip definition you did not read in the code or the data contract.
• You are making text fainter with /NN, opacity-* or a hand-picked grey, or hand-styling a menu group label.

The sweep — Discover → Review → Fix → Confirm (Pattern Patrol P14)

Each phase is its own agent. Read only the file for the phase you were given:

Phase	Lane	Read
Discover — build units for a slice, classify each, propose the exact fix; the validator must pass	quick with sonnet (haiku mapped rules to verdicts without reading and cut rewrites mid-sentence — 2026-09-30)	discover.md
Review — accept or correct the classifications, find primitive-level fixes, batch the work, pick what goes to Arman	standard (opus — judgment over the classifications)	review.md
Fix — apply a reviewed batch in its files	quick (sonnet) for mechanical batches, standard otherwise	fix.md
Confirm — independent check of a fixed batch	standard (sonnet), never the fixer	confirm.md

The proof record and regression scenario for this skill is evals.md; the next editor reruns it.