command-code 1.24.0 → 1.26.0

package/dist/bundled/design/references/interaction.md

@@ -12,6 +12,7 @@ Interaction drives the behavior pass — consult these when each dimension comes
 
 - [button.md](button.md) — for correct button states and the full control system when auditing interactive elements
 - [motion.md](motion.md) — for correct transition timing and easing when specifying state-change animation
+- [accessibility.md](accessibility.md) — for the mechanics behind every behavior in this file: focus rings, tabindex and roving tabindex, focus trapping and restoration, APG keyboard patterns, form labels and error announcement, live regions, and hit-area math
 
 ---
 
@@ -85,6 +86,10 @@ On touch devices, controls need enough room for fingers, not cursors. Adjacent l
 
 If a feature only exists on hover, it does not exist for touch users.
 
+The floor is 24×24px, the working target is 44×44px for touch and 40×40px for desktop when density permits. A small visible control keeps its size and gets an expanded hit area from a pseudo-element on the wrapping label or button — never on the `<input>`, which does not render pseudo-elements reliably. Two interactive elements never have overlapping hit areas: if an expanded area would collide, I shrink it to the largest size that does not. Exact math, exceptions, and recipes: [accessibility.md](accessibility.md#hit-areas).
+
+I detect input mode rather than screen size — `pointer: coarse` for sizing, `hover: hover` for hover affordances — and add `touch-action: manipulation` so taps do not wait out the double-tap-zoom delay.
+
 ---
 
 ## Direction-Aware Controls
@@ -113,6 +118,8 @@ Labels stay visible. Placeholders show examples, not identity. Required fields a
 
 Every error answers what happened and how to recover. Blame is forbidden.
 
+I keep submit enabled until the request starts. A submit button disabled until the form is valid hides the very thing that must be fixed — I let the user submit, then focus the first invalid field, which is both the fix path and the announcement. Once the request starts, the button disables with a spinner and **keeps its original label**. Every field gets the right `type`, an `inputmode` that summons the right mobile keyboard, and an `autocomplete` token so password managers and one-time-code autofill work. I never block paste, and I never filter characters as the user types — I accept the input, trim it, and validate after. Markup and announcement mechanics: [accessibility.md](accessibility.md#forms).
+
 On mobile, I verify every `input`, `select`, and `textarea` uses a font-size of at least 16px. A sub-16px form element triggers iOS Safari auto-zoom on focus, shifting layout and forcing the user to pinch back — it breaks the interaction, not just the visuals. Fix guidance and the specificity gotcha: [responsive.md](responsive.md#ios-safari-input-zoom).
 
 ---

package/dist/bundled/design/references/layout.md

@@ -119,10 +119,67 @@ I avoid dead-perfect section endings on long pages. A hint of the next section k
 
 ---
 
+## Layout Mechanics
+
+**Group with space, not lines.** Three tools, in order of preference: negative space, then a background shape when a group must read as one unit, then a separator line — last, and only where space would cost too much (dense tables, long settings lists). The structural rule: **the gap between groups is at least 2× the gap within a group.** 8px inside, 16px+ between. Below that ratio the grouping reads as noise, and adding a line to compensate is treating the symptom.
+
+A line that has genuinely earned its place still keeps its voice down — thin, dim, and never sitting inside a wide gap. If the space is already doing the separating, the line is just repeating it louder.
+
+**Controls must not look like content.** An interactive element needs a background, a border, an underline, or a consistent control zone. A link styled exactly like the sentence around it is invisible. The inverse holds too: a static badge shaped like the buttons beside it collects dead clicks.
+
+**Shared edges.** I pick a small set of alignment edges and put everything on them. Every stray edge — an icon 2px off the text edge, a card padded differently from its neighbor — reads as noise even when nobody can name it. One spacing step expresses each level of subordination, and deeper nesting repeats the same step rather than inventing a new one.
+
+**Logical properties, not physical.** Direction-dependent position is written as leading/trailing so the layout mirrors under `dir="rtl"`:
+
+| Physical (avoid) | Logical (use) |
+|---|---|
+| `margin-left` | `margin-inline-start` |
+| `padding-right` | `padding-inline-end` |
+| `left: 0` | `inset-inline-start: 0` |
+| `text-align: left` | `text-align: start` |
+| `border-right` | `border-inline-end` |
+
+Physical properties are reserved for genuinely physical geometry: a device notch, a gesture direction. When an arrangement encodes progression — star ratings, step indicators, progress bars — the sequence mirrors too; flexbox and grid with logical properties do it automatically, hand-positioned elements do not.
+
+**Breathing room between targets.** Without an established density scale: `12px` between adjacent bordered or filled controls, `24px` around borderless text and icon buttons, `24px`+ between unrelated groups. Borderless controls need more because nothing marks where one target ends and the next begins — the space *is* the boundary. Compact professional tools may use less, as long as hit areas stay distinct and never overlap ([accessibility.md](accessibility.md#hit-areas)). I preserve an established, usable density rather than inflating controls to match a number.
+
+**Progressive disclosure needs an affordance.** Hiding complexity is good; hiding it with no cue is a trap. In a horizontal scroller, items are sized so the next one peeks `16–32px` past the edge — a row that ends exactly at the container edge looks complete, and nobody scrolls it. Collapsed sections get a control whose label states what is hidden ("Show 12 more results", not "More"). Clamped text shows an ellipsis *and* a way to expand.
+
+**Content bleeds, controls float.** Backgrounds, hero media, and scrollable lists extend to the viewport edges. Text and controls stay inside the layout margins and safe areas. Sticky chrome floats above the content layer; it does not dam it.
+
+```css
+/* Full-bleed media inside a constrained article */
+.article { display: grid; grid-template-columns: 1fr min(65ch, calc(100% - 48px)) 1fr; }
+.article > * { grid-column: 2; }
+.article > .full-bleed { grid-column: 1 / -1; }
+
+/* Floating chrome respects the notch */
+.fab {
+  position: fixed;
+  inset-inline-end: calc(16px + env(safe-area-inset-right));
+  bottom: calc(16px + env(safe-area-inset-bottom));
+}
+```
+
+**Breakpoints come from content.** I break where the layout actually stops fitting — where the sidebar squeezes content below its minimum measure, where the card grid drops below a usable column width — not at 768px because a preset says so. I collapse late: a layout that holds its expanded structure as long as it genuinely fits stays stable and familiar, and premature collapsing throws away space the user paid for. I test the smallest and largest supported sizes first, because those break first.
+
+**Plan for growth and clipping.** String expansion varies by language and by source-string length, so no universal percentage saves me. No fixed widths sized to English labels — `max-width` plus wrapping. No fixed heights on text containers — `min-height` if a floor is needed. Buttons size from their label via `padding-inline`, never a hardcoded width. And I never park a critical action where resizing, scrolling, or an expanding keyboard can clip it: primary actions live in the normal flow or in stable chrome with safe-area padding. If a modal's content scrolls, its action row does not.
+
+---
+
 ## Container Sense
 
 Components should know the space they live in. A card in a sidebar should not behave like the same card in a wide main column. Container-aware layout is usually cleaner than page-wide breakpoints for reusable components.
 
+```css
+/* The component adapts to its column */
+.card-list { container-type: inline-size; }
+@container (max-width: 400px) { .card { grid-template-columns: 1fr; } }
+
+/* A viewport query breaks the same card inside a narrow sidebar */
+@media (max-width: 768px) { .card { grid-template-columns: 1fr; } }
+```
+
 Viewport rules still matter for page shell decisions. Component composition belongs closer to the component.
 
 ---

package/dist/bundled/design/references/motion.md

@@ -131,6 +131,41 @@ If the reduced version loses meaning, the original motion was carrying too much
 - Full motion: Element slides in over 400ms
 - Reduced motion: Element fades in over 150ms (no translation)
 
+I write motion as **opt-in**, so the static version is the default and I am not chasing every animation with an override:
+
+```css
+.card { /* static styles */ }
+@media (prefers-reduced-motion: no-preference) {
+  .card { transition: transform 200ms ease-out; }
+}
+```
+
+In an existing codebase where opt-in is not feasible, the global kill switch uses `0.01ms` rather than `none`, so `transitionend` and `animationend` still fire and any JS waiting on them does not hang.
+
+The preference asks for less motion, not none. What it protects against is vestibular upset, not the interface answering the user:
+
+| Cut it | Swap it | Leave it alone |
+|---|---|---|
+| Parallax | Anything that slides, scales, or zooms → a plain opacity crossfade | Spinners and progress indicators |
+| Video, GIFs, and looping decoration that start themselves | Smooth scrolling → jump straight there | State that changes instantly: hover color, the focus ring |
+| Spinning, and anything travelling a long way across the screen | Carousels that rotate on their own → hand them over paused | The short confirmation that a press registered |
+
+Independent of the preference: anything moving, blinking, or updating on its own for more than 5 seconds needs a visible pause control. Every animation stays interruptible and driven by user input.
+
+---
+
+## Enter And Exit Mechanics
+
+For an infrequent staged entrance — a page hero, a success state, an empty state — I split the container into semantic chunks (title, description, action) and stagger them by ~100ms, combining `opacity`, a small `translateY`, and `blur`. Titles can go a level finer, word by word at ~80ms. I do not stagger routine, high-frequency interactions; the attention cost repeats on every trigger.
+
+Exits are softer than enters and run shorter — roughly 150ms against a 300ms entrance. A small fixed `translateY` (about `-12px`) indicates direction without drama; the full container height is theatre. When motion adds no information, or the interaction repeats often, removing the element immediately is the correct exit.
+
+I use CSS transitions for interactive state changes, because they can be interrupted mid-flight, and reserve keyframes for staged sequences that run once. I transition exact properties (`transition-property: opacity, scale`), never `all`. `will-change` is for `transform`, `opacity`, and `filter` only, added when I actually see first-frame stutter — never `will-change: all`.
+
+**Icon swaps** animate with `opacity`, `scale`, and `blur` rather than toggling visibility: scale `0.25` → `1`, opacity `0` → `1`, blur `4px` → `0`. With a motion library, `{ type: "spring", duration: 0.3, bounce: 0 }` — bounce stays `0`. Without one, both icons stay in the DOM (one absolutely positioned) and cross-fade with `cubic-bezier(0.2, 0, 0, 1)`, which gives enter and exit with no dependency.
+
+Nothing is communicated by movement alone. Anything I animate to mark a change also has to read as changed once it stops moving — through color, a glyph, or words.
+
 ---
 
 ## Timing Reference

package/dist/bundled/design/references/review.md

@@ -111,10 +111,12 @@ I do not inflate scores to be polite. Most real work lives in the middle.
 
 I do not leave the user with a pile of observations.
 
-I name the top improvements in order of impact and map each to the right Command Code design mode: recolor, typeset, relayout, interaction, writing, refine, finish, redesign, or create.
+I name the top improvements in order of impact and map each to the right Command Code design mode: recolor, typeset, relayout, interaction, a11y, writing, refine, finish, redesign, or create.
 
 If the fix is not a design-mode issue, I say that too.
 
+Recommendations use the severity scale, evidence bar, findings table, considered-but-rejected list, and verdict in [severity.md](severity.md). An escalation trigger from that file outranks every aesthetic finding in the report, regardless of what the lens scores say — a surface that scores well on all five lenses and cannot be operated with a keyboard is a `Block`.
+
 ---
 
 ## Report Boundary

package/dist/bundled/design/references/severity.md

@@ -0,0 +1,111 @@
+# Findings: severity, evidence, verdict
+
+Every report mode — `smell`, `checkup`, `review` — uses this scale, this evidence bar, and this verdict. Scores answer "how good is this?". Findings answer "what do I fix, in what order?". A report needs both.
+
+A finding the user cannot act on is an observation. This file turns observations into work.
+
+---
+
+## Severity
+
+One scale, three levels.
+
+**HIGH** — blocks a task, misleads the user, hides content or controls, risks data loss, or repeats as a systemic failure across the surface.
+
+**MEDIUM** — meaningfully harms comprehension, efficiency, adaptability, or consistency. The user gets there, but pays for it.
+
+**LOW** — isolated polish with limited task impact.
+
+Within a severity I rank by reach and leverage. A fix in a token or a shared component outranks the same symptom in one leaf component, because it fixes every instance at once.
+
+---
+
+## Escalation Triggers
+
+These are `HIGH` on sight. I do not average them down because the surface is minor, and I do not hold them back to keep a report short.
+
+- Something a user can operate that never says what it is
+- Something Tab can land on with nothing visible to show it landed
+- A path the mouse can walk and the keyboard cannot
+- Decorative or vestibular motion — parallax, self-starting video/GIFs, spinning, long-travel movement, autoplaying carousels — that runs regardless of `prefers-reduced-motion`
+- Anything cut off, buried, or out of reach once the window narrows to 320px or the text doubles
+- Text sitting on a background it does not have enough contrast against
+- A distinction the user can only make by seeing a hue
+- Something irreversible with no confirmation, no undo, and nothing marking it apart from a safe action
+- A field whose placeholder is doing the label's job
+
+Triggers rank above every other finding and are listed first. Mechanics and fixes: [accessibility.md](accessibility.md).
+
+These set the *cost* of a symptom, not whether it exists. The discipline reference still decides whether the symptom is present.
+
+---
+
+## Evidence
+
+Every finding cites `path/to/file:line` and shows the current implementation. When the artifact has no source files, I cite the exact screen and component instead.
+
+I do not report a code-level finding from appearance alone, or a visual finding from source alone when runtime behavior decides the result. If I could not check something, it is not a finding — it is a verification gap, and I say so.
+
+---
+
+## Findings Table
+
+Findings go in one table, ordered by severity, then by reach and leverage. Never as loose "Before:" / "After:" lines.
+
+| # | Severity | Discipline | Location | Before | After | Why |
+|---|---|---|---|---|---|---|
+| 1 | HIGH | Accessibility | `src/CommandBar.tsx:88` | `<div onClick={run}><PlayIcon /></div>` | Make it a `<button>`, name it `Run command`, hide the glyph from the tree | Nothing here is focusable, and nothing announces what it does |
+| 2 | HIGH | Color | `src/Badge.tsx:14` | Status shown as `bg-red-500` / `bg-green-500` only | Add an icon and a text label beside the fill | Meaning carried by color alone |
+| 3 | MEDIUM | Layout | `src/Toolbar.tsx:22` | Five icon buttons at `gap-1` | Raise to the project's `12px` step | Adjacent targets merge and get mis-tapped |
+
+**Discipline** is the reference that owns the rule: Accessibility, Color, Type, Layout, Motion, Interaction, Writing, Surface, Voice. One rule, one owner — when two references seem to cover an issue, it belongs to whichever owns the underlying rule, and the secondary effect goes in the **Why** cell. I report it once.
+
+---
+
+## Consolidate
+
+One root cause is one finding. Twelve components missing focus rings because a shared button strips the outline is one row with twelve locations, not twelve rows.
+
+I never pad a report to look thorough. A short findings list is a valid result, and so is an empty one.
+
+---
+
+## Considered but Rejected
+
+Every report includes 2–5 candidates I inspected and deliberately did not report. This is how the user can tell restraint from oversight.
+
+| Location | Candidate | Rejected because |
+|---|---|---|
+| `src/Card.tsx:28` | Increase the shadow | Depth already matches the shared surface token; changing one card would cost consistency |
+
+I drop a candidate when the discipline reference allows what is already there, when I could not gather enough evidence to be sure, when the project's way of doing it holds up on its own merits rather than merely being the way it has always been done, or when my proposed change would cost complexity and buy the user nothing.
+
+These are real candidates from this pass, not invented filler. If the surface genuinely had fewer borderline calls, I list the ones that exist and say so.
+
+---
+
+## Verification
+
+I list every check I ran, the exact command or interaction, and what I observed. Checks that passed and checks marked **Not verified** go in separate groups.
+
+A verification gap never becomes a finding, and never becomes a silent pass either.
+
+---
+
+## Verdict
+
+Every report ends with exactly one:
+
+- **Block** — at least one `HIGH` is still standing.
+- **Needs changes** — nothing `HIGH` left, but `MEDIUM` or `LOW` work is outstanding.
+- **Approve** — nothing left to act on, and I actually ran the checks I am claiming coverage from.
+
+I do not write "Approve" with pending actionable findings, and I do not write "Block" for polish.
+
+---
+
+## Report Modes Do Not Fix
+
+`smell`, `checkup`, and `review` produce findings only. The fix happens when the user runs `redesign`, `relayout`, `recolor`, `typeset`, `a11y`, `deslop`, `refine`, or `finish` — a separate, explicit command.
+
+The severity, the locations, and the **After** column are what those modes consume next. A finding written vaguely today becomes a fix nobody can apply tomorrow.

package/dist/bundled/design/references/shadow.md

@@ -94,6 +94,33 @@ Flat systems use borders and maybe a whisper of shadow. Layered systems use shad
 
 I choose the elevation strategy per project and stay with it.
 
+When a border on a button, card, or container exists **only to create depth**, a layered transparent shadow does the job better: it adapts to any background, where a solid border color only works on the background it was picked for. Three layers — a 1px ring, a subtle lift, and ambient depth:
+
+```css
+:root {
+  --shadow-border:
+    0 0 0 1px oklch(0 0 0 / 0.06),
+    0 1px 2px -1px oklch(0 0 0 / 0.06),
+    0 2px 4px 0 oklch(0 0 0 / 0.04);
+  --shadow-border-hover:
+    0 0 0 1px oklch(0 0 0 / 0.08),
+    0 1px 2px -1px oklch(0 0 0 / 0.08),
+    0 2px 4px 0 oklch(0 0 0 / 0.06);
+}
+```
+
+In dark mode this collapses to a single white ring — `0 0 0 1px oklch(1 0 0 / 0.08)`, hover `0.13` — because layered depth shadows are not visible on dark backgrounds.
+
+This never applies to borders whose job is separation: dividers, table cell boundaries, hairlines in dense UI, and input outlines stay borders.
+
+---
+
+## Image Outlines
+
+Images get a `1px` low-opacity outline so they sit in the same depth system as everything else. `outline` rather than `border` because it never affects layout, and `outline-offset: -1px` draws the ring just inside the image edge so it hugs the corner radius instead of floating outside it.
+
+The color is non-negotiable: **pure black in light mode** (`oklch(0 0 0 / 0.1)`), **pure white in dark mode** (`oklch(1 0 0 / 0.1)`). Never a near-black or tinted neutral from the palette — slate, zinc, `#111827`, `#f5f5f7` — and never the accent. A tinted outline picks up the surface color beneath it and reads as dirt on the image edge.
+
 ---
 
 ## Performance

package/dist/bundled/design/references/smell.md

@@ -153,6 +153,14 @@ The heuristics table in the report uses 10 rows (one per odor tracked). Each row
 
 ---
 
+## Finding Format
+
+Each confirmed tell gets a severity, a `path/to/file:line` location, and a concrete replacement, per [severity.md](severity.md). A repeated tell is one finding with every location listed, not one row per occurrence — the whole point of a smell is that it is systemic.
+
+Smell also carries the escalation triggers in that file. Generic patterns and access failures travel together: a placeholder-only label, an icon button with no name, and a `focus:outline-none` on a shared component are all AI reflexes, and all of them are `HIGH`.
+
+---
+
 ## Report Boundary
 
 Smell always produces two report artifacts:

package/dist/bundled/design/references/typeset.md

@@ -137,6 +137,36 @@ I test it with real content, not a perfect headline.
 
 ---
 
+## Type Mechanics
+
+The taste above decides what to do. This decides how to write it. I write every fix in the project's own styling system, never a second one alongside it.
+
+**Wrapping.** `text-wrap: balance` on headings, `text-wrap: pretty` on descriptions. Both, together, on a heading-plus-subtitle pair. Neither in long-form: browsers ignore `balance` past a few lines, and evening out a whole article wastes space and slows reading. `overflow-wrap: break-word` wherever a long word, URL, or ID could escape its container. `white-space: nowrap` on labels and badges where a break looks broken.
+
+**Measure.** 60–75 characters. `65ch` measures it directly, but a rem or pixel cap is equally valid — at a 16px body size the range lands roughly between 560px and 680px, so Tailwind's `max-w-xl` or `max-w-2xl` fit. What matters is that a cap exists and the rendered line length sits in range; I recheck it if the body size changes.
+
+**Line-height by role.** Headings near `1.1`, body `1.5`–`1.6`, always unitless so it scales with the font size — `line-height: 24px` does not. Tight leading is for short text: anything that wraps to three or more lines needs at least `1.4`, even in a height-constrained card.
+
+**Weight floors.** Below `18px`, stay at weight `400` or heavier. Weights under `300` are display-only at `28px`+; they disappear at text sizes. Long-form body starts near `16px`; UI text can go to `14px` for inputs and menus, `13px` for captions, rarely below `12px`.
+
+**Properties over raw tags.** `font-weight: 650`, not `font-variation-settings: "wght" 650`. `font-optical-sizing: auto`, not `"opsz"`. `font-variant-numeric: tabular-nums`, not `font-feature-settings: "tnum" 1`. Properties keep working when a non-variable fallback renders; raw settings silently do nothing. Raw tags are for custom axes (`"GRAD" 80`) and numbered slots (`"ss01"`) that have no property of their own.
+
+**Synthesis.** Browsers may fake a weight or style the family does not ship. I load the faces the design actually uses. `font-synthesis: none` goes on only after I have verified that every required bold, italic, small-cap, superscript, and subscript form stays visually distinct across the whole fallback stack — it is not a diagnostic, and it must never erase emphasis. If only one mode is unwanted, I use the longhand.
+
+**Truncation.** Single line is `text-overflow: ellipsis` with `overflow: hidden` and `white-space: nowrap`. Multiple lines is `line-clamp`. Truncation hides content, so if the missing text matters, the full value stays reachable in a tooltip or an expanded view.
+
+**Underlines.** Pull position and thickness from the font with `text-underline-position: from-font` and `text-decoration-thickness: from-font`, or tune with `text-underline-offset` and `text-decoration-skip-ink`. A dotted underline is the conventional hint that a word carries extra information. Color is the only part of a real underline that animates reliably — anything else, I build the underline as a separate element.
+
+**Punctuation.** Copy is stored in natural case and presented with `text-transform`, so a redesign never means rewriting strings. Curly quotes in prose and straight quotes in code. En dash for ranges (`2010–2020`). The single `…` character, not three periods. ` ` to keep `16 px` together, `­` to control where a long word may break. Em dashes stay out of generated UI copy for this project — see [writing.md](writing.md).
+
+**Rendering and language.** `-webkit-font-smoothing: antialiased` plus `-moz-osx-font-smoothing: grayscale` once at the root, never per component. `lang` set so the browser picks the right quotes, hyphenation, and pronunciation; `dir` set at the boundary where direction changes. Digit order never reverses in RTL — I wrap mixed-direction values in `<bdi>` rather than fighting the bidi algorithm. A paragraph of three or more lines aligns to its own script's direction; `text-align: start` with correct `lang`/`dir` handles it.
+
+**Selection stays on.** `user-select: none` belongs only on a specific draggable or gesture surface where accidental selection demonstrably breaks the interaction — never across application chrome because a button label can be highlighted.
+
+**Mobile inputs.** iOS Safari zooms the page when an input's text is under `16px`. Two fixes hold the size differently, so I ask which the design wants rather than choosing silently: size the input up on small screens (`text-base sm:text-sm`), which changes how it looks, or keep `font-size: 16px` and render the intended size with `transform: scale()`, compensating width and line-height so the design is identical everywhere. Details: [responsive.md](responsive.md#ios-safari-input-zoom).
+
+---
+
 ## What I Refuse
 
 - Choosing the first trendy family that fits the category

package/dist/bundled/design/references/writing.md

@@ -94,6 +94,26 @@ Icon-only controls need accessible names. Link text stands alone. Alt text descr
 
 ---
 
+## Settings And Toggles
+
+A toggle is labeled for what happens when it is **on**: "Send read receipts". The user infers the off state. Labeling the negative ("Don't send read receipts") turns every interaction into a double negative.
+
+When copy refers to another setting, I link straight to it. A "Notification settings" link beats "Go to Settings > Notifications > Email", which goes stale the moment the navigation changes.
+
+---
+
+## Links And Flow Vocabulary
+
+Link text has to make sense out of context, because screen-reader users navigate by a list of the page's links. "Read the billing docs", never "Click here" — which also assumes a mouse. A bare "Learn more" fails the moment two of them appear on one page; each gets a suffix: "Learn more about exports".
+
+A multi-step flow uses one vocabulary throughout: one word to enter, one word to advance — "Continue" or "Next", picked once and kept — and one word to finish. Alternating synonyms across steps makes users wonder whether the buttons do different things.
+
+A confirmation's buttons restate what is about to happen, so the user can answer the dialog from the buttons alone without parsing the paragraph above them. "Delete this project?" is answered with **Delete project** and **Cancel** — never Yes and No, which force the user back up to the question to work out which one is which.
+
+I address the reader as "you", not "the user". In errors I avoid "we", which reads as deflection: "Unable to load content" beats "We're having trouble loading this content".
+
+---
+
 ## Voice And Tone
 
 Voice stays consistent. Tone adapts to the moment.
@@ -110,6 +130,8 @@ I leave room for expansion. German and Finnish get longer. Chinese may use fewer
 
 I keep full sentences as translation units. I avoid string fragments that assume English grammar. I avoid abbreviations when clarity matters.
 
+I never build a sentence by concatenating fragments around a variable — `"You have " + n + " new messages"` assumes English word order and English plural rules, and breaks in most other languages. Full templated strings with proper pluralization instead. I also skip idioms, colloquialisms, and humor that will not survive translation, and I match the verb to the input device: "tap" on touch, "click" with a pointer, "select" when both are possible.
+
 ---
 
 ## Punctuation