rgaa-html-css

name	rgaa-html-css
description	RGAA HTML/CSS accessibility compliance skill. Use when editing, reviewing, generating, or refactoring frontend markup and styles that must comply with RGAA rules. Triggers on tasks involving HTML templates, forms, navigation, tables, images, icons, or keyboard accessibility.
license	MIT
metadata	{"author":"SocialGouv","version":"1.0.0"}

RGAA HTML/CSS Compliance

Comprehensive accessibility compliance guide for HTML and CSS based on the RGAA (Référentiel Général d'Amélioration de l'Accessibilité). Contains ~98 rules across 13 categories, each with non-compliant and compliant code examples.

When to Apply

Use this skill when:

• Writing or reviewing HTML templates and frontend components
• Generating server-rendered pages or static HTML
• Working on CSS and design-system styles
• Building or fixing form markup, navigation, tables, or images
• Auditing code for accessibility compliance
• Fixing accessibility bugs reported in reviews

This skill is strictly focused on RGAA-oriented HTML and CSS implementation rules. It is not a general coding workflow skill.

Main Rule

Prefer native, semantic HTML first.

Only use ARIA to complement semantics when native HTML is insufficient. Do not use ARIA to compensate for incorrect HTML structure.

Agent Behavior

When working on UI code:

1. Inspect the rendered HTML structure, not only component names.
2. Preserve or improve semantics with the smallest possible change.
3. Do not add accessibility attributes mechanically.
4. Do not introduce accessibility regressions while solving unrelated UI issues.
5. If a requested design conflicts with RGAA rules, say so clearly and implement the closest compliant version.

Rule Categories by Priority

Priority	Category	Impact	Prefix	Rules
1	Page Structure and Landmarks	CRITICAL	structure-	9
2	Page Title	HIGH	title-	2
3	Language	HIGH	lang-	3
4	HTML Validity and Semantics	HIGH	semantics-	4
5	Links and Buttons	HIGH	controls-	5
6	Images, SVG, and Icons	CRITICAL	images-	13
7	Forms	CRITICAL	forms-	11
8	Lists	MEDIUM	lists-	4
9	Tables	HIGH	tables-	10
10	CSS Usage and Content Robustness	HIGH	css-	12
11	Keyboard Accessibility	CRITICAL	keyboard-	12
12	Iframes	MEDIUM	iframes-	1
13	Additional Conformity Rules	MEDIUM	additional-	12

Quick Reference

1. Page Structure and Landmarks (CRITICAL)

• structure-header-banner - Use header with banner role
• structure-search-role - Use role="search" for search area
• structure-main-landmark - Single visible main landmark
• structure-footer-contentinfo - Single footer with contentinfo role
• structure-nav-navigation - Use nav for internal navigation
• structure-nav-lists - Mark navigation menus with lists
• structure-heading-hierarchy - Logical heading structure
• structure-no-fake-headings - Do not use fake headings
• structure-aria-heading-lastresort - ARIA heading only as last resort

2. Page Title (HIGH)

• title-precise-title - Precise page title
• title-state-aware - Update title on state changes

3. Language (HIGH)

• lang-html-attribute - Set lang on html element
• lang-inline-changes - Mark inline language changes
• lang-hidden-text - Translate hidden text consistently

4. HTML Validity and Semantics (HIGH)

• semantics-valid-html - Produce valid HTML
• semantics-meaningful-elements - Use semantic elements
• semantics-no-div-replacement - Do not replace semantic HTML with divs
• semantics-no-table-layout-as-data - Do not misuse table markup

5. Links and Buttons (HIGH)

• controls-link-for-navigation - Use links for navigation
• controls-button-for-action - Use buttons for actions
• controls-aria-label-clarify - Clarify controls with aria-label
• controls-no-redundant-aria - No redundant aria-label on explicit controls
• controls-no-title-only - Do not rely on title alone

6. Images, SVG, and Icons (CRITICAL)

• images-decorative-alt-empty - Empty alt for decorative images
• images-informative-alt - Concise alt for informative images
• images-link-button-alt - Image links expose destination
• images-complex-description - Complex images need detailed description
• images-never-omit-alt - Never omit alt attribute
• images-no-text-in-images - Do not put text in images
• images-svg-decorative-hidden - Hide decorative SVG
• images-svg-informative-alt - Alt text for informative SVG
• images-svg-link-button - SVG links expose action
• images-icon-font-hidden - Hide icon font elements
• images-icon-only-accessible-name - Icon-only controls need text
• images-no-css-only-icons - Do not use CSS-only icons for meaning
• images-figure-figcaption - Use figure and figcaption

