@hegemonart/get-design-done 1.41.5 → 1.43.0

package/reference/motion-transition-taxonomy.md

@@ -9,113 +9,113 @@ Eight controlled transition families derived from the hyperframes registry. Each
 
 ## 1. 3d
 
-The 3d family covers transitions driven by depth and perspective. Elements rotate or flip along a spatial axis so the viewer perceives them moving through three-dimensional space rather than sliding across a flat surface. The visual character is physical and mechanical — content feels like it has mass, faces, and hinge points. Timing curves should emphasize the acceleration and deceleration of a real object rotating under gravity.
+The 3d family covers transitions driven by depth and perspective. Elements rotate or flip along a spatial axis so the viewer perceives them moving through three-dimensional space rather than sliding across a flat surface. The visual character is physical and mechanical - content feels like it has mass, faces, and hinge points. Timing curves should emphasize the acceleration and deceleration of a real object rotating under gravity.
 
 **Canonical examples:** `flip-x`, `flip-y`, `rotate-3d-left`, `cube-left`
 
 ### When to use
 
-- **Page flips in book or document viewers** — the metaphor of a literal page turning reinforces the reading model.
-- **Card flip interactions** — revealing the back of a card (e.g., a flashcard, a product tile showing detail) benefits from the physical flip metaphor.
-- **Onboarding carousel slides** — a cube or rotating panel transition communicates sequential steps with a stronger sense of progression than a flat slide.
+- **Page flips in book or document viewers** - the metaphor of a literal page turning reinforces the reading model.
+- **Card flip interactions** - revealing the back of a card (e.g., a flashcard, a product tile showing detail) benefits from the physical flip metaphor.
+- **Onboarding carousel slides** - a cube or rotating panel transition communicates sequential steps with a stronger sense of progression than a flat slide.
 
 ---
 
 ## 2. blur
 
-The blur family transitions content by shifting focus: the outgoing element loses sharpness while the incoming element sharpens into clarity. The motion resembles a camera rack-focus — attention narrows onto a single point and then expands to the new content. Unlike most transition families, blur operates in the depth-of-field axis rather than the spatial or temporal axis, making it feel intimate and selective.
+The blur family transitions content by shifting focus: the outgoing element loses sharpness while the incoming element sharpens into clarity. The motion resembles a camera rack-focus - attention narrows onto a single point and then expands to the new content. Unlike most transition families, blur operates in the depth-of-field axis rather than the spatial or temporal axis, making it feel intimate and selective.
 
 **Canonical examples:** `blur-in`, `blur-out`, `blur-in-up`, `blur-in-down`
 
 ### When to use
 
-- **Focus-mode overlays** — blurring underlying content when a modal, drawer, or spotlight opens communicates that the rest of the UI has receded.
-- **Photo gallery lightbox opens** — racking focus from thumbnail to full image reinforces the zoom metaphor without a disorienting scale jump.
-- **Loading skeleton to content** — blurring out a skeleton and sharpening in the real content feels more organic than an abrupt swap or a flat cross-fade.
+- **Focus-mode overlays** - blurring underlying content when a modal, drawer, or spotlight opens communicates that the rest of the UI has receded.
+- **Photo gallery lightbox opens** - racking focus from thumbnail to full image reinforces the zoom metaphor without a disorienting scale jump.
+- **Loading skeleton to content** - blurring out a skeleton and sharpening in the real content feels more organic than an abrupt swap or a flat cross-fade.
 
 ---
 
 ## 3. cover
 
-The cover family uses a fill or wipe that expands from one edge to conceal the outgoing content and simultaneously reveal the incoming content behind it. The transition is directional — left, right, up, or down — giving users a strong spatial cue about where they are navigating. The incoming content is already fully rendered beneath the cover layer, so there is no compositional ambiguity mid-transition.
+The cover family uses a fill or wipe that expands from one edge to conceal the outgoing content and simultaneously reveal the incoming content behind it. The transition is directional - left, right, up, or down - giving users a strong spatial cue about where they are navigating. The incoming content is already fully rendered beneath the cover layer, so there is no compositional ambiguity mid-transition.
 
 **Canonical examples:** `cover-left`, `cover-right`, `cover-up`, `cover-down`
 
 ### When to use
 
