@hegemonart/get-design-done 1.43.0 → 1.45.0

package/reference/motion.md

@@ -1,6 +1,27 @@
-# Motion & Animation Framework
+# Motion - Animation Domain Index
 
-Based on Emil Kowalski's design engineering philosophy. Apply these rules in order - do not skip to "how should this animate" before answering "should this animate."
+Based on Emil Kowalski's design engineering philosophy. Apply these rules in order. Do not skip to "how should this animate" before answering "should this animate."
+
+<!-- Phase 45 domain-index: loads this file instead of individual motion fragments -->
+
+---
+
+## Mission
+
+Motion governs animation decisions across the UI: whether to animate, duration budgets, easing choices, spring physics, transition taxonomy, and interpolation. Read this file first for the decision framework and core rules, then drill into the specialist fragment below. Does not cover CSS layout transitions (see `spatial.md`) or OS-level reduced-motion policy (see `responsive.md`).
+
+---
+
+## Fragment Index
+
+| Fragment | When to load |
+|---|---|
+| `./motion-easings.md` | Choosing or auditing easing curve values: 12 canonical `--ease-*` presets, cubic-bezier equivalents, 60fps settle-times |
+| `./motion-spring.md` | Interaction is draggable or needs physics feel: gentle/wobbly/stiff/slow presets, Framer Motion and React Spring syntax |
+| `./motion-transition-taxonomy.md` | Classifying page or route transitions: 8 families (3d, blur, cover, destruction, dissolve, distortion, grid, light) |
+| `./motion-interpolate.md` | Mapping input-to-output ranges: progress/scroll/gesture/time-linked animations, 4 extrapolation modes |
+| `./motion-advanced.md` | Advanced platform APIs: FLIP, scroll-driven, View Transitions, gesture/drag, clip-path, WAAPI |
+| `./framer-motion-patterns.md` | Codebase uses Framer Motion: spring/tween config, AnimatePresence, variants, gestures, a11y, bounce:0 rule |
 
 ---
 
@@ -12,7 +33,7 @@ Based on Emil Kowalski's design engineering philosophy. Apply these rules in ord
 |---|---|
 | 100+/day - keyboard shortcuts, command palette, list navigation | **No animation. Ever.** |
 | Tens/day - hover states, toggles, tab switching | Remove or keep to <80ms. No delay. |
-| Occasional - modals opening, drawers, toasts | Standard animation (150–300ms) |
+| Occasional - modals opening, drawers, toasts | Standard animation (150-300ms) |
 | Rare - onboarding, celebrations, first-time flows | Can add personality and delight |
 | Once - loading splash, page transitions | Full animation budget |
 
@@ -25,9 +46,9 @@ Valid animation purposes only. If it doesn't serve one of these, remove it.
 | Purpose | Example |
 |---|---|
 | **Spatial consistency** | Toast enters/exits same edge each time |
-| **State indication** | Button morphs to show loading → success |
+| **State indication** | Button morphs to show loading to success |
 | **Cause-effect explanation** | Item deletion - item flies to trash |
-| **Feedback** | Button scales 0.97 on press |
+| **Feedback** | Button scales on press |
 | **Prevent jarring changes** | Content appearing/disappearing needs transition |
 
 Invalid purposes: "It looks cool", "It feels modern", "Other apps do it."
@@ -42,44 +63,28 @@ Invalid purposes: "It looks cool", "It feels modern", "Other apps do it."
 | **Interactive/draggable** | Spring physics | Follows finger/cursor naturally |
 | **Bounce/elastic** | **Never** | Feels toy-like and dated |
 
-CSS:
-```css
-/* Enter */
-transition: transform 200ms cubic-bezier(0, 0, 0.2, 1); /* ease-out */
-
-/* Exit */
-transition: transform 150ms cubic-bezier(0.4, 0, 1, 1); /* ease-in */
-
-/* Transition */
-transition: all 200ms cubic-bezier(0.4, 0, 0.2, 1); /* ease-in-out */
-```
+See `reference/motion-easings.md` for the full `--ease-*` token catalog.
 
 ### Question 4: What Duration?
 
 | Animation type | Duration | Notes |
 |---|---|---|
