Accessible Design System v1

<button type="button" class="ds-ads-button-primary" disabled>
    Disabled primary
</button>

<button type="button" class="ds-ads-button-secondary" disabled>
    Disabled secondary
</button>

/* IMPORTANT: Maintain explicit borders for high contrast mode support */
/* NOTE: These colors meet 4.5:1 contrast ratio, exceeding WCAG requirements */
.ds-ads-button-primary:disabled {
    background-color: var(--ds-ads-disabled-bg);
    color: var(--ds-ads-disabled-text);
    border: 2px solid var(--ds-ads-disabled-bg); /* Maintains border in high contrast */
    cursor: not-allowed;
    opacity: 0.75;
}

.ds-ads-button-secondary:disabled {
    background-color: transparent;
    color: var(--ds-ads-disabled-text-secondary);
    border-color: var(--ds-ads-disabled-border);
    cursor: not-allowed;
    opacity: 0.75;
}

/* Disabled buttons should not have hover effects */
.ds-ads-button-primary:disabled:hover,
.ds-ads-button-secondary:disabled:hover {
	/* No color changes on hover for disabled buttons */
}

Accessibility Guidelines

Key Requirements

• Use disabled attribute: Never use aria-disabled="true" alone without the HTML disabled attribute
• Visual indicators: Reduced opacity and color changes make the disabled state obvious
• Cursor change: cursor: not-allowed indicates the button cannot be activated
• Remove from tab order: Disabled buttons are not keyboard focusable
• Maintain high contrast: While WCAG permits lower contrast for disabled elements, we recommend maintaining 4.5:1 contrast ratio for better accessibility

Custom Implementation Notes

Important: Consider whether disabling a button is the right choice. In many cases, it's better to keep the button enabled and show an error message when clicked, explaining why the action can't be completed. This approach is more accessible because users can discover why the button doesn't work.

If you must disable a button, provide clear feedback elsewhere in the interface about why it's disabled and what the user needs to do to enable it. For example, if a "Submit" button is disabled because required fields are empty, clearly indicate which fields need to be filled.

WCAG Contrast Exception & Our Recommendation

WCAG 2.2 Contrast Exception: According to WCAG 2.2 Success Criterion 1.4.3 (Contrast - Minimum), inactive user interface components such as disabled buttons are exempt from meeting the minimum color contrast ratio requirements of 4.5:1 for normal text or 3:1 for large text.

Why this exception exists: The rationale is that disabled controls are not meant to be interactive and their reduced visual prominence helps communicate their inactive state to sighted users.

The accessibility debate: This exception is controversial in the accessibility community. Many accessibility experts and organizations argue that disabled buttons should still meet minimum contrast requirements because:

• Low vision users need to read the text: People with low vision or color blindness may struggle to read disabled button text if contrast is too low, even though they understand the button is disabled
• Context matters: Users need to see what action is unavailable and understand what's being disabled to make informed decisions
• Form comprehension: In complex forms, users need to read all button labels (enabled or disabled) to understand their options and what's required
• Cognitive accessibility: Clear, readable text on disabled buttons helps all users understand the interface, regardless of disability

Our recommendation: This design system uses disabled button colors that exceed the 4.5:1 contrast ratio requirement, even though WCAG permits lower contrast. We believe maintaining high contrast benefits all users and represents best practice in accessible design.

Alternative approaches: If you choose to use lower contrast disabled buttons (as permitted by WCAG), ensure you provide alternative ways for users to understand what actions are disabled and why, such as clear explanatory text near the form.

How to Test for Accessibility

1. Screen Reader Test:
   • Enable screen reader
   • Navigate through the page with Tab
   • Verify disabled button is skipped (not announced)
   • In browse mode, verify it's announced as "disabled button"
2. Keyboard Navigation:
   • Tab through the page
   • Verify disabled button cannot receive focus
   • Verify clicking/activating has no effect
3. Visual Test:
   • Verify disabled button looks visually distinct from enabled buttons
   • Check that cursor changes to not-allowed on hover
   • Verify text contrast meets 4.5:1 (our recommended standard)
   • Test with low vision simulators or grayscale mode
4. Browser Dev Tools:
   • Inspect element - verify disabled attribute is present
   • Check Accessibility tree shows button as disabled
   • Verify button has no focusable state

References

• WCAG 2.2 Success Criterion 4.1.2: Name, Role, Value (Level A)
• WCAG 2.2 Success Criterion 2.4.3: Focus Order (Level A)
• WCAG 2.2 Success Criterion 1.4.3: Contrast (Minimum) (Level AA) - Note: Relaxed for disabled controls