RAWeb 1.1 — Accessible Code Development Guide

You are an accessibility-aware developer. Every piece of HTML, CSS, and JavaScript you write MUST conform to RAWeb 1.1 (Level AA by default). RAWeb is Luxembourg's official web accessibility framework implementing EN 301 549 and WCAG 2.1.

How to use the reference data

The full RAWeb 1.1 criteria, test methodologies, and glossary are available as JSON files. Use the lookup script to query specific criteria on demand:

# List all topics
!`${CLAUDE_SKILL_DIR}/scripts/raweb-lookup.sh topics`

# Look up a specific criterion
bash ${CLAUDE_SKILL_DIR}/scripts/raweb-lookup.sh criterion 1.1

# Look up test methodology
bash ${CLAUDE_SKILL_DIR}/scripts/raweb-lookup.sh methodology 1.1.1

# Search criteria by keyword
bash ${CLAUDE_SKILL_DIR}/scripts/raweb-lookup.sh search "form"

# Check glossary definition
bash ${CLAUDE_SKILL_DIR}/scripts/raweb-lookup.sh glossary "text alternative"

The raw JSON reference files are located at:

• ${CLAUDE_SKILL_DIR}/references/criteres.json — All 136+ criteria with tests and WCAG/EN 301 549 mappings
• ${CLAUDE_SKILL_DIR}/references/methodologies.json — Step-by-step test procedures
• ${CLAUDE_SKILL_DIR}/references/glossaire.json — Glossary of accessibility terms
• ${CLAUDE_SKILL_DIR}/references/themes.json — Topic names
• ${CLAUDE_SKILL_DIR}/references/niveaux.json — WCAG conformance levels per criterion

When writing code for a specific component, ALWAYS look up the relevant RAWeb criteria first to ensure full compliance. For example, before writing a form, run search "form" and topic 11.

Core rules (apply to ALL code you write)

1. Images (Topic 1)

ALWAYS:

• Every <img> conveying information MUST have a meaningful alt attribute (1.1)
• Every decorative <img> MUST have alt="" and no title, aria-label, or aria-labelledby (1.2)
• Every <svg> conveying information MUST have role="img" + text alternative via aria-label or aria-labelledby (1.1)
• Decorative <svg> MUST have aria-hidden="true" (1.2)
• Text alternatives must be short and concise — 80 characters max recommended (1.3)
• Complex images (charts, infographics) need a detailed description accessible via adjacent link or aria-describedby (1.6)
• Avoid images of text unless the visual effect cannot be achieved with CSS (1.8, 1.9 — Level AA)

NEVER:

• Leave alt undefined on an informative image
• Use alt="image", alt="photo", alt="icon" — describe what the image conveys
• Use title as the sole text alternative (poor assistive technology support)

<!-- GOOD: informative image -->
<img src="chart.png" alt="Sales increased 40% in Q3 2024">

<!-- GOOD: decorative image -->
<img src="decoration.svg" alt="">

<!-- GOOD: complex image with detailed description -->
<figure>
  <img src="orgchart.png" alt="Company organisation chart. Full description below.">
  <figcaption>
    <details>
      <summary>Full description of the organisation chart</summary>
      <p>The CEO reports to the board. Three departments report to the CEO...</p>
    </details>
  </figcaption>
</figure>

<!-- GOOD: SVG informative -->
<svg role="img" aria-label="Warning: connection unstable">
  <use href="#icon-warning"/>
</svg>

<!-- GOOD: SVG decorative -->
<svg aria-hidden="true" focusable="false"><use href="#flourish"/></svg>

2. Frames (Topic 2)

• Every <iframe> MUST have a descriptive title attribute (2.1)
• The title must be relevant to the frame content (2.2)

<iframe src="map.html" title="Interactive map of our office locations"></iframe>

3. Colours (Topic 3)

• Information must NEVER be conveyed by colour alone (3.1)
• Text contrast ratio: at least 4.5:1 (normal text) or 3:1 (large text ≥18pt / bold ≥14pt) (3.2 — Level AA)
• Non-text elements (icons, borders, UI components): at least 3:1 contrast against adjacent colours (3.3 — Level AA)

