CSS flex or grid order does not match DOM order

What is this issue?

A flex or grid container’s children are visually rearranged using the CSS order property (or an equivalent technique, such as CSS Grid’s explicit grid-column/grid-row placement) so that what appears first, second, and third on screen no longer matches the order those same elements appear in the HTML source. The DOM (the tree structure the browser builds from HTML, representing every element and how they nest) still reflects the original, unreordered sequence.

Assistive technology reads the DOM, not the rendered visual layout, so a screen reader announces the elements in their original source order regardless of where CSS has visually repositioned them. The same is true of the browser’s default keyboard tab order, which is derived from DOM order rather than visual position. The mismatch is invisible to a sighted mouse user, since visual order is all they perceive; it only surfaces for anyone relying on DOM order instead.

Why does this matter?

Semantic HTML relies on document order to convey meaning (a form’s fields, a card’s heading followed by its description, a navigation menu’s items), and CSS order breaks that link silently, with nothing in the rendered page hinting that a mismatch exists. A developer testing visually sees a perfectly laid-out page and has no reason to suspect the underlying reading order has drifted apart from it.

This is especially damaging on responsive layouts, where order is frequently used to rearrange content differently at different viewport widths, such as a sidebar moved above the main content on mobile. Each responsive breakpoint can introduce its own version of the mismatch, so a page can pass a review at one screen size and fail at another with no code change in between, just a different order value taking effect.

Who is affected?

• Screen reader users: hear content announced in its original DOM order, which can be substantially different from, and less coherent than, the reordered visual sequence a sighted user experiences, especially across text that relies on reading things in sequence to make sense.
• Keyboard users: Tab through elements in DOM order, so a visually reordered layout produces a tab sequence that jumps around relative to what’s on screen, the same underlying mismatch as a positive tabindex, just caused by CSS instead.
• Cognitive disabilities: users relying on a page’s structure matching its announced or navigated order to build understanding lose that consistency when visual layout and underlying sequence diverge, adding confusion on top of whatever the page’s content already asks of them.

What users experience

Grace uses VoiceOver on her Mac to read a product page laid out with CSS Grid. On desktop, the layout visually places the price and “Add to cart” button before the full product description, using grid-row placement to pull them up in the visual stack even though they sit last in the HTML. VoiceOver announces the full multi-paragraph description first, its actual DOM position, followed only afterward by the price and the add-to-cart button, the opposite of what a sighted user sees at a glance. Grace has to listen through several paragraphs of description before she even hears the price, then decide whether it’s worth reading the whole thing again to find the button.

How do I fix it?

Reorder the elements in the HTML source itself to match the intended reading order, rather than using CSS to visually rearrange them away from it. This works because it fixes the actual DOM sequence that assistive technology and keyboard navigation both depend on, instead of only changing what sighted users see; once source order and visual order agree, every user of the page experiences the same sequence, by whatever means they navigate it.

Reserve CSS order (and similar layout-only repositioning techniques) strictly for changes that carry no reading-order meaning at all: a small decorative flourish, or a genuinely interchangeable pair of elements where either sequence conveys the same information. For anything that affects comprehension (form field sequence, a card’s heading before its body, a checkout flow’s steps), restructure the markup instead of reaching for a CSS property that only ever changes what one group of users perceives.

Code Examples

<div class="layout">
  <aside>Sidebar</aside>
  <main>Main content</main>
</div>

.layout { display: flex; }
main { order: -1; } /* visually first, but last in the DOM */

<div class="layout">
  <main>Main content</main>
  <aside>Sidebar</aside>
</div>

.layout { display: flex; } /* no order needed - DOM order already matches */

Moving <main> ahead of <aside> in the HTML achieves the exact same visual result the order: -1 declaration was producing, but now the DOM order, the tab order, and what a screen reader announces all match the visual layout automatically, with one fewer CSS property to keep track of at every future breakpoint.

Common Mistakes

Mistake: “CSS order is purely a visual tool, so it can’t cause an accessibility problem.” order is visual-only in the sense that it doesn’t touch the DOM, but that’s precisely the mechanism behind this rule’s failure: assistive technology and keyboard navigation read the DOM, not the rendered visual layout, so a purely visual change is exactly what creates the mismatch between what sighted and non-sighted users experience.

Mistake: “We tested this page with a screen reader and it sounded fine.” A screen reader test only catches this defect if the tester happens to notice the announced sequence differs from what they’d expect visually, on content where either order is plausible, or on a page the tester isn’t deeply familiar with, the mismatch can pass an informal listen-through undetected. Comparing the DOM source order directly against the visual layout is a more reliable check than listening alone.

Mistake: “This only matters on desktop, since that’s where our complex Grid layouts live.” Responsive layouts frequently use different order values at different breakpoints specifically to rearrange content for smaller screens, which means a mobile layout can introduce its own independent version of this mismatch even if the desktop layout is fine, so each breakpoint needs its own check.

How RedFlag Detects This

Guidance only: RedFlag documents this issue but does not currently flag it; verify manually. RedFlag’s own coverage model records this criterion’s evidence as docs_only: there is no automated comparison anywhere in RedFlag’s detection code between an element’s DOM order and its rendered visual order. Confirming a mismatch requires comparing computed CSS layout position against source order, which today only happens through manual review.

False negative: every occurrence of this defect passes every RedFlag scan silently, since nothing automatically compares DOM order against visual order. False positive: not applicable, since nothing is ever automatically flagged. Manual step: for any layout using CSS order, Grid placement properties, or similar techniques, compare the HTML source order against the rendered visual order directly, and check with a screen reader whether the announced sequence still makes sense.

Manual Testing

1. Open the page’s HTML source or DevTools’ Elements panel and note the DOM order of elements inside any flex or grid container.
2. Compare that order against what you see rendered on screen, checking specifically for CSS order values or Grid placement properties that differ from source order.
3. Turn on a screen reader (NVDA, JAWS, or VoiceOver) and listen to the sequence it announces for that section.
4. Confirm the announced sequence makes sense as a standalone reading order, not just that it happens to match the visual layout by coincidence.
5. Repeat at each responsive breakpoint where the layout’s CSS changes, since order values commonly differ across screen sizes.

Related WCAG Success Criteria

1.3.2 Meaningful Sequence: When the sequence in which content is presented affects its meaning, a correct reading sequence must be programmatically determinable. This rule is a direct, common failure of that requirement: CSS visually presents one sequence while the DOM (the only sequence assistive technology can determine) represents a different one.

2.4.3 Focus Order: Components must receive focus in an order that preserves meaning and operability. When the reordered content is also keyboard-focusable, the same underlying CSS mismatch produces a confusing tab sequence, making this rule relevant to both criteria depending on whether the reordered content is interactive.

Related Issues

Tab order doesn’t match visual order and Manual check flagged an incorrect tab order document the keyboard-focus consequence of this same CSS-driven mismatch, for the subset of cases where the reordered content is also interactive.

Element has a positive tabindex is the other common root cause of a scrambled tab order, distinct from this rule’s CSS-driven cause but producing an equivalent symptom.

Element in the focus order has no matching interactive role is a related but distinct focus-order defect within the same 2.4.3 neighborhood, covering missing semantics rather than sequence.

References

• W3C Understanding 1.3.2: Meaningful Sequence
• MDN: CSS order property
• MDN: CSS Grid Layout