How to Inspect and Control CSS reading-flow in Safari Web Inspector

Modern CSS layout primitives—most notably CSS Grid and Flexbox—provide powerful mechanisms for reordering visual presentation without altering underlying DOM structures. Through properties such as order, grid-auto-flow: dense, or explicit template placements, elements can appear in entirely different positions from where they reside in markup. Historically, this discrepancy introduced severe accessibility hurdles: keyboard tabbing navigation and assistive screen-readers followed the original DOM sequence rather than the rendered visual flow. The emerging CSS reading-flow property bridges this gap, and Apple’s Safari Web Inspector provides dedicated developer tooling to inspect and debug focus traversal.

The Accessibility Disconnect Between DOM Order and Visual Presentation

When developers build magazine-style multi-column grids or dynamic dashboard cards, visual hierarchy often shifts dynamically across viewport sizes. Consider an e-commerce checkout page where summary cards are placed top-right via CSS Grid, while personal details reside bottom-left. Visually, a user expects the Tab key to traverse top-to-bottom, left-to-right.

However, the Web Content Accessibility Guidelines (WCAG) criterion 2.4.3 (Focus Order) requires navigation to preserve meaning and operability. When DOM order does not match visual positioning, sighted keyboard navigators experience disorientation as their focus indicator jumps erratically across the display. The reading-flow CSS property instructs the browser to calculate reading and focus sequence directly from visual positioning.

Syntax and Values of the CSS reading-flow Property

Applied to a flex or grid container, reading-flow accepts the following values:

• reading-flow: normal: The default setting. Focus traversal strictly respects DOM source tree order regardless of visual transformations.
• reading-flow: flex-visual: For flex containers, traverses items based on their visual presentation along the main axis and cross axis, factoring in the order property and writing modes.
• reading-flow: flex-flow: Traverses items along the flex flow direction established by flex-direction.
• reading-flow: grid-rows: For grid containers, navigates horizontally across rows, resolving grid items according to their computed row and column tracks.
• reading-flow: grid-columns: For grid containers, navigates vertically down columns before advancing to subsequent tracks.
• reading-flow: grid-order: Respects the visual arrangement determined by the explicit order property within grid structures.

Enabling Experimental Features in Safari

Because CSS reading-flow is part of the CSS Display Module Level 4 specification, ensure experimental web platform features are active in Safari or Safari Technology Preview:

1. Launch Safari on macOS.
2. Open Settings (Cmd + ,) and navigate to the Advanced tab.
3. Check the box at the bottom: Show features for web developers.
4. From the Safari menu bar, click Develop > Feature Flags.
5. Search for reading-flow or CSS reading-flow and ensure it is toggled On.
6. Restart Safari or reload your development tab.

Inspecting and Debugging Focus Sequences in Web Inspector

Safari Web Inspector offers visual overlays to audit focus and accessibility ordering:

1. Right-click the container element on your page and select Inspect Element.
2. In the Elements tree, select the container node styled with display: grid or display: flex.
3. In the Styles sidebar, locate the reading-flow rule. You can toggle the property on and off or edit values in real time to observe changes.
4. Switch to the Accessibility tab in the right-hand panel.
5. Look for the Focus Order / Reading Flow overlay toggle icon in the inspector header.
6. When active, Safari draws numbered badges over each child element on the live webpage, displaying the exact sequence in which keyboard tab focus and VoiceOver cursor navigation will occur.

Sample Implementation and Validation

The following example illustrates how to align visual grid placement with keyboard navigation:

.dashboard-grid {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  grid-auto-flow: dense;
  reading-flow: grid-rows;
  gap: 1.5rem;
}

.dashboard-card {
  padding: 1rem;
  border-radius: 8px;
}

Press the Tab key repeatedly through the rendered cards. With reading-flow: grid-rows enabled, the focus cursor moves predictably across the visual rows from left to right, rather than jumping backward and forward according to arbitrary source order.

By leveraging Safari Web Inspector to validate and fine-tune reading-flow, web authors can craft innovative responsive interfaces while preserving accessible, predictable navigation for all users.