-| Micro-interactions | 80–150ms | Hover, press, toggle |
-| Component enter/exit | 150–250ms | Modals, drawers, dropdowns |
-| Page transitions | 200–350ms | Route changes |
-| Complex/orchestrated | ≤400ms | Multi-step, staggered reveals |
+| Micro-interactions | 80-150ms | Hover, press, toggle |
+| Component enter/exit | 150-250ms | Modals, drawers, dropdowns |
+| Page transitions | 200-350ms | Route changes |
+| Complex/orchestrated | <=400ms | Multi-step, staggered reveals |
 | **Never exceed** | 400ms | Anything longer feels broken |
 
-**Exit faster than enter**: Exit animations should run at **60–70%** of the enter duration. Exiting elements should get out of the way fast.
-
-```
-Enter: 250ms
-Exit: 150ms (60% of 250)
-```
+**Exit faster than enter**: Exit animations should run at **60-70%** of the enter duration.
 
 ### Question 5: Only Animate `transform` and `opacity`
 
-**Only these properties animate on the GPU:**
 ```css
-/* SAFE */
+/* SAFE - GPU-accelerated */
 transform: translateX(), translateY(), scale(), rotate()
-opacity: 0 → 1
+opacity: 0 to 1
 
-/* DANGEROUS — triggers layout/paint */
+/* DANGEROUS - triggers layout/paint */
 width, height, top, left, margin, padding, font-size
 ```
 
@@ -89,319 +94,73 @@ Exception: `filter` (blur) is GPU-accelerated in modern browsers but battery-exp
 
 ## Stagger Rules
 
-When animating a list of items entering:
-- Stagger delay: **30–50ms** per item
-- Maximum stagger depth: **6–8 items** (items beyond that appear simultaneously)
-- Direction: top-to-bottom OR left-to-right - never random
-
-```css
-.item:nth-child(1) { animation-delay: 0ms; }
-.item:nth-child(2) { animation-delay: 40ms; }
-.item:nth-child(3) { animation-delay: 80ms; }
-/* etc. — cap at ~6 staggered items */
-```
+- Stagger delay: **30-50ms** per item
+- Maximum stagger depth: **6-8 items** (items beyond that appear simultaneously)
+- Direction: top-to-bottom OR left-to-right, never random
 
 ---
 
 ## Press Feedback
 
-Every clickable element must give visual feedback within **100ms** of interaction.
+Every clickable element must give visual feedback within **100ms** of interaction. The canonical scale value for press feedback is **`0.96`**.
+
+- Never use `scale(0.95)` - too large, feels unresponsive
+- Never use `scale(0.97)` or higher - imperceptible at high DPI
+- `0.96` is the correct value for standard interactive elements
 
 ```css
 button:active {
-  transform: scale(0.97); /* NOT 0.90 — too dramatic */
+  transform: scale(0.96);
   transition: transform 80ms ease-out;
 }
-
-/* On release */
-button:not(:active) {
-  transform: scale(1);
-  transition: transform 150ms ease-out;
-}
 ```
 
-Scale range: **0.95–0.98** for buttons. **0.97** is the safest default.
-Never scale below 0.90 - it looks broken.
-
 ---
 
 ## `prefers-reduced-motion`
 
-Always respect this. It's not optional.
+Always respect this. It is not optional.
 
 ```css
 @media (prefers-reduced-motion: reduce) {
-  *,
-  *::before,
-  *::after {
+  *, *::before, *::after {
     animation-duration: 0.01ms !important;
-    animation-iteration-count: 1 !important;
     transition-duration: 0.01ms !important;
     scroll-behavior: auto !important;
   }
 }
 ```
 