-- **Route transitions in marketing sites** — a cover wipe from the current page edge toward the next reinforces the left-to-right or top-to-bottom navigation model.
-- **Section reveals on scroll** — covering the previous section as the next one rises into view creates a satisfying page-turning rhythm for long-form content.
-- **Slide-panel opens** — a drawer or side panel that covers the main content from its natural edge feels grounded rather than floating.
+- **Route transitions in marketing sites** - a cover wipe from the current page edge toward the next reinforces the left-to-right or top-to-bottom navigation model.
+- **Section reveals on scroll** - covering the previous section as the next one rises into view creates a satisfying page-turning rhythm for long-form content.
+- **Slide-panel opens** - a drawer or side panel that covers the main content from its natural edge feels grounded rather than floating.
 
 ---
 
 ## 4. destruction
 
-The destruction family fragments outgoing content before new content appears. Elements shatter, explode, pixelate, or break apart into constituent pieces that scatter or dissolve. The transition is intentionally dramatic and high-entropy — it signals a decisive, irreversible state change rather than a soft navigation event. Because of its visual weight, destruction transitions should be reserved for moments where the drama is earned.
+The destruction family fragments outgoing content before new content appears. Elements shatter, explode, pixelate, or break apart into constituent pieces that scatter or dissolve. The transition is intentionally dramatic and high-entropy - it signals a decisive, irreversible state change rather than a soft navigation event. Because of its visual weight, destruction transitions should be reserved for moments where the drama is earned.
 
 **Canonical examples:** `shatter`, `explode`, `pixelate-out`, `break-apart`
 
 ### When to use
 
-- **Onboarding celebrations** — completing a significant setup milestone (connecting an account, finishing a profile) can warrant a brief destruction-style break of the previous step.
-- **Error states (use sparingly)** — a pixelate-out or shatter on a failed action can reinforce the severity of the error without a generic fade, but overuse deadens the signal.
-- **Game-style transitions** — level completions, score reveals, or achievement unlocks in game-adjacent products match the genre conventions users already associate with this visual language.
+- **Onboarding celebrations** - completing a significant setup milestone (connecting an account, finishing a profile) can warrant a brief destruction-style break of the previous step.
+- **Error states (use sparingly)** - a pixelate-out or shatter on a failed action can reinforce the severity of the error without a generic fade, but overuse deadens the signal.
+- **Game-style transitions** - level completions, score reveals, or achievement unlocks in game-adjacent products match the genre conventions users already associate with this visual language.
 
 ---
 
 ## 5. dissolve
 
-The dissolve family cross-fades both the outgoing and incoming content so they overlap during the transition period. Neither element is hidden at the midpoint — the viewer sees a superimposition of both states. This creates a sense of continuity and blending rather than replacement. Dissolves feel gentle and temporal: time is passing, but the context is preserved.
+The dissolve family cross-fades both the outgoing and incoming content so they overlap during the transition period. Neither element is hidden at the midpoint - the viewer sees a superimposition of both states. This creates a sense of continuity and blending rather than replacement. Dissolves feel gentle and temporal: time is passing, but the context is preserved.
 
 **Canonical examples:** `dissolve`, `fade-through-black`, `fade-through-white`, `morph-dissolve`
 
 ### When to use
 
-- **Content replacement where continuity matters** — updating a detail panel or a card's content without navigating away benefits from dissolve so the user understands they are still in the same location.
-- **Photo slideshows** — the classic cross-dissolve between images preserves the sense of a continuous viewing experience.
-- **Wizard step changes** — stepping through a multi-step form where each step occupies the same spatial region reads more clearly with a dissolve than a directional slide, because the user has not navigated anywhere.
+- **Content replacement where continuity matters** - updating a detail panel or a card's content without navigating away benefits from dissolve so the user understands they are still in the same location.
+- **Photo slideshows** - the classic cross-dissolve between images preserves the sense of a continuous viewing experience.
+- **Wizard step changes** - stepping through a multi-step form where each step occupies the same spatial region reads more clearly with a dissolve than a directional slide, because the user has not navigated anywhere.
 
 ---
 
 ## 6. distortion
 
-The distortion family applies mesh warping, ripple, stretch, or liquid deformation to content during the transition. Rather than moving content spatially or temporally, distortion transitions make the pixels themselves behave like a physical medium — rubber, water, or fabric — that stretches and snaps back. The effect is visceral and tactile. Used well, it adds a signature moment that makes a product feel materially distinct.
+The distortion family applies mesh warping, ripple, stretch, or liquid deformation to content during the transition. Rather than moving content spatially or temporally, distortion transitions make the pixels themselves behave like a physical medium - rubber, water, or fabric - that stretches and snaps back. The effect is visceral and tactile. Used well, it adds a signature moment that makes a product feel materially distinct.
 
 **Canonical examples:** `warp`, `ripple`, `stretch-in`, `liquid`
 
 ### When to use
 
