@hegemonart/get-design-done 1.42.0 → 1.43.0

package/reference/heuristics.md

@@ -4,7 +4,7 @@ Use this during Discover (identifying real problems), Plan (determining what to
 
 ---
 
-## Nielsen Norman Group — 10 Usability Heuristics
+## Nielsen Norman Group - 10 Usability Heuristics
 
 The baseline evaluation framework. Score each 0–4 (0=violation, 4=excellent). Include in audit output.
 
@@ -56,7 +56,7 @@ Minimize the user's memory load by making objects, actions, and options visible.
 - **Fail cases**: Users must remember previous step's data, keyboard shortcuts only without visual hints
 
 ### H-07: Flexibility and Efficiency of Use
-Accelerators — unseen by the novice user — allow experts to speed up interaction.
+Accelerators - unseen by the novice user - allow experts to speed up interaction.
 - Keyboard shortcuts for power users
 - Bulk actions for lists
 - Saved searches/filters
@@ -93,19 +93,19 @@ Even though it is better if the system can be used without documentation, it may
 
 Use during layout and visual hierarchy decisions.
 
-**Proximity** — Elements close together are perceived as related. Use: group related controls (8–16px between group members, 32–64px between groups).
+**Proximity** - Elements close together are perceived as related. Use: group related controls (8–16px between group members, 32–64px between groups).
 
-**Similarity** — Elements looking alike are perceived as the same type. Use: consistent styling for all links, all CTAs, all destructive actions.
+**Similarity** - Elements looking alike are perceived as the same type. Use: consistent styling for all links, all CTAs, all destructive actions.
 
-**Continuity** — The eye follows lines and curves. Use: align elements to create reading flow (left-to-right, top-to-bottom).
+**Continuity** - The eye follows lines and curves. Use: align elements to create reading flow (left-to-right, top-to-bottom).
 
-**Closure** — The mind fills in incomplete shapes. Use: card borders can be implied by spacing and background difference alone.
+**Closure** - The mind fills in incomplete shapes. Use: card borders can be implied by spacing and background difference alone.
 
-**Figure/Ground** — Foreground vs background differentiation. Use: modals and overlays need clear depth separation (shadow, blur, dimming).
+**Figure/Ground** - Foreground vs background differentiation. Use: modals and overlays need clear depth separation (shadow, blur, dimming).
 
-**Common Fate** — Elements moving together are perceived as a group. Use: animation groups related elements together — stagger within groups, not across.
+**Common Fate** - Elements moving together are perceived as a group. Use: animation groups related elements together - stagger within groups, not across.
 
-**Prägnanz (Simplicity)** — The mind perceives the simplest possible interpretation. Use: reduce visual complexity. If 2 elements can do the job of 5, use 2.
+**Prägnanz (Simplicity)** - The mind perceives the simplest possible interpretation. Use: reduce visual complexity. If 2 elements can do the job of 5, use 2.
 
 ---
 
@@ -115,8 +115,8 @@ Use during layout and visual hierarchy decisions.
 
 Time to click = function of distance / target size. Implications:
 - Minimum touch target: **44×44pt** (iOS), **48×48dp** (Android). Never smaller.
-- Destructive actions (Delete, Cancel) must be **physically far** from primary actions OR significantly smaller — not adjacent at the same size.
-- Screen edges and corners are fast (infinite size in that direction) — use for primary navigation (iOS bottom bar, macOS menu bar).
+- Destructive actions (Delete, Cancel) must be **physically far** from primary actions OR significantly smaller - not adjacent at the same size.
+- Screen edges and corners are fast (infinite size in that direction) - use for primary navigation (iOS bottom bar, macOS menu bar).
 - Dense interfaces that require clicking small targets = high error rate + user frustration.
 
 ---
@@ -148,7 +148,7 @@ Working memory holds approximately **5–9 items**. Implications:
 Users remember the **first** and **last** items in a list best (primacy and recency). Implications:
 - Put most important actions first and last in navigation.
 - In long forms, critical fields go near the top or after a clear section break.
-- CTAs at the bottom of long pages work (recency) — but add one above the fold too (primacy).
+- CTAs at the bottom of long pages work (recency) - but add one above the fold too (primacy).
 
 ---
 
@@ -156,8 +156,8 @@ Users remember the **first** and **last** items in a list best (primacy and rece
 
 The item that **differs** from its group is most memorable. Implications:
 - One primary CTA per screen (contrast makes it memorable).
-- Don't use "primary" styling on 3 different buttons — only one stands out.
-- Highlight key data points in tables (bold, color accent) — but only the truly key ones.
+- Don't use "primary" styling on 3 different buttons - only one stands out.
+- Highlight key data points in tables (bold, color accent) - but only the truly key ones.
 - Overuse of emphasis = no emphasis. Use it for 1–2 items per view maximum.
 
 ---
@@ -183,10 +183,10 @@ People **remember incomplete tasks** better than completed ones. Implications:
 
 ## Peak-End Rule
 
-Users judge an experience primarily by how it felt at its most intense moment (the **peak**) and how it ended — not by the average across the whole session. Implications:
+Users judge an experience primarily by how it felt at its most intense moment (the **peak**) and how it ended - not by the average across the whole session. Implications:
 - Design a deliberate positive peak in every primary flow (e.g., a celebratory completion screen, an instant result, a delightful empty state).
 - The **end state** of a flow matters disproportionately: the last screen the user sees shapes their memory of the whole interaction.
-- Reduce negative peaks first (error states, loading hangs) — they weigh heavier than neutral moments.
+- Reduce negative peaks first (error states, loading hangs) - they weigh heavier than neutral moments.
 - A long frustrating form followed by a satisfying completion screen is remembered more positively than a mildly annoying end to an otherwise smooth flow.
 
 ---
@@ -195,7 +195,7 @@ Users judge an experience primarily by how it felt at its most intense moment (t
 
 Users feel the pain of loss approximately **twice as strongly** as the pleasure of an equivalent gain (Kahneman & Tversky). Implications:
 - Frame CTAs around what users keep/save, not what they gain: "Don't lose your progress" over "Save your work."
-- Subscription cancellation flows that show what the user will lose (features, data, streak) leverage loss aversion ethically to reduce churn — but only if the stated losses are real.
+- Subscription cancellation flows that show what the user will lose (features, data, streak) use loss aversion ethically to reduce churn - but only if the stated losses are real.
 - Free trial countdowns ("3 days left") trigger loss aversion more effectively than benefit reminders.
 - Destructive action confirmations should name what is lost: "Delete this project and all 47 files?" not just "Are you sure?"
 
@@ -212,7 +212,7 @@ Working memory is limited to approximately **7 ± 2 chunks** simultaneously (Mil
 | **Germane** | Load that builds understanding (learning, pattern recognition) | Preserve and support |
 
 Practical rules:
-- Every element of visual noise is extraneous load — remove it.
+- Every element of visual noise is extraneous load - remove it.
 - New UI patterns create extraneous load (Jakob's Law); use platform conventions.
 - Chunk complex tasks into steps of ≤3 decisions each.
 - Error messages that require decoding ("Error 422") create extraneous load; plain language removes it.
@@ -221,11 +221,11 @@ Practical rules:
 
 ## Aesthetic-Usability Effect
 
-Users perceive **aesthetically pleasing designs as more usable**, even when functionality is identical — and this perception persists through initial usability problems. Implications:
+Users perceive **aesthetically pleasing designs as more usable**, even when functionality is identical - and this perception persists through initial usability problems. Implications:
 - A polished visual appearance buys tolerance for minor UX rough edges in early releases.
 - This effect is strongest on first impression; it degrades over time as behavioral friction compounds.
 - The effect can mask genuine usability problems in user testing if participants rate overall satisfaction rather than task completion.
-- Do NOT use the aesthetic-usability effect as a reason to defer fixing usability problems — it explains tolerance, not satisfaction.
+- Do NOT use the aesthetic-usability effect as a reason to defer fixing usability problems - it explains tolerance, not satisfaction.
 
 ---
 
@@ -242,7 +242,7 @@ A system that responds within **400ms** keeps users in a state of flow. Response
 
 ## Flow (Csikszentmihalyi)
 
-Users enter a **flow state** when task difficulty matches their skill level exactly — high enough to engage, low enough to feel achievable. Flow is characterized by complete absorption, loss of time awareness, and intrinsic motivation. Implications:
+Users enter a **flow state** when task difficulty matches their skill level exactly - high enough to engage, low enough to feel achievable. Flow is characterized by complete absorption, loss of time awareness, and intrinsic motivation. Implications:
 - Progressive difficulty: onboarding tasks should be trivially easy; expert tasks should provide just enough challenge.
 - Interruptions break flow permanently for that session; avoid modal interruptions in high-focus workflows.
 - Clear goals + immediate feedback are the two design levers for inducing flow (H-01, H-05).
@@ -257,11 +257,11 @@ For each NNG heuristic (H-01 through H-10), rate 0–4:
 
 | Score | Meaning |
 |---|---|
-| 4 | Excellent — actively exemplifies the heuristic |
-| 3 | Passes — meets the heuristic requirement |
-| 2 | Minor violation — notable issue but not blocking |
-| 1 | Major violation — users will notice and be impacted |
-| 0 | Critical violation — breaks the interface |
+| 4 | Excellent - actively exemplifies the heuristic |
+| 3 | Passes - meets the heuristic requirement |
+| 2 | Minor violation - notable issue but not blocking |
+| 1 | Major violation - users will notice and be impacted |
+| 0 | Critical violation - breaks the interface |
 
 **Overall Heuristic Score** = (sum / 40) × 100
 
@@ -297,7 +297,7 @@ function dfs(node):
 **Bias notes:** the DFS visits each node at most once per traversal, so duplicate cycles
 across multiple entry points are deduped by the `visited` guard. The `path.index(node)`
 slice captures only the cycle suffix; nodes before the entry point are not part of the
-cycle. Pre-existing acyclic chains stay invisible — only back-edges surface.
+cycle. Pre-existing acyclic chains stay invisible - only back-edges surface.
 
 ---
 
@@ -321,7 +321,7 @@ minor bumps. They register via `OFF_CADENCE_VERSIONS.add('<version>')` in
 `tests/semver-compare.test.cjs`. The semver-compare test treats them as if they had a
 canonical predecessor (`v1.28.5` after `v1.28.0`, not `v1.28.4`).
 
-**Preview-suffix trap:** model IDs with `-preview` (`gpt-5-preview` vs `gpt-5`) drift — today's
+**Preview-suffix trap:** model IDs with `-preview` (`gpt-5-preview` vs `gpt-5`) drift - today's
 preview is tomorrow's GA. Tooling MUST store the parent name in `provider_model_id` and treat
 the suffix as decorative. See `./peer-cli-protocol.md` for the peer-CLI-side context.
 
@@ -333,22 +333,22 @@ Reference catalog for `skills/optimize/SKILL.md`. Four deterministic rules; rule
 analysis applied in order. Each rule inspects per-agent aggregates from
 `.design/agent-metrics.json` and emits zero or more rows to the recommendations table.
 
-**R1 — Low cache hit rate.**
+**R1 - Low cache hit rate.**
 - *Condition:* `total_spawns >= --min-spawns` AND `cache_hit_rate < 0.20`.
 - *Emit:* `"Consider batching tasks for agent {agent} — cache hit rate is {rate*100}%. Investigate cache-aligned ordering (see reference/shared-preamble.md) and whether input paths can be normalized."`
 - *Proposed action:* Batch similar tasks; confirm shared-preamble import ordering.
 
-**R2 — Expensive and rarely lazy-skipped.**
+**R2 - Expensive and rarely lazy-skipped.**
 - *Condition:* `total_cost_usd > 0.50` AND `lazy_skip_rate < 0.10`.
 - *Emit:* `"Agent {agent} is expensive (${cost}) and rarely skipped ({rate*100}% lazy-skip). Consider adding a lazy gate heuristic at agents/{agent}-gate.md (see plan 10.1-04 pattern)."`
 - *Proposed action:* Add lazy-gate agent.
 
-**R3 — Tier override churn.**
+**R3 - Tier override churn.**
 - *Condition:* Multiple telemetry rows show recorded `tier` differing from frontmatter `default-tier` (e.g., frontmatter `opus` but measured rows consistently `haiku` from budget.json override or soft-threshold downgrade).
 - *Emit:* `"Tier override churn detected for {agent}: frontmatter says {frontmatter-tier} but measured tier is {measured-tier} in {N} of last {M} rows. Consider updating frontmatter default-tier or removing the budget.json override."`
 - *Proposed action:* Update frontmatter default-tier OR prune budget.json `tier_overrides` entry.
 
-**R4 — Typical duration drift.**
+**R4 - Typical duration drift.**
 - *Condition:* Measured `typical_duration_seconds` (computed as avg wall-clock between paired spawn/complete rows; fall back to frontmatter when pairing unavailable) differs from frontmatter `typical-duration-seconds` by more than 50%.
 - *Emit:* `"Typical duration for {agent} has drifted: frontmatter {old}s vs measured {new}s ({delta_pct}% drift). Update frontmatter typical-duration-seconds: {new}."`
 - *Proposed action:* Edit `agents/{agent}.md` frontmatter.

package/reference/i18n.md

@@ -7,15 +7,15 @@ tags: [i18n, intl, icu, unicode, rtl, multi-script, wcag-i18n]
 last_updated: 2026-05-18
 ---
 
-# i18n — Internationalization Engineering Primitives
+# 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.
+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.
+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.
+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                          |
 | ------------------- | --------- | ------------------------------ |
@@ -31,7 +31,7 @@ These factors drive width constraints in component design and the verifier overf
 
 ## 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.
+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
 
@@ -69,7 +69,7 @@ A concrete card component authored entirely in logical props:
 }
 ```
 
-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.
+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
 
@@ -89,7 +89,7 @@ Per-element `dir` is reserved for genuinely mixed-direction content (a username
 
 ### 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.
+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                                          |
 | ----------------------------- | ------------ | -------------------------------------------------- |
@@ -98,7 +98,7 @@ Not every icon should mirror under RTL. The rule is intent: if the icon means "n
 | 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    |
+| 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    |
@@ -108,11 +108,11 @@ Not every icon should mirror under RTL. The rule is intent: if the icon means "n
 
 ### 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:
+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.
+- `<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:
 
@@ -132,15 +132,15 @@ A mixed-direction example: a comment list rendering an Arabic sentence that quot
 </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.
+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.
+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.
+`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');
@@ -188,7 +188,7 @@ new Intl.NumberFormat('ja-JP', { style: 'unit', unit: 'kilometer-per-hour' }).fo
 
 ### 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.
+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');
@@ -205,7 +205,7 @@ 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.
+`"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' });
@@ -220,7 +220,7 @@ 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.
+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'];
@@ -235,7 +235,7 @@ new Intl.ListFormat('de', { style: 'long', type: 'conjunction' }).format(tags);
 
 ### 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.
+`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'];
@@ -254,7 +254,7 @@ names.slice().sort(deCollator.compare);
 
 ### 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.
+`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
@@ -275,7 +275,7 @@ 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.
+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,
@@ -304,17 +304,17 @@ ICU MessageFormat is the canonical input format for the dominant i18n library ma
 }
 ```
 
-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.
+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.
+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.
+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
@@ -334,7 +334,7 @@ Restating from §Intl.Segmenter as a hard rule: **never `string.slice(0, n)` for
 
 ### 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()`.
+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 highlights. Normalize on input via `new Intl.Locale(tag).toString()`.
 
 ```js
 new Intl.Locale('pt-br').toString();   // → "pt-BR"  (canonicalized)
@@ -357,11 +357,11 @@ 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.
+`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.
+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
 
@@ -405,7 +405,7 @@ Devanagari (Hindi, Marathi, Sanskrit) requires conjunct shaping and proper combi
 
 ### `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.
+`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`
 
@@ -431,13 +431,13 @@ Shipping the full Noto Sans CJK is a 5–15MB asset. Browsers will only fetch a
 
 ### 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.
+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
+### 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.
 
@@ -449,9 +449,9 @@ Every page must declare its primary language on `<html>`. Screen readers select
 </html>
 ```
 
-### 3.1.2 — Language-of-parts
+### 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.
+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>
@@ -461,15 +461,15 @@ When the page's primary language is set on `<html>` but a span of text is in a d
 </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.
+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).
+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.
+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="[^"]+"
@@ -490,11 +490,11 @@ 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.
+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.
+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:
@@ -512,7 +512,7 @@ Output line in the verifier report: `i18n_readiness: <N> components overflow at
 
 ## 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.
+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)
 
@@ -541,14 +541,14 @@ Output line in explore report (single informational line, per D-04):
 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.
+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.
+- [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).