-Or in JavaScript:
-```js
-const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
-if (!prefersReduced) {
-  // Run animation
-}
-```
-
----
-
-## What Never To Animate
-
-- Keyboard shortcuts and commands (too frequent)
-- Tab switching within a page
-- Filter/sort toggles on data tables
-- Expanding/collapsing sidebar navigation items during heavy use
-- Any interaction the user will perform 50+ times in a session
-
----
-
-## The Invisible Detail Rule
-
-The best animations are ones users cannot describe but notice when absent. Signs of this:
-- The interaction feels "snappy" or "responsive" without thinking about why
-- Removing the animation makes the UI feel broken
-- Users say "it feels premium" but can't point to any specific feature
-
-This is the goal. Not "look at this animation" - "why does this feel so good to use?"
-
 ---
 
-## Quick Animation Audit Checklist
+## Quick Audit Checklist
 
 - [ ] No animation on keyboard-triggered actions
-- [ ] All durations ≤ 400ms
+- [ ] All durations <=400ms
 - [ ] Exit < enter duration
 - [ ] Only `transform` and `opacity` for performance
 - [ ] `prefers-reduced-motion` implemented
-- [ ] Stagger ≤ 50ms per item, capped at 6–8 items
+- [ ] Stagger <=50ms per item, capped at 6-8 items
 - [ ] Press feedback on all interactive elements
 - [ ] No bounce/elastic easing anywhere
 - [ ] All animations have a defined purpose
 
 ---
 
-## Spring Physics
-
-Spring-based animation replaces duration-based tweening with physics parameters
-(stiffness, damping, mass). Output feels more organic and adapts to interruption.
-
-### React Spring
-
-```jsx
-import { useSpring, animated } from '@react-spring/web';
-
-const styles = useSpring({
-  from: { opacity: 0, transform: 'translateY(20px)' },
-  to:   { opacity: 1, transform: 'translateY(0px)' },
-  config: { tension: 170, friction: 26 }  // default preset
-});
-```
-
-React Spring presets:
-
-| Preset | tension | friction | Character |
-|--------|---------|----------|-----------|
-| default | 170 | 26 | balanced |
-| gentle | 120 | 14 | smooth, leisurely |
-| wobbly | 180 | 12 | playful bounce |
-| stiff | 210 | 20 | snappy |
-| slow | 280 | 60 | slow and deliberate |
-| molasses | 280 | 120 | very slow, no bounce |
-
-### Framer Motion
-
-```jsx
-<motion.div
-  animate={{ x: 100 }}
-  transition={{ type: "spring", stiffness: 100, damping: 15, mass: 1 }}
-/>
-```
-
-Parameter guidance:
-
-| Param | Range | Effect |
-|-------|-------|--------|
-| stiffness | 50–300 | higher = snappier arrival |
-| damping | 10–40 | higher = less oscillation |
-| mass | 0.5–2 | higher = more inertia, slower response |
-
-Rule of thumb: for UI micro-interactions use stiffness 150–250, damping 20–30, mass 1.
-
----
-
-## Scroll-Triggered Animations
-
-Use IntersectionObserver for scroll-reveal effects - it replaces scroll-event
-listeners with a throttled browser-native API.
-
-### Basic pattern
-
-```js
-const observer = new IntersectionObserver((entries) => {
-  entries.forEach(entry => {
-    if (entry.isIntersecting) {
-      entry.target.classList.add('in-view');
-      // Optional: disconnect after first trigger
-      // observer.unobserve(entry.target);
-    }
-  });
-}, {
-  threshold: 0.1,
-  rootMargin: '0px 0px -100px 0px'  // trigger 100px before entering viewport bottom
-});
-
-document.querySelectorAll('.reveal').forEach(el => observer.observe(el));
-```
-
-### Threshold guidance
-
-| threshold | Meaning |
-|-----------|---------|
-| 0.0 | element enters viewport edge |
-| 0.1–0.25 | element partially visible (most common for reveals) |
-| 0.5 | element half-visible |
-| 1.0 | element fully visible |
-
-### Once vs repeat
-
-- **Once** - call `observer.unobserve(entry.target)` after first intersection.
-  Use for: hero reveals, one-shot entrance animations, stat counters.
-- **Repeat** - leave observer active. Use for: progress indicators, parallax effects,
-  sticky nav state changes.
-
-### Performance rules
-
-1. Animate only `transform` and `opacity` (GPU-accelerated). Avoid `top`, `left`, `width`, `height`.
-2. No debounce/throttle needed - IntersectionObserver is already throttled by the browser.
-3. For many elements, share a single observer instance and call `observe()` once per element.
-4. Prefer CSS transitions triggered by a class toggle over requestAnimationFrame loops.
-5. Use `will-change: transform, opacity` sparingly (only on elements that animate repeatedly).
-
----
-
-## MIFB Micro-Motion Extensions
-Source: jakubkrehel/make-interfaces-feel-better (MIT) - motion.md
-
-### Interruptible Animations
-
-Use CSS transitions for interactive elements because transitions retarget mid-animation - when a user moves their cursor away before a hover animation completes, the transition reverses smoothly from wherever it currently is. Keyframe animations restart from the beginning, creating a jarring jump.
-
-**Decision rule:**
-- Interactive states (hover, focus, active, pressed): always CSS transitions
-- Orchestrated sequences, entrance effects, data-driven animations: keyframe or JS animation
-
-```css
-/* Good — transition retargets smoothly */
-.button { transition: background-color 150ms ease-out; }
-
-/* Avoid for interactive — restarts on interruption */
-.button:hover { animation: hover-bg 150ms ease-out forwards; }
-```
-
-### Split-and-Stagger Enter/Exit
-
-For multi-element entrances (card grids, lists, feature sections):
-
-- Default stagger: 100ms between elements
-- Heading words: 80ms per word
-- Entrance transform: `opacity: 0 → 1` + `translateY(12px → 0)` + `blur(4px → 0)`
-- Entrance duration: 300ms, `ease-out`
-- Exit transform: `opacity: 1 → 0` + `translateY(0 → -12px)` (opposite direction, smaller offset)
-- Exit duration: 150ms (half the entrance duration - exits should be faster)
-
-The blur component adds a depth cue that makes entrances feel less flat. Keep blur modest (4px) - the goal is a subtle focus effect, not a visible blur.
-
-### Contextual Icon Animations - Cross-Fade Pattern
-
-When swapping two icons (e.g., play ↔ pause, chevron-up ↔ chevron-down, bookmark ↔ bookmarked), use this exact cross-fade spec:
-
-**Framer Motion spring (preferred):**
-- `scale: 0.25 → 1` (entering), `scale: 1 → 0.25` (exiting)
-- `opacity: 0 → 1` (entering), `opacity: 1 → 0` (exiting)
-- `filter: blur(4px) → blur(0)` (entering), `blur(0) → blur(4px)` (exiting)
-- `transition: { type: "spring", duration: 0.3, bounce: 0 }` - **bounce MUST be 0**
+## Rules of Thumb
 
