Custom Elements

An encapsulated DOM subtree attached to a custom element that isolates its internal structure and styles from the main document. While Shadow DOM prevents CSS and JavaScript conflicts, it creates a semantic boundary that AI parsers cannot easily cross. To maintain accessibility, developers must use declarative shadow DOM or programmatically expose internal semantics via aria-owns, aria-labelledby, and slot-based content projection. Without these techniques, the accessibility tree remains empty, rendering the component invisible to assistive technologies and AI crawlers.

A set of predefined roles—including banner, navigation, main, complementary, and contentinfo—added to HTML elements to programmatically identify distinct page regions. When building custom elements, assigning landmark roles ensures AI agents can efficiently navigate the document outline and understand the purpose of each component. Key practices:

• Use role="main" on the primary content wrapper
• Apply role="navigation" to custom menu components
• Ensure all content resides within a landmark region
• Avoid over-nesting landmarks, which confuses parser hierarchy

The browser's algorithm for determining the programmatically determined, human-readable label for a UI element. For custom elements, the accessible name is calculated from sources in this order of precedence:

• aria-labelledby (highest priority)
• aria-label
• Host language labeling (e.g., <label> association)
• Inner text content (lowest priority)

AI agents rely on accessible names as the primary identifier for interactive components. A custom button without a computed name will appear as an anonymous, unlabeled control to both screen readers and generative AI parsers.

The practice of using HTML elements according to their intrinsic, programmatically determined meaning rather than solely for visual presentation. Custom elements extend this vocabulary, but must be built on a foundation of native semantics:

• Use <header>, <main>, <footer> for document structure
• Employ <article>, <section>, <aside> for content partitioning
• Leverage <nav>, <ol>, <ul> for navigation and lists

When custom elements wrap or replace native elements, they must preserve or re-implement the original semantic roles using ARIA to maintain interpretability by AI crawlers and knowledge graph extractors.

A parallel structure generated by the browser from the DOM that exposes semantic information, properties, and relationships exclusively to assistive technologies and programmatic agents. For custom elements, the accessibility tree is the critical bridge to AI interpretability. Key considerations:

• Shadow DOM boundaries can block tree construction unless slots are used
• aria-hidden="true" removes elements from the tree entirely
• Custom interactive elements must expose role, name, and state
• The tree reflects computed properties, not just markup

AI crawlers increasingly consume the accessibility tree directly to understand component semantics.

The principle that the meaning, state, and value of a user interface component can be reliably interpreted by software—including AI agents—through standardized, machine-readable properties. Custom elements achieve this through:

• Explicit ARIA attributes (aria-expanded, aria-selected, aria-valuenow)
• Semantic HTML foundations within the component's template
• Declarative state management that syncs DOM attributes with component logic
• Structured data annotations (JSON-LD, Microdata) for entity-rich components

Without programmatic determinism, AI models must rely on visual heuristics and guesswork, leading to misinterpretation of component function and content.