-Display Order

+Display Order: the 'order' property

-Display Order Shorthand: the 'order' property

+	
 	Name: order
-	Value: [ <<'layout-order'>> <<'reading-order'>>? ] |
-	       [ [ reading || layout ] && <> ]
+	Value: <>
+	Initial: 0
 	Applies to: [=flex items=] and [=grid items=]
 	Inherited: no
+	Computed value: specified integer
+	Animation type: by computed value type
 	
 
+	
+		flexible-order.html
+	
+
 	Boxes are generally displayed and laid out
 	in the same order as they appear in the source document.
-	The 'order' property and its [=longhands=]
-	can be used to rearrange the order of boxes
+	In some [=formatting contexts=],
+	the 'order' property can be used to rearrange the order of boxes
 	to deliberately create a divergence
-	of the underlying order of elements
-	and their speech and navigation order
-	and/or their spatial arrangement on the 2D visual canvas.
-
-	Advisement: The 'order' property is not a replacement for correct source ordering.
-	The ordering of content within conformant documents must be sensical without CSS.
-	Authoring tools and documents that use 'order' or its [=longhands=]
-	as a lazy way of reordering the document
-	are non-conformant.
-
-	The 'order' property sets both 'layout-order' and 'reading-order'
-	in a single declaration.
-	Values have the following meanings:
-
-	

-		
<>
-		

-			If one integer and no keyword is specified,
-			then sets 'layout-order' to the specified integer,
-			and sets 'reading-order' to its [=initial value=].
-			If two integers are specified,
-			the first sets 'layout-order' and the second sets 'reading-order'.
-			Otherwise sets the appropriate [=longhand=](s) to the specified integer(s).
-
-		
layout
-		

-			Indicates setting 'layout-order' to the specified integer.
-			If ''reading'' is not specified,
-			'reading-order' is set to its [=initial value=].
-
-		
reading
-		