-**CSS fallback (no Framer):**
-- Keep both icons in the DOM, one `position: absolute`
-- Use `cubic-bezier(0.2, 0, 0, 1)` easing
-- Duration: 200ms
-
-The scale + blur combination creates a focus-snap effect that feels intentional rather than mechanical. The `bounce: 0` hard constraint exists because any bounce on a 0.25-scale origin point makes icons appear to "pop" invasively.
-
-### Scale on Press - Canonical Value
-
-The canonical scale value for press feedback is **`0.96`**.
-
-Rules:
-- Never use `scale(0.95)` - too large, feels unresponsive
-- Never use `scale(0.97)` - too subtle at high DPI, not perceived as feedback
-- Never use `scale(0.98)` or higher - imperceptible
-- `0.96` is the ONLY correct value for standard interactive elements
-
-Tailwind: `active:scale-[0.96]`
-Framer: `whileTap={{ scale: 0.96 }}`
-
-For primary CTAs where maximum tactility is needed (purchase, send, confirm):
-use `0.96` with a shadow reduction: `box-shadow: none` during press.
-
-Deprecation note: earlier versions of `reference/checklists.md` referenced `scale(0.97)`. That entry has been reconciled. **0.96 is the canonical value.**
-
-### AnimatePresence initial={false}
-
-When `AnimatePresence` wraps UI that exists in the DOM before it enters the animation scope (e.g., a tab panel that renders its first tab immediately, a dropdown that's already open on first load), use `initial={false}`:
-
-```tsx
-<AnimatePresence initial={false}>
-  {isOpen && <motion.div key="panel" initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }} />}
-</AnimatePresence>
-```
-
-Without `initial={false}`, Framer will animate the FIRST render of children - meaning UI that's immediately visible on page load will "fade in" unnecessarily. This creates a flash/flicker that signals poor craftsmanship.
-
-**Rule:** Any `AnimatePresence` wrapping persistent UI should have `initial={false}`.
-
-### will-change - GPU Property Table
-
-Only add `will-change` when you observe first-frame stutter on lower-end hardware. Do NOT add it preemptively - it consumes GPU memory continuously for every element that has it.
-
-GPU-compositable properties (safe with will-change):
-| Property | will-change value |
-|----------|------------------|
-| transform (translate, scale, rotate) | `transform` |
-| opacity | `opacity` |
-| filter (blur, brightness, contrast) | `filter` |
-| clip-path | `clip-path` |
-
-Never use `will-change: all` or `will-change: contents` - this forces the entire element and its subtree onto a new compositor layer, thrashing memory.
-
-Remove `will-change` after the animation completes if applied dynamically:
-```js
-element.addEventListener('transitionend', () => element.style.willChange = 'auto')
-```
+1. Keyboard-initiated actions (command palette, list navigation, shortcuts) must have zero animation. They repeat hundreds of times daily and every ms is felt.
+2. Default to named spring presets (gentle/wobbly/stiff/slow) rather than raw stiffness/damping numbers; presets are tuned for 60fps settle-time and predictable feel.
+3. Always use `--ease-*` CSS custom property tokens rather than inline `cubic-bezier()` strings; tokens keep easing consistent and respect `prefers-reduced-motion`.
+4. OKLCH is the correct color space for animated color transitions; sRGB interpolation produces muddy mid-transition colors. See `reference/color-theory.md` for color interpolation in animation.
 
 ---
 
-## Advanced Patterns
-
-For spring physics, scroll-driven animation, FLIP, View Transitions API, gesture & drag mechanics, clip-path animation patterns, blur-to-mask crossfades, WAAPI, Framer Motion hardware-acceleration gotcha, motion cohesion & personality, and the next-day slow-motion review process, see:
-
-→ **`reference/motion-advanced.md`** (Phase 18)
-
-For the canonical easing catalog (`--ease-*` tokens, cubic-bezier equivalents, 60fps settle-times):
-
-→ **`reference/motion-easings.md`** (Phase 18)
-
-For spring parameter presets (gentle / wobbly / stiff / slow):
-
-→ **`reference/motion-spring.md`** (Phase 18)
-
-For transition family taxonomy (8 families: 3d / blur / cover / destruction / dissolve / distortion / grid / light):
+## Cross-Domain See Also
 
-→ **`reference/motion-transition-taxonomy.md`** (Phase 18)
+- Color animation uses OKLCH path: `reference/color.md`
+- Gesture semantics (velocity, pointer capture): `reference/interaction.md`
+- OS-level reduced-motion: `reference/responsive.md`
+- CSS layout transitions: `reference/spatial.md`
+- Typography: `reference/typography.md`
+- UX writing: `reference/ux-writing.md`

package/reference/registry.json

@@ -625,8 +625,9 @@
     {
       "name": "motion",
       "path": "reference/motion.md",
-      "type": "motion",
-      "description": "Motion vocabulary seed (extended in Phase 18)"
+      "type": "domain-index",
+      "description": "Phase 45 domain-index: motion navigation - indexes easings, spring, transition-taxonomy, interpolate, advanced, framer-motion-patterns.",
+      "phase": 45
     },
     {
       "name": "motion-advanced",
@@ -797,8 +798,9 @@
     {
       "name": "typography",
       "path": "reference/typography.md",
-      "type": "heuristic",
-      "description": "Typography-system heuristics used by visual-hierarchy-mapper"
+      "type": "domain-index",
+      "description": "Phase 45 domain-index: typography navigation - indexes type-scale heuristics, variable-fonts-loading, proportion-systems.",
+      "phase": 45
     },
     {
       "name": "user-research",
@@ -1049,6 +1051,41 @@
       "type": "meta-rules",
       "phase": 42,
       "description": "Phase 42 multi-harness skill-placeholder catalogue: the four placeholders ({{command_prefix}}/{{model}}/{{config_file}}/{{ask_instruction}}) + per-harness substitution table + the \\{{...}} escape + the <!-- harness-only: a,b --> block rule. Skills authored once in source/skills/, compiled per-harness by scripts/build-skills.cjs via scripts/lib/build/factory.cjs reading scripts/lib/manifest/harnesses.json."
+    },
+    {
+      "name": "color",
+      "path": "reference/color.md",
+      "type": "domain-index",
+      "phase": 45,
+      "description": "Phase 45 domain-index: color + contrast navigation - color-theory, palette-catalog, contrast-advanced, style-vocabulary."
+    },
+    {
+      "name": "spatial",
+      "path": "reference/spatial.md",
+      "type": "domain-index",
+      "phase": 45,
+      "description": "Phase 45 domain-index: layout/spacing/composition - composition, proportion-systems, css-grid-layout, visual-hierarchy-layout, gestalt, image-optimization, data-visualization, surfaces."
+    },
+    {
+      "name": "interaction",
+      "path": "reference/interaction.md",
+      "type": "domain-index",
+      "phase": 45,
+      "description": "Phase 45 domain-index: interaction + a11y + components - accessibility, component-authoring, form-patterns, information-architecture, onboarding-progressive-disclosure, emotional-design, components/."
+    },
+    {
+      "name": "responsive",
+      "path": "reference/responsive.md",
+      "type": "domain-index",
+      "phase": 45,
+      "description": "Phase 45 domain-index: responsive + i18n + platforms - i18n, rtl-cjk-cultural, platforms, native-platforms, performance, css-grid-layout."
+    },
+    {
+      "name": "ux-writing",
+      "path": "reference/ux-writing.md",
+      "type": "domain-index",
+      "phase": 45,
+      "description": "Phase 45 domain-index: UX-writing + voice - brand-voice, style-vocabulary, anti-patterns."
     }
   ]
 }

