Dublin Library

The Publishing Project

Document order, visual order, and accessibility

  • 10 min. read

 

While exploring features like CSS grid lanes, a critical question arises: If the visual order of items differs from the Document Object Model (DOM) order, does it break accessibility for users who rely on assistive technologies?

The answer requires understanding the difference between document order (the sequence of elements in the HTML) and visual order (the sequence in which items display on the screen). When these two orders diverge, it can severely impact users with different kinds of disabilities.

This post explores document order, visual order, and how to balance complex CSS layouts with strict accessibility requirements.

Defining the problem #

To establish a baseline, developers must differentiate between the two structural orders of a web page:

Visual order
The sequence of elements as visually arranged on the screen. Developers manipulate this using CSS properties like grid-template-areas, grid-lanes, Flexbox order, or absolute positioning.
Document order
The sequence of elements as they appear in the HTML source code (the Document Object Model, or DOM). Assistive technologies, such as screen readers, rely on this order to read and parse the content of the page.

When developers author HTML in the exact sequence they want it displayed, these two orders align. When developers use CSS to visually rearrange items independently of the HTML structure, the orders diverge, creating potential accessibility failures.

Understanding the human impact #

A common misconception equates "assistive technology" strictly with screen readers used by individuals who are blind. Because screen readers process the raw HTML strictly from top to bottom (in Latin languages), visual reordering via CSS actually does not affect them. They receive the perfect, intended DOM sequence.

However, developers must ensure the visual order matches the DOM order for sighted users who navigate with a keyboard or use visual assistive technologies.

Here is why a disconnect between visual order and DOM order causes major usability failures:

Sighted keyboard users (motor disabilities)
Users with motor impairments (such as Parkinson's disease, tremors, or repetitive strain injuries) often navigate the web visually using the Tab key to move from link to link. When CSS visually rearranges items, the Tab key still follows the underlying HTML DOM.
  • Expected behavior: Pressing Tab moves the focus indicator logically across visible cards (usually left-to-right, top-to-bottom).
  • Broken behavior: If the visual order is scrambled, pressing Tab causes the focus ring to jump erratically across the screen—from the top-left, down to the bottom-right, and back up to the top-middle. Comparison shopping or filling out forms becomes exhausting and nearly unusable.
Screen magnifier users (low vision)
Users with low vision often use screen magnification software, zooming into the screen at 400% or more. Because they can only see a small quadrant of the screen at any given time, they rely heavily on predictable focus movement.
If keyboard focus jumps to an item visually placed on the opposite side of the screen, the viewport violently yanks to that new location, causing the user to lose their orientation and abandon the task.
Cognitive accessibility
For users with cognitive or learning disabilities (like ADHD or dyslexia), a predictable, logical flow of information is critical. When the visual layout implies one sequence, but interacting with the page forces a completely different, hidden DOM sequence, the user must constantly re-map context. This cognitive load increases fatigue and error rates.

The Web Content Accessibility Guidelines (WCAG) #

The Web Content Accessibility Guidelines (WCAG) explicitly govern this issue to protect the user experiences outlined above.

WCAG Success Criterion 2.4.3 (Focus Order): "If a Web page can be navigated sequentially and the navigation sequences affect meaning or operation, focusable components receive focus in an order that preserves meaning and operability."

In plain language: if users navigate a page sequentially, the focus order must remain logical. This does not imply a single "correct" focus sequence. However, the provided sequence must not confuse users, break tasks, or hide the intended reading and interaction flow.

WCAG actively works to prevent:

  • Focus jumping around the viewport in a seemingly random pattern.
  • Users encountering form controls before the content that explains them.
  • Keyboard users receiving a drastically different task flow than sighted mouse users.

ote:

All the links in this section point to WCAG 2.2 Understanding resources, which is the most recent version of the guidelines as of this writing. However, these criteria have been in place since WCAG 2.0 and remain relevant regardless of the version.

Focus order is a central pillar of accessibility, but it does not operate in isolation. The following criteria often fail alongside focus order issues:

WCAG 3.0 (Editor's draft) is currently in development and may introduce new criteria or adjustments to existing ones, but the core principles of focus order and its relationship to visual order are expected to remain consistent.

Common failure patterns #

The following patterns represent the most frequent causes of a mismatch between the visual presentation and the keyboard experience:

  • Using Flexbox order to move primary actions above content, while the DOM keeps those actions lower in the document.
  • Using Grid template placement to create a visual sequence that entirely disregards the source order.
  • Using positive tabindex values to manually "fix" a sequence, which invariably introduces new inconsistencies elsewhere on the page.
  • Using absolute positioning to move interactive UI to a new location without altering the DOM sequence.

The core anti-pattern behind all of these is identical: allowing the presentation layer to dictate the semantic interaction order.

When visual reordering is acceptable (and when it is not) #

Not every visual/DOM mismatch constitutes an automatic failure. A page can still conform to WCAG standards if the sequential focus path preserves meaning and operability.

Use this decision matrix as a baseline for layout architectures:

Pattern Reordering Risk Recommendation
Decorative-only cards (no links or buttons) Low Usually acceptable if the overall reading sequence remains understandable.
Article teasers (clickable titles) Medium Prefer matching the DOM order to the visual order.
Interactive grids (cards with multiple controls) High Keep DOM and visual order strictly aligned.
Navigation menus High Never visually reorder items independently of the source.
Forms and multi-step flows Very High Never break the semantic or focus sequence.
Handling tradeoffs
If an engineering team must argue why a specific mismatch is acceptable, the design is likely already in a risky area. The more interactive the UI becomes, the less tolerance there is for divergence.

Implementation guidance by layout type #

As a general rule, start by writing a meaningful DOM order that reflects the logical reading and interaction sequence. Apply CSS to style and position elements without altering that underlying order.

Flexbox #

Treat the order property as a last resort for interactive content. It remains safer for cosmetic shifts than for meaningful task flows. Prefer keeping the semantic order in the HTML and allowing CSS wrapping to handle the layout.

<ul class="cards">
  <li><a href="/a">Card A</a></li>
  <li><a href="/b">Card B</a></li>
  <li><a href="/c">Card C</a></li>
</ul>

Use flex-wrap: wrap in CSS to allow items to flow naturally without changing their visual order.

.cards {
  display: flex;
  flex-wrap: wrap;
  gap: 1rem;
}

.cards > li {
  flex: 1 1 16rem;
}

Avoid negative values for the order attribute in interactive sequences. Negative order items will always place before positive order items in the focus sequence, regardless of their visual placement.

/* ❌ Anti-pattern: Reorders visual layout but not keyboard/DOM order */
.cards > li.featured {
  order: -1;
}

CSS Grid #

Use CSS Grid for layout, but prioritize the logical source order first. Place items into columns and rows without altering the narrative or interaction sequence.

<main class="layout">
  <nav>Section navigation</nav>
  <article>Main content</article>
  <aside>Related links</aside>
</main>

Prefer explicit placement that respects the semantic sequence of the DOM. This ensures that the keyboard focus follows a predictable path.

.layout {
  display: grid;
  gap: 1rem;
  grid-template-columns: repeat(3, 1fr);
  grid-auto-flow: 15rem;
}

/* ✅ Safe: Explicit grid rows respect the DOM order (nav -> article -> aside) */
.layout > nav { grid-row: 1; }
.layout > article { grid-row: 2; }
.layout > aside { grid-row: 3; }

If the design requires a mobile reflow, change the layout using media queries rather than manipulating the DOM order via JavaScript.

Masonry-like layouts #

Masonry layouts are the easiest to break from an accessibility standpoint. If the masonry cards are interactive, developers must maintain a predictable source order.

When using native CSS grid lanes, utilize the flow-tolerance property to enforce reading order. Accept a slight visual packing inefficiency (gaps in the layout) in exchange for a usable keyboard flow.

<ul class="masonry">
  <li><a href="/item-1">Item 1</a></li>
  <li><a href="/item-2">Item 2</a></li>
  <li><a href="/item-3">Item 3</a></li>
  <li><a href="/item-4">Item 4</a></li>
</ul>

In CSS, use the flow-tolerance property to ensure that the keyboard focus follows the DOM order, even if it creates gaps in the visual layout.

.masonry {
  display: grid-lanes;
  grid-template-columns: repeat(6, 1fr);
  gap: 1rem;
  /* Enforces DOM order placement over tight visual packing */
  flow-tolerance: strict;
}

.masonry > li {
  list-style: none;
}

Remediation playbook #

To remediate existing layout order issues, follow this sequence:

  • Restore DOM order: Revert to a meaningful HTML sequence that reflects the intended reading and task progression.
  • Remove manual indices: Delete all positive tabindex values (tabindex="2") unless there is a highly specific, documented necessity.
  • Task-based testing: Re-test the keyboard order by attempting to complete real tasks (like checking out), rather than just tabbing through isolated components.
  • Stress testing: Re-test the interface at high zoom levels (400%) and within narrow mobile viewports.
  • AT validation: Spot-check the layout using at least one screen reader and one magnification workflow.
  • User testing: If possible, test with real users who rely on assistive technologies to ensure the layout is genuinely accessible.

Testing checklist and tooling #

While automated tooling helps identify baseline issues, evaluating focus order remains primarily a manual interaction test. Apply this lightweight testing routine to your layouts:

  • Keyboard-only pass: Navigate using only Tab, Shift+Tab, Enter, Space, and the arrow keys.
  • Visual focus pass: Confirm the focus indicator remains visible at all times and preserves the user's context.
  • Zoom pass: Test the layout at 200% and 400% browser zoom.
  • Screen reader spot-check: Verify that the reading sequence and interaction sequence remain coherent.
  • Automated pass: Run Axe or Lighthouse to catch obvious structural issues, then follow up with the manual tests above.

Guidance for design systems

To prevent teams from repeating these accessibility bugs across different products, incorporate order rules directly into the design system:

  • Define semantic order: Establish the expected semantic DOM order as part of every component's API documentation.
  • Require reviews: Treat visual reordering via CSS as an opt-in exception requiring an accessibility review, rather than a default layout pattern.
  • Enforce acceptance criteria: Add strict keyboard sequence checks to the QA acceptance criteria for all new components.
  • Document anti-patterns: Maintain a clear record of known safe and unsafe layout patterns for engineering teams to reference.

Conclusion #

Whether building a simple flexbox row or experimenting with experimental CSS grid lanes, document order and visual order do not need to perfectly mirror each other in every cosmetic detail. However, they must strictly align wherever the sequence affects meaning, navigation, or task completion.

By starting with meaningful HTML, utilizing CSS solely for presentation rather than semantics, and testing layouts exclusively with a keyboard prior to shipping, developers can ensure their applications remain robust and accessible to all users.

Edit on Github