-- **Creative and editorial contexts** — design portfolios, editorial publications, and art-directed landing pages where differentiation is a primary goal.
-- **Unique brand moments** — a single, well-timed warp or ripple on a hero image transition can become a brand signature without overwhelming the interface.
-- **Hero section transitions on marketing sites** — distortion applied at the seam between a full-bleed hero and the next section creates a visceral scroll reward that flat transitions cannot match.
+- **Creative and editorial contexts** - design portfolios, editorial publications, and art-directed landing pages where differentiation is a primary goal.
+- **Unique brand moments** - a single, well-timed warp or ripple on a hero image transition can become a brand signature without overwhelming the interface.
+- **Hero section transitions on marketing sites** - distortion applied at the seam between a full-bleed hero and the next section creates a visceral scroll reward that flat transitions cannot match.
 
 ---
 
 ## 7. grid
 
-The grid family breaks content into a regular matrix of tiles that animate independently — entering, exiting, flipping, or fading in a choreographed sequence. The grid subdivision can be dense (many small tiles for a mosaic effect) or coarse (a few large panels). The transition communicates that the content is composed of discrete pieces, which suits imagery and portfolio work where the grid metaphor is already meaningful.
+The grid family breaks content into a regular matrix of tiles that animate independently - entering, exiting, flipping, or fading in a choreographed sequence. The grid subdivision can be dense (many small tiles for a mosaic effect) or coarse (a few large panels). The transition communicates that the content is composed of discrete pieces, which suits imagery and portfolio work where the grid metaphor is already meaningful.
 
 **Canonical examples:** `grid-in`, `grid-out`, `checkerboard`, `tile-flip`
 
 ### When to use
 
-- **Portfolio galleries** — revealing a new set of work by animating each thumbnail cell independently reinforces the gallery grid metaphor.
-- **Image reveals** — a grid-in where tiles appear in a wave pattern draws the eye across the composition before the full image settles.
-- **Dramatic content transitions in editorial contexts** — a checkerboard or tile-flip between major sections of an editorial layout creates a theatrical reveal suited to magazine-style layouts.
+- **Portfolio galleries** - revealing a new set of work by animating each thumbnail cell independently reinforces the gallery grid metaphor.
+- **Image reveals** - a grid-in where tiles appear in a wave pattern draws the eye across the composition before the full image settles.
+- **Dramatic content transitions in editorial contexts** - a checkerboard or tile-flip between major sections of an editorial layout creates a theatrical reveal suited to magazine-style layouts.
 
 ---
 
 ## 8. light
 
-The light family uses luminosity effects — flash, glow, lens flare, or bloom — to punctuate the moment of transition. Rather than moving content spatially, light transitions overwhelm the frame briefly with brightness or radiant energy before the new content resolves. The effect is momentary and climactic, borrowed from cinematic language where a burst of light signals a revelation, a completion, or the passage of significance.
+The light family uses luminosity effects - flash, glow, lens flare, or bloom - to punctuate the moment of transition. Rather than moving content spatially, light transitions overwhelm the frame briefly with brightness or radiant energy before the new content resolves. The effect is momentary and climactic, borrowed from cinematic language where a burst of light signals a revelation, a completion, or the passage of significance.
 
 **Canonical examples:** `flash`, `whiteout`, `bloom`, `lens-flare`
 
 ### When to use
 
-- **Onboarding completions** — a flash or bloom when the user finishes setup signals that something important has happened.
-- **Achievement unlocks** — reward moments in any product (reaching a milestone, earning a badge) suit light transitions because brightness is universally read as positive and celebratory.
-- **Brand-moment animations and moments of delight** — a subtle lens-flare or glow on a signature interaction (e.g., hitting a streak, confirming a purchase) adds warmth without disrupting flow.
+- **Onboarding completions** - a flash or bloom when the user finishes setup signals that something important has happened.
+- **Achievement unlocks** - reward moments in any product (reaching a milestone, earning a badge) suit light transitions because brightness is universally read as positive and celebratory.
+- **Brand-moment animations and moments of delight** - a subtle lens-flare or glow on a signature interaction (e.g., hitting a streak, confirming a purchase) adds warmth without disrupting flow.
 
 ---
 
@@ -140,13 +140,13 @@ Quick-reference guide for selecting the right transition family based on visual
 
 Transition family choice constrains the appropriate duration range. The duration system (defined in `reference/motion.md`) maps timing to semantic classes: narrative, slow, standard, quick, and instant.
 