-			Indicates setting 'reading-order' to the specified integer.
-			If ''layout'' is not specified,
-			'layout-order' is set to its [=initial value=].
-	
-
-	Note: The single-integer syntax sets only 'layout-order',
-	in order to enable rearranging layout for better visual display
-	without changing the underlying reading order.
+	of the logical order of elements
+	and their spatial arrangement on the 2D visual canvas.
+	(See [[#order-accessibility]].)
+
+	Specifically,
+	the 'order' property controls the order in which
+	[=flex items=] or [=grid items=] appear within their container,
+	by assigning them to ordinal groups.
+	It takes a single <> value,
+	which specifies which ordinal group the item belongs to.
 
 	

 		Here's an example of a catalog item card
@@ -1160,119 +1077,36 @@ Display Order Shorthand: the 'order' property
 		
 	
 
-

-Reading Order: the 'reading-order' property
-
-	
-	Name: reading-order
-	Value: <>
-	Initial: 0
-	Applies to: all elements
-	Inherited: no
-	Computed value: specified integer
-	Animation type: by computed value type
-	
-
-	The 'reading-order' property controls the order in which
-	elements are rendered to speech
-	or are navigated to when using (linear) sequential navigation methods.
-	It takes a single <> value,
-	which specifies which ordinal group the item belongs to.
-	Sibling elements are ordered starting from the lowest numbered ordinal group and going up;
-	elements with the same ordinal group are keep the order they appear in the source document.
-
-	The 'reading-order' property affects neither layout nor painting order
-	and therefore has no effect on rendering to the visual [=canvas=].
-
-	Advisement: The source document should express
-	the underlying logical order of elements.
-	The 'reading-order' property exists for cases where a given document
-	can have multiple reading orders depending on layout changes,
-	e.g. in response to [=media queries=].
-	In such cases, the most common or most fundamental reading order
-	should be encoded in the source order
-	so that the document is sensical without CSS.
-
-	If the host language defines features for explicitly controlling
-	the reading or navigation order
-	(such as tabindex [[HTML]]),
-	these take precedence over 'reading-order':
-	the modified document order created by 'reading-order'
-	essentially replaces the underlying source order
-	for the purpose of such features.
-
-	ISSUE: Is this the most appropriate interaction with with tabindex?
-
-

-Box Order: the 'layout-order' property
-
-	
-	Name: layout-order
-	Value: <>
-	Initial: 0
-	Applies to: [=flex items=] and [=grid items=]
-	Inherited: no
-	Computed value: specified integer
-	Animation type: by computed value type
-	
-
-	
-		flexible-order.html
-	
-
-	By allowing the layout to be rearranged
-	without affecting the underlying document source order,
-	the 'layout-order' property lets authors keep
-	a document’s reading and interaction order matched to the visual perception order
-	in cases where it does not match the layout order.
-
-	Specifically, the 'layout-order' property controls the order in which
-	[=flex items=] or [=grid items=] appear within their container
-	by assigning them to the ordinal groups,
-	as specified by its <> value.
-
-	[=flex container|Flex=] and [=grid containers=] then lay out their contents
+	[=flex container|Flex=] and [=grid containers=] lay out their contents
 	in order-modified document order,
 	starting from the lowest numbered ordinal group and going up.
 	Items with the same ordinal group are laid out in the order they appear in the source document.
-
 	This also affects the painting order [[!CSS2]],
 	exactly as if the [=flex item|flex=]/[=grid items=] were reordered in the source document.
 	Absolutely-positioned children of a [=flex container|flex=]/[=grid container=]
 	are treated as having ''order: 0''
 	for the purpose of determining their painting order relative to [=flex item|flex=]/[=grid items=].
 
-	Advisement: Authors should generally use the 'order' [=shorthand=]
-	(which overrides prior values of 'reading-order')
-	rather than 'layout-order'.
-	This prevents inappropriate values of 'reading-order'
-	declared elsewhere in the [=cascade=]
-	from combining with 'layout-order'
-	to create incomprehensible layouts.
-
-	Note: Since it was introduced in Level 3,
-	'order' also has broader support than the 'layout-order' longhand.
-
 	Unless otherwise specified by a future specification,
 	this property has no effect on boxes that are not [=flex items=] or [=grid items=].
 
 

 Reordering and Accessibility
 
-	The 'layout-order' property does not affect ordering in non-visual media
+	The 'order' property does not affect ordering in non-visual media
 	(such as speech).
-	Likewise, 'layout-order' does not affect
+	Likewise, 'order' does not affect
 	the default traversal order of sequential navigation modes
 	(such as cycling through links, see e.g. tabindex [[HTML]]).
 
 	Advisement:
-	Authors must use 'layout-order' only for spatial, not logical, reordering of content.
-	Style sheets that use 'layout-order' to perform logical reordering are non-conforming.
+	Authors must use 'order' only for spatial, not logical, reordering of content.
+	Style sheets that use 'order' to perform logical reordering are non-conforming.
 
 	Note: This is so that non-visual media and non-CSS UAs,
 	which typically present content linearly,
 	can rely on a logical source order,
-	while 'layout-order' is used to tailor the layout order.
+	while 'order' is used to tailor the layout order.
 	(Since visual perception is two-dimensional and non-linear,
 	the desired layout order is not always logical.)
 
@@ -1280,7 +1114,7 @@ Reordering and Accessibility
 	authoring tools--
 	including WYSIWYG editors as well as Web-based authoring aids--
 	must reorder the underlying document source
-	and not use 'layout-order' to perform reordering
+	and not use 'order' to perform reordering
 	unless the author has explicitly indicated that
 	the spatial order should be out-of-sync with
 	the underlying document order (which determines speech and navigation order).
@@ -1306,14 +1140,218 @@ Reordering and Accessibility
 
 	Note: User agents, including browsers, accessible technology, and extensions,
 	may offer spatial navigation features.
-	This section does not preclude respecting the 'layout-order' property
+	This section does not preclude respecting the 'order' property
 	when determining element ordering in such spatial navigation modes;
 	indeed it would need to be considered for such a feature to work.
-	But 'layout-order' is not the only (or even the primary) CSS property
+	But 'order' is not the only (or even the primary) CSS property
 	that would need to be considered for such a spatial navigation feature.
 	A well-implemented spatial navigation feature would need to consider
 	all the layout features of CSS that modify spatial relationships.
 
+

+Reading Order: the 'reading-order-items' property
+
+	
+	Name: reading-order-items
+	Value: normal from-order? | flex [ visual | flow ] | grid [ rows | columns ]
+	Initial: normal
+	Applies to: flex and grid containers
+	Inherited: no
+	Computed value: as specified
+	Animation type: not animatable
+	
+
+	The 'reading-order-items' property controls the order in which
+	elements in a flex or grid layout are rendered to speech
+	or are navigated to when using (linear) sequential navigation methods.
+
+	It takes one or more keyword values. Values are defined as follows:
+
+	

+		
normal
+		

+			Follow the order of elements in the DOM.
+		
normal from-order
+		

+			Follows the [=order-modified document order=].
+			Therefore, as 'normal' unless the 'order'
+			property has been used to change the order of items.
+		
flex visual
+		

+			Only takes effect on flex containers. 
+			Follows the visual reading order of flex items,
+			taking the writing mode into account.
+			Therefore, a document in English, with a 'flex-direction' of 'row-reverse'
+			and 'reading-order-items' of 'flex visual'
+			would have a reading order of left to right.
+		
flex flow
+		

+			Only takes effect on flex containers.
+			Follows the 'flex-flow' direction.
+		
grid rows
+		

+			Only takes effect on grid containers.
+			Follows the visual order of grid items by row,
+			taking the writing mode into account.
+		
grid columns
+		

+			Only takes effect on grid containers.
+			Follows the visual order of grid items by column,
+			taking the writing mode into account.
+	
+
+	ISSUE: As raised in a comment by fantasai,
+	do we need the multiple keywords, or should we hyphenate?
+
+	

+		In this example, there are three flex items displayed as a row,
+		The 'reading-order-items' property has a value of 'flex visual'.
+		The 'flex-direction' property is 'row-reverse'.
+		The reading order of these items is therefore
+		"Item 3", "Item 2", "Item 1", reading from left to right.
+		
+		
+		<div class="wrapper">
+        	<a href="#">Item 1</a>
+        	<a href="#">Item 2</a>
+        	<a href="#">Item 3</a>
+    	</div>
+		
+
+		
+        .wrapper {
+            display: flex;
+            flex-direction: row-reverse;
+            reading-order-items: flex visual;
+        }
+		
+	
+
+	

+		In this example there are four grid items,
+		placed on a grid and displayed visually out of DOM order.
+		The 'reading-order-items' property has a value of 'grid rows',
+		and the document is in English.
+		The reading order of these items is therefore
+		"Item 4", "Item 2", "Item 3", "Item 1".
+
+		
+		<div class="wrapper">
+        	<a class="a" href="#">Item 1</a>
+        	<a class="b" href="#">Item 2</a>
+        	<a class="c" href="#">Item 3</a>
+			<a class="d" href="#">Item 4</a>
+    	</div>
+		
+
+		
+		.wrapper {
+            display: grid;
+            grid-template-columns: repeat(3, 150px);
+            grid-template-areas: "d b b"
+                                 "c c a";  
+            reading-order-items: grid rows;
+        }
+
+        .a { grid-area: a; }
+        .b { grid-area: b; }
+        .c { grid-area: c; }
+        .d { grid-area: d; }
+		
+	
+
+	The 'reading-order-items' property affects neither layout nor painting order
+	and therefore has no effect on rendering to the visual [=canvas=].
+
+	When using a 'flex' or 'grid' keyword value,
+	the 'order' property is taken into account.
+
+	

+		In this example, there are three flex items displayed as a row,
+		The 'reading-order-items' property has a value of 'flex flow'.
+		The third item in the DOM has 'order=-1'.
+		The reading order of these items is therefore
+		"Item 3", "Item 1", "Item 2".
+		
+		
+		<div class="wrapper">
+        	<a href="#">Item 1</a>
+        	<a href="#">Item 2</a>
+        	<a href="#">Item 3</a>
+    	</div>
+		
+
+		
+		.wrapper a:nth-child(3) {
+            order: -1;
+        }
+
+        .wrapper {
+            display: flex;
+            reading-order-items: flex flow;
+        }
+		
+	
+
+	Advisement: The source document should express
+	the underlying logical order of elements.
+	The 'reading-order-items' property exists for cases where a given document
+	can have multiple reading orders depending on layout changes,
+	e.g. in response to [=media queries=].
+	In such cases, the most common or most fundamental reading order
+	should be encoded in the source order
+	so that the document is sensical without CSS.
+
+	If the host language defines features for explicitly controlling
+	the reading or navigation order
+	(such as tabindex [[HTML]]),
+	these take precedence over 'reading-order-items':
+	the modified document order created by 'reading-order-items'
+	essentially replaces the underlying source order
+	for the purpose of such features.
+
+	ISSUE: Is this the most appropriate interaction with with tabindex?
+
+	

+		
Design Considerations and Background
+
+		Some of the considerations that went into the design
+		of 'reading-order-items' are:
+
+		* There are clear use cases for disconnecting
+			the [=reading and navigation order=] from the box layout order,
+			the most fundamental of which is to make sure
+			the [=reading and navigation order=] matches the visual perception order
+			when it is not the same as the box layout order.
+			(Visual perception is non-linear, and is influenced by things like
+				the size, color contrast, and spacing of a visual element,
+				not just its spatial coordinates on the page.)
+		* It is a core principle of Web platform architecture,
+			in order to allow content to be accessible to the widest possible audience
+			across devices that exist now and in the future,
+			for the underlying document to be sensical independent of CSS.
+			Therefore the underlying document order
+			should represent a logical ordering of its elements
+			regardless of its visual presentation.
+		* For components of a page that do not have a strong inherent order,
+			a document can have multiple visual presentations with different layouts,
+			all conveying the same semantic information.
+			It should be possible for all of these presentations to have good accessibility.
+		* Linear navigation, focus sequencing order, and screen-reader order
+			should always match, because there are users who use them together.
+		* Each component or hierarchical level of a page
+			can have different requirements for reordering,
+			so CSS reordering controls should not lend themselves
+			too easily to blanket use
+			(like 'box-sizing')
+			rather than tailored use
+			(like flow-relative vs. physical properties and values).
+	
+
+	ISSUE(7387): DOM needs a convenient reordering function
+	so that authors (even authors who don't usually write JS)
+	can easily perform source order reordering when necessary
+	instead of misusing 'order' or 'reading-order-items'.