| 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:
- Inspect the rendered HTML structure, not only component names.
- Preserve or improve semantics with the smallest possible change.
- Do not add accessibility attributes mechanically.
- Do not introduce accessibility regressions while solving unrelated UI issues.
- 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 rolestructure-search-role - Use role="search" for search areastructure-main-landmark - Single visible main landmarkstructure-footer-contentinfo - Single footer with contentinfo rolestructure-nav-navigation - Use nav for internal navigationstructure-nav-lists - Mark navigation menus with listsstructure-heading-hierarchy - Logical heading structurestructure-no-fake-headings - Do not use fake headingsstructure-aria-heading-lastresort - ARIA heading only as last resort
2. Page Title (HIGH)
title-precise-title - Precise page titletitle-state-aware - Update title on state changes
3. Language (HIGH)
lang-html-attribute - Set lang on html elementlang-inline-changes - Mark inline language changeslang-hidden-text - Translate hidden text consistently
4. HTML Validity and Semantics (HIGH)
semantics-valid-html - Produce valid HTMLsemantics-meaningful-elements - Use semantic elementssemantics-no-div-replacement - Do not replace semantic HTML with divssemantics-no-table-layout-as-data - Do not misuse table markup
5. Links and Buttons (HIGH)
controls-link-for-navigation - Use links for navigationcontrols-button-for-action - Use buttons for actionscontrols-aria-label-clarify - Clarify controls with aria-labelcontrols-no-redundant-aria - No redundant aria-label on explicit controlscontrols-no-title-only - Do not rely on title alone
6. Images, SVG, and Icons (CRITICAL)
images-decorative-alt-empty - Empty alt for decorative imagesimages-informative-alt - Concise alt for informative imagesimages-link-button-alt - Image links expose destinationimages-complex-description - Complex images need detailed descriptionimages-never-omit-alt - Never omit alt attributeimages-no-text-in-images - Do not put text in imagesimages-svg-decorative-hidden - Hide decorative SVGimages-svg-informative-alt - Alt text for informative SVGimages-svg-link-button - SVG links expose actionimages-icon-font-hidden - Hide icon font elementsimages-icon-only-accessible-name - Icon-only controls need textimages-no-css-only-icons - Do not use CSS-only icons for meaningimages-figure-figcaption - Use figure and figcaption
7. Forms (CRITICAL)
forms-label-for-id - Associate labels with for/idforms-title-fallback - Use title for fields without visible labelforms-autocomplete - Use correct autocomplete valuesforms-input-help-in-label - Include input help in labelforms-required-attribute - Mark required fieldsforms-fieldset-legend - Group related controlsforms-error-association - Associate errors with fieldsforms-aria-invalid - Use aria-invalid for invalid fieldsforms-no-placeholder-only - Do not use placeholder as only labelforms-no-css-mandatory - Do not indicate required with CSS onlyforms-no-separated-instructions - Keep instructions with label
8. Lists (MEDIUM)
lists-unordered - Use ul/li for unordered listslists-ordered - Use ol/li for ordered sequenceslists-description - Use dl/dt/dd for description listslists-no-fake-lists - Do not fake lists
9. Tables (HIGH)
tables-data-caption - Use caption for table titletables-data-th-headers - Use th for headerstables-data-scope - Use scope for simple tablestables-data-complex-headers-id - Use headers/id for complex tablestables-data-complex-summary - Include summary in captiontables-layout-presentation - Mark layout tables as presentationtables-layout-no-data-semantics - No data semantics in layout tablestables-layout-reading-order - Coherent reading order in layout tablestables-no-layout-unless-needed - Avoid tables for layouttables-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 textcss-readable-without-images - Readable without imagescss-text-over-background-fallback - Fallback color behind textcss-understandable-without-css - Understandable without CSScss-no-shape-only-meaning - No shape/size/position-only meaningcss-text-spacing-readable - Readable with custom text spacingcss-text-zoom-200 - Readable at 200% zoomcss-no-informative-generated-content - No informative CSS contentcss-no-mandatory-pseudo-elements - No mandatory pseudo-element markerscss-no-informative-bg-images - No CSS informative background imagescss-no-lock-zoom - Do not lock zoomcss-relative-units - Prefer relative units
11. Keyboard Accessibility (CRITICAL)
keyboard-visible-focus - Focus must be visiblekeyboard-mouse-equivalent - Keyboard equivalent for mousekeyboard-no-trap - No keyboard trapskeyboard-tab-order - Tab order follows reading orderkeyboard-skip-link - Skip to content linkkeyboard-skip-link-first - Skip link is first interactive elementkeyboard-skip-link-visible-on-focus - Skip link visible on focuskeyboard-no-remove-outline - Do not remove focus outlineskeyboard-no-degrade-focus - Do not degrade focus visibilitykeyboard-no-positive-tabindex - No positive tabindexkeyboard-no-hidden-skip-link - Do not hide skip link with display nonekeyboard-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/objectadditional-canvas-embed-object-name - Accessible name for interactive embedsadditional-canvas-embed-object-decorative - Hide decorative embedsadditional-no-press-state-action - No action on press stateadditional-optgroup - Group select optionsadditional-button-a-for-context - Use button/a for context changesadditional-dir-attribute - Use dir for reading directionadditional-visually-hidden-technique - Correct visually hidden techniqueadditional-blockquote - Use blockquote for block quotesadditional-inline-quote - Use q for inline quotesadditional-source-order - Source order follows reading orderadditional-captcha-alternative - Provide CAPTCHA alternatives
Reference Documents
For review workflows and checklists, see:
reference/forbidden-patterns.md - Patterns to never introducereference/review-workflow.md - Ordered review checklistreference/fix-strategy.md - Prioritized fix approachreference/validation-checklist.md - Pre-completion verificationreference/output-style.md - How to report compliance changesreference/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
