astro-accessibility

name	astro-accessibility
description	WCAG 2.1 AA accessibility guidelines for Astro components. Use when creating or modifying .astro files, working on accessibility, ARIA attributes, keyboard navigation, screen readers, semantic HTML, or accessible images.

Accessibility Rules (WCAG 2.1 AA)

This project must meet WCAG 2.1 AA guidelines.

Semantic Structure

• Use semantic HTML: <header>, <nav>, <section>, <article>, <footer>, <ul>, <li>
• Use ARIA roles only when native semantics are not possible (e.g. <div role="list">)

Images

• Informative images: use the custom <Img> component and pass the media prop, it includes the correct alt text
• Functional images/icons (used in buttons or links): use alt or aria-label to describe the action/purpose
• Decorative images/icons: use aria-hidden="true" and alt=""

Active State

• Use aria-current="page" or aria-current="location" for the current page (e.g. navigation, breadcrumbs)
• Use aria-current for styling: aria-current:font-semibold

Lists

• Use semantic HTML: <ul>, <ol>, <li>
• For custom components rendering lists, explicitly set ARIA roles:
  • role="list" on the container
  • role="listitem" on each item

Keyboard Navigation

• All functionality must be operable using only the keyboard
• Do not rely solely on hover, drag, or pointer events for core interactions

Aria Labels

• Do NOT hardcode strings for aria-label or visually hidden (sr-only) text
• Always use dynamic labels from the global state: labels.global['skipToMainContent']
• Select elements must have an accessible name (e.g. label tag or aria-label)