Selector Stability

Selector stability is the designers contract with the agent. It guarantees that the buttons forms and links an agent learned to use last week will still be findable after your next refactor. The shift from 2024 to 2026 made this non optional. In 2024 you could ship a div with an onClick and some fancy styling and call it a button. In 2026 that pattern breaks every agent that tries to drive your product. The fix lives in three decisions. Use real semantic HTML. Button elements for buttons. Select elements for dropdowns. Never fake it with divs. Add data-testid attributes to every important surface so agents and tests have a stable hook that survives class name changes and component rewrites. Keep accessible names identical across releases. If your primary action is labeled Create Campaign today it stays Create Campaign even if the design team wants to test new microcopy. Linear mastered this because they built the product API first. The UI is just one client. Every action has a name that matches across their API their keyboard shortcuts and their DOM. Agents can trust Linear the same way developers trust their API endpoints. This layer sits right in the middle of the five layer stack from the Designing for Agents Watching article because without stable selectors the other layers have nothing to grab onto.

Selector stability is not throwing a few ARIA labels on your existing div soup and calling the job done. It is not the same thing as traditional accessibility work although it rides on top of those practices. Accessibility serves humans with screen readers. Selector stability serves agents that read the DOM like an API. It is not a occasional task you remember during launch week. The stability must hold through every sprint and every design refresh. It is not a problem you can solve with smarter models that look at screenshots. Vision based agents are useful but they are slower and more error prone than a clean selector query. A data-testid approach wins every time on speed and reliability. It is not about locking your visual design in amber. Change the look. Change the layout. Change the spacing. Just do not change how the agent finds the thing it needs to activate. Too many teams still treat their rendered HTML as a disposable byproduct of their React components. They let styled components generate random class names. They hide controls behind hover states that agents cannot trigger. They use generic text like Click here that gives no clue what the action actually does. Each choice turns their product into a moving target that agents learn once and then abandon.

The gold standard concrete example is Linear in 2025. Every issue has a resolve button with data-testid="issue-resolve-button" and the accessible name Resolve issue. That name and selector have remained unchanged through multiple major updates. When Cursor wants to bulk update issues it does not scan the page for a green checkmark icon. It directly targets the stable selector and invokes the action with confidence. Stripe follows the same religion. Their checkout flows and dashboard actions carry selectors that match their well documented API verbs. OpenAI Operator can complete purchases on sites powered by Stripe because the machine plane matches the human one perfectly. Contrast that with what happened to a popular no code platform in 2024. They performed a seemingly innocent upgrade to their component library. Buttons that used to have predictable data attributes became buried inside three layers of shadow roots with dynamically generated ids. Every agent integration their users had built stopped working. The company issued emergency documentation and even then many users moved to competitors whose interfaces were more stable. Vercel v0 shows the pattern in their rendering pipeline. The accept and reject surfaces for generated code have stable handles that allow agents to iterate without breaking. Raycast commands and Replit workspace controls follow the same discipline. These products do not treat selector stability as a bolt on feature. They treat the DOM as a first class surface that deserves the same attention as their marketing site or their API reference docs. The result is agents that just work instead of agents that constantly need new instructions.

Deploy selector stability any time you are building a surface that carries an action an agent might want to call. Dashboards with filters. Forms with submissions. Editors with publish buttons. Navigation with primary flows. If the article Designing for Agents Watching calls it a tool surface then it needs selector stability. Start during design. Put the stable names in your Figma components. Add the test ids on first implementation. Review them during every code review the same way you review API changes. The payoff comes when agents discover your product and integrate without custom scrapers or constant maintenance. You can skip it for static marketing pages that contain zero interactive elements. Early throwaway prototypes also do not need the full treatment. One off internal tools with a known small set of human users can slide. But the moment your product faces the public and wants to participate in the agent economy this discipline becomes mandatory. Teams that treat it as optional watch their conversion rates for agent driven traffic stay at zero. The ones that ship it from day one become the default platforms that every new agent adds to their supported list first. Retrofitting after the fact is painful. You end up with mapping tables and deprecation warnings and support burden that never goes away. Run the seven question dual user audit before every release. If stable selector is not checked your product is only half shipped.

Selector stability turns your interface from a fragile picture into a dependable platform that agents can drive without guesswork.