# ARIA Patterns for Developers: Use Native HTML First

Traditional Chinese version: [https://accesserty.com/ai/guides/aria-patterns-for-developers.md](https://accesserty.com/ai/guides/aria-patterns-for-developers.md)

Page version: [https://accesserty.com/en/guides/aria-patterns-for-developers/](https://accesserty.com/en/guides/aria-patterns-for-developers/)

Last updated: 2026-09-29

Compare native details with a working button-based ARIA disclosure. Check names, state, keyboard behavior and visibility together, then use W3C APG for other interaction patterns.

## Summary

- Choose native elements that fit the task, then decide whether ARIA is needed.
- ARIA expresses semantics and state; it does not implement keyboard actions or visibility changes.
- When following APG Patterns, implement keyboard behavior, focus management, and state updates together.

## Use native HTML first, then add ARIA only when needed

The first rule of ARIA is straightforward: use native HTML before adding ARIA. Elements such as button, a, input, select, details, and summary already carry semantics and keyboard behavior that browsers and assistive technologies understand.

If a div or span is used to recreate a button, menu, or tab interface, the team must implement name, role, state, keyboard behavior, and focus management manually. That is usually more error-prone than using native elements.

## Start with native disclosure: details and summary

For optional information that readers can expand, first consider details/summary. This native version needs no extra role, aria-expanded or toggle script. Still verify it with your supported browsers and assistive technology.

```html
<details>
  <summary>Delivery details</summary>
  <p>Tracking information is provided after dispatch.</p>
  <a href="/en/contact/">Ask about delivery</a>
</details>
```

This interaction illustrates a fictional shop, not an Accesserty delivery service. Expect Tab to reach summary and Enter/Space to toggle the content; the inner link is skipped when collapsed. This is a disclosure, not a menu or tabs, so do not add unrelated arrow-key behavior.

## When you need custom structure: a working ARIA disclosure

If native details does not fit the actual requirement, keep native button keyboard behavior and use aria-expanded for state. aria-controls points to the controlled region; it does not toggle visibility. Until the script runs, the content remains readable and the inactive trigger stays hidden.

```html
<button id="delivery-toggle" type="button" hidden
  aria-expanded="false" aria-controls="delivery-panel">
  Delivery details
</button>
<div id="delivery-panel">
  <p>Tracking information is provided after dispatch.</p>
  <a href="/en/contact/">Ask about delivery</a>
</div>
<script>
{
  const toggle = document.getElementById('delivery-toggle');
  const panel = document.getElementById('delivery-panel');
  toggle.addEventListener('click', () => {
    const expanded = toggle.getAttribute('aria-expanded') === 'true';
    panel.hidden = expanded;
    toggle.setAttribute('aria-expanded', String(!expanded));
  });
  panel.hidden = true;
  toggle.hidden = false;
}
</script>
```

Put the complete HTML and script on an isolated test page. After initialization, content is collapsed and the name stays “Delivery details.” Enter/Space each toggle expanded and hidden once while focus stays on the button. Tab reaches the inner link only when expanded. Listen for click because a native button already supports keyboard activation; an additional keydown toggle can undo the action. This is one instance: use unique IDs and separate bindings for multiple disclosures. With CSP, move the code into an allowed external script rather than weakening the policy.

## Do not copy only the role

ARIA changes the semantics exposed to assistive technologies. It does not add interaction behavior. role="button" does not make a div support Enter or Space automatically, and aria-expanded="true" does not open content or manage focus by itself.

Incorrect ARIA can make the visual interface look fine while exposing the wrong signal to assistive technologies. That is harder to debug because the issue often appears only in screen reader, voice control, or keyboard workflows.

## Use APG patterns for behavior as well as semantics

The W3C ARIA Authoring Practices Guide (APG) offers implementation guidance for interactive components. Its patterns can inform tabs, dialogs, accordions, menu buttons and comboboxes, but copying one or two attributes is not enough. Check keyboard behavior, focus, accessible names, roles, states and relationships between HTML elements together. Following an example does not establish whole-site WCAG conformance.

- Name: the control name users hear or see is clear.
- Role: the role matches the component’s actual purpose.
- State: expanded, selected, checked, disabled, and similar states update immediately.
- Keyboard: Arrow keys, Enter, Space, Escape, and Tab follow the expected pattern.
- Focus: after opening, closing, or switching content, focus lands in a reasonable place.

## Common mistakes

ARIA issues often appear in custom components, design system components, and third-party widgets. Once those components are reused, the same defect spreads across many pages, so the fix should usually happen at the component layer.

- Adding a role without implementing keyboard behavior.
- Using aria-label in a way that overrides clearer visible text.
- Using aria-hidden on content that can still receive focus or be operated.
- Failing to sync aria-expanded, aria-selected, aria-current, and similar states with the visual state.
- Dialogs, menus, or tabs appear usable visually but manage focus in unexpected ways.

## Where DevCheck and UI Kit fit

DevCheck can help find some ARIA and semantic issues on the current page, including after interaction. But it cannot guarantee that a pattern is fully implemented, because keyboard behavior, focus management, and content understanding still require real-flow review.

UI Kit addresses the component layer. For common components, the earlier native HTML, ARIA, keyboard, and focus rules are built into the foundation, the less likely each page is to repeat the same defects.

## Related pages

- [Accesserty DevCheck](<https://accesserty.com/en/devcheck/>) — Run browser-based checks on local builds, staging pages, authenticated screens, and interactive states.

- [ARIA glossary page](<https://accesserty.com/en/glossary/aria/>)

- [Accesserty UI Kit](<https://accesserty.com/en/uikit/>)

- [W3C APG: Disclosure pattern](<https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/>)

- [HTML Standard: the details element](<https://html.spec.whatwg.org/multipage/interactive-elements.html#the-details-element>)

- [Web accessibility checker](<https://accesserty.com/en/web-accessibility-checker/>) — Check real pages, authenticated states, and interactive states before release.

- [Understand WCAG check results](<https://accesserty.com/en/wcag-compliance-tool/>) — Review WCAG A/AA issue clues, severity, affected elements, and remediation hints.

- [Accessibility practice and maintenance guides](<https://accesserty.com/en/guides/>) — Browse guides by practical task: public signals, pre-release checks, post-launch maintenance, and standards limits.