diff --git a/docs/motion-and-high-refresh.md b/docs/motion-and-high-refresh.md
index bf9da6ed..9fa2d07b 100644
--- a/docs/motion-and-high-refresh.md
+++ b/docs/motion-and-high-refresh.md
@@ -138,7 +138,11 @@ Suggested order: A1 → A2 → A3 in parallel with A4; then A5; A6 closes the mi
 
 ---
 
-## 7. Review rule — no magic UI durations
+## 7. Theme morph cost
+
+`AnimatedQueryaTheme` / `ShadcnAnimatedTheme` notify **app-wide** theme dependents on every animation tick. That is acceptable only as an **opt-in** Preference (`themeAnimationEnabled`, default **false**) and only when Motion is Full. Motion Off / preference off must snap. Do not enable theme animation by default without a profiled 120 Hz pass ([perf-baseline.md](perf-baseline.md) §14).
+
+## 8. Review rule — no magic UI durations
 
 When reviewing PRs that touch animation:
 
@@ -157,7 +161,7 @@ When reviewing PRs that touch animation:
 
 Checklist for 120 Hz verification: [perf-baseline.md](perf-baseline.md) § Fluid shell.
 
-## 8. References
+## 9. References
 
 - Flutter engine — high refresh rate gap: `flutter/flutter#160952`, `#90675` (ProMotion scrolling), `#94508` (`CADisableMinimumFrameDurationOnPhone` default).
 - `refresh_rate` package (query/unlock/overlay/benchmark, all platforms): https://pub.dev/packages/refresh_rate
@@ -168,7 +172,7 @@ Checklist for 120 Hz verification: [perf-baseline.md](perf-baseline.md) § Fluid
 
 ---
 
-## 9. Measured results (0.4.4)
+## 10. Measured results (0.4.4)
 
 The table below shows the measured refresh rates and frame times on target monitors before and after the 0.4.4 implementation (using a profile build, measured with DevTools and `QUERYA_REFRESH_OVERLAY=true`):
 
diff --git a/docs/perf-baseline.md b/docs/perf-baseline.md
index 141df5bd..feaa6260 100644
--- a/docs/perf-baseline.md
+++ b/docs/perf-baseline.md
@@ -37,4 +37,6 @@ Repeat on a **120 Hz** display (budget **≤ 8.3 ms** build+raster). Prefer prof
 12. **Results modes**: idle → run (spinner) → grid; force an error — mode keys morph; scrolling the grid must not fade rows.
 13. **Dialog / dropdown**: open/close `showAppDialog` and a `QueryaDropdown` — enter fade-slide, exit uses exit curve; Motion Off snaps.
 14. **Theme cross-fade**: Preferences → enable Animate theme + Motion Full; switch dark/light — shadcn + `AnimatedQueryaTheme` lerp. Repeat with Motion Off (snap).
-15. **Split settle**: drag the connections sidebar handle and the SQL/results vertical split with a fling — mid-drag stays 1:1; release may soft-settle. Focus the handle — ring uses motion tokens (not mid-drag animation). Expect **layout** of editor/results each tick (constraint/flex); paint is isolated via `RepaintBoundary` on panes — do not add mid-drag springs to “fix” that cost.
+    **Cost note:** theme morph rebuilds app-wide InheritedTheme dependents every tick — keep **Animate theme** **off by default** (`ThemeController`); only enable for demos/profile. Never ship it default-on without a 120 Hz timeline.
+15. **Split settle**: drag the connections sidebar handle and the SQL/results vertical split with a fling — mid-drag stays 1:1; release may soft-settle. Focus the handle — ring uses motion tokens (not mid-drag animation).
+