diff --git a/packages/examples-react/stories/ElementTiming.stories.tsx b/packages/examples-react/stories/ElementTiming.stories.tsx
index 2024d1a..e836a69 100644
--- a/packages/examples-react/stories/ElementTiming.stories.tsx
+++ b/packages/examples-react/stories/ElementTiming.stories.tsx
@@ -57,9 +57,11 @@ function ElementTimingDemo({imageCount = 6, staggerMs = 400}: {imageCount?: numb
   // Generate deterministic placeholder colors
   const hue = (i: number) => (i * 137) % 360
 
-  // Element Timing API only tracks <img> elements and text nodes rendered as
-  // contentful paint. We use dynamically-generated SVG data-URIs as img sources
-  // so each card is a real image element that the API observes.
+  // Element Timing API only tracks *eligible* elements (images, SVG images,
+  // videos with poster frames, contentful background-images, and plain text).
+  // Arbitrary custom elements aren’t reported, and anything inside a shadow
+  // root is ignored. We generate SVG data‑URI images here so each card counts as
+  // a real <img> element the API will observe.
   const placeholderSrc = (i: number) => {
     const h = hue(i)
     const h2 = h + 60
diff --git a/packages/examples-react/stories/Metrics.mdx b/packages/examples-react/stories/Metrics.mdx
index 5530607..b7b7ec8 100644
--- a/packages/examples-react/stories/Metrics.mdx
+++ b/packages/examples-react/stories/Metrics.mdx
@@ -452,6 +452,9 @@ Collected via [Element Timing API](https://w3c.github.io/element-timing/) (optim
 <div elementtiming="main-content">Important content</div>
 ```
 
+> [!NOTE]
+> Only timing‑eligible elements emit entries. Per the [Element Timing spec](https://w3c.github.io/paint-timing/#timing-eligible) that means things like images, SVG images, postered videos, contentful background-images, and text nodes. Custom elements aren't directly supported, and items hidden inside shadow DOM will be ignored. Ensure the attribute is applied to a supported node to see it show up in the panel.
+
 ---
 
 ## Browser Compatibility
diff --git a/packages/examples-react/stories/Setup.mdx b/packages/examples-react/stories/Setup.mdx
index 92d5367..45dc9ed 100644
--- a/packages/examples-react/stories/Setup.mdx
+++ b/packages/examples-react/stories/Setup.mdx
@@ -99,3 +99,7 @@ To track specific elements with the Element Timing collector, add the `elementti
 ```
 
 Each tracked element will appear individually in the Element Timing section of the panel with its render time.
+
+> [!IMPORTANT]
+> The browser only generates timing entries for *eligible* elements – see the [Element Timing spec](https://w3c.github.io/paint-timing/#timing-eligible) for details. In practice this means plain `<img>`s, SVG `<image>`s, videos with a poster frame, elements with contentful `background-image`s, or text nodes. Custom elements themselves are not timing‑eligible, and anything inside a shadow root is currently ignored. Make sure the attribute is on an element the browser can actually time.
+
diff --git a/packages/storybook-addon-performance-panel/README.md b/packages/storybook-addon-performance-panel/README.md
index 5d2601b..60b20f5 100644
--- a/packages/storybook-addon-performance-panel/README.md
+++ b/packages/storybook-addon-performance-panel/README.md
@@ -104,6 +104,7 @@ The addon consists of two main parts:
 - **Individual Elements**: Render time for each tracked element
   - Add `elementtiming="identifier"` attribute to elements you want to track
   - Useful for measuring when hero images, key content, or specific UI elements render
+  - Only *timing‑eligible* elements produce entries. The browser will ignore arbitrary custom elements or nodes inside shadow DOM. Valid targets include images (`<img>`), SVG `<image>`s, videos with poster frames, elements with contentful `background-image`s, and text nodes. See the [Element Timing spec](https://w3c.github.io/paint-timing/#timing-eligible) for details.
 
 ### Layout Stability
 - **CLS**: Cumulative Layout Shift score (Core Web Vital)