-**3d and destruction** require slow-to-narrative durations (400–700 ms). Their visual complexity — rotating geometry, fragmenting particles — needs time to resolve clearly. At quick durations they read as broken or glitchy rather than intentional.
+**3d and destruction** require slow-to-narrative durations (400–700 ms). Their visual complexity - rotating geometry, fragmenting particles - needs time to resolve clearly. At quick durations they read as broken or glitchy rather than intentional.
 
 **distortion** works best in the slow-to-standard range (300–500 ms). Warping too fast looks like an artifact; too slow it becomes self-indulgent. The sweet spot is long enough to feel physical but short enough to feel responsive.
 
 **grid** tolerates a wider range depending on tile count. Coarse grids (2×2 or 3×3) can run at standard (200–300 ms); dense mosaics need slow (350–500 ms) so individual tile motion is legible.
 
-**light** transitions are typically the shortest of the heavy-weight families. A flash or whiteout at 150–250 ms (standard-to-quick) feels like a camera flash — instantaneous and climactic. Extending it past 400 ms turns a flash into a fade.
+**light** transitions are typically the shortest of the heavy-weight families. A flash or whiteout at 150–250 ms (standard-to-quick) feels like a camera flash - instantaneous and climactic. Extending it past 400 ms turns a flash into a fade.
 
 **dissolve and cover** are the workhorses of the system. Both operate comfortably at standard (200–300 ms) and can be compressed to quick (100–150 ms) for secondary navigation without losing legibility. They are the default choice when in doubt.
 

package/reference/motion.md

@@ -1,6 +1,6 @@
 # Motion & Animation Framework
 
-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."
 
 ---
 
@@ -10,11 +10,11 @@ Based on Emil Kowalski's design engineering philosophy. Apply these rules in ord
 
 | Action frequency | Decision |
 |---|---|
-| 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) |
-| Rare — onboarding, celebrations, first-time flows | Can add personality and delight |
-| Once — loading splash, page transitions | Full animation budget |
+| 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) |
+| Rare - onboarding, celebrations, first-time flows | Can add personality and delight |
+| Once - loading splash, page transitions | Full animation budget |
 
 **Critical rule**: Never animate keyboard-initiated actions. They repeat hundreds of times daily. Every ms of animation is felt.
 
@@ -26,7 +26,7 @@ Valid animation purposes only. If it doesn't serve one of these, remove it.
 |---|---|
 | **Spatial consistency** | Toast enters/exits same edge each time |
 | **State indication** | Button morphs to show loading → success |
-| **Cause-effect explanation** | Item deletion — item flies to trash |
+| **Cause-effect explanation** | Item deletion - item flies to trash |
 | **Feedback** | Button scales 0.97 on press |
 | **Prevent jarring changes** | Content appearing/disappearing needs transition |
 
@@ -36,9 +36,9 @@ Invalid purposes: "It looks cool", "It feels modern", "Other apps do it."
 
 | Element state | Easing | Rationale |
 |---|---|---|
-| **Entering** | `ease-out` (fast start, slow end) | Feels responsive — starts immediately |
-| **Exiting** | `ease-in` (slow start, fast end) | Gets out of the way — doesn't linger |
-| **State transition** (same element) | `ease-in-out` | Natural — neither abrupt start nor end |
+| **Entering** | `ease-out` (fast start, slow end) | Feels responsive - starts immediately |
+| **Exiting** | `ease-in` (slow start, fast end) | Gets out of the way - doesn't linger |
+| **State transition** (same element) | `ease-in-out` | Natural - neither abrupt start nor end |
 | **Interactive/draggable** | Spring physics | Follows finger/cursor naturally |
 | **Bounce/elastic** | **Never** | Feels toy-like and dated |
 
@@ -92,7 +92,7 @@ Exception: `filter` (blur) is GPU-accelerated in modern browsers but battery-exp
 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
+- Direction: top-to-bottom OR left-to-right - never random
 
 ```css
 .item:nth-child(1) { animation-delay: 0ms; }
@@ -121,7 +121,7 @@ button:not(:active) {
 ```
 
 Scale range: **0.95–0.98** for buttons. **0.97** is the safest default.
-Never scale below 0.90 — it looks broken.
+Never scale below 0.90 - it looks broken.
 
 ---
 
@@ -169,7 +169,7 @@ The best animations are ones users cannot describe but notice when absent. Signs
 - 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?"
+This is the goal. Not "look at this animation" - "why does this feel so good to use?"
 
 ---
 
@@ -238,7 +238,7 @@ Rule of thumb: for UI micro-interactions use stiffness 150–250, damping 20–3
 
 ## Scroll-Triggered Animations
 
