Skip to main content

Accessible Design System v1

Type to filter components by name, description, or keywords

Buttons with Icons

Accessible buttons that combine text labels with icons to enhance visual communication and provide additional context to users.

HTML

<button type="button" class="ds-ads-button-icon">
    <svg aria-hidden="true" width="20" height="20" viewBox="0 0 20 20" fill="none">
        <path d="M2 5h16M2 10h16M2 15h16" stroke="currentColor" stroke-width="2" stroke-linecap="round"/>
    </svg>
    Menu
</button>

CSS

/* IMPORTANT: Use explicit borders for high contrast mode support */
.ds-ads-button-icon {
    display: inline-flex;
    align-items: center;
    gap: 0.5rem;
    background-color: var(--ds-ads-primary-color);
    color: white;
    border: 2px solid var(--ds-ads-primary-color); /* Same as background */
    padding: 0.75rem 1.5rem;
    font-size: 16px;
    border-radius: 4px;
    cursor: pointer;
    min-height: 44px;
}

.ds-ads-button-icon svg {
    flex-shrink: 0;
}

.ds-ads-button-icon:hover {
    background-color: var(--ds-ads-primary-hover);
    border-color: var(--ds-ads-primary-hover);
}

.ds-ads-button-icon:focus {
    outline: 3px solid var(--ds-ads-focus-outline);
    outline-offset: 2px;
}

Accessibility Guidelines

Key Requirements

  • Always include visible text: The text label describes the button's purpose
  • Use aria-hidden="true" on icons: Prevents redundant announcements by screen readers
  • Icon placement: Position icon before or after text for consistent scanning
  • Color independence: Don't rely solely on the icon to convey meaning
  • Explicit borders: Use border: 2px solid (matching background color) instead of border: none to ensure visibility in Windows High Contrast Mode

Custom Implementation Notes

When implementing buttons with icons, ensure the text clearly describes the action. The icon is decorative and enhances visual communication but should not be the sole indicator of the button's purpose. Users who cannot see the icon or have custom stylesheets disabled should still understand the button's function from the text alone.

How to Test for Accessibility

  1. Screen Reader Test:
    • Enable NVDA, JAWS, or VoiceOver
    • Navigate to the button with Tab key
    • Verify it announces: "Menu, button" (not "Menu, graphic, button")
  2. Keyboard Navigation:
    • Tab to the button - verify visible focus indicator
    • Press Enter or Space - verify button activates
  3. Visual Test:
    • Disable CSS - verify text is still readable
    • Verify button meets minimum 44x44px touch target
    • Check contrast ratio meets 4.5:1 minimum
  4. Browser Dev Tools:
    • Inspect element and check Accessibility tree
    • Verify role="button" is present
    • Verify name includes only the text, not the icon

References