package/reference/registry.schema.json

@@ -4,19 +4,41 @@
   "title": "Reference Registry",
   "description": "Typed index of every reference/*.md (and reference/*.json default) in the plugin. Enables agents to query by type instead of grep-hunting import strings. Round-trip enforced: every reference/*.md must appear in entries[], every entry must resolve to an existing file.",
   "type": "object",
-  "required": ["version", "generated_at", "entries"],
+  "required": [
+    "version",
+    "generated_at",
+    "entries"
+  ],
   "properties": {
-    "$schema": { "type": "string" },
-    "version": { "const": 1 },
-    "generated_at": { "type": "string", "format": "date-time" },
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
     "entries": {
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["name", "path", "type"],
+        "required": [
+          "name",
+          "path",
+          "type"
+        ],
         "properties": {
-          "name": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-._]*$" },
-          "path": { "type": "string", "minLength": 1 },
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[a-z0-9][a-z0-9-._]*$"
+          },
+          "path": {
+            "type": "string",
+            "minLength": 1
+          },
           "type": {
             "type": "string",
             "enum": [
@@ -41,13 +63,28 @@
               "typography",
               "layout",
               "performance",
-              "component-spec"
+              "component-spec",
+              "domain-index"
+            ]
+          },
+          "tier": {
+            "enum": [
+              "L0",
+              "L1",
+              "L2"
             ]
           },
-          "tier": { "enum": ["L0", "L1", "L2"] },
-          "phase": { "type": "number", "description": "Phase that introduced this entry. Numbers are allowed (e.g., 19.6, 27.5, 27.6, 27.7, 28.5) — decimal phases are valid per the long-standing precedent established by Phases 19.6 / 27.5 / 27.6 / 27.7 / 28.5." },
-          "description": { "type": "string" },
-          "registered_at": { "type": "string", "format": "date-time" }
+          "phase": {
+            "type": "number",
+            "description": "Phase that introduced this entry. Numbers are allowed (e.g., 19.6, 27.5, 27.6, 27.7, 28.5) — decimal phases are valid per the long-standing precedent established by Phases 19.6 / 27.5 / 27.6 / 27.7 / 28.5."
+          },
+          "description": {
+            "type": "string"
+          },
+          "registered_at": {
+            "type": "string",
+            "format": "date-time"
+          }
         },
         "additionalProperties": false
       }

