diff --git a/docs/catalog/components/motion-blur.mdx b/docs/catalog/components/motion-blur.mdx
index d510e853130..265debc0017 100644
--- a/docs/catalog/components/motion-blur.mdx
+++ b/docs/catalog/components/motion-blur.mdx
@@ -26,8 +26,9 @@ That writes one file: `compositions/components/motion-blur.html`.
```
@@ -435,19 +751,31 @@ That writes one file: `compositions/components/motion-blur.html`.
## Usage
-Paste the snippet into your composition, then call `attachMotionBlur()` after your GSAP tweens and before registering `window.__timelines`.
+Paste the snippet into your composition, then put `data-hf-motion-blur` on any element your timeline animates. Nothing else to call, and no order to get wrong.
+
+```html
+
+```
+
+The element finds its own timeline: its nearest `[data-composition-id]` ancestor names the key, and the snippet reads `window.__timelines[key]`. An element whose composition never registers a timeline says so in the console instead of rendering sharp in silence.
+
+`attachMotionBlur()` stays available for a target built after the page has settled. It has an ordering contract the attribute does not: call it after every tween is defined, so the timeline's final duration is known.
```html
tl.set(document.body, {}, DATA_DURATION);
-attachMotionBlur("#my-box", tl, {
+attachMotionBlur("#late-box", tl, {
shutterAngle: 720, // degrees of the frame interval the shutter is open
samplesPerFrame: 16, // sub-intervals of the window; 17 duplicates at 1/16 each
});
-
-window.__timelines = window.__timelines || {};
-window.__timelines["my-composition"] = tl;
```
## How it works
diff --git a/docs/catalog/components/shutter-slam.mdx b/docs/catalog/components/shutter-slam.mdx
index d32bb6ddcc6..aeed58fd7af 100644
--- a/docs/catalog/components/shutter-slam.mdx
+++ b/docs/catalog/components/shutter-slam.mdx
@@ -154,16 +154,48 @@ you paste it into.
\n \n \n \n \n \n\n
\n
3.0seconds
\n
shape
\n
text
\n
\n
\n
\n
\n
DRIFT
\n
slow
\n
\n\n
\n
1.5seconds
\n
shape
\n
text
\n
\n
\n
\n
\n
GLIDE
\n
medium
\n
\n\n
\n
0.7seconds
\n
shape
\n
text
\n
\n
\n
\n
\n
RUSH
\n
fast
\n
\n\n
\n
\n 0.35seconds\n
\n
shape
\n
text
\n
\n
\n
\n
\n
BLAST
\n
faster
\n
\n\n
\n
0.2seconds
\n
shape
\n
text
\n
\n
\n
\n
\n
WARP
\n
extreme
\n
\n\n \n
\n \n