Not breaking your app

The tool has to insert nodes into your page to resolve tokens in context, which is exactly the sort of thing that quietly corrupts what it is measuring. So:

• Probes go inside the inspected element, never beside it. A sibling changes that element's own :nth-child/:last-child matching, which would corrupt the values being read off it. The cost of that choice is the element's own children: a probe is an element child, so for as long as one is present, :last-child, :nth-last-child and :only-child match differently among them. Nothing outside the inspected element moves.
• Everything injected is position: absolute, so it is not a flex or grid item and adds no gap, no track and no reordering.
• Everything is removed in a finally. The one path that must touch your DOM — swapping a theme class on an ancestor, for a token declared with a selector only that ancestor can match — is synchronous, so no frame is ever painted in the wrong variant, and it is unwound even if something throws.
• A failure shows up as a message in the panel, not as a broken page.

Inspecting every element on the playground page, twice, produces zero layout differences and zero leftover nodes. The same holds for a full-page record() sweep, which probes every element rather than one.

How that is checked

In a real browser, in CI, and by sampling the page at the moment a probe is inserted rather than afterwards. That distinction is the whole point: probes exist for microseconds inside a synchronous call, so nothing observing from outside — a MutationObserver, a rendered frame, an assertion after the call — can ever see the DOM while they are in it. An after-the-fact check passes no matter how badly the page was disturbed.

The test intercepts appendChild, and at each insertion compares a style and layout signature for every element in the document against the state before. Two windows are allowed, and they are the two described above: the inspected element's own children may match structural pseudo-classes differently, and while a variant class is off an ancestor the whole page is in that variant. Everything else must be identical, every probe must be removed, and every attribute must be back.

It is verified by breaking it. Insert probes as siblings, skip the disposal, or drop the class restore, and the relevant assertion fails — a test that has only ever passed is not yet evidence of anything.

Trust and diagnostics

__xray.diagnose();
// { rules: 134, tokensInScope: 1831, enumeratesCustomProperties: true,
//   axes: [{ name: 'mode', variants: ['dark','light'], tokens: 182 }, …],
//   dismissedAxes: [], unreadableStylesheets: [], shadowRoots: 1 }

Cross-origin stylesheets cannot be read. Rather than guess, xray says so: the panel shows a warning and rules from those sheets are not considered.

Token values are unaffected, because the browser resolves those — a var() pointing at a token declared only in an unreadable sheet is reported as fine, not as missing.

Shadow DOM

Elements inside a shadow root are inspected with that root's own stylesheets, and the walk up to find a theme provider steps over shadow boundaries onto the host — so a web component's internals still resolve against the theme that wraps the component.