package/reference/responsive.md

@@ -0,0 +1,74 @@
+# Responsive Design - Domain Index
+
+This is the domain entry-point for responsive design. Load this file when the
+interface will render in more than one locale, platform, or viewport condition.
+It covers i18n engineering primitives, RTL and CJK cultural adaptation,
+platform-specific conventions, native token bridging, and performance budgets.
+It does not cover the CSS Grid implementation of responsive layouts (see
+`reference/spatial.md` for container queries and `clamp()`); it does not cover
+copy tone for localized content (see `reference/ux-writing.md`).
+
+---
+
+## Fragment Index
+
+→ **`reference/i18n.md`** (Phase 28) - use when localizing text: expansion
+budgets (+30-40%), CSS logical props, `Intl.*` APIs, ICU MessageFormat,
+bidi isolation, Unicode normalization, multi-script font stacks
+
+→ **`reference/rtl-cjk-cultural.md`** (Phase 28) - use when targeting RTL
+locales or CJK audiences: layout mirroring rules, bidirectional text isolation,
+Arabic/Hebrew/Devanagari rendering, cultural color meanings and imagery norms
+
+→ **`reference/platforms.md`** (Phase 19) - use when targeting multiple
+platforms: iOS/Android/web/visionOS/watchOS nav patterns, safe area insets,
+gesture vocabularies, haptics, native typography conventions
+
+→ **`reference/native-platforms.md`** (Phase 34.1) - use when bridging design
+tokens to native code: canonical CSS token to SwiftUI Color / Compose Color /
+Flutter ThemeData mapping, precision contract for the round-trip
+
+→ **`reference/performance.md`** (Phase 19) - use for any production
+responsive build: Core Web Vitals budgets by project type, JS/font/image
+budgets, React runtime perf rules
+
+→ **`reference/css-grid-layout.md`** (Phase 18) - load the container-queries
+and `clamp()` sections only: fluid responsive components, safe-area insets,
+logical CSS props in Grid context
+
+---
+
+## Rules of Thumb
+
+**1. Size containers for the worst-case expansion locale.**
+Russian and Finnish strings expand +40% from an English baseline. Any text
+container designed at English width will overflow in those locales. Build for
+`EN base x 1.4` as the standard layout-budget rule; top-aligned labels absorb
+expansion without horizontal breakage.
+
+**2. CSS logical properties are the implementation primitive for RTL.**
+Never use `left`/`right` in a layout that will need to mirror. Replace
+`margin-left` with `margin-inline-start`, `padding-right` with
+`padding-inline-end`, and positioned `left` with `inset-inline-start`. The full
+mapping is in `reference/rtl-cjk-cultural.md`.
+
+**3. `prefers-reduced-motion` is a responsive property, not optional.**
+Any animation behind a media query must resolve to `transition: none` or
+`animation-duration: 0.01ms` when the user has set OS-level reduced-motion.
+The CSS reset pattern is in `reference/motion.md`.
+
+**4. Native token precision contract: no re-derivation in component code.**
+Color hex values bridge to native at 8-bit channel precision (no rounding).
+Dimension px values bridge as integer dp/pt. The token-bridge round-trip in
+`reference/native-platforms.md` is the source of truth - any re-derivation
+in component code will drift from the canonical value.
+
+---
+
+## Cross-Domain See Also
+
+- i18n text expansion affects type container sizing: `reference/typography.md`
+- Touch targets differ from pointer targets: `reference/interaction.md`
+- Layout shifts at breakpoints: `reference/spatial.md`
+- OS-level reduced-motion links to animation rules: `reference/motion.md`
+- Civic multi-language government forms: `reference/domains/civic-patterns.md`