Skip to content

Comments

fix(a11y): correct heading hierarchy in React components#1634

Open
juanmitriatti wants to merge 1 commit intodevfrom
UDS-2130
Open

fix(a11y): correct heading hierarchy in React components#1634
juanmitriatti wants to merge 1 commit intodevfrom
UDS-2130

Conversation

@juanmitriatti
Copy link
Contributor

Fix heading hierarchy accessibility issues in React components

Fixed heading hierarchy issues to improve accessibility by correcting heading level skips in AnchorMenu,
ImageCarousel, and ImageGalleryCarousel.

  • Changed AnchorMenu from h4 to h2 to avoid skipping heading levels
  • Changed ImageCarousel and ImageGalleryCarousel from h3 to h2
  • Updated CSS in unity-bootstrap-theme to maintain visual appearance
  • Used heading-three variables for h2 in image captions
  • Added explicit font-size, line-height, and letter-spacing
  • Ensures h2 displays identically to previous h3/h4 styles

These changes ensure proper semantic HTML structure without affecting visual design.

Description

Problem:
Heading hierarchy accessibility errors were occurring in several React components due to skipped heading levels. For
example, AnchorMenu was using h4 which skipped from h1 (page title) to h4, and image carousels were using h3 which
could skip heading levels depending on page context.

Added
h2 styles for image-gallery context

  • Used existing SASS variables ($heading-three-font-size, $heading-three-line-height,
    $heading-three-letter-spacing) instead of hardcoded values

Testing Steps:

  1. Run Storybook: cd packages/unity-react-core && yarn storybook
  2. Navigate to AnchorMenu story - verify heading still appears visually identical
  3. Navigate to ImageCarousel story - verify caption heading appears visually identical
  4. Navigate to ImageGalleryCarousel story - verify caption heading appears visually identical
  5. Inspect elements to confirm they now use h2 instead of h3/h4
  6. Run tests: yarn test - all tests should pass

Checklist

  • Tests pass for relevant code changes

Important Reminders

  • No new tests were needed as this change only affects semantic HTML and CSS styling
  • All existing tests continue to pass

Links

Fixed heading hierarchy issues to improve accessibility by correcting
heading level skips in AnchorMenu, ImageCarousel, and ImageGalleryCarousel.

- Changed AnchorMenu from h4 to h2 to avoid skipping heading levels
- Changed ImageCarousel and ImageGalleryCarousel from h3 to h2
- Updated CSS in unity-bootstrap-theme to maintain visual appearance
- Used heading-three variables for h2 in image captions
- Added explicit font-size, line-height, and letter-spacing
- Ensures h2 displays identically to previous h3/h4 styles

These changes ensure proper semantic HTML structure without affecting
visual design.
@juanmitriatti juanmitriatti requested a review from a team as a code owner February 20, 2026 16:59
@asu-jenkins-devops
Copy link
Collaborator

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants