@hegemonart/get-design-done 1.41.5 → 1.43.0

package/reference/peer-protocols.md

@@ -1,10 +1,10 @@
-# Peer-CLI Protocols — ACP + ASP Cheat Sheet
+# Peer-CLI Protocols - ACP + ASP Cheat Sheet
 
 **Phase 27 (v1.27.0).** This file is the protocol-level reference for gdd's peer-CLI delegation layer. If you're authoring a new peer adapter or debugging a protocol-level issue, start here.
 
 For ops-level guidance (when delegation fires, how to enable/disable, fallback diagnostics), see `docs/PEER-DELEGATION.md`.
 
-Protocol shapes are adapted from [`greenpolo/cc-multi-cli-plugin`](https://github.com/greenpolo/cc-multi-cli-plugin) under Apache 2.0 — see `NOTICE` for full attribution.
+Protocol shapes are adapted from [`greenpolo/cc-multi-cli-plugin`](https://github.com/greenpolo/cc-multi-cli-plugin) under Apache 2.0 - see `NOTICE` for full attribution.
 
 ---
 
@@ -21,7 +21,7 @@ Line-buffer overflow guard: 16 MiB per line (both clients reject lines longer th
 
 ---
 
-## ACP — Agent Client Protocol
+## ACP - Agent Client Protocol
 
 ### Initialize handshake
 
@@ -99,7 +99,7 @@ Verify via the `peer-cli-add` skill's verification ladder (Step 1) before adding
 
 ---
 
-## ASP — App Server Protocol (Codex)
+## ASP - App Server Protocol (Codex)
 
 ### Service identification
 
@@ -144,7 +144,7 @@ Server → client:
 
 #### threadResume
 
-Useful for cross-cycle conversation continuity (out of scope for v1.27.0 — gdd always creates fresh threads per delegated call — but the API surface exists):
+Useful for cross-cycle conversation continuity (out of scope for v1.27.0 - gdd always creates fresh threads per delegated call - but the API surface exists):
 
 ```json
 {
@@ -191,7 +191,7 @@ Server streams turn-progress notifications, ends with a structured result:
 }
 ```
 
-**Error path** (does NOT throw on the client side — resolves with the error structure):
+**Error path** (does NOT throw on the client side - resolves with the error structure):
 
 ```json
 {
@@ -209,7 +209,7 @@ Server streams turn-progress notifications, ends with a structured result:
 }
 ```
 
-The caller decides retry vs fallback per session-runner contract — gdd's session-runner falls back to local Anthropic on `status: "error"` per D-07.
+The caller decides retry vs fallback per session-runner contract - gdd's session-runner falls back to local Anthropic on `status: "error"` per D-07.
 
 ### Codex ASP entry point
 
@@ -230,12 +230,12 @@ The caller decides retry vs fallback per session-runner contract — gdd's sessi
 
 - Requests carry `id` (monotonic integer per session).
 - Responses carry the same `id` in `result` or `error`.
-- Notifications have no `id` and no `result` — they are routed to the active request's `onNotification` callback (each protocol allows only one "active" request at a time per session — half-duplex).
+- Notifications have no `id` and no `result` - they are routed to the active request's `onNotification` callback (each protocol allows only one "active" request at a time per session - half-duplex).
 
 ### Process lifecycle
 
 - The peer process is spawned via `scripts/lib/peer-cli/spawn-cmd.cjs` (handles Windows `.cmd` EINVAL workaround per D-04).
-- The client connects directly OR through gdd's broker (`broker-lifecycle.cjs`) — both surfaces present the same `{initialize, prompt, close}` (ACP) or `{threadStart, threadResume, turn, close}` (ASP) API.
+- The client connects directly OR through gdd's broker (`broker-lifecycle.cjs`) - both surfaces present the same `{initialize, prompt, close}` (ACP) or `{threadStart, threadResume, turn, close}` (ASP) API.
 - On process death mid-request, the client rejects the in-flight promise with a structured `{error_class: "process_exited"}` event for telemetry.
 
 ---
@@ -245,8 +245,8 @@ The caller decides retry vs fallback per session-runner contract — gdd's sessi
 gdd v1.27.0 ships only ACP and ASP. If a new peer speaks neither (e.g., a future REST-only or HTTP/2-streaming protocol), the path forward is:
 
 1. Document the gap in `.design/RESEARCH.md` for a future phase to scope a new protocol layer.
-2. Do **not** stretch ACP/ASP to fit — they're documented contracts, not generalist multiplexers.
-3. The `peer-cli-add` skill (Step 1's verification ladder) refuses to scaffold a peer that doesn't speak ACP or ASP — by design.
+2. Do **not** stretch ACP/ASP to fit - they're documented contracts, not generalist multiplexers.
+3. The `peer-cli-add` skill (Step 1's verification ladder) refuses to scaffold a peer that doesn't speak ACP or ASP - by design.
 
 A future phase may add a new `scripts/lib/peer-cli/<protocol>-client.cjs` mirror following the same shape (line-buffer + JSON-RPC framing if applicable, or whatever the new protocol natively uses).
 
@@ -254,13 +254,13 @@ A future phase may add a new `scripts/lib/peer-cli/<protocol>-client.cjs` mirror
 
 ## Cross-references
 
-- `scripts/lib/peer-cli/acp-client.cjs` — ACP client implementation.
-- `scripts/lib/peer-cli/asp-client.cjs` — ASP client implementation.
-- `scripts/lib/peer-cli/spawn-cmd.cjs` — Windows `.cmd` EINVAL workaround.
-- `scripts/lib/peer-cli/broker-lifecycle.cjs` — long-lived broker.
-- `scripts/lib/peer-cli/adapters/*.cjs` — per-peer thin wrappers.
-- `scripts/lib/peer-cli/registry.cjs` — central dispatch.
-- `tests/peer-cli-{acp,asp,spawn,registry,adapters}.test.cjs` — protocol-level tests.
-- `docs/PEER-DELEGATION.md` — ops guide.
-- `NOTICE` — Apache 2.0 attribution for cc-multi-cli.
-- `.planning/phases/27-peer-cli-delegation/CONTEXT.md` — decision lineage (D-01, D-02, D-03, D-04).
+- `scripts/lib/peer-cli/acp-client.cjs` - ACP client implementation.
+- `scripts/lib/peer-cli/asp-client.cjs` - ASP client implementation.
+- `scripts/lib/peer-cli/spawn-cmd.cjs` - Windows `.cmd` EINVAL workaround.
+- `scripts/lib/peer-cli/broker-lifecycle.cjs` - long-lived broker.
+- `scripts/lib/peer-cli/adapters/*.cjs` - per-peer thin wrappers.
+- `scripts/lib/peer-cli/registry.cjs` - central dispatch.
+- `tests/peer-cli-{acp,asp,spawn,registry,adapters}.test.cjs` - protocol-level tests.
+- `docs/PEER-DELEGATION.md` - ops guide.
+- `NOTICE` - Apache 2.0 attribution for cc-multi-cli.
+- `.planning/phases/27-peer-cli-delegation/CONTEXT.md` - decision lineage (D-01, D-02, D-03, D-04).

package/reference/perf-budget.md

@@ -6,12 +6,12 @@ type: meta-rules
 description: Per-agent token-cost budget reference and CI regression-gate documentation. Budgets sourced from current p50 + 25% buffer (Phase 27.6 D-05); CI gate fails on >25% regression vs baseline across 3 cycles (D-01); thresholds configurable via .design/budget.json.
 ---
 
-# Per-Agent Performance Budgets — Phase 27.6
+# Per-Agent Performance Budgets - Phase 27.6
 
 This reference documents the token-cost budgets that the pipeline measures itself against. Two surfaces consume this document:
 
-1. `tests/perf-budget.test.cjs` — CI regression gate. Fails the build when any agent's p50 USD-cost has regressed > 25% vs baseline across the last 3 cycles.
-2. `agents/perf-analyzer.md` — cross-cycle reflector. Reads the same budget + telemetry; surfaces top-3 regressions as `[REGRESSION]` proposals.
+1. `tests/perf-budget.test.cjs` - CI regression gate. Fails the build when any agent's p50 USD-cost has regressed > 25% vs baseline across the last 3 cycles.
+2. `agents/perf-analyzer.md` - cross-cycle reflector. Reads the same budget + telemetry; surfaces top-3 regressions as `[REGRESSION]` proposals.
 
 Phase 27.5 (v1.27.5, shipped 2026-05-17) made production telemetry real by wiring the bandit into routing. Phase 27.6 reads what 27.5 writes.
 
@@ -29,7 +29,7 @@ chore(27.6): recalibrate perf-budget against measured cycles
 
 Per **D-01**, the regression-gate threshold is **25%**, configurable via `.design/budget.json#perf_regression_threshold`. A minimum of **3 distinct cycles** must be observed per agent before that agent is evaluated for regression. Agents with fewer than 3 cycles are silently skipped (cold-start tolerance).
 
-This conservative-then-tighten discipline matches Phase 23.5 `PRIOR_STRENGTH` calibration — start wide to avoid noise, tighten once enough samples accumulate to compute realistic p95 bounds.
+This conservative-then-tighten discipline matches Phase 23.5 `PRIOR_STRENGTH` calibration - start wide to avoid noise, tighten once enough samples accumulate to compute realistic p95 bounds.
 
 ---
 
@@ -47,7 +47,7 @@ This conservative-then-tighten discipline matches Phase 23.5 `PRIOR_STRENGTH` ca
 
 These values are **seed numbers**, re-calibrated after 1-2 real production cycles. The authoritative numbers live in `test-fixture/baselines/phase-27-6/perf-baseline.json` (created at Phase 27.6 closeout in Plan 27.6-06). The CI gate reads that file at runtime, not this table.
 
-When the baseline JSON is **absent** (first run after this plan lands but before 27.6-06), the gate passes silently with a stderr notice — it does NOT block Wave A from shipping.
+When the baseline JSON is **absent** (first run after this plan lands but before 27.6-06), the gate passes silently with a stderr notice - it does NOT block Wave A from shipping.
 
 ---
 
@@ -55,10 +55,10 @@ When the baseline JSON is **absent** (first run after this plan lands but before
 
 File: `tests/perf-budget.test.cjs`
 
-Algorithm (single source of truth — re-uses `detectCostRegressions` from `scripts/lib/perf-analyzer/cost-regression.cjs`):
+Algorithm (single source of truth - re-uses `detectCostRegressions` from `scripts/lib/perf-analyzer/cost-regression.cjs`):
 
-1. Load `test-fixture/baselines/phase-27-6/perf-baseline.json`. If absent, exit early — gate passes with stderr notice. (Phase 27.6-06 creates this file at closeout.)
-2. Load `.design/telemetry/costs.jsonl` via `loadCosts`. If absent or empty, exit early — no data to regress against.
+1. Load `test-fixture/baselines/phase-27-6/perf-baseline.json`. If absent, exit early - gate passes with stderr notice. (Phase 27.6-06 creates this file at closeout.)
+2. Load `.design/telemetry/costs.jsonl` via `loadCosts`. If absent or empty, exit early - no data to regress against.
 3. Read `perf_regression_threshold` from `.design/budget.json` (default 25 per D-01).
 4. Call `detectCostRegressions({rows, baseline: parsedBaseline.agents, thresholdPct, cyclesRequired: 3})`.
 5. If `result.regressions.length === 0`, gate passes.
@@ -67,10 +67,10 @@ Algorithm (single source of truth — re-uses `detectCostRegressions` from `scri
 The gate is intentionally **low-noise**:
 
 - Skips agents with fewer than 3 distinct cycles of data (avoids false positives during cold-start).
-- Only fires on the **regression rule** — NOT on cache-hit-rate drops or p95 latency spikes; those surface as `agents/perf-analyzer.md` proposals only.
-- Top-3 cap on the regressions list — a "noisy day" can flag at most three agents, never the entire roster.
+- Only fires on the **regression rule** - NOT on cache-hit-rate drops or p95 latency spikes; those surface as `agents/perf-analyzer.md` proposals only.
+- Top-3 cap on the regressions list - a "noisy day" can flag at most three agents, never the entire roster.
 
-The gate runs as a regular `node --test` entry under the `tests/**/*.test.cjs` glob — no special CI wiring required. If you can run `npm test`, you run the gate.
+The gate runs as a regular `node --test` entry under the `tests/**/*.test.cjs` glob - no special CI wiring required. If you can run `npm test`, you run the gate.
 
 ---
 
@@ -97,7 +97,7 @@ Override the cache-warming false-positive tolerance (used by Phase 27.6-03):
 - `perf_regression_threshold: 25`
 - `cache_warming_falsepositive_threshold: 20`
 
-After 5 measured cycles accumulate, re-tune based on observed natural variance. The 25%-default is conservative — likely too loose once real telemetry stabilizes. The first tightening pass belongs to a measurement-gated follow-up, not v1.27.6 itself.
+After 5 measured cycles accumulate, re-tune based on observed natural variance. The 25%-default is conservative - likely too loose once real telemetry stabilizes. The first tightening pass belongs to a measurement-gated follow-up, not v1.27.6 itself.
 
 ---
 
@@ -116,19 +116,19 @@ That commit:
 3. Bumps the budget numbers in this document to match.
 4. Optionally tightens `perf_regression_threshold` from 25 toward 15-20 if measured variance permits.
 
-The synthetic baseline is **not a hack** — it's the documented v1 path per spec Success Criterion #7. Real-cycle data simply doesn't exist yet at v1.27.6 cut, because Phase 27.5 only shipped 2026-05-17.
+The synthetic baseline is **not a hack** - it's the documented v1 path per spec Success Criterion #7. Real-cycle data simply doesn't exist yet at v1.27.6 cut, because Phase 27.5 only shipped 2026-05-17.
 
 ---
 
 ## Cross-references
 
-- `agents/perf-analyzer.md` — cross-cycle reflector that reads the same baseline. Surfaces top-3 cost regressions, hit-rate deltas, and p95 spikes as `[REGRESSION]` proposals per `/gdd:reflect`.
-- `scripts/lib/perf-analyzer/cost-regression.cjs` — **single source of truth** for the regression rule. The CI gate re-uses `detectCostRegressions` from this module; it does NOT re-implement the rule.
-- `scripts/lib/perf-analyzer/index.cjs` — telemetry loader (`loadCosts`, `loadTrajectories`). JSONL-tolerant; blank lines silently ignored, malformed lines counted in `skipped_count`.
-- `tests/perf-budget.test.cjs` — the CI gate itself. Always-green when no baseline + no data; fails on >25% regression vs baseline once both exist.
-- `reference/bandit-integration.md` — Phase 27.5 routing reference (precursor; the bandit picks tier **within** the budget — the gate evaluates whether the picked tier behaved within budget).
-- `.design/budget.json` — operator-tunable thresholds. Optional file; absent file means defaults (`perf_regression_threshold: 25`, `cache_warming_falsepositive_threshold: 20`).
-- `test-fixture/baselines/phase-27-6/perf-baseline.json` — authoritative per-agent p50 / hit_rate / p95_ms values. Created in Plan 27.6-06 closeout.
+- `agents/perf-analyzer.md` - cross-cycle reflector that reads the same baseline. Surfaces top-3 cost regressions, hit-rate deltas, and p95 spikes as `[REGRESSION]` proposals per `/gdd:reflect`.
+- `scripts/lib/perf-analyzer/cost-regression.cjs` - **single source of truth** for the regression rule. The CI gate re-uses `detectCostRegressions` from this module; it does NOT re-implement the rule.
+- `scripts/lib/perf-analyzer/index.cjs` - telemetry loader (`loadCosts`, `loadTrajectories`). JSONL-tolerant; blank lines silently ignored, malformed lines counted in `skipped_count`.
+- `tests/perf-budget.test.cjs` - the CI gate itself. Always-green when no baseline + no data; fails on >25% regression vs baseline once both exist.
+- `reference/bandit-integration.md` - Phase 27.5 routing reference (precursor; the bandit picks tier **within** the budget - the gate evaluates whether the picked tier behaved within budget).
+- `.design/budget.json` - operator-tunable thresholds. Optional file; absent file means defaults (`perf_regression_threshold: 25`, `cache_warming_falsepositive_threshold: 20`).
+- `test-fixture/baselines/phase-27-6/perf-baseline.json` - authoritative per-agent p50 / hit_rate / p95_ms values. Created in Plan 27.6-06 closeout.
 
 ---
 
@@ -139,4 +139,4 @@ The synthetic baseline is **not a hack** — it's the documented v1 path per spe
 - **base = 0 + current = 0** → NOT a regression (both `delta_pct = 0`).
 - **Missing baseline entry** → agent silently skipped (no false positive on new agents that haven't been calibrated yet).
 
-The gate's "fail loud, false-positive rare" character comes from these boundary choices plus the 3-cycle minimum — together they make the gate safe to wire into CI without flaking on first-run noise.
+The gate's "fail loud, false-positive rare" character comes from these boundary choices plus the 3-cycle minimum - together they make the gate safe to wire into CI without flaking on first-run noise.

package/reference/performance.md

@@ -1,4 +1,4 @@
-# Performance — Reference Guide
+# Performance - Reference Guide
 
 Performance is a design constraint, not an engineering afterthought. Every millisecond of delay in LCP is a measurable reduction in conversion rate; every layout shift during page load erodes user trust. This reference establishes authoritative performance budgets, measurement targets, and implementation rules for all project types handled by the get-design-done framework.
 
@@ -19,17 +19,17 @@ Google's Core Web Vitals are the industry-standard performance metrics for user
 
 ### SaaS / Dashboard Applications
 
-Authenticated dashboard applications carry more JavaScript, more real-time data subscriptions, and more complex component trees than public pages. LCP tolerance is relaxed to ≤3.0s because users have a high motivation to wait (they are trying to accomplish a work task) and the LCP element is often a data-heavy chart or table that legitimately takes time to render. However, INP must be held to ≤200ms strictly — dashboards involve dense interaction patterns (filter, sort, paginate, drill down) and a sluggish response loop destroys the power-user experience.
+Authenticated dashboard applications carry more JavaScript, more real-time data subscriptions, and more complex component trees than public pages. LCP tolerance is relaxed to ≤3.0s because users have a high motivation to wait (they are trying to accomplish a work task) and the LCP element is often a data-heavy chart or table that legitimately takes time to render. However, INP must be held to ≤200ms strictly - dashboards involve dense interaction patterns (filter, sort, paginate, drill down) and a sluggish response loop destroys the power-user experience.
 
 ### Marketing / Landing Pages
 
-Conversion-critical pages have zero tolerance for perceived slowness. LCP must reach ≤2.0s because first impressions determine bounce rate, and bounce rate directly impacts conversion. CLS must be ≤0.05 (half the general threshold) because layout pop during hero section rendering — caused by web font loading, lazy image dimensions, or server-side-rendered content shifting — destroys the premium impression marketing pages are designed to create. Every 100ms of LCP improvement correlates with measurable conversion lift in e-commerce and SaaS trials.
+Conversion-critical pages have zero tolerance for perceived slowness. LCP must reach ≤2.0s because first impressions determine bounce rate, and bounce rate directly impacts conversion. CLS must be ≤0.05 (half the general threshold) because layout pop during hero section rendering - caused by web font loading, lazy image dimensions, or server-side-rendered content shifting - destroys the premium impression marketing pages are designed to create. Every 100ms of LCP improvement correlates with measurable conversion lift in e-commerce and SaaS trials.
 
 ### E-Commerce
 
 | Metric | Target | Rationale |
 |--------|--------|-----------|
-| LCP | ≤2.5s | Product images are the LCP element — optimize aggressively |
+| LCP | ≤2.5s | Product images are the LCP element - optimize aggressively |
 | CLS | ≤0.1 | Price and "Add to Cart" button must not jump as images load |
 | INP | ≤200ms | Cart interactions, quantity updates, and variant selection must feel instant |
 
@@ -41,7 +41,7 @@ Cart and checkout flows are revenue-critical paths where a 500ms interaction del
 |--------|--------|-----------|
 | LCP | ≤3.0s | Docs users are high-intent; tolerate slightly longer loads |
 | CLS | ≤0.1 | Code blocks and long-form content must not reflow after load |
-| TTFB | ≤600ms | Docs are often statically generated — TTFB should approach CDN speed |
+| TTFB | ≤600ms | Docs are often statically generated - TTFB should approach CDN speed |
 
 Documentation sites benefit from aggressive static generation and CDN distribution. TTFB at ≤600ms is achievable with proper static export (Next.js, Astro, Docusaurus) and CDN edge caching.
 
@@ -51,7 +51,7 @@ Documentation sites benefit from aggressive static generation and CDN distributi
 
 The browser must parse and execute CSS before it can paint pixels. CSS that blocks rendering is the most impactful optimization target after eliminating render-blocking JavaScript. The goal is to get the above-the-fold experience to paint within the first TCP round trip (≤14KB compressed).
 
-**Inline above-the-fold styles:** Identify the CSS rules that affect visible content within the initial viewport — typically layout grid, hero component, navigation bar, and typography declarations. Inline these rules in a `<style>` block in the `<head>`. Keep this block under 14KB compressed, which corresponds to approximately 40–60KB uncompressed depending on your gzip ratio.
+**Inline above-the-fold styles:** Identify the CSS rules that affect visible content within the initial viewport - typically layout grid, hero component, navigation bar, and typography declarations. Inline these rules in a `<style>` block in the `<head>`. Keep this block under 14KB compressed, which corresponds to approximately 40–60KB uncompressed depending on your gzip ratio.
 
 **Defer non-critical CSS with preload:** Load the full stylesheet asynchronously to prevent it from blocking rendering:
 
@@ -68,11 +68,11 @@ This pattern preloads the stylesheet at high priority (ensuring it is fetched be
 
 ## 3. Image Budgets
 
-Images are typically the single largest contributor to LCP and total page weight. Every image decision — format, dimensions, lazy-loading strategy, and priority — directly affects Core Web Vitals.
+Images are typically the single largest contributor to LCP and total page weight. Every image decision - format, dimensions, lazy-loading strategy, and priority - directly affects Core Web Vitals.
 
 **Format requirements:**
 - **Photos and complex rasters:** WebP as primary format, AVIF as progressive enhancement where browser support allows. Never ship JPEG or PNG for photos in new projects. AVIF achieves 20–50% smaller file sizes than WebP at equivalent visual quality; use it where CMS and CDN pipelines support it.
-- **Icons and logos:** SVG only. Never rasterize icons for web delivery — SVGs are resolution-independent, style-inheriting, and typically smaller than equivalent PNG at display sizes.
+- **Icons and logos:** SVG only. Never rasterize icons for web delivery - SVGs are resolution-independent, style-inheriting, and typically smaller than equivalent PNG at display sizes.
 - **Illustrations:** SVG if illustration complexity allows; WebP for complex multi-color illustrations that would produce large SVG files.
 
 **Responsive images with `srcset`:**
@@ -92,7 +92,7 @@ Always specify `width` and `height` attributes. These allow the browser to reser
 
 **Lazy loading below-the-fold images:** Apply `loading="lazy"` to all images that are not visible in the initial viewport. This defers their network requests until the user scrolls toward them, reducing initial page weight significantly on image-heavy pages.
 
-**The LCP image must never be lazy-loaded.** The LCP image — typically the hero image or first product image — must load as fast as possible. Apply `fetchpriority="high"` to signal the browser to deprioritize other resources in favor of this image:
+**The LCP image must never be lazy-loaded.** The LCP image - typically the hero image or first product image - must load as fast as possible. Apply `fetchpriority="high"` to signal the browser to deprioritize other resources in favor of this image:
 
 ```html
 <img
@@ -121,7 +121,7 @@ Smooth animation requires a consistent 60 frames per second, which means each fr
 
 **Never animate layout-triggering properties.** Properties like `width`, `height`, `margin`, `padding`, `top`, `left`, `right`, `bottom`, `border-width`, and `font-size` force the browser to recalculate layout for the entire affected subtree on every animation frame. This is guaranteed to exceed the 10ms JS budget on all but the simplest pages.
 
-**Only animate `transform` and `opacity`.** These two properties are composited by the GPU independently of the browser's main thread layout system. An animation that only changes `transform` and `opacity` does not trigger layout or paint — it executes entirely on the compositor thread, achieving smooth 60fps even when the main thread is busy:
+**Only animate `transform` and `opacity`.** These two properties are composited by the GPU independently of the browser's main thread layout system. An animation that only changes `transform` and `opacity` does not trigger layout or paint - it executes entirely on the compositor thread, achieving smooth 60fps even when the main thread is busy:
 
 ```css
 /* DO: GPU-composited, no layout cost */
@@ -140,7 +140,7 @@ Smooth animation requires a consistent 60 frames per second, which means each fr
 }
 ```
 
-Use `will-change: transform, opacity` on elements that will be animated to promote them to their own compositor layer before the animation begins. Use this property sparingly — each compositor layer consumes GPU memory, and overuse causes memory pressure on mobile devices.
+Use `will-change: transform, opacity` on elements that will be animated to promote them to their own compositor layer before the animation begins. Use this property sparingly - each compositor layer consumes GPU memory, and overuse causes memory pressure on mobile devices.
 
 ---
 
@@ -148,7 +148,7 @@ Use `will-change: transform, opacity` on elements that will be animated to promo
 
 Bundle size is a proxy for parse time and execution time, both of which block interactivity. Every kilobyte of JavaScript must be justified against its user-visible value.
 
-**Initial load budget:** The JavaScript required to render the first meaningful page interaction must be ≤170KB gzipped. This budget includes the framework runtime, routing, and any above-the-fold component logic. At average mobile connection speeds (≈1.5 Mbps download), 170KB gzipped represents approximately 900ms of transfer time — already a significant portion of a 2.5s LCP budget before parse and execution time is counted.
+**Initial load budget:** The JavaScript required to render the first meaningful page interaction must be ≤170KB gzipped. This budget includes the framework runtime, routing, and any above-the-fold component logic. At average mobile connection speeds (≈1.5 Mbps download), 170KB gzipped represents approximately 900ms of transfer time - already a significant portion of a 2.5s LCP budget before parse and execution time is counted.
 
 **Code splitting strategy:**
 - **Route-level splitting:** Each page/route is a separate async chunk. Users only download code for the pages they visit.
@@ -177,9 +177,9 @@ function Dashboard() {
 
 Web fonts are blocking resources in the critical rendering path. Every additional font family, weight, and style file adds to the payload that must load before text can be rendered.
 
-**Maximum two font families per product.** One for headings/display, one for body and UI. This constraint is both a performance budget and a typographic discipline — every additional font family increases visual complexity and requires justification against a clear aesthetic goal.
+**Maximum two font families per product.** One for headings/display, one for body and UI. This constraint is both a performance budget and a typographic discipline - every additional font family increases visual complexity and requires justification against a clear aesthetic goal.
 
-**`font-display: swap` is required.** This CSS property instructs the browser to use a system fallback font immediately and swap in the web font when it loads. Without `swap`, text is invisible during font loading (FOIT — Flash of Invisible Text), which directly hurts LCP and user experience:
+**`font-display: swap` is required.** This CSS property instructs the browser to use a system fallback font immediately and swap in the web font when it loads. Without `swap`, text is invisible during font loading (FOIT - Flash of Invisible Text), which directly hurts LCP and user experience:
 
 ```css
 @font-face {
@@ -215,7 +215,7 @@ Web fonts are blocking resources in the critical rendering path. Every additiona
 
 ## 7. Lighthouse CI Integration
 
-Automated performance regression testing prevents gradual budget creep — small performance regressions accumulate unnoticed through routine development until the product is significantly slower than its target.
+Automated performance regression testing prevents gradual budget creep - small performance regressions accumulate unnoticed through routine development until the product is significantly slower than its target.
 
 **GitHub Actions workflow:** Create `.github/workflows/lighthouse.yml` to run Lighthouse CI on every pull request against a staging deployment:
 
@@ -265,35 +265,35 @@ jobs:
 
 ## 8. React Runtime Performance
 
-React's rendering model is optimized by default, but naive usage patterns — particularly around object identity, memoization, and context — can introduce significant re-render cascades that degrade INP and animation smoothness.
+React's rendering model is optimized by default, but naive usage patterns - particularly around object identity, memoization, and context - can introduce significant re-render cascades that degrade INP and animation smoothness.
 
 **Source: nextlevelbuilder/ui-ux-pro-max-skill (MIT)**
 
 ### `React.memo()`
 
-Use `React.memo()` only when the React DevTools Profiler demonstrates that a component re-renders with identical props and the render takes ≥50ms. `React.memo()` adds overhead — a shallow prop comparison on every parent render — that only pays for itself when the avoided render cost exceeds the comparison cost. Never memoize components that receive primitive values (strings, numbers, booleans) as props; React's reconciler handles these efficiently without memoization.
+Use `React.memo()` only when the React DevTools Profiler demonstrates that a component re-renders with identical props and the render takes ≥50ms. `React.memo()` adds overhead - a shallow prop comparison on every parent render - that only pays for itself when the avoided render cost exceeds the comparison cost. Never memoize components that receive primitive values (strings, numbers, booleans) as props; React's reconciler handles these efficiently without memoization.
 
 ### `useMemo()`
 
-Use `useMemo()` for computationally expensive derivations — sorting or filtering large arrays, running statistical calculations, or building complex objects from raw data — where the computation takes more than 1ms and the dependencies are stable across most renders. Do not use `useMemo()` to memoize simple object creation for the purpose of maintaining reference identity; instead, move the object outside the component or into a `useRef` if it is genuinely static.
+Use `useMemo()` for computationally expensive derivations - sorting or filtering large arrays, running statistical calculations, or building complex objects from raw data - where the computation takes more than 1ms and the dependencies are stable across most renders. Do not use `useMemo()` to memoize simple object creation for the purpose of maintaining reference identity; instead, move the object outside the component or into a `useRef` if it is genuinely static.
 
 ### `useCallback()`
 
-Use `useCallback()` when a function is passed as a prop to a memoized child component and the function's creation would invalidate the child's memo on every parent render. `useCallback()` is not needed for event handlers attached directly to DOM elements (`onClick`, `onChange`) — the DOM does not compare function references. The cost of useCallback (closure creation + dependency comparison) is only justified when it prevents a measurable re-render cascade.
+Use `useCallback()` when a function is passed as a prop to a memoized child component and the function's creation would invalidate the child's memo on every parent render. `useCallback()` is not needed for event handlers attached directly to DOM elements (`onClick`, `onChange`) - the DOM does not compare function references. The cost of useCallback (closure creation + dependency comparison) is only justified when it prevents a measurable re-render cascade.
 
 ### Re-render Root Causes
 
-The two most common causes of unnecessary re-renders are (1) new object and array references created inline in JSX, and (2) Context value changes propagating to all consumers. Avoid `value={{ key: value }}` inline in Context providers — this creates a new object reference on every parent render, re-rendering all consumers. Memoize the context value with `useMemo()` or split contexts so consumers only subscribe to the slice of state they need.
+The two most common causes of unnecessary re-renders are (1) new object and array references created inline in JSX, and (2) Context value changes propagating to all consumers. Avoid `value={{ key: value }}` inline in Context providers - this creates a new object reference on every parent render, re-rendering all consumers. Memoize the context value with `useMemo()` or split contexts so consumers only subscribe to the slice of state they need.
 
 Avoid anonymous arrow functions as props to performance-critical components: `<List onItemClick={() => handleClick(id)} />` creates a new function reference on every render of the parent.
 
 ### Suspense Boundaries
 
-Place Suspense boundaries at two levels: route-level (wrapping each page's lazy-loaded component tree) and per-expensive-async-boundary (wrapping individual data-fetching components that have independent loading states). The fallback UI must match the approximate layout dimensions of the loaded content — a fallback that occupies significantly different space than the loaded component will cause CLS when the content arrives.
+Place Suspense boundaries at two levels: route-level (wrapping each page's lazy-loaded component tree) and per-expensive-async-boundary (wrapping individual data-fetching components that have independent loading states). The fallback UI must match the approximate layout dimensions of the loaded content - a fallback that occupies significantly different space than the loaded component will cause CLS when the content arrives.
 
 ### React Server Components vs. Client Components
 
-Use RSC (React Server Components) for data fetching, static markup generation, and components that do not require browser APIs or user interaction. RSC output is streamed as HTML — it adds zero JavaScript to the client bundle. Use client components (`'use client'`) only when browser APIs (localStorage, geolocation, IntersectionObserver) or event handlers (onClick, onChange) are required. Co-locate client components as deep in the component tree as possible so that only the interactive leaf nodes are included in the client bundle, not their entire parent subtrees.
+Use RSC (React Server Components) for data fetching, static markup generation, and components that do not require browser APIs or user interaction. RSC output is streamed as HTML - it adds zero JavaScript to the client bundle. Use client components (`'use client'`) only when browser APIs (localStorage, geolocation, IntersectionObserver) or event handlers (onClick, onChange) are required. Co-locate client components as deep in the component tree as possible so that only the interactive leaf nodes are included in the client bundle, not their entire parent subtrees.
 
 ### Virtualization