How do you decide which selectors a shared widget's JavaScript uses to find its own DOM nodes, so that a CSS or markup refactor cannot silently break its behaviour?

## The problem: selectors are a coupling surface Every selector string in JavaScript is an invisible dependency on markup that someone else edits. `container.querySelector('.card__footer .btn-primary')` names four things — two class conventions, a nesting relationship, and an implicit assumption about which `.btn-primary` comes first. None of them are enforced anywhere. A designer renaming `.btn-primary`, or a developer adding a wrapper `<div>` for a grid, breaks behaviour with no compile error, no type error, and often no runtime error either — `querySelector` simply returns `null` and the code takes the `?.` path into silence. The question is not "which selector is fastest". It is "which selector expresses something the markup owner has agreed not to change". ## Separate the vocabularies The durable rule is one vocabulary per consumer: - **Classes belong to CSS.** They are presentational and are expected to churn. - **`data-*` attributes belong to behaviour.** `data-menu-trigger`, `data-row-id`, `data-state="open"` — these say what a node *is* in the widget's model, not how it looks. - **Test ids belong to tests**, and it is a legitimate design choice either to reuse the behaviour hooks or to keep a separate `data-testid` namespace. Reusing them keeps markup lean and guarantees tests exercise the same anchors as the code; separating them lets you strip test ids from production builds. Pick one and write it down. - **`id` belongs to the document**, and a shared widget rendered more than once on a page cannot own one. Prefer attributes for anything a component instantiates repeatedly. A useful test of a hook: if a pure-visual redesign that changes no behaviour would require touching it, it is the wrong hook. ## Anchor and shallow-scope every query Two mechanics keep queries honest. **Scope to the widget root.** Never query from `document` inside a component; query from the root element the component was handed. Otherwise a second instance on the page, or an unrelated element with the same class, wins the race. **Anchor the selector.** An element-scoped `querySelectorAll` filters results to descendants but still matches the selector against the whole tree, so an ancestor part such as `.card` can be satisfied by an element outside the widget. Writing `:scope > [data-list]` or `:scope [data-row]` removes that ambiguity and simultaneously keeps the query shallow. ```js class Menu { constructor(root) { this.root = root; this.trigger = root.querySelector(':scope > [data-menu-trigger]'); this.panel = root.querySelector(':scope > [data-menu-panel]'); if (!this.trigger || !this.panel) { throw new Error('Menu: markup is missing data-menu-trigger or data-menu-panel'); } } } ``` ## Ban structural selectors `div > div:nth-child(2)`, `.row span:last-of-type`, `parentElement.parentElement` — all of these encode the current shape of the DOM rather than its meaning. Any wrapper added for layout, any conditional element, any localisation that reorders content shifts the match. Where you need to walk upwards, `closest('[data-row]')` is depth-independent and survives added wrappers; where you need to go down, a named hook is. ## Fail loudly, once Resolve required nodes at construction time and treat a missing hook as a programming error: throw, or log an error naming the widget and the missing hook. The anti-pattern is `this.panel?.classList.add('open')` scattered through the code, which converts a broken contract into a widget that quietly does nothing — the hardest class of frontend bug to notice, because nothing appears in the console and nothing turns red in CI. Caching resolved references also removes repeated queries from hot paths. The tradeoff is that a cached reference goes stale if the subtree is re-rendered; if the widget owns its own DOM this is fine, and if it does not, re-resolve on the mutation that replaced the subtree rather than on every interaction. ## Interpolation and escaping Any selector built from data needs `CSS.escape()`, or, better, no interpolation at all: `[data-row-id]` plus a `dataset` comparison, or `getElementById` for raw id strings, avoids the escaping question entirely. A selector assembled by string concatenation from a database value is both a throw site and, in the worst case, a place where attacker-controlled data changes what your code selects. ## Where the question dissolves If the widget owns a shadow root, its internal selectors are genuinely private — outside CSS and outside queries cannot reach in, so the coupling problem largely disappears for internals. Similarly, when a component framework hands you a direct node reference, that reference is a stronger contract than any selector and should be preferred. The discipline above is for the large middle ground: framework-free widgets, progressive enhancement layers, analytics and instrumentation code, and anything that must attach to markup another team renders.