Change record: Hide content properly

This record explains the proposed revision of Hide Content Properly. The page remains at its current URL and is rewritten for supported Drupal releases, current HTML, WAI-ARIA, and WCAG guidance.

Summary

The existing page identifies several useful Drupal classes, but it treats hiding as a choice between sighted people and screen-reader users. It also presents hidden, display: none, and aria-hidden as substitutes when they have different effects. The revision organizes the subject around the intended result for visual presentation, the accessibility tree, keyboard operation, and layout.

What was retained

What was updated or added

Decision table

The old table's search-engine column was removed. The replacement compares whether each technique is visually rendered, exposed in the accessibility tree, and keyboard operable. These are the distinctions developers need to select an accessible implementation.

Drupal 11 source verification

The four utility classes and their effects were checked against the Drupal 11 System module's hidden.module.css. The page directs developers to use the core classes instead of copying their implementation. This reduces duplicated CSS and prevents documentation examples from drifting away from core.

Conditional rendering and access control

The revision adds a clear direction not to render content that is unauthorized or unnecessary. CSS, hidden, inert, and ARIA remain available in the browser and are not security controls.

State and focus management

The replacement explains that hiding a region is an interaction-state change. It adds synchronization of hidden and aria-expanded, focus movement before a focused subtree is hidden, Ajax testing, and use of established disclosure components.

aria-hidden constraints

The new page explains that aria-hidden="true" affects the accessibility tree but does not reliably remove descendants from keyboard navigation. It prohibits focusable descendants, explains inherited hidden state, and notes the effect on voice-control users who depend on visible labels.

inert

The HTML inert attribute was added for temporarily inactive subtrees. The page explains its effects on interaction, focus, find-in-page, and accessibility APIs. It also states that inert supplies no visual treatment and should not be applied to essential content without a usable active alternative.

Hidden names and descriptions

The revision documents the current Accessible Name and Description Computation rule for content directly referenced by aria-labelledby or aria-describedby. It distinguishes text used only in a computed name or description from visually hidden content that remains independently available in the accessibility tree.

Testing

The page adds review of computed CSS, the accessibility tree, keyboard order, focus transitions, JavaScript failure, Ajax, voice control, touch, zoom, and forced colors. Automated tests are limited to the deterministic conditions they can inspect.

What was removed or corrected

Material removed or corrected and the reason
Existing material Change and reason
The framing of content as available to sighted users or screen-reader users Rewritten. People use many combinations of vision, keyboards, screen readers, voice control, magnification, touch, and other technologies. The relevant implementation distinctions are visual rendering, accessibility-tree exposure, focus, and operation.
Search-engine visibility and an accessibility-versus-SEO trade-off Removed. Search-engine behavior is outside the page's accessibility purpose, changes independently, and is not reliably described by the existing table. Visible labels and headings are recommended because they help people, not because of ranking claims.
A general recommendation against display: none Corrected. display: none is appropriate when content should be unavailable to everyone in the current state. The failure is hiding content that people still need, not the CSS property itself.
The statement that hidden is semantically the same as display: none Qualified. They normally produce a similar rendered result, but hidden expresses an HTML state and can be overridden by CSS. The page describes the intended state rather than claiming complete equivalence.
The advice to use aria-hidden only when the HTML hidden attribute cannot be used Removed. The techniques are not substitutes. hidden removes visual and accessibility exposure, while aria-hidden leaves content visible and removes it from the accessibility tree.
General encouragement to visually hide interactive elements for custom styling Restricted. A visually hidden control can remain in the keyboard order without a visible target or focus indicator. The replacement requires a visible associated surface that exposes every relevant state and prefers styling the native control.
Copied implementations of the visually hidden and focusable utility classes Removed. Drupal already supplies these classes. Copying their CSS duplicates core behavior and becomes stale when the implementation changes.
The Drupal 7 Color module preview example Removed. It is obsolete and does not help developers choose among current hiding techniques.
The hidden heading for status messages as the primary visually hidden example Removed. Current status messages require correct structure and dynamic announcement behavior. Adding a hidden heading is not a general solution and is covered more accurately in the forms and interactive-components guidance.
WCAG 2.0 references and old external articles Replaced with Drupal 11 source, the living HTML Standard, WAI-ARIA 1.2, Accessible Name and Description Computation 1.2, and the relevant W3C ACT rule.
The statement that aria-hidden makes content invisible to screen readers Made more precise. It removes the element from the accessibility tree and affects assistive technologies beyond screen readers. It can still leave descendants in keyboard navigation, which is a serious failure.
Exclamation marks and hypothetical user quotations Removed. Direct implementation requirements are shorter and more consistent with the Drupal.org content style.

Content mapping

Where existing concepts appear in the revised page
Revised section Source or reason
Choose the intended result The old quick table, rebuilt around accessibility effects rather than search-engine claims.
Use Drupal's hiding utilities The existing Drupal class and field-display guidance, verified against Drupal 11.
Hide content visually but retain it for assistive technologies The existing .visually-hidden guidance, with interactive-control risks added.
Reveal controls when they receive keyboard focus The existing skip-link guidance, simplified to use the core classes.
Hide content from everyone The existing hidden, .hidden, and display: none material, corrected for state and focus management.
Preserve layout without exposing content The existing .invisible class, which appeared only in the old summary and needed explanation.
Hide decorative or redundant content from assistive technologies The existing aria-hidden example, expanded with accessibility-tree and focus constraints.
Make a temporarily inactive region inert New HTML platform guidance.
Use hidden text for accessible names and descriptions carefully Current accessible-name computation requirements.
Test hidden content and state changes New repeatable manual and automated review scope.

Sources checked