Building Accessible React Applications with ARIA

{
  "title": "Building Accessible React Applications with ARIA",
  "description": "Best practices for enhancing accessibility in React apps using ARIA attributes and roles.",
  "category": "React Cursor Rules",
  "rules": [
    {
      "id": "use-semantic-html",
      "description": "Use semantic HTML elements to provide meaningful structure to your content, enhancing accessibility and SEO.",
      "severity": "error",
      "examples": {
        "bad": [
          {
            "code": "<div onClick={handleClick}>Click me</div>",
            "explanation": "Using a <div> for a clickable element lacks semantic meaning and is not accessible."
          }
        ],
        "good": [
          {
            "code": "<button onClick={handleClick}>Click me</button>",
            "explanation": "Using a <button> element provides semantic meaning and is accessible."
          }
        ]
      }
    },
    {
      "id": "aria-labels-for-non-text-controls",
      "description": "Provide ARIA labels for interactive elements that lack visible text to ensure they are accessible to screen readers.",
      "severity": "error",
      "examples": {
        "bad": [
          {
            "code": "<button><svg>...</svg></button>",
            "explanation": "A button with only an icon lacks a text label, making it inaccessible."
          }
        ],
        "good": [
          {
            "code": "<button aria-label='Close'><svg>...</svg></button>",
            "explanation": "Adding an aria-label provides a text alternative for screen readers."
          }
        ]
      }
    },
    {
      "id": "keyboard-navigable-interactive-elements",
      "description": "Ensure all interactive elements are keyboard accessible by using appropriate HTML elements or managing focus and keyboard events.",
      "severity": "error",
      "examples": {
        "bad": [
          {
            "code": "<div onClick={handleClick}>Click me</div>",
            "explanation": "A <div> is not focusable or keyboard accessible by default."
          }
        ],
        "good": [
          {
            "code": "<button onClick={handleClick}>Click me</button>",
            "explanation": "A <button> is natively focusable and keyboard accessible."
          }
        ]
      }
    },
    {
      "id": "aria-live-for-dynamic-content",
      "description": "Use ARIA live regions to announce dynamic content updates to assistive technologies.",
      "severity": "warning",
      "examples": {
        "bad": [
          {
            "code": "<div>{message}</div>",
            "explanation": "Dynamic content changes are not announced to screen readers."
          }
        ],
        "good": [
          {
            "code": "<div aria-live='polite'>{message}</div>",
            "explanation": "Using aria-live='polite' ensures updates are announced without interrupting the user."
          }
        ]
      }
    },
    {
      "id": "avoid-aria-hidden-on-interactive-elements",
      "description": "Do not use aria-hidden='true' on interactive elements, as it makes them inaccessible to assistive technologies.",
      "severity": "error",
      "examples": {
        "bad": [
          {
            "code": "<button aria-hidden='true'>Submit</button>",
            "explanation": "The button is hidden from assistive technologies, making it inaccessible."
          }
        ],
        "good": [
          {
            "code": "<button>Submit</button>",
            "explanation": "The button is accessible to all users."
          }
        ]
      }
    },
    {
      "id": "use-aria-roles-appropriately",
      "description": "Apply ARIA roles to elements when native HTML semantics are insufficient, ensuring they accurately describe the element's purpose.",
      "severity": "warning",
      "examples": {
        "bad": [
          {
            "code": "<div role='button' onClick={handleClick}>Click me</div>",
            "explanation": "Using role='button' on a <div> is unnecessary when a <button> element should be used."
          }
        ],
        "good": [
          {
            "code": "<button onClick={handleClick}>Click me</button>",
            "explanation": "Using a <button> element provides the correct semantics without additional roles."
          }
        ]
      }
    },
    {
      "id": "ensure-focus-visible",
      "description": "Ensure that all interactive elements have a visible focus indicator to aid keyboard navigation.",
      "severity": "error",
      "examples": {
        "bad": [
          {
            "code": "button:focus { outline: none; }",
            "explanation": "Removing the focus outline makes it difficult for keyboard users to navigate."
          }
        ],
        "good": [
          {
            "code": "button:focus { outline: 2px solid #007bff; }",
            "explanation": "Providing a visible focus outline aids keyboard navigation."
          }
        ]
      }
    },
    {
      "id": "use-aria-describedby-for-form-instructions",
      "description": "Use aria-describedby to associate form inputs with descriptive text, providing additional context to users.",
      "severity": "warning",
      "examples": {
        "bad": [
          {
            "code": "<input id='email' type='email' /><span>Enter a valid email address.</span>",
            "explanation": "The instruction is not programmatically associated with the input."
          }
        ],
        "good": [
          {
            "code": "<input id='email' type='email' aria-describedby='email-desc' /><span id='email-desc'>Enter a valid email address.</span>",
            "explanation": "Using aria-describedby associates the instruction with the input."
          }
        ]
      }
    },
    {
      "id": "avoid-positive-tabindex",
      "description": "Avoid using positive tabindex values to manage focus order, as it can lead to unpredictable navigation.",
      "severity": "warning",
      "examples": {
        "bad": [
          {
            "code": "<div tabindex='1'>First</div><div tabindex='2'>Second</div>",
            "explanation": "Using positive tabindex values can disrupt the natural tab order."
          }
        ],
        "good": [
          {
            "code": "<div tabindex='0'>First</div><div tabindex='0'>Second</div>",
            "explanation": "Using tabindex='0' maintains the natural tab order."
          }
        ]
      }
    },
    {
      "id": "provide-alt-text-for-images",
      "description": "Ensure all images have descriptive alt text to convey their meaning to users who cannot see them.",
      "severity": "error",
      "examples": {
        "bad": [
          {
            "code": "<img src='logo.png' />",
            "explanation": "The image lacks alt text, making it inaccessible to screen readers."
          }
        ],
        "good": [
          {
            "code": "<img src='logo.png' alt='Company Logo' />",
            "explanation": "Providing alt text describes the image to users who cannot see it."
          }
        ]
      }
    }
  ]
}