@hegemonart/get-design-done 1.27.7 → 1.28.0

package/reference/i18n.md

@@ -0,0 +1,554 @@
+---
+name: i18n
+type: heuristic
+version: 1.0.0
+phase: 28
+tags: [i18n, intl, icu, unicode, rtl, multi-script, wcag-i18n]
+last_updated: 2026-05-18
+---
+
+# i18n — Internationalization Engineering Primitives
+
+This file closes a gap: the existing references touch internationalization in fragments — [rtl-cjk-cultural.md](./rtl-cjk-cultural.md) covers cultural context (greeting forms, color symbolism, CJK family-name order), [typography.md](./typography.md) covers font-family stacks, [accessibility.md](./accessibility.md) cites WCAG 3.1.1, [form-patterns.md](./form-patterns.md) cites locale-aware autofill — but none stitch the engineering primitives together. This is the file an agent should consult any time it is writing code that will render a localized string, format a number or date, mirror a layout, truncate user text, or audit a UI for i18n readiness.
+
+The boundary is strict and additive. `rtl-cjk-cultural.md` owns the *cultural* layer — what gestures and color associations mean in a region, when a name field should accept both family-name-first and given-name-first orders, why a thumbs-up icon is unsafe in parts of the Middle East. This file owns the *code* layer — which CSS property to author, which `Intl.*` API to call, which Unicode normalization form to apply on input, which regex catches a hardcoded English string in a JSX file. Both files are needed; neither replaces the other.
+
+## Text Expansion
+
+Localized strings expand or contract depending on the target language. A button label that fits in a 96px container in English will overflow at +30% in German, +40% in Russian, and clip cleanly in Japanese. Design must absorb this variation — either by sizing containers for the worst-case expansion, by allowing wrapping, or by truncating with grapheme-aware logic. The factors below are conservative aggregates suitable for layout-budget planning and for the verifier overflow-simulation probe documented further down this file.
+
+| Locale family       | Expansion | Notes                          |
+| ------------------- | --------- | ------------------------------ |
+| EN (baseline)       |    0%     | reference                      |
+| DE, FR              |   +30%    | medium-long compounds          |
+| RU, FI, PL          |   +40%    | morphology + diacritics        |
+| NL, SV              |   +25%    | similar to DE/FR magnitude     |
+| ES, IT, PT          |   +25%    | romance-language drift         |
+| JA, ZH, KO          |   −50%    | ideographic density            |
+| AR (RTL)            |   +25%    | RTL + tall script line-height  |
+
+These factors drive width constraints in component design and the verifier overflow-simulation probe (§Verifier Integration Spec below). A container that holds `EN base × 1.4` for any string is safe against the worst row of this table (RU at +40%) and remains the standard layout-budget rule. Treat the table as the contract between designer and engineer for any new component touching localizable text.
+
+## RTL Mirroring
+
+Right-to-left scripts — Arabic, Hebrew, Persian, Urdu — do not merely reverse text direction; they reverse the entire spatial logic of the interface. The reading eye enters from the right, "start" becomes the right edge, "end" becomes the left, and every directional affordance must be reconsidered. The engineering rule is to author all spatial CSS in *logical* properties so a single `dir="rtl"` flip on the document root produces a fully mirrored UI with zero per-element overrides.
+
+### CSS logical properties
+
+Logical properties resolve relative to the writing direction. They replace physical-direction properties one-for-one and are the only spatial CSS that an i18n-ready codebase should author. The mapping below is the working catalog; reach for the logical form by default and only use the physical form when the property is genuinely orientation-locked (e.g., a scrollbar position).
+
+| Physical (avoid)            | Logical (prefer)              | Notes                              |
+| --------------------------- | ----------------------------- | ---------------------------------- |
+| `margin-left`               | `margin-inline-start`         | mirrors with `dir`                 |
+| `margin-right`              | `margin-inline-end`           | mirrors with `dir`                 |
+| `padding-left`              | `padding-inline-start`        | mirrors with `dir`                 |
+| `padding-right`             | `padding-inline-end`          | mirrors with `dir`                 |
+| `border-top-left-radius`    | `border-start-start-radius`   | block-start × inline-start corner  |
+| `border-bottom-right-radius`| `border-end-end-radius`       | block-end × inline-end corner      |
+| `left: 0` (positioned)      | `inset-inline-start: 0`       | absolute / fixed offsets           |
+| `right: 0`                  | `inset-inline-end: 0`         | absolute / fixed offsets           |
+| `text-align: left`          | `text-align: start`           | aligns with reading direction      |
+| `text-align: right`         | `text-align: end`             | aligns with reading direction      |
+
+A concrete card component authored entirely in logical props:
+
+```css
+.card {
+  padding-inline: 1rem;
+  padding-block: 0.75rem;
+  border-start-start-radius: 8px;
+  border-end-end-radius: 8px;
+  margin-inline-end: 1.5rem;
+  border-inline-start: 4px solid var(--accent);
+}
+
+.card .badge {
+  position: absolute;
+  inset-block-start: 0.5rem;
+  inset-inline-end: 0.5rem;
+}
+```
+
+Under `dir="ltr"` the accent border lands on the left edge and the badge floats top-right. Under `dir="rtl"` the same CSS produces an accent border on the right edge and a badge that floats top-left — no media query, no override, no separate stylesheet.
+
+### `dir="rtl"` cascade rules
+
+The `dir` attribute on `<html>` propagates directionality through every descendant. Set it once at the document root from the user's locale, never per element to work around a missing logical property. If the product serves both directions from one codebase, control `dir` at runtime based on `Intl.Locale(userLocale).textInfo.direction`:
+
+```html
+<!-- Set once at the root, controls the entire subtree -->
+<html lang="ar" dir="rtl">
+  <body>
+    <nav class="sidebar">...</nav>
+    <main>...</main>
+  </body>
+</html>
+```
+
+Per-element `dir` is reserved for genuinely mixed-direction content (a username inside an Arabic sentence; see §Bidi isolation).
+
+### Directional-icon flip catalog
+
+Not every icon should mirror under RTL. The rule is intent: if the icon means "next in reading order" or "back in reading order", it mirrors; if it means "play this video" or "this is a brand mark" or "this is the digit four", it does not. The catalog below is the working contract — apply `transform: scaleX(-1)` (via a `[dir="rtl"] .icon-directional { ... }` rule) for the flip-yes rows; leave the rest untouched.
+
+| Icon                          | Flip in RTL? | Rationale                                          |
+| ----------------------------- | ------------ | -------------------------------------------------- |
+| Chevron next / back           | yes          | reading-order directional                          |
+| Arrow forward / arrow back    | yes          | reading-order directional                          |
+| Breadcrumb separator chevrons | yes          | reading-order directional                          |
+| Progress-bar fill direction   | yes          | progression in reading order                       |
+| Send / reply arrow            | yes          | implies outbound direction in reading order        |
+| Search (magnifier glass)      | no           | universal — handle angle is convention not flow    |
+| Brand logos, wordmarks        | no           | brand asset is fixed                               |
+| Numerals (0–9)                | no           | digits render LTR even inside Arabic text          |
+| Media controls play / pause   | no           | bound to a physical timeline, not reading order    |
+| Close (×), settings gear      | no           | non-directional symbol                             |
+| Star, heart, like             | no           | non-directional symbol                             |
+| Compass / map north           | no           | geographic orientation is universal                |
+
+### Bidi isolation
+
+When a string mixes scripts of different directions — an Arabic UI showing an English username, a French sentence quoting a Hebrew title — the Unicode Bidirectional Algorithm needs a hint to keep punctuation and adjacent content from leaking direction across the embed. Three tools handle this:
+
+- `<bdi>` — bidi isolate; wraps user-provided runs whose direction is unknown.
+- `dir="auto"` — first-strong heuristic; useful on user-input fields whose locale is unknown until typed.
+- `unicode-bidi: isolate` — CSS equivalent of `<bdi>`; isolates a span without a semantic element.
+
+A mixed-direction example: a comment list rendering an Arabic sentence that quotes an English handle:
+
+```html
+<p lang="ar" dir="rtl">
+  أعجبني المنشور من
+  <bdi>@user_42</bdi>
+  وأضفت تعليقاً.
+</p>
+
+<style>
+  /* If a `<bdi>` element isn't semantic for the case, use the CSS form */
+  .username {
+    unicode-bidi: isolate;
+    direction: ltr;
+  }
+</style>
+```
+
+Without `<bdi>` the trailing `42` digit pair can adopt the surrounding RTL direction and render reversed — a class of bug that is almost invisible in QA but jarring to native readers. Wrap any user-controlled identifier in `<bdi>` by default.
+
+## Locale Formatting
+
+Hand-rolled string concatenation for dates, numbers, lists, and plurals breaks at the locale boundary. The `Intl.*` family is the canonical replacement — every modern engine ships it, every example below is one call away from being correct in 150+ locales. The rule is unambiguous: never build a localized string by interpolation; always pass through an `Intl.*` formatter parameterized on the user's BCP 47 locale tag.
+
+### Intl.DateTimeFormat
+
+`Intl.DateTimeFormat` replaces `Date.toLocaleString` patterns and hand-formatted `YYYY-MM-DD` templates. It composes a date and time according to locale conventions — day/month ordering, separator characters, 12- vs 24-hour clocks, calendar systems, and time-zone naming.
+
+```js
+const event = new Date('2026-05-18T14:30:00Z');
+
+const enUS = new Intl.DateTimeFormat('en-US', {
+  dateStyle: 'medium',
+  timeStyle: 'short',
+  timeZone: 'America/New_York',
+});
+enUS.format(event); // "May 18, 2026, 10:30 AM"
+
+const deDE = new Intl.DateTimeFormat('de-DE', {
+  dateStyle: 'medium',
+  timeStyle: 'short',
+});
+deDE.format(event); // "18.05.2026, 16:30"
+
+const arEG = new Intl.DateTimeFormat('ar-EG', {
+  dateStyle: 'full',
+});
+arEG.format(event); // "الاثنين، 18 مايو 2026"
+```
+
+### Intl.NumberFormat
+
+Three modes cover the dominant cases: `currency` for prices, `percent` for ratios, `unit` for physical quantities. The formatter knows the locale-correct decimal separator, grouping character, currency symbol position, and unit spelling.
+
+```js
+// currency mode
+new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(1234.5);
+// → "$1,234.50"
+new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' }).format(1234.5);
+// → "1.234,50 €"
+
+// percent mode
+new Intl.NumberFormat('en-US', { style: 'percent', maximumFractionDigits: 1 }).format(0.087);
+// → "8.7%"
+
+// unit mode
+new Intl.NumberFormat('en-US', { style: 'unit', unit: 'kilometer-per-hour' }).format(72);
+// → "72 km/h"
+new Intl.NumberFormat('ja-JP', { style: 'unit', unit: 'kilometer-per-hour' }).format(72);
+// → "時速 72 キロメートル"
+```
+
+### Intl.PluralRules
+
+Pluralization is not "1 vs many". Arabic has six categories (`zero`, `one`, `two`, `few`, `many`, `other`); Russian has four; Welsh has six. A ternary `count === 1 ? 'item' : 'items'` is wrong in nearly every non-English locale. `Intl.PluralRules` resolves the count to a category which is then looked up in a translation table — usually via an ICU MessageFormat string (next section), but available standalone.
+
+```js
+const ruPlural = new Intl.PluralRules('ru');
+ruPlural.select(1);  // → "one"
+ruPlural.select(2);  // → "few"
+ruPlural.select(5);  // → "many"
+ruPlural.select(21); // → "one"   — yes, twenty-one is "one" in Russian
+ruPlural.select(22); // → "few"
+
+const enPlural = new Intl.PluralRules('en');
+enPlural.select(1);  // → "one"
+enPlural.select(2);  // → "other"
+```
+
+### Intl.RelativeTimeFormat
+
+`"3 days ago"`, `"in 2 hours"`, `"yesterday"` — relative-time phrases are wildly different across locales and tense systems. `Intl.RelativeTimeFormat` returns the locale-correct phrase given a number and a unit.
+
+```js
+const enRel = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });
+enRel.format(-1, 'day');  // → "yesterday"
+enRel.format(-3, 'day');  // → "3 days ago"
+enRel.format(2, 'hour');  // → "in 2 hours"
+
+const jaRel = new Intl.RelativeTimeFormat('ja', { numeric: 'auto' });
+jaRel.format(-1, 'day');  // → "昨日"
+jaRel.format(-3, 'day');  // → "3 日前"
+```
+
+### Intl.ListFormat
+
+Joining a list of items into a sentence — `"A, B, and C"` — has locale-specific rules: serial comma usage, conjunction word, segment separator. `Intl.ListFormat` covers both conjunction (`and`) and disjunction (`or`) modes.
+
+```js
+const tags = ['React', 'Vue', 'Svelte'];
+
+new Intl.ListFormat('en', { style: 'long', type: 'conjunction' }).format(tags);
+// → "React, Vue, and Svelte"
+new Intl.ListFormat('en', { style: 'long', type: 'disjunction' }).format(tags);
+// → "React, Vue, or Svelte"
+new Intl.ListFormat('de', { style: 'long', type: 'conjunction' }).format(tags);
+// → "React, Vue und Svelte"
+```
+
+### Intl.Collator
+
+`Array.prototype.sort` on strings uses Unicode code-point order — which produces wrong results outside ASCII (`'Ö'` sorts after `'Z'` instead of with `'O'` in Swedish; `'é'` sorts after `'z'` in French). `Intl.Collator` provides locale-aware sorting and is the only correct choice for any user-facing sorted list.
+
+```js
+const names = ['Zebra', 'Élan', 'Ödipus', 'Apple'];
+
+names.slice().sort(); // raw — wrong
+// → ["Apple", "Zebra", "Élan", "Ödipus"]
+
+const svCollator = new Intl.Collator('sv');
+names.slice().sort(svCollator.compare);
+// → ["Apple", "Élan", "Zebra", "Ödipus"]   — Swedish: Ö is its own letter, sorts after Z
+
+const deCollator = new Intl.Collator('de');
+names.slice().sort(deCollator.compare);
+// → ["Apple", "Élan", "Ödipus", "Zebra"]   — German: Ö collates near O
+```
+
+### Intl.Segmenter
+
+`Intl.Segmenter` produces grapheme-cluster, word, or sentence segments according to the Unicode segmentation algorithm. The grapheme-cluster mode is the *only* correct way to count or truncate user text. JavaScript `string.length` counts UTF-16 code units, not graphemes — a family-style ZWJ sequence such as `U+1F468 U+200D U+1F469 U+200D U+1F467` (Man + ZWJ + Woman + ZWJ + Girl) reports as length 5 or 7 depending on the engine, and `string.slice(0, 10)` will split an emoji or combining character mid-sequence, producing a string that renders as a broken-glyph diamond.
+
+```js
+// HARD RULE: never `string.slice(0, n)` for unknown text
+// const truncated = name.slice(0, 20);   // ✗ may split a grapheme
+
+const seg = new Intl.Segmenter('en', { granularity: 'grapheme' });
+function truncateGraphemes(input, max) {
+  const out = [];
+  for (const { segment } of seg.segment(input)) {
+    if (out.length >= max) break;
+    out.push(segment);
+  }
+  return out.join('');
+}
+
+truncateGraphemes('café 🇫🇷👨‍👩‍👧 résumé', 6); // → "café 🇫🇷"
+```
+
+## ICU MessageFormat
+
+ICU MessageFormat is the canonical input format for the dominant i18n library matrix — `react-intl`, `formatjs`, `lingui`, `next-intl`, `i18next` all parse it natively. It is a small DSL with three constructs that matter — `plural`, `select`, `selectordinal` — each of which encodes a branch that string concatenation cannot.
+
+```txt
+{count, plural,
+  =0 {No items}
+  one {# item}
+  few {# items}
+  many {# items}
+  other {# items}
+}
+```
+
+```txt
+{gender, select,
+  female {She invited you}
+  male {He invited you}
+  other {They invited you}
+}
+```
+
+```txt
+{place, selectordinal,
+  one {You finished #st}
+  two {You finished #nd}
+  few {You finished #rd}
+  other {You finished #th}
+}
+```
+
+Why ICU beats string concatenation: pluralization rules vary by locale (Russian has four categories — `one`, `few`, `many`, `other`; Welsh has six — `zero`, `one`, `two`, `few`, `many`, `other`), gendered forms vary (Slavic and Semitic languages branch verb forms on subject gender), and ordinal suffixes differ (English `1st 2nd 3rd 4th`; many languages use a single suffix). Concatenation hardcodes English assumptions; ICU encodes the branch as data, and the runtime picks the correct branch per locale.
+
+The library bridge is direct: `react-intl` consumes ICU via `<FormattedMessage>` props, `formatjs` provides the underlying formatter, `lingui` ships its own ICU-compatible parser, `next-intl` accepts ICU strings as namespace values, and `i18next` supports ICU via the `i18next-icu` plugin. Pick the framework's idiom; the input syntax is the same.
+
+## Unicode Hygiene
+
+Five rules below are non-negotiable for any code path that touches user text — input, storage, comparison, display, or truncation. Skipping them produces bugs that surface in production months after the code ships, when a user with a non-ASCII name discovers their record cannot be found or their display name renders as boxes.
+
+### NFC normalization on input
+
+The same visible character can be encoded as a single precomposed code point (`é` = `U+00E9`) or as a base character plus a combining mark (`e` + `U+0301`). Two strings that look identical may compare as not-equal, hash to different keys, and fail length comparisons. Normalize all input to NFC at the boundary — the moment text enters the application, before storage, before comparison.
+
+```js
+const a = 'é';                       // U+00E9
+const b = 'é';                 // U+0065 U+0301
+a === b;                              // false
+a.normalize('NFC') === b.normalize('NFC'); // true
+
+// Apply at input boundaries:
+input.addEventListener('blur', (e) => {
+  e.target.value = e.target.value.normalize('NFC');
+});
+```
+
+### Grapheme-aware truncation
+
+Restating from §Intl.Segmenter as a hard rule: **never `string.slice(0, n)` for unknown text**. Code-point and code-unit slicing splits emojis, combining marks, and ZWJ sequences. Use `Intl.Segmenter` with `granularity: 'grapheme'` for any truncation operation on user-controlled input. See the `truncateGraphemes` helper in §Intl.Segmenter.
+
+### BCP 47 language tag structure
+
+Locale identifiers in code are BCP 47 tags. The structure is `language[-Script][-Region][-Variant]` with case rules: language lowercase, script title-case, region uppercase. `pt-BR` is correct; `pt_br`, `PT-br`, and `pt_BR` are all wrong and will produce silent failures in `Intl.*` (or worse, partial matches that miss region-specific formatting). Use hyphens, never underscores. Normalize on input via `new Intl.Locale(tag).toString()`.
+
+```js
+new Intl.Locale('pt-br').toString();   // → "pt-BR"  (canonicalized)
+new Intl.Locale('zh-hant-tw').toString(); // → "zh-Hant-TW"
+```
+
+### RTL detection from Intl.Locale
+
+Never maintain a hardcoded `RTL_LOCALES` regex. The platform exposes the directional metadata directly:
+
+```js
+new Intl.Locale('ar').textInfo.direction;  // → "rtl"
+new Intl.Locale('he').textInfo.direction;  // → "rtl"
+new Intl.Locale('fa').textInfo.direction;  // → "rtl"
+new Intl.Locale('en').textInfo.direction;  // → "ltr"
+
+// Apply at the document root:
+document.documentElement.dir = new Intl.Locale(userLocale).textInfo.direction;
+```
+
+### Browser-support drift
+
+`Intl.Segmenter` shipped late on Safari (March 2023, version 16.4). Projects targeting older Safari, embedded WebViews on older iOS, or pre-2023 Node versions need a polyfill — `intl-segmenter-polyfill` or the underlying ICU library exposed via WebAssembly. Check current support at [caniuse.com/?search=Intl.Segmenter](https://caniuse.com/?search=Intl.Segmenter) before relying on grapheme-aware truncation in a hot path; for the rest of `Intl.*` the support has been universal since 2020.
+
+## Multi-Script Font Stacks
+
+A multi-script product (any product shipping outside a single Latin-script locale) cannot rely on one font family. Latin-only fonts are missing CJK ideographs, Arabic shapes, Devanagari conjuncts, and Cyrillic accents. The browser falls back to a system font when a glyph is missing, and the result is a visible style mismatch — a paragraph that switches typeface mid-sentence. The fix is an explicit per-script fallback stack, chosen so each script has a high-quality font available before the system fallback fires.
+
+### CJK fallbacks
+
+The Noto Sans CJK family is the open-source default; on macOS/iOS the platform fonts (Hiragino Sans, Apple SD Gothic Neo) render better and load instantly; on Windows the bundled font (Microsoft YaHei for Simplified Chinese) is the right local fallback. The stack composes from most-specific (region-locked) to most-generic.
+
+```css
+:root {
+  --font-cjk-ja: "Hiragino Sans", "Noto Sans CJK JP", "Yu Gothic", sans-serif;
+  --font-cjk-sc: "Microsoft YaHei", "Noto Sans CJK SC", "PingFang SC", sans-serif;
+  --font-cjk-tc: "PingFang TC", "Noto Sans CJK TC", "Microsoft JhengHei", sans-serif;
+  --font-cjk-ko: "Apple SD Gothic Neo", "Noto Sans CJK KR", "Malgun Gothic", sans-serif;
+}
+
+:lang(ja) { font-family: var(--font-cjk-ja); }
+:lang(zh-Hans) { font-family: var(--font-cjk-sc); }
+:lang(zh-Hant) { font-family: var(--font-cjk-tc); }
+:lang(ko) { font-family: var(--font-cjk-ko); }
+```
+
+### Arabic fallbacks
+
+Arabic text demands cursive shaping (initial / medial / final / isolated glyph forms) and tall line metrics. Noto Naskh Arabic is the standard naskh choice; Cairo is a contemporary sans alternative with strong UI rendering.
+
+```css
+:lang(ar) {
+  font-family: "Noto Naskh Arabic", "Cairo", "Geeza Pro", "Segoe UI", sans-serif;
+  line-height: 1.7; /* Arabic needs more vertical room than Latin */
+}
+```
+
+### Devanagari fallbacks
+
+Devanagari (Hindi, Marathi, Sanskrit) requires conjunct shaping and proper combining-mark positioning. Noto Sans Devanagari is the open-source default.
+
+```css
+:lang(hi),
+:lang(mr) {
+  font-family: "Noto Sans Devanagari", "Mangal", "Kohinoor Devanagari", sans-serif;
+}
+```
+
+### `font-display: swap` and FOUC across scripts
+
+`font-display: swap` shows the fallback immediately and swaps to the web font once loaded — the trade is a Flash of Unstyled Text (FOUT) instead of a Flash of Invisible Text (FOIT). Across scripts the FOUT problem is more severe: the system fallback for a CJK glyph may have radically different proportions from the loaded web font, so the swap moment causes a noticeable layout shift. Mitigations: preload the most-likely script subset for the user's locale, set `size-adjust` on the `@font-face` to match the fallback metrics, and accept FOIT (`font-display: block`) on the smallest critical-text subset where shift is unacceptable. See [variable-fonts-loading.md](./variable-fonts-loading.md) §font-display Values for the complete tradeoff.
+
+### Subset strategy via `unicode-range`
+
+Shipping the full Noto Sans CJK is a 5–15MB asset. Browsers will only fetch a subset if the `@font-face` declares one via `unicode-range`, so split into per-script files and let the browser fetch only the ranges the page uses.
+
+```css
+/* Latin subset — fetched for any page */
+@font-face {
+  font-family: "Inter";
+  src: url("/fonts/inter-latin.woff2") format("woff2");
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+  font-display: swap;
+}
+
+/* CJK Unified Ideographs subset — only fetched when page renders these code points */
+@font-face {
+  font-family: "Noto Sans JP";
+  src: url("/fonts/noto-sans-jp-cjk-unified.woff2") format("woff2");
+  unicode-range: U+4E00-9FFF;
+  font-display: swap;
+}
+```
+
+### Variable-font interaction
+
+For a single-script product, one variable font with `wght`, `ital`, and `opsz` axes is the byte-budget win — one file, all weights, all styles. For a multi-script product the calculus reverses: shipping `script-count × axis-count` axes in a single variable file balloons the asset, and very few variable fonts cover CJK or Arabic at all (the glyph count multiplies the axis storage). For multi-script products, prefer multiple weighted-static fonts per script, each subset via `unicode-range`, over one mega-variable file. The full tradeoff is in [variable-fonts-loading.md](./variable-fonts-loading.md) §Variable Font Axes; this is the cross-link that downstream agents should follow when the project's `package.json` shows both CJK and Latin scripts in active use.
+
+## WCAG i18n
+
+Two WCAG success criteria are the i18n contract a designer-engineer agent must enforce. Both are Level A (the lowest threshold) and both are commonly missed by codebases that otherwise pass contrast and target-size audits.
+
+### 3.1.1 — `lang` attribute on root
+
+Every page must declare its primary language on `<html>`. Screen readers select the correct phoneme inventory and prosody rules from this attribute; without it the reader falls back to its default voice (often US English), producing accented mispronunciation of every word.
+
+```html
+<!doctype html>
+<html lang="ja">
+  <head>...</head>
+  <body>...</body>
+</html>
+```
+
+### 3.1.2 — Language-of-parts
+
+When the page's primary language is set on `<html>` but a span of text is in a different language — a French quote inside an English article, an Arabic title rendered inside an English page — the foreign span needs its own `lang` attribute. The screen reader switches voice for that span and switches back at its close.
+
+```html
+<p>
+  The original report, titled
+  <span lang="fr">Le développement durable</span>,
+  was published in 1987.
+</p>
+```
+
+The auditor catches a missed 3.1.2 by scanning for untranslated quotes, proper nouns in a non-root script, and any code-switching pattern in body copy. Common failure: a marketing page in English embeds a customer-quote in Japanese with no `lang="ja"` wrapper, producing US-English phonemes applied to Japanese romaji — an outcome unintelligible to a screen-reader user. The fix is one attribute per foreign span.
+
+## Verifier Integration Spec
+
+This section specifies two probes for [agents/design-verifier.md](../agents/design-verifier.md). 28-06 implements; this file owns the spec. Both probes attach to a new `### i18n probes` subsection at the end of Phase 1 — Re-Audit + Category Scoring (after the existing `### Category Scores` subsection), and both classify findings under the orthogonal lens-tag `i18n_readiness` (per D-03 / D-07 — no new pillar, no audit-format change).
+
+### Probe 1: Hardcoded-string scan
+
+The probe scans component source files for hardcoded user-facing strings that bypass the i18n framework. The regex catalog matches the four library patterns from D-10 — these are the *expected* call shapes; anything that *resembles* a user-facing string but does *not* match one of these patterns is a candidate finding.
+
+```txt
+react-intl:  <FormattedMessage\s+id="[^"]+"
+next-intl:   \bt\(\s*['"][a-zA-Z][\w.]*['"]
+i18next:     \bt\(\s*['"][a-zA-Z][\w.]*['"]\s*,\s*\{
+vue-i18n:    \$t\(\s*['"][a-zA-Z][\w.]*['"]
+```
+
+Allow-list seed (per D-10) prevents day-1 false-positive flood by exempting strings that never reach the UI:
+
+```txt
+console\.(log|error|warn|info|debug)        — dev logging
+^\s*/\*.*\*/\s*$                            — dev-only block comments
+data-testid="[^"]+"                         — test selectors
+className="[^"]+"                           — CSS class names
+import\s+.*\s+from\s+['"][^'"]+['"]         — import paths
+```
+
+Finding classification: tagged `i18n_readiness`. Default severity `MINOR`; raised to `MAJOR` if the file count of unique violating files exceeds 10 (the codebase has a systemic problem, not a one-off oversight). Output line in the verifier report: `i18n_readiness: <N> hardcoded strings in <M> files — see ./i18n.md §ICU MessageFormat`.
+
+Reflector hook (D-10): the probe records false-positive count over the first N audit runs. If the false-positive rate exceeds the threshold defined in the Phase 11 self-improvement loop, the reflector proposes a tightened regex or an extended allow-list — the same pattern Phase 11 uses for self-improvement of other heuristics.
+
+### Probe 2: +40% Text-overflow simulation
+
+The probe simulates the worst-case row of the §Text Expansion table — RU/FI/PL at +40% — by inflating every text node in the rendered DOM and measuring whether containers overflow. The pseudo-code spec below is the integration contract; 28-06 may implement via either DOM measurement or Preview-MCP screenshot diff, whichever is available in the run context.
+
+```txt
+FOR every text node T in rendered DOM:
+  original    := T.textContent
+  expanded    := original repeated/padded until length(expanded) = length(original) × 1.4
+  T.textContent := expanded
+  measure: T.parentElement.scrollWidth > T.parentElement.clientWidth?
+    YES → finding(selector(T.parentElement), original, "overflows at +40%")
+  T.textContent := original   // restore
+```
+
+Implementation note for 28-06: prefer Preview MCP screenshot-diff if the run has a Preview client attached (catches overflow + clipping + ellipsis + wrapping changes in one pass); fall back to in-process DOM measurement (`scrollWidth > clientWidth`) when running headless or without Preview. Either way, classify findings under `i18n_readiness`, severity `MINOR` per finding (raised to `MAJOR` if more than 10 components overflow).
+
+Output line in the verifier report: `i18n_readiness: <N> components overflow at +40% text expansion — widen containers or allow text wrap`.
+
+## Explore Integration Spec
+
+This section specifies one probe for [skills/explore/SKILL.md](../skills/explore/SKILL.md). 28-06 implements; this file owns the spec. The probe attaches as a sub-step "**i18n readiness probe**" inside Step 2 — Inventory scan (before the close of Step 2), and produces one informational line in the standard explore report.
+
+### Probe: i18n-readiness (3-state, informational)
+
+3-state classification logic (per D-04 / D-11):
+
+```txt
+1. Read package.json (dependencies + devDependencies).
+
+2. Check against library matrix:
+     react-intl, next-intl, i18next, vue-i18n, formatjs, lingui
+   ≥1 library found in deps or devDeps → state = "framework-managed"
+                                          → STOP, emit line, exit probe.
+
+3. Else (no library):
+     grep -RE "Intl\.(DateTimeFormat|NumberFormat|PluralRules|RelativeTimeFormat|ListFormat|Collator|Segmenter)" src/
+   ≥1 match → state = "partial"
+              → emit line, exit probe.
+
+4. Else: state = "none"
+         → emit line, exit probe.
+```
+
+Output line in explore report (single informational line, per D-04):
+
+```txt
+Localization readiness: framework-managed | partial | none
+```
+
+The probe is **informational only**. No gate, no blocking, no required-action — explore's job is to describe the project's current state, not prescribe change. A consumer downstream (a planning agent, a roadmap reviewer, the user) can act on the signal if a gap is meaningful for the project, but the probe itself never forces a step. This matches the orthogonal-lens discipline of D-07 — surface signal, do not bolt on a new pillar.
+
+## Cross-References
+
+- [typography.md](./typography.md) §Variable Fonts — variable-font axes the multi-script subset strategy interacts with.
+- [rtl-cjk-cultural.md](./rtl-cjk-cultural.md) — cultural context (greeting forms, color symbolism, CJK family-name order); this file deepens the engineering side without overlap.
+- [accessibility.md](./accessibility.md) §WCAG 2.1 / 2.2 — the §WCAG i18n section above is the language-specific cross-reference to the broader WCAG corpus.
+- [form-patterns.md](./form-patterns.md) — locale-aware input formatting, `autocomplete` taxonomy, BCP 47 tag use in form locale negotiation.
+- [variable-fonts-loading.md](./variable-fonts-loading.md) — multi-script subset strategy interaction; when shipping multiple weighted-static fonts beats one mega-variable font.
+
+Reciprocal inbound cross-links into this file land in Phase 28-06 (additive-only, D-06).

package/reference/iconography.md

@@ -20,6 +20,8 @@ Icons are not scalable art objects that merely get bigger — they are optical i
 
 **Pixel alignment rules:** Icons on an even grid (16px, 24px, 32px) align their strokes to whole pixels. Icons on an odd grid (20px, 28px) should have strokes centered on 0.5px boundaries to avoid sub-pixel blur on non-retina displays. For SVG exports, always set `shape-rendering: crispEdges` on icon wrappers, and center the viewBox exactly on the pixel grid (e.g., `viewBox="0 0 24 24"`, not `"0.5 0.5 23 23"`). A stroke centered on the path boundary will anti-alias; a stroke offset by 0.5px will render sharply.
 
+**See:** [`./composition.md`](./composition.md) §Optical vs. Mathematical Centering for why icon glyphs (chevrons, play triangles, asymmetric arrows) need a small (−1 to −2px) nudge from mathematical center — the visual-weight asymmetry of the glyph shifts perceived center away from the geometric centroid.
+
 ---
 
 ## 2. Weight & Stroke Consistency

package/reference/motion-interpolate.md

@@ -280,3 +280,4 @@ This is equivalent to three separate interpolations chained by range.
 
 - Easing functions for the `easing` / `ease` parameter: [motion-easings.md](./motion-easings.md)
 - Spring-based animation (an alternative driver to progress/scroll): [motion-spring.md](./motion-spring.md)
+- Color-specific interpolation paths (sRGB muddy-mid transition vs OKLCH perceptual path): **See** [`./color-theory.md`](./color-theory.md) §Color Interpolation in Animation for the color-channel application of the same interpolation discipline.

package/reference/palette-catalog.md

@@ -20,6 +20,8 @@ This catalog gives design agents and the brief-stage palette picker a pre-verifi
 
 **Step 4 — Adjust for brand uniqueness.** All values here are mid-point baselines. Shift the primary hue ±15°, adjust lightness ±10%, or introduce a proprietary tint to differentiate the brand. Do not use these hex values verbatim in production without at least one brand-distinguishing adjustment.
 
+**See:** [`./color-theory.md`](./color-theory.md) §Color Harmonies for the OKLCH model that grounds these hue-shift instructions (perceptual lightness preserved across hues; sRGB ±15° distorts perceived brightness asymmetrically across yellow/blue).
+
 **Step 5 — Verify pairing.** After choosing the palette, consult `reference/typography.md` for matching typeface pairings that reinforce the vertical's tone.
 
 ## WCAG Compliance Notes