Accessibility Rules

WCAG 2.1 AA standards for code generation. The framework's accessibility agents apply these rules to every UI file they touch.

Semantic HTML

  1. Use <button> for clickable actions, never <div> or <span> with onClick.
  2. Use <a> for navigation links, never <div> or <span> with onClick.
  3. Use heading hierarchy correctly (h1 > h2 > h3) — never skip levels.
  4. Use landmark elements: <main>, <nav>, <header>, <footer>, <aside>.
  5. Use <ul> or <ol> for lists of related items, not divs.

Forms

  1. Every input must have a visible <label> element.
  2. Labels must be associated with inputs via htmlFor/id.
  3. Never use placeholder as the only label.
  4. Mark required fields with aria-required="true" and a visible indicator.
  5. Group related inputs with <fieldset> and <legend>.
  6. Link error messages to inputs with aria-describedby.
  7. Use appropriate input types: email, tel, url, number, password.
  8. Add autocomplete attributes for common fields (email, name, address, etc.).

Keyboard Accessibility

  1. All interactive elements must be keyboard accessible.
  2. Tab order must follow logical reading order.
  3. Focus indicators must be visible — never use outline: none without a replacement.
  4. Custom components need keyboard handlers: Enter, Space, Escape, Arrow keys.
  5. No keyboard traps — users must be able to tab away from any element.
  6. Modals must trap focus while open and return focus when closed.

Images and Media

  1. All images must have an alt attribute.
  2. Informative images: alt describes the content.
  3. Decorative images: alt="" (empty string).
  4. Icons with meaning need accessible text (aria-label or visually hidden text).
  5. Icons that are decorative use aria-hidden="true".

ARIA

  1. Use ARIA only when native HTML is insufficient.
  2. Custom components must have appropriate role attributes.
  3. Interactive components must have aria-expanded, aria-selected, etc. as needed.
  4. Use aria-label only when visible text is insufficient.
  5. Use aria-describedby for additional context.
  6. Use aria-live="polite" to announce dynamic content changes.
  7. Use aria-live="assertive" only for critical alerts.

Color and Contrast

  1. Text contrast must be at least 4.5:1 (3:1 for large text 18px+ or 14px bold).
  2. UI component contrast must be at least 3:1.
  3. Never use color alone to convey information — add icons, text, or patterns.
  4. Focus indicators must have 3:1 contrast against background.

Dynamic Content

  1. Announce loading states to screen readers.
  2. Announce errors with role="alert" or aria-live.
  3. Manage focus when content changes (modals, page transitions, deletions).
  4. Single-page navigation must announce new page content.

Touch and Pointer

  1. Touch targets must be at least 44×44 CSS pixels.
  2. Provide alternatives to drag-and-drop interactions.
  3. Ensure click actions fire on pointer up, not down (allows cancel).

Related