RGAA & accessibility with Lagoon

RGAA, the French general framework for improving accessibility, sets the reference for verifying digital accessibility. Lagoon provides Blazor WebAssembly components that carry part of these requirements: labels, focus, keyboard navigation, ARIA roles and attributes, screen reader announcements, loading states, and theme variables.

Lagoon's commitment is to provide reusable components that facilitate compliance, without replacing the application's own responsibility: every screen must keep a readable structure, translated text, consistent keyboard navigation, and contrasts adapted to the chosen theme.

Project responsibility

An accessible component can become non-compliant if its label is missing, if the reading order is altered, if information is conveyed by color alone, or if a theme reduces contrasts. Always verify the final screen against the applicable RGAA rules.

Historical source reused

The previous documentation stated the following rules for Lagoon components:

Across all Lagoon components, it is possible to add the following two Aria tags:

• AriaLabel: adds the aria-label attribute on components.
• AriaLabelledBy: adds the aria-labelledby attribute on the component

Note that if the component is a container for other elements (LgFrame, LgListView, ...), the attribute is added on that container and not on all its children.

A mechanism allows reporting information to the screen reader. The behavior

The rest of this guide clarifies these points with the usages verified in the current component documentation.

Best practices by topic

Accessible labels

• Give visible fields and actions a label as early as possible: Label, Text, Title, or text content depending on the documented component.
• Use translation keys for user-facing text, for example #Save, #OrderNumber, or #OrdersGridAria.
• For a button or action primarily identified by an icon, add an accessible label with AriaLabel or link the action to existing text with AriaLabelledBy.
• For form fields, prefer the Lagoon component's Label over native HTML. The theme can display labels outside the field via the SCSS variable $custom-label-outside.

Label outside the field

The $custom-label-outside mode positions labels above or outside fields in themes that support it. It improves the persistence of the visible label and avoids relying on a placeholder as the only accessible name.

Keyboard navigation

• Use Lagoon components rather than native HTML elements whenever an equivalent exists: LgButton, LgEditForm, LgGridView, LgModal, LgSelect, etc.
• Verify that every action is reachable by keyboard and that the tab order follows the page's visual and business order.
• Shortcuts configured on LgButton with ShortcutKey are documented in its tooltip; avoid ambiguous shortcuts or ones that conflict with the browser's own shortcuts.
• In a grid, avoid column grouping or reordering when the screen reader's reading order takes priority.

Visible focus

• Never remove the focus indicator without providing an alternative that is at least as visible.
• Themes expose focus variables, for example for the header or the GridView. The GridView module notably defines $gridview-rgaa-indicator and $gridview-rgaa-indicator-offset.
• Use AutoFocus sparingly: it is useful for a primary action or a return after loading, but it must not surprise the user.

Contrasts and themes

• Enable or adapt the theme options provided for enhanced contrast, notably $custom-rgaa in themes that declare it.
• Check text/background pairs after customizing $primary, $secondary, toolbar colors, GridView colors, notification colors, and hover/focus states.
• Never convey information through color alone: add text, a label, a state, a named icon, or a suitable announcement.

ARIA attributes

AriaLabel and AriaLabelledBy allow naming a component for assistive technologies. For container components, the attribute is applied to the container itself; it does not automatically name each child element. Interactive children must therefore keep their own labels when they carry a distinct action.

Use AriaLabel to provide a direct textual name, and AriaLabelledBy when the accessible name must reuse the text of an already visible element. Do not needlessly duplicate a clear visible label.

Text alternatives and icons

• A decorative icon must not be the sole carrier of information.
• An interactive icon must be carried by an actionable component with an accessible label, for example an LgButton with Text or AriaLabel.
• Empty-state messages, banners, notifications, and loaders must provide understandable, translated text consistent with the displayed state.

Screen reader announcements

Lagoon provides a mechanism to announce information to screen readers via ShowScreenReaderInformation. LgLoaderView uses it to announce state changes with RgaaTextLoading and RgaaTextLoaded, whose default values are translation keys.

Use this mechanism for significant dynamic changes that do not necessarily move the focus: end of loading, result refresh, language change, or global information that is not immediately visible.

Summary table

Component	Accessibility focus point
LgButton	Provide Text, AriaLabel, or AriaLabelledBy for icon buttons; check keyboard shortcuts and the use of AutoFocus.
LgGridView<TItem>	Name the grid with Title, AriaLabel, or AriaLabelledBy; preserve a consistent reading order; check filters, sorting, pagination, and grouping.
LgLoaderView	Customize the RgaaTextLoading and RgaaTextLoaded texts with translated keys if needed.
LgListView<TItem>	Name the root group; verify that each item and the selection actions remain understandable without relying on color alone.
LgHyperlink	Provide content that clearly describes the destination or the triggered action.
LgFrame	If the panel structures an important area, provide a clear title or an accessible name on the container.

References to components

The component pages detail their parameters and their "Accessibility" section. See in particular:

• LgButton for buttons, keyboard shortcuts, focus, and ARIA labels.
• LgGridView<TItem> for grids, reading order, and table labels.
• LgLoaderView for RGAA loading announcements.
• LgListView<TItem> for lists and named groups.
• LgHyperlink for explicit links.
• LgFrame for named containers.

RGAA review checklist

• Visible text and accessible labels use #... keys.
• Every iconified action has an accessible name.
• Keyboard navigation reaches every action in a logical order.
• Focus remains visible in the application theme.
• Contrasts are checked after SCSS customization, in particular with $custom-rgaa and $custom-label-outside.
• Important dynamic messages are visible or announced to screen readers.
• Tables, lists, and containers have a title or an accessible name when their context is not obvious.
• Information does not rely solely on color, position, or an icon.