Bringing back the reading-order property

Author: rachelandrew

css-display-4/Overview.bs

@@ -1176,7 +1176,6 @@ The order is determined by the 'reading-flow' property.
 
 ISSUE(9922): Should this property also apply to tables?
 
-ISSUE(9230): Define how reading-flow interacts with focusable display: contents elements.
 
 	<pre class='propdef'>
 	Name: reading-flow
@@ -1319,9 +1318,61 @@ ISSUE(9230): Define how reading-flow interacts with focusable display: contents
 		</pre>
 	</div>
 
+	<h3 id='reading-order'>
+	Overriding Reading Flow: the 'reading-order' property</h3>
+	<pre class='propdef'>
+	Name: reading-order
+	Value: <<integer>>
+	Initial: 0
+	Applies to: Direct children of a reading flow container
+	Inherited: no
+	Computed value: specified integer
+	Animation type: by computed value type
+	</pre>
+	
+	The 'reading-order' property lets the author change where in the reading flow an item is visited, 
+	overriding the position set by the 'reading-flow' property on its parent.
+	It takes a single <dfn value for=reading-order><<integer>></dfn> value,
+	which specifies which ordinal group the item belongs to.
+	Sibling elements are ordered starting from the lowest numbered ordinal group and going up.
+
+	If the reading order of two items is equivalent, the 'reading-flow' property breaks the tie.
+
+	<div class='example'>
+		In this example there are six grid items,
+		the 'grid-auto-flow' property has a value of ''dense'',
+		therefore items may display out of source order.
+		The 'reading-order' property on the item with a class of 'top' is '-1'
+		Therefore Item 4 will be the first item in reading flow.
+		The remaining items will be visited in the order they display in rows,
+		as 'reading-flow' has a value of 'grid-rows'.
+
+		<pre class="lang-markup">
+		&lt;div class="wrapper"&gt;
+			&lt;a href="#"&gt;Item 1&lt;/a&gt;
+			&lt;a href="#"&gt;Item 2&lt;/a&gt;
+			&lt;a href="#"&gt;Item 3&lt;/a&gt;
+			&lt;a class="top" href="#"&gt;Item 4&lt;/a&gt;
+			&lt;a href="#"&gt;Item 5&lt;/a&gt;
+			&lt;a href="#"&gt;Item 6&lt;/a&gt;
+		&lt;/div&gt;
+		</pre>
+
+		<pre class="lang-css">
+		.wrapper {
+			display: grid;
+			grid-template-columns: repeat(3, 150px);
+			grid-auto-flow: dense;
+			reading-flow: grid-rows;
+		}
+
+		.top { reading-order: -1; }
+		</pre>
+	</div>
+
 	Advisement: The source document should express
 	the underlying logical order of elements.
-	The 'reading-flow' property exists for cases where a given document
+	The 'reading-flow' and 'reading-order' properties exist 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
@@ -2160,9 +2211,10 @@ Additions since Level 3</h3>
 
 	The following features were added since <a href="https://www.w3.org/TR/css-display-3/">CSS Display Module Level 3</a>:
 
-	* the 'reading-flow' property 
+	* The 'reading-flow' property 
 		(<a href="https://github.com/w3c/csswg-drafts/issues/8589#issuecomment-1721504153">Issue 8589</a>)
-	* the ability to animate 'display'
+	* The 'reading-order' property (<a href="https://github.com/w3c/csswg-drafts/issues/11208#issuecomment-2625850559">Issue </a>)
+	* The ability to animate 'display'
 
 <h2 id="priv" class="no-num">
 Privacy Considerations</h2>