7. Forms (CRITICAL)

• forms-label-for-id - Associate labels with for/id
• forms-title-fallback - Use title for fields without visible label
• forms-autocomplete - Use correct autocomplete values
• forms-input-help-in-label - Include input help in label
• forms-required-attribute - Mark required fields
• forms-fieldset-legend - Group related controls
• forms-error-association - Associate errors with fields
• forms-aria-invalid - Use aria-invalid for invalid fields
• forms-no-placeholder-only - Do not use placeholder as only label
• forms-no-css-mandatory - Do not indicate required with CSS only
• forms-no-separated-instructions - Keep instructions with label

8. Lists (MEDIUM)

• lists-unordered - Use ul/li for unordered lists
• lists-ordered - Use ol/li for ordered sequences
• lists-description - Use dl/dt/dd for description lists
• lists-no-fake-lists - Do not fake lists

9. Tables (HIGH)

• tables-data-caption - Use caption for table title
• tables-data-th-headers - Use th for headers
• tables-data-scope - Use scope for simple tables
• tables-data-complex-headers-id - Use headers/id for complex tables
• tables-data-complex-summary - Include summary in caption
• tables-layout-presentation - Mark layout tables as presentation
• tables-layout-no-data-semantics - No data semantics in layout tables
• tables-layout-reading-order - Coherent reading order in layout tables
• tables-no-layout-unless-needed - Avoid tables for layout
• tables-no-td-for-headers - Do not use td where th is needed

10. CSS Usage and Content Robustness (HIGH)

• css-real-text-not-images - Use real text, not image text
• css-readable-without-images - Readable without images
• css-text-over-background-fallback - Fallback color behind text
• css-understandable-without-css - Understandable without CSS
• css-no-shape-only-meaning - No shape/size/position-only meaning
• css-text-spacing-readable - Readable with custom text spacing
• css-text-zoom-200 - Readable at 200% zoom
• css-no-informative-generated-content - No informative CSS content
• css-no-mandatory-pseudo-elements - No mandatory pseudo-element markers
• css-no-informative-bg-images - No CSS informative background images
• css-no-lock-zoom - Do not lock zoom
• css-relative-units - Prefer relative units

11. Keyboard Accessibility (CRITICAL)

• keyboard-visible-focus - Focus must be visible
• keyboard-mouse-equivalent - Keyboard equivalent for mouse
• keyboard-no-trap - No keyboard traps
• keyboard-tab-order - Tab order follows reading order
• keyboard-skip-link - Skip to content link
• keyboard-skip-link-first - Skip link is first interactive element
• keyboard-skip-link-visible-on-focus - Skip link visible on focus
• keyboard-no-remove-outline - Do not remove focus outlines
• keyboard-no-degrade-focus - Do not degrade focus visibility
• keyboard-no-positive-tabindex - No positive tabindex
• keyboard-no-hidden-skip-link - Do not hide skip link with display none
• keyboard-hover-focus-mirror - Mirror hover with focus

12. Iframes (MEDIUM)

• iframes-title-attribute - Every iframe needs a title

13. Additional Conformity Rules (MEDIUM)

• additional-canvas-embed-object-alt - Alt for canvas/embed/object
• additional-canvas-embed-object-name - Accessible name for interactive embeds
• additional-canvas-embed-object-decorative - Hide decorative embeds
• additional-no-press-state-action - No action on press state
• additional-optgroup - Group select options
• additional-button-a-for-context - Use button/a for context changes
• additional-dir-attribute - Use dir for reading direction
• additional-visually-hidden-technique - Correct visually hidden technique
• additional-blockquote - Use blockquote for block quotes
• additional-inline-quote - Use q for inline quotes
• additional-source-order - Source order follows reading order
• additional-captcha-alternative - Provide CAPTCHA alternatives

Reference Documents

For review workflows and checklists, see:

• reference/forbidden-patterns.md - Patterns to never introduce
• reference/review-workflow.md - Ordered review checklist
• reference/fix-strategy.md - Prioritized fix approach
• reference/validation-checklist.md - Pre-completion verification
• reference/output-style.md - How to report compliance changes
• reference/definition-of-done.md - When a task is complete

How to Use

Read individual rule files for detailed explanations and code examples:

rules/structure-header-banner.md
rules/forms-label-for-id.md
rules/keyboard-visible-focus.md

Each rule file contains:

• Brief explanation of why it matters
• Non-compliant code example
• Compliant code example
• Reference to official RGAA criteria

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md