-Use IntersectionObserver for scroll-reveal effects — it replaces scroll-event
+Use IntersectionObserver for scroll-reveal effects - it replaces scroll-event
 listeners with a throttled browser-native API.
 
 ### Basic pattern
@@ -271,15 +271,15 @@ document.querySelectorAll('.reveal').forEach(el => observer.observe(el));
 
 ### Once vs repeat
 
-- **Once** — call `observer.unobserve(entry.target)` after first intersection.
+- **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,
+- **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.
+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).
@@ -287,11 +287,11 @@ document.querySelectorAll('.reveal').forEach(el => observer.observe(el));
 ---
 
 ## MIFB Micro-Motion Extensions
-Source: jakubkrehel/make-interfaces-feel-better (MIT) — motion.md
+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.
+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
@@ -314,11 +314,11 @@ For multi-element entrances (card grids, lists, feature sections):
 - 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)
+- 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.
+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
+### 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:
 
@@ -326,7 +326,7 @@ When swapping two icons (e.g., play ↔ pause, chevron-up ↔ chevron-down, book
 - `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**
+- `transition: { type: "spring", duration: 0.3, bounce: 0 }` - **bounce MUST be 0**
 
 **CSS fallback (no Framer):**
 - Keep both icons in the DOM, one `position: absolute`
@@ -335,14 +335,14 @@ When swapping two icons (e.g., play ↔ pause, chevron-up ↔ chevron-down, book
 
 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
+### 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
+- 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]`
@@ -363,13 +363,13 @@ When `AnimatePresence` wraps UI that exists in the DOM before it enters the anim
 </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.
+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
+### 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.
+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 |
@@ -379,7 +379,7 @@ GPU-compositable properties (safe with will-change):
 | 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.
+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

package/reference/multi-author-model.md

@@ -1,12 +1,12 @@
-# Multi-Author Model — Team Collaboration Contract
+# Multi-Author Model - Team Collaboration Contract
 
 Phase 40 contract. GDD's single-process baseline (Phase 20 lockfile + atomic STATE.md RMW) is safe for
 one operator. This file is the contract for **multiple developers** working a design in parallel: how
 STATE.md merges, how decisions are attributed and reviewed, how writes coordinate across processes,
-and who is allowed to write what. Everything here is **git-native + advisory** — no server, no live
+and who is allowed to write what. Everything here is **git-native + advisory** - no server, no live
 multiplayer, no SSO.
 
-## 1. Multi-writer STATE.md — git-merge-driver with per-section semantic merge
+## 1. Multi-writer STATE.md - git-merge-driver with per-section semantic merge
 
 GDD does **not** ship a CRDT or OT engine. The chosen model (lowest risk, highest familiarity) is a
 **git merge driver with per-section semantic conflict detection**. The append-mostly `<decisions>`
@@ -17,8 +17,8 @@ block is the common case: two branches each adding a new `D-NN` must merge clean
 - **Equal duplicates collapse.** The same `D-NN` with identical text/status/attribution on both sides
   is kept once.
 - **Divergence is the only conflict.** The same `D-NN` with different text or status on the two sides
-  is a genuine conflict — surfaced to `agents/conflict-resolver.md`, never auto-resolved.
-- **Decisions are durable.** A `D-NN` removed on one side but unchanged on the other is **kept** — a
+  is a genuine conflict - surfaced to `agents/conflict-resolver.md`, never auto-resolved.
+- **Decisions are durable.** A `D-NN` removed on one side but unchanged on the other is **kept** - a
   decision is never silently deleted by a merge; removal goes through the unlock flow (§3).
 
 A single-value section (e.g. `status`) merges with `mergeStatusScalar`: if only one side changed, take
@@ -32,13 +32,13 @@ A decision line carries an **optional** attribution suffix:
 D-07: Use OKLCH design tokens (locked) [author=alice co-author=gdd-3f9a]
 ```
 
-- `author` — the git user who made the decision.
-- `co-author` — the GDD instance id (which machine/agent run produced it).
+- `author` - the git user who made the decision.
+- `co-author` - the GDD instance id (which machine/agent run produced it).
 
 The suffix is backward-compatible: a plain `D-01: text (locked)` parses with `author`/`co-author` =
 null. `scripts/lib/collab/attribution.cjs` parses + formats the line and groups decisions by author.
 `agents/design-reflector.md` reads attribution to surface **per-author patterns** (who tends to lock
-early, whose decisions get reverted). This is the SC#5 "attribution field" — encoded in the line, not
+early, whose decisions get reverted). This is the SC#5 "attribution field" - encoded in the line, not
 a schema-breaking change to the `Decision` type.
 
 ## 3. Async review queue + decision locks
@@ -64,10 +64,10 @@ proposed → reviewing → approved → locked
 mode the Phase 20 defaults apply (`maxWaitMs: 5000`). When `collab.multi_writer_enabled: true`, a
 teammate's write may be queued, so the policy waits up to **30 s** with a **100 ms** backoff poll and a
 2-minute stale threshold. `collab.lock_timeout_ms` overrides the wait. The gdd-state MCP write path
-passes these options to the existing advisory lock — coordinated multi-process writes, no new lock
+passes these options to the existing advisory lock - coordinated multi-process writes, no new lock
 mechanism.
 
-## 5. Sectional handoff — `gdd_cycle_mode`
+## 5. Sectional handoff - `gdd_cycle_mode`
 
 `.design/config.json#gdd_cycle_mode` partitions a cycle by role (`scripts/lib/collab/cycle-mode.cjs`):
 
@@ -77,7 +77,7 @@ mechanism.
 | `dev` | Plan, Design, Verify |
 | `full` | all (the default / current behavior) |
 
-`stagePermitted(mode, stage)` gates STATE writes by stage — a designer-mode cycle cannot write Plan/Design
+`stagePermitted(mode, stage)` gates STATE writes by stage - a designer-mode cycle cannot write Plan/Design
 state, and vice versa. This lets a designer hand a brief to a dev without either overwriting the other's
 sections.
 
@@ -101,9 +101,9 @@ permissive (`owner` can do everything); an override can restrict, e.g. "only `@l
 ## 8. Cross-machine sync (opt-in)
 
 `scripts/lib/collab/sync-backend.cjs` `resolveBackend(config)` selects the `.design/` sync backend:
-`git` (the **default** — existing behavior), or an opt-in `s3` / `git-lfs` for orgs whose git
+`git` (the **default** - existing behavior), or an opt-in `s3` / `git-lfs` for orgs whose git
 push/pull cadence is too slow. Sync is **opt-in and off by default**; a live S3/LFS client is out of
-scope for this phase — the selector + contract ship, the backend is pluggable.
+scope for this phase - the selector + contract ship, the backend is pluggable.
 
 ## Boundaries
 

package/reference/native-platforms.md

@@ -1,9 +1,9 @@
-# Native Platforms — Token-Bridge Spec
+# Native Platforms - Token-Bridge Spec
 
 This reference is the **token→native-code bridge**: it specifies how the canonical
 CSS-token form produced by the Phase-23 token engine
-(`scripts/lib/design-tokens/`) maps onto the three native theme systems —
-SwiftUI, Jetpack Compose, and Flutter — and pins down the **precision contract**
+(`scripts/lib/design-tokens/`) maps onto the three native theme systems -
+SwiftUI, Jetpack Compose, and Flutter - and pins down the **precision contract**
 that defines what "token identity preserved" means for the deterministic
 round-trip (`reference/native-platforms.md` is the authority that
 `test/suite/native-token-bridge.test.cjs` asserts against).
@@ -13,15 +13,15 @@ have distinct jobs and must not be confused:
 
 | File | Job |
 | --- | --- |
-| `reference/platforms.md` (Phase 19) | Interaction **conventions** — navigation, safe areas, gestures, native typography, haptics. *Behavioral* knowledge the executors reference when laying out a screen. |
-| `reference/native-platforms.md` (Phase 34.1, this file) | The token→theme **bridge** — how a design token (`#3B82F6`, `16px`, `Inter`) becomes a SwiftUI `Color` / Compose `Color(0x…)` / Flutter `Color(0x…)`, plus the precision contract for the round-trip. *Structural* knowledge the emitters implement. |
+| `reference/platforms.md` (Phase 19) | Interaction **conventions** - navigation, safe areas, gestures, native typography, haptics. *Behavioral* knowledge the executors reference when laying out a screen. |
+| `reference/native-platforms.md` (Phase 34.1, this file) | The token→theme **bridge** - how a design token (`#3B82F6`, `16px`, `Inter`) becomes a SwiftUI `Color` / Compose `Color(0x…)` / Flutter `Color(0x…)`, plus the precision contract for the round-trip. *Structural* knowledge the emitters implement. |
 
 Per **D-02** the bridge **extends** the Phase-23 engine with three new emitters
 (`scripts/lib/design-tokens/{swift,compose,flutter}.cjs`) rather than forking a
 separate native IR. There is one canonical token form (below) and one set of
 readers; the native emitters are additional *sinks* on the same facade. Per
-**D-10** the round-trip operates at the **token level** — deterministic emit +
-re-extract with documented precision — never full-view parsing and never a live
+**D-10** the round-trip operates at the **token level** - deterministic emit +
+re-extract with documented precision - never full-view parsing and never a live
 simulator, so the default `npm test` stays green on any machine.
 
 ---
@@ -55,7 +55,7 @@ whose values are the raw token values as strings.
 ```
 
 Each emitter accepts either the full Phase-23 `TokenSet`
-(`{ tokens, source?, format? }`) **or** a bare `{ tokens }` object — it reads
+(`{ tokens, source?, format? }`) **or** a bare `{ tokens }` object - it reads
 `tokenSet.tokens` and throws a `TypeError` only when no `.tokens` object is
 present.
 
@@ -77,20 +77,20 @@ to decide whether a value is a color, a dimension, or a string:
 A value is **always** re-sniffed regardless of prefix, so a `#…` value under a
 non-color prefix is still emitted as a color and a `Npx` value under a non-space
 prefix is still emitted as a dimension. The prefix is the hint; the value is the
-authority. This keeps the bridge robust against arbitrary token-naming schemes.
+authority. This keeps the bridge solid against arbitrary token-naming schemes.
 
 ---
 
 ## 3. SwiftUI mapping
 
 Target: a Swift source string exposing an `enum` of static theme constants
-(`enum GDDTheme { … }`) — colors as `Color`, dimensions as `CGFloat` points,
+(`enum GDDTheme { … }`) - colors as `Color`, dimensions as `CGFloat` points,
 typography families as `String` (and an optional `Font` helper).
 
 | Token | SwiftUI form |
 | --- | --- |
 | color `#RRGGBB` | `Color(red: R/255.0, green: G/255.0, blue: B/255.0, opacity: A/255.0)` from the 8-bit channels |
-| dimension `Npx` | `CGFloat` point literal — integer `N` (pt) |
+| dimension `Npx` | `CGFloat` point literal - integer `N` (pt) |
 | font-family | `String` literal (`"Inter, system-ui"`) |
 
 Illustrative (2-line) snippet:
@@ -102,7 +102,7 @@ static let space4: CGFloat = 16
 
 SwiftUI uses normalized `0.0…1.0` channel fractions; to keep the round-trip
 **exact** the emitter writes each channel as the 8-bit numerator over `255.0`
-(e.g. `59.0/255.0`) rather than a pre-divided decimal — the re-extractor reads
+(e.g. `59.0/255.0`) rather than a pre-divided decimal - the re-extractor reads
 the numerator back as the integer channel, avoiding float drift. The `Color` /
 `Font` / `ViewModifier` consumption pattern (applying the constants to views) is
 the executor's job; this emitter produces the *constants*.
@@ -144,7 +144,7 @@ carries the typography tokens, plus a constants class
 | Token | Flutter form |
 | --- | --- |
 | color `#RRGGBB` | `Color(0xAARRGGBB)` (alpha-first, 8 hex digits) |
-| dimension `Npx` | logical-px **double** — `N.0` |
+| dimension `Npx` | logical-px **double** - `N.0` |
 | typography family | `String` (`fontFamily: 'Inter'`) |
 
 Illustrative (2-line) snippet:
@@ -155,7 +155,7 @@ static const space4 = 16.0;
 ```
 
 Flutter measures in logical pixels and keeps the value as a `double` (`16.0`),
-so — unlike pt/dp — Flutter dimensions are **not** rounded to integers; the
+so - unlike pt/dp - Flutter dimensions are **not** rounded to integers; the
 fractional part survives.
 
 ---
@@ -164,29 +164,29 @@ fractional part survives.
 
 This section is the crux. It defines, per value category, exactly what
 information the emit → re-extract round-trip preserves. The test asserts token
-identity **within this precision** — not bit-exact floats, not lossy
+identity **within this precision** - not bit-exact floats, not lossy
 approximation. An emitter is correct **iff** `reextract(emit({tokens}))`
 reproduces every token in the identity set under these rules.
 
-### COLOR — 8-bit-per-channel, EXACT
+### COLOR - 8-bit-per-channel, EXACT
 
 - Accepted input forms: `#RGB`, `#RRGGBB`, `#RGBA`, `#RRGGBBAA` (case-insensitive).
 - `#RGB` / `#RGBA` shorthand **expands** to `#RRGGBB` / `#RRGGBBAA` by
   duplicating each nibble (`#3af` → `#33aaff`). This expansion is part of the
   contract: the re-extractor recovers the **expanded** `#RRGGBB(AA)` form, so
   `#3af` round-trips to `#33aaff` (canonically equal, the documented identity).
-- Each channel is an 8-bit integer (0–255) and is preserved **exactly** — no
+- Each channel is an 8-bit integer (0–255) and is preserved **exactly** - no
   channel may be off by one. SwiftUI stores channels as `N.0/255.0` numerators;
   Compose/Flutter store them in a `0xAARRGGBB` literal. Both forms recover the
   identical 8-bit channels.
 - **Alpha:** when the input has no alpha (`#RGB`/`#RRGGBB`) the emitted color is
-  **opaque** — alpha byte `0xFF` (Compose/Flutter) / `opacity: 255.0/255.0`
+  **opaque** - alpha byte `0xFF` (Compose/Flutter) / `opacity: 255.0/255.0`
   (SwiftUI). The re-extractor emits an alpha channel **only when the original
   had one**: a 6-digit input round-trips to a 6-digit `#RRGGBB` (the implied
   opaque alpha is dropped on the way back); an 8-digit input round-trips to the
   8-digit `#RRGGBBAA`. This keeps `#3B82F6 → #3B82F6` an exact identity.
 
-### DIMENSION — integer pt/dp, logical-px double
+### DIMENSION - integer pt/dp, logical-px double
 
 - Accepted input: `Npx` or a bare unit-less number (`16px`, `16`). The unit is
   normalised to `px` on the canonical side.
@@ -200,7 +200,7 @@ reproduces every token in the identity set under these rules.
 - The re-extractor always recovers the canonical `Npx` string form, so the
   emit→re-extract identity for an integer dimension is `"16px" === "16px"`.
 
-### `rem` / `em` — passed through verbatim (non-mappable)
+### `rem` / `em` - passed through verbatim (non-mappable)
 
 `rem`/`em` values depend on a root/element font-size that the token map does not
 carry, so they are **not** converted. They are treated as **non-mappable**
@@ -208,18 +208,18 @@ carry, so they are **not** converted. They are treated as **non-mappable**
 identity set. (A future plan may add an explicit base-size option; until then,
 verbatim pass-through is the stated, deterministic behavior.)
 
-### TYPOGRAPHY / NAMED VALUES — string pass-through
+### TYPOGRAPHY / NAMED VALUES - string pass-through
 
 `font-family`, `font-weight`, named sizes, and any other string token are
 emitted **verbatim** as a string literal and recovered **string-equal**
 (`"Inter, system-ui" → "Inter, system-ui"`). No normalisation, no quoting
 changes that alter the recovered string.
 
-### NON-MAPPABLE — verbatim, EXCLUDED from the identity set
+### NON-MAPPABLE - verbatim, EXCLUDED from the identity set
 
-Values the emitter cannot represent as a native primitive — CSS `var(--x)`
+Values the emitter cannot represent as a native primitive - CSS `var(--x)`
 references, `calc(…)` expressions, gradients (`linear-gradient(…)`), and `rem`/
-`em` dimensions — are **passed through verbatim** into a raw-string slot
+`em` dimensions - are **passed through verbatim** into a raw-string slot
 (a trailing comment such as `// non-mappable: <name> = <value>` or the language
 equivalent) so no information is lost, and are **explicitly excluded** from the
 round-trip identity assertion. The contract documents them as
@@ -256,18 +256,18 @@ regression baseline.
 This reference is registered in
 [`reference/registry.json`](./registry.json) as the `native-platforms` entry
 (type `heuristic`, phase `34.1`) so the registry round-trip test
-(`test/suite/reference-registry.test.cjs`) stays green — every `reference/*.md`
+(`test/suite/reference-registry.test.cjs`) stays green - every `reference/*.md`
 must be registered and resolve (D-05, the 33.5-01 lesson).
 
 ---
 
 ## 9. Cross-references
 
-- [`reference/platforms.md`](./platforms.md) — the interaction-conventions
+- [`reference/platforms.md`](./platforms.md) - the interaction-conventions
   sibling (navigation, safe areas, gestures, native typography). Executors read
   **both**: this file for the token→theme bridge, that file for layout/behavior.
-- `scripts/lib/design-tokens/` — the Phase-23 token engine this bridge extends
+- `scripts/lib/design-tokens/` - the Phase-23 token engine this bridge extends
   (`index.cjs` facade + `css-vars` / `js-const` / `tailwind` / `figma` readers +
   the new `swift` / `compose` / `flutter` emitters).
-- `test/fixtures/mapper-outputs/tokens.json` — the canonical token fixture the
+- `test/fixtures/mapper-outputs/tokens.json` - the canonical token fixture the
   round-trip test derives its map from.