<!-- BAD: colour alone conveys meaning -->
<span class="text-red">Required field</span>

<!-- GOOD: colour + text indicator -->
<span class="text-red">Required field *</span>
<span class="sr-only">(required)</span>

<!-- Or better with native HTML -->
<input type="text" required aria-required="true">

4. Multimedia (Topic 4)

• Pre-recorded video with audio MUST have captions (4.1, 4.3)
• Pre-recorded audio MUST have a text transcript (4.1)
• Pre-recorded video MUST have audio description if visual information is not in the audio track (4.5, 4.6 — Level AA)
• Auto-playing media MUST be controllable: pause, stop, or mute within 3 seconds (4.10)
• No auto-playing audio longer than 3 seconds without a control mechanism (4.11)

<video controls>
  <source src="presentation.mp4" type="video/mp4">
  <track kind="captions" src="captions-en.vtt" srclang="en" label="English" default>
  <track kind="descriptions" src="descriptions-en.vtt" srclang="en" label="English audio descriptions">
</video>

5. Tables (Topic 5)

• Data tables MUST use <th> elements for headers with appropriate scope attribute (5.6, 5.7)
• Complex tables MUST use id/headers associations (5.7)
• Every data table MUST have a caption or title via <caption>, aria-label, or aria-labelledby (5.4)
• Layout tables MUST NOT use <th>, <caption>, scope, or headers (5.8)
• Every data table MUST have a summary to help understand its structure when the table is complex (5.5)

<!-- GOOD: simple data table -->
<table>
  <caption>Q3 2024 Revenue by Region</caption>
  <thead>
    <tr>
      <th scope="col">Region</th>
      <th scope="col">Revenue</th>
      <th scope="col">Growth</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row">Europe</th>
      <td>€2.4M</td>
      <td>+12%</td>
    </tr>
  </tbody>
</table>

6. Links (Topic 6)

• Every link MUST have an explicit accessible name (6.1)
• The link's accessible name must be relevant and describe the destination or function (6.1)
• Avoid ambiguous link text: never use "click here", "read more", "learn more" without context (6.1)
• If the visible text is not sufficient, add context via aria-label or aria-labelledby — but the aria-label MUST include the visible text (6.1, 6.2)

<!-- BAD -->
<a href="/report.pdf">Click here</a>

<!-- GOOD -->
<a href="/report.pdf">Download the Q3 2024 financial report (PDF, 2.4 MB)</a>

<!-- GOOD: contextual with aria-label containing visible text -->
<article>
  <h3>RAWeb 1.1 released</h3>
  <p>The new version adds 17 additional criteria...</p>
  <a href="/news/raweb" aria-label="Read more about RAWeb 1.1 released">Read more</a>
</article>

7. Scripts (Topic 7)

• Every script MUST be operable by keyboard AND any pointing device (7.1)
• All script-driven UI must be compatible with assistive technologies (7.1)
• Status messages must be communicated without focus change using role="status", role="alert", role="log", aria-live, or aria-relevant (7.4)
• Script-inserted content must be accessible (7.2)
• Moving, blinking, or auto-updating content must be controllable: pause, stop, hide (7.5 — Level AA)

<!-- GOOD: live region for status updates -->
<div role="status" aria-live="polite" aria-atomic="true">
  <p>3 results found.</p>
</div>

<!-- GOOD: alert for important messages -->
<div role="alert">
  <p>Your session will expire in 2 minutes.</p>
</div>

// GOOD: keyboard + pointer support
button.addEventListener('click', handler);  // covers mouse + Enter/Space
button.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' || e.key === ' ') {
    e.preventDefault();
    handler(e);
  }
});

8. Mandatory Elements (Topic 8)

• Every page MUST have a valid <!DOCTYPE html> (8.1)
• Every page MUST have a lang attribute on <html> matching the primary language (8.3)
• Language changes in content MUST be marked with lang on the relevant element (8.7 — Level AA)
• Every page MUST have a unique and relevant