Overview.bs

<pre class='metadata'>
Title: CSS Gap Decorations Module Level 1
Shortname: css-gaps
Level: 1
Status: ED
Prepare for TR: no
Group: csswg
Work Status: exploring
Repository: w3c/csswg-drafts
URL: https://drafts.csswg.org/css-gaps-1
TR: https://www.w3.org/TR/css-gaps-1/
Editor: Kevin Babbitt, Microsoft, https://github.com/kbabbitt, w3cid 124689
Abstract: This module introduces several properties to add row and column gap decorations to container layout types such as grid and flex.
</pre>
<pre class='anchors'>
urlPrefix: https://drafts.csswg.org/css-grid-3/; type: dfn; spec: CSS-GRID-3; text: masonry container
</pre>
<pre class='link-defaults'>
spec:css-color-5; type:type; text:<color>
</pre>

<h2 id="intro">
Introduction</h2>

	<em>This section is not normative.</em>

	[[CSS-MULTICOL-1#column-gaps-and-rules]] allows for rules to be drawn
	between columns in a <a>multicol container</a>. This specification expands
	upon the 'column-rule-width', 'column-rule-style', and 'column-rule-color'
	properties, adding equivalents in the row direction, expanding their
	application to other container layouts, and giving advanced control over
	where and how gap decorations are painted.

<h3 id="values">
Value Definitions</h3>

	This specification follows the <a href="https://www.w3.org/TR/CSS2/about.html#property-defs">CSS property definition conventions</a> from [[!CSS2]]
	using the <a href="https://www.w3.org/TR/css-values-3/#value-defs">value definition syntax</a> from [[!CSS-VALUES-3]].
	Value types not defined in this specification are defined in CSS Values &amp; Units [[!CSS-VALUES-3]].
	Combination with other CSS modules may expand the definitions of these value types.

	In addition to the property-specific values listed in their definitions,
	all properties defined in this specification
	also accept the <a>CSS-wide keywords</a> as their property value.
	For readability they have not been repeated explicitly.

<h2 id="gap-decorations">
Gap decorations</h2>

	Various layouts in CSS such as
	<a>multicol containers</a>, <a>flex containers</a>, <a>grid containers</a>, and <a>masonry containers</a>
	position child boxes adjacent to each other with gaps, also known as <a>gutters</a>, between them.
	Each such gap may contain a <dfn>gap decoration</dfn>,
	which is a visible separator (such as a line) painted between adjacent boxes.

	<div class="example">
		<pre>
			.grid-with-spans {
			  display: grid;
			  grid-template: repeat(4, 100px) / repeat(4, 100px);
			  gap: 20px;
			  row-rule: 6px solid red;
			  column-rule: 6px solid blue;
			}
		</pre>
		<figure>
			<img alt="" src="images/example-grid-with-spans.png">
			<figcaption>A grid with spanning items and gap decorations.</figcaption>
		</figure>
	</div>

	<div class="example">
		<pre>
			.flex {
			  display: flex;
			  flex-wrap: wrap;
			  gap: 20px;
			  width: 500px;
			  row-rule: 6px solid red;
			  column-rule: 6px solid blue;
			}
		</pre>
		<figure>
			<img alt="" src="images/example-flex.png">
			<figcaption>A flexbox with gap decorations.</figcaption>
		</figure>
	</div>

<h3 id="layout-painting">
Layout and painting</h3>

	This specification does not generally define the geometry of gaps in container layouts;
	that is left to other specifications.
	See [[CSS-ALIGN-3#gaps]] for definitions pertaining to
	<a>multicol containers</a>, <a>flex containers</a>, and <a>grid containers</a>.

	<a>Gap decorations</a> do not take up space.
	That is, the presence or width of a <a>gap decoration</a> will not alter the placement of anything else.
	If a <a>gap decoration</a> is wider than its gap,
	any adjacent boxes will overlap the decoration,
	and in some cases the decoration may extend outside the box of the container.
	<a>Gap decorations</a> are painted just above the border of the container.
	For scrollable containers,
	note that while the border and background of the container aren't scrolled,
	the decorations need to scroll along with items in the container.

	A <dfn>gap intersection point</dfn> is defined to exist in each of the following locations:
	<ul>
		<li>The center of an intersection between a gap and the content edge of the container.</li>
		<li>The center of an intersection between gaps in different directions.</li>
	</ul>

	The following examples illustrate the locations of <a>gap intersection points</a>,
	marked with a magenta <span style="color:#f0f">+</span> in each case.

	<div class="example">
		<pre>
			.grid {
				display: grid;
				grid-template: repeat(4, 100px) / repeat(4, 100px);
				gap: 20px;
				background: rgb(255 255 128);
			}
			.grid > * {
				border: 1px dashed black;
			}
		</pre>
		<figure>
			<img alt="" src="images/example-gap-intersection-grid.png">
			<figcaption>
				Locations of <a>gap intersection points</a> in a grid with spanning items.
				Note the presence of <a>gap intersection points</a>
				even where a spanning item touches the edge of a container,
				and where an intersection is flanked by spanning items on either side
				(for example between #2 and #6, or #4 and #7).
			</figcaption>
		</figure>
	</div>

	<div class="example">
		<pre>
			.flex {
				display: flex;
				flex-wrap: wrap;
				gap: 20px;
				width: 500px;
				background: rgb(255 255 128);
			}
			.flex > * {
				border: 1px dashed black;
			}
		</pre>
		<figure>
			<img alt="" src="images/example-gap-intersection-flex.png">
			<figcaption>
				Locations of <a>gap intersection points</a> in a flexbox.
				Note the presence of <a>gap intersection points</a> at edges of the container,
				and the presence of two <a>gap intersection points</a> in close proximity where
				items in adjacent rows don't quite line up with each other (between #2, #3, #4, and, #5).
			</figcaption>
		</figure>
	</div>

	Note: [[CSS-ALIGN-3#column-row-gap]] defines
	cross-direction gaps in flex containers
	as being between adacent flex items in a single line.
	Thus, in the example above,
	even though the right edges of #4 and #7 line up,
	and the left edges of #5 and #8 line up,
	the spaces between those two pairs of items are <em>two distinct gaps</em>
	since they are on different lines.
	Therefore, the intersection between #4, #5, #7, and #8
	contains two <a>gap intersection points</a> whose locations coincide:
	one at the bottom of the gap between #4 and #5,
	and one at the top of the gap between #7 and #8.

	<a>Gap decorations</a> are painted relative to pairs of <a>gap intersection points</a>,
	in the center of the corresponding gap and parallel to its edges.

	If the positions of one or more gaps coincide exactly due to being [=collapsed gutter|collapsed=],
	at most one decoration will be drawn for that set of gaps.
	The decoration that is drawn is selected according to the
	<a href="https://www.w3.org/TR/CSS2/tables.html#border-conflict-resolution">border conflict resolution</a> rules for tables.

<h3 id="break">
Breaking gap decorations into segments: The 'column-rule-break', 'row-rule-break', and 'rule-break' properties</h3>

	<pre class='propdef'>
		Name: column-rule-break, row-rule-break
		Value: ''none'' | ''spanning-item'' | ''intersection''
		Initial: ''spanning-item''
		Applies to: <a>grid containers</a>, <a>flex containers</a>, <a>multicol containers</a>, and <a>masonry containers</a>
		Inherited: no
		Animation type: discrete
	</pre>

	Sets the behavior for breaking decorations within a given gap into segments
	at visible "T" or "cross" intersections formed by items in the container.
	Precise details for how to apply these values are given in the steps to <a>determine pairs of gap decoration endpoints</a>.

	<dl dfn-type="value" dfn-for="column-rule-break, row-rule-break">
		<dt><dfn>none</dfn>
		<dd>
			Gap decorations do not start or end at visible "T" or "cross" intersections.
			Instead, a single continuous decoration is painted from one end of the gap to the other.
		</dd>
		<dt><dfn>spanning-item</dfn>
		<dd>
			Gap decorations start and end at visible "T" intersections but continue through visible "cross" intersections.
		</dd>
		<dt><dfn>intersection</dfn>
		<dd>
			Gap decorations start and end at visible "T" and "cross" intersections.
		</dd>
	</dl>

	Issue: Bikeshed these values.

	<pre class='propdef shorthand'>
		Name: rule-break
		Value: <<'column-rule-break'>>
		Applies to: Same as 'column-rule-break' and 'row-rule-break'
	</pre>

	Sets the 'column-rule-break' and 'row-rule-break' properties to the same value.

<h4 id="pairing">
Pairing gap intersection points into segments</h4>

	<div algorithm>
		In the context of a given |gap|,
		a pair of <a>gap intersection points</a> |a| and |b| is considered
		<dfn noexport>discontiguous</dfn>
		if a line segment from |a| to |b|,
		with the same width as |gap|,
		intersects a child item in the container.

		Note: The primary use case for this definition is to avoid having
		<a>gap decorations</a> intersect spanning items when not intended by the author,
		for example when a spanning item touches the edge of the container,
		or when a spanning item forms a "T intersection".
		However, the specific phrasing of the definition
		is also intended to address cases such as the one below:
		<br>
		<img alt="" src="images/flex-offset-gap.png">
		<br>
		The four marked <a>gap intersection points</a> fall along a common gap centerline.
		However, because item 3 is slightly wider than items 1 and 5,
		the second and third points from the top are <a>discontiguous</a>.
		Thus, the two upper <a>gap intersection points</a> form a pair,
		and the two lower <a>gap intersection points</a> form a pair.
		(There is an additional pair of <a>gap intersection points</a>,
		slightly offset to the right of the two middle points,
		which are not marked.
		These points will form another pair.)
	</div>

	<div algorithm>
		To <dfn>determine pairs of gap decoration endpoints</dfn> within a given |gap|:
		<ol>
			<li>
				Let |pairs| be an empty list.
				Let |endpoints| be the list of <a>gap intersection points</a> that fall along the centerline of |gap|,
				ordered from start to end along |gap|'s axis.
				Let |break| be the used value of either 'column-rule-break' or 'row-rule-break',
				whichever applies to |gap|.
			</li>

			<li>
				If |endpoints| contains fewer than 2 items, return |pairs|.
			</li>

			<li>
				If |break| is other than ''column-rule-break/none'',
				and the first two items in |endpoints| are <a>discontiguous</a>,
				remove the first item from |endpoints|, then go back to step 2.
			</li>

			<li>
				Remove the first item from |endpoints|.
				Let |start| be equal to that item.
			</li>

			<li>
				Remove the first item from |endpoints|.
				Let |end| be equal to that item.
			</li>

			<li>
				If |endpoints| is non-empty, and any of the following conditions are true...
				<ol>
					<li>
						|break| is ''column-rule-break/none''.
					</li>
					<li>
						|break| is ''column-rule-break/spanning-item'',
						and |start| is not <a>discontiguous</a> with the first item in |endpoints|.
					</li>
					<li>
						|break| is ''column-rule-break/intersection'',
						and |start| is not <a>discontiguous</a> with the first item in |endpoints|,
						and the intersection is flanked by spanning items on opposing sides.
					</li>
				</ol>
				...then go back to step 5.
			</li>

			<li>
				<a>Compute the offset</a> for |start| within |gap|.
				Offset |start| by the result,
				in the forward direction along |gap|'s axis.
			</li>

			<li>
				<a>Compute the offset</a> for |end| within |gap|.
				Offset |end| by the result,
				in the reverse direction along |gap|'s axis.
			</li>

			<li>
				Add to |pairs| a tuple consisting of |start| and |end|.
			</li>

			<li>
				Go back to step 2.
			</li>
		</ol>
	</div>

	A <a>gap decoration</a> is painted between each pair of endpoints identified using the steps above.

	The following examples illustrate various settings for the <a href="#break">*-rule-break</a> properties.
	To make the differences more apparent, the <a href="#outset">*-rule-outset</a> properties are set to ''0''.

	<div class="example">
		<pre>
			.break-none-grid {
				display: grid;
				grid-template: repeat(4, 100px) / repeat(4, 100px);
				gap: 20px;
				row-rule: 6px solid red;
				column-rule: 6px solid blue;
				rule-break: none;
				rule-outset: 0px;
			}
		</pre>
		<figure>
			<img alt="" src="images/example-break-none-grid.png">
			<figcaption>
				Grid <a>gap decorations</a> with no breaks.
				Note that the <a>gap decorations</a> extend "behind" items placed in the grid.
			</figcaption>
		</figure>
	</div>

	<div class="example">
		<pre>
			.break-spanning-item-grid {
				display: grid;
				grid-template: repeat(4, 100px) / repeat(4, 100px);
				gap: 20px;
				row-rule: 6px solid red;
				column-rule: 6px solid blue;
				rule-break: spanning-item;
				rule-outset: 0px;
			}
		</pre>
		<figure>
			<img alt="" src="images/example-break-spanning-item-grid.png">
			<figcaption>
				Grid <a>gap decorations</a> broken at <a>gap intersection points</a>
				that are not adjacent to spanning items.
			</figcaption>
		</figure>
	</div>

	<div class="example">
		<pre>
			.break-intersection-grid {
				display: grid;
				grid-template: repeat(4, 100px) / repeat(4, 100px);
				gap: 20px;
				row-rule: 6px solid red;
				column-rule: 6px solid blue;
				rule-break: intersection;
				rule-outset: 0px;
			}
		</pre>
		<figure>
			<img alt="" src="images/example-break-intersection-grid.png">
			<figcaption>
				Grid <a>gap decorations</a> broken at every <a>gap intersection point</a>
				that is not flanked by spanning items on opposing sides.
			</figcaption>
		</figure>
	</div>

	<div class="example">
		<pre>
			.break-none-flex {
				display: flex;
				flex-wrap: wrap;
				gap: 20px;
				row-rule: 6px solid red;
				column-rule: 6px solid blue;
				rule-break: none;
				rule-outset: 0px;
			}
		</pre>
		<figure>
			<img alt="" src="images/example-break-none-flex.png">
			<figcaption>
				Flexbox <a>gap decorations</a> with no breaks.
				Note that each flex line has its own distinct gaps.
				Therefore, <a>gap decorations</a> in adjacent flex lines
				are separate from each other even if the gaps happen to line up.
			</figcaption>
		</figure>
	</div>

	Note: Because flexbox has no concept of spanning items,
	''column-rule-break/spanning-item'' on a flexbox has the same effect as
	''column-rule-break/none''.

	<div class="example">
		<pre>
			.break-intersection-flex {
				display: flex;
				flex-wrap: wrap;
				gap: 20px;
				width: 500px;
				gap: 20px;
				row-rule: 6px solid red;
				column-rule: 6px solid blue;
				rule-break: intersection;
				rule-outset: 0px;
			}
		</pre>
		<figure>
			<img alt="" src="images/example-break-intersection-flex.png">
			<figcaption>
				Flexbox <a>gap decorations</a> broken at every <a>gap intersection point</a>.
			</figcaption>
		</figure>
	</div>

<h3 id="outset">
Adjusting gap decoration endpoints: The 'column-rule-outset', 'row-rule-outset', and 'rule-outset' properties</h3>

	<pre class='propdef'>
		Name: column-rule-outset, row-rule-outset
		Value: <<length-percentage>>
		Initial: ''50%''
		Applies to: <a>grid containers</a>, <a>flex containers</a>, <a>multicol containers</a>, and <a>masonry containers</a>
		Inherited: no
		Percentages: refer to the <a>crossing gap width</a>
		Animation type: by computed value type
	</pre>

	These properties can be used to offset the endpoints of <a>gap decorations</a> relative to the
	<a>gap intersection points</a> which would normally determine their endpoints.
	The initial value of ''50%'' places the <a>gap decoration</a> endpoint in the center of the intersection.
	With a value of ''0'', the <a>gap decoration</a> endpoint will coincide with the edge of the intersection.
	Positive values extend towards the center of the intersection;
	negative values recede from it.
	These offsets also apply at the edges of the container,
	where positive values may extend beyond the content bounds of the container.

	<pre class='propdef shorthand'>
		Name: rule-outset
		Value: <<'column-rule-outset'>>
		Applies to: Same as 'column-rule-outset' and 'row-rule-outset'
	</pre>

	Sets the 'column-rule-outset' and 'row-rule-outset' properties to the same value.

	<div class="example">
		<pre>
			.outset-0px {
				column-rule-outset: 0px;
				column-rule-break: intersection;
			}
		</pre>
		<figure>
			<img alt="" src="images/example-column-outset-0px.png">
			<figcaption>
				An outset of ''0px'' aligns the ends of <a>gap decorations</a> with adjacent items.
			</figcaption>
		</figure>
	</div>

	<div class="example">
		<pre>
			.outset-5px {
				column-rule-outset: 5px;
				column-rule-break: intersection;
			}
		</pre>
		<figure>
			<img alt="" src="images/example-column-outset-5px.png">
			<figcaption>
				An outset of ''5px'' extends the ends of <a>gap decorations</a>
				slightly beyond the edges of adjacent items.
			</figcaption>
		</figure>
	</div>

	<div class="example">
		<pre>
			.outset-50percent {
				column-rule-outset: 50%;
				column-rule-break: intersection;
			}
		</pre>
		<figure>
			<img alt="" src="images/example-column-outset-50percent.png">
		<figcaption>
			An outset of ''50%'' - the initial value - extends each end of a <a>gap decoration</a>
			halfway into its intersection.
			Neighboring <a>gap decorations</a> "meet in the middle" to create a continuous line.
			Note that at the edges of the container, the <a>crossing gap width</a> is defined to be ''0'',
			so the outset value of ''50%'' resolves to ''0''
			and thus the <a>gap decoration</a> does not extend beyond the bounds of the container.
			(Contrast with the previous example, which specified an outset in ''px'' units.)
		</figcaption>
		</figure>
	</div>

	<div class="example">
		<pre>
			.outset-negative-5px {
				column-rule-outset: -5px;
				column-rule-break: intersection;
			}
		</pre>
		<figure>
			<img alt="" src="images/example-column-outset-minus-5px.png">
			<figcaption>
				An outset of ''-5px'' shortens the ends of <a>gap decorations</a>
				relative to the edges of adjacent items.
			</figcaption>
		</figure>
	</div>

	When considering the <a>gap intersection points</a> within a given gap,
	each point is assigned a <dfn>crossing gap width</dfn>, defined as follows:
	<dl>
		<dt>
			At the content edge of the container
		<dd>
			The <a>crossing gap width</a> is ''0''.

		<dt>
			At an intersection with another gap
		<dd>
			The <a>crossing gap width</a> is the used value of the 'column-gap' or 'row-gap' property,
			whichever applies to the intersecting gap.
	</dl>

	<div algorithm>
		To <dfn>compute the offset</dfn> for a given <a>gap intersection point</a> |point| within a given |gap|:

		<ol>
			<li>
				Let |width| be the <a>crossing gap width</a> for |point|.
			</li>
			
			<li>
				Let |outset| be the computed value of either 'column-rule-outset' or 'row-rule-outset',
				whichever applies to |gap|.
				Resolve any percentages in |outset| against |width|.
			</li>

			<li>
				Let |result| be |width| multiplied by 50%.
				Subtract |outset| from |result|.
			</li>

			<li>
				Return |result|.
			</li>
		</ol>
	</div>

	For details on how the offset is applied,
	see the steps to <a>determine pairs of gap decoration endpoints</a>.

<h3 id="paint-order">
Gap decoration paint order: The 'rule-paint-order' property</h3>

	<pre class='propdef'>
		Name: rule-paint-order
		Value: row-over-column | column-over-row
		Initial: row-over-column
		Applies to: <a>grid containers</a>, <a>flex containers</a>, and <a>masonry containers</a>
		Inherited: no
		Animation type: discrete
	</pre>

	Sets the paint order for <a>gap decorations</a> in two-dimensional containers.

	The following examples illustrate adjustment of gap decoration paint order using the 'rule-paint-order' property.

	<div class="example">
		<pre>
			.row-over-coulumn {
				rule-paint-order: row-over-column;
				row-rule: 6px solid red;
				column-rule: 6px solid blue;
			}
		</pre>
		<figure>
			<img alt="" src="images/example-row-over-column.png">
			<figcaption>
				Row-over-column gap decoration paint order.
			</figcaption>
		</figure>
	</div>

	<div class="example">
		<pre>
			rule-paint-order: column-over-row;
			row-rule: 6px solid red;
			column-rule: 6px solid blue;
		</pre>
		<figure>
			<img alt="" src="images/example-column-over-row.png">
			<figcaption>
				Column-over-row gap decoration paint order.
			</figcaption>
		</figure>
	</div>

<h2 id="color-style-width">
Color, style, and width</h2>

Property definitions in this section supersede the definitions of properties with the same names in
[[CSS-MULTICOL-1]].

<h3 id="column-row-rule-color">
Gap decoration color: The 'column-rule-color' and 'row-rule-color' properties</h3>

	<pre class='propdef'>
		Name: column-rule-color, row-rule-color
		Value: <<line-color-list>> | <<auto-line-color-list>>
		Initial: currentcolor
		Applies to: <a>grid containers</a>, <a>flex containers</a>, <a>multicol containers</a>, and <a>masonry containers</a>
		Inherited: no
		Animation type: by computed value type
	</pre>

	<pre class='prod'>
		<dfn>&lt;line-color-list&gt;</dfn>          = [ <<line-color-or-repeat>> ]+

		<dfn>&lt;auto-line-color-list&gt;</dfn>     = [ <<line-color-or-repeat>> ]*
									               <<auto-repeat-line-color>>
									               [ <<line-color-or-repeat>> ]*

		<dfn>&lt;line-color-or-repeat&gt;</dfn>     = [ <<color>> | <<repeat-line-color>> ]

		<dfn>&lt;repeat-line-color&gt;</dfn>        = repeat( [ <<integer [1,∞]>> ] , [ <<color>> ]+ )

		<dfn>&lt;auto-repeat-line-color&gt;</dfn>   = repeat( auto , [ <<color>> ]+ )
	</pre>

	<dl>
		<dt><dfn value for=column-rule-color><<color>></dfn></dt>
		<dd>
			Sets the color of <a>gap decorations</a>.
		</dd>
	</dl>

<h3 id="column-row-rule-style">
Gap decoration style: The 'column-rule-style' and 'row-rule-style' properties</h3>

	<pre class='propdef'>
		Name: column-rule-style, row-rule-style
		Value: <<line-style-list>> | <<auto-line-style-list>>
		Initial: none
		Applies to: <a>grid containers</a>, <a>flex containers</a>, <a>multicol containers</a>, and <a>masonry containers</a>
		Inherited: no
		Animation type: discrete
	</pre>

	<pre class='prod'>
		<dfn>&lt;line-style-list&gt;</dfn>          = [ <<line-style-or-repeat>> ]+

		<dfn>&lt;auto-line-style-list&gt;</dfn>     = [ <<line-style-or-repeat>> ]*
									               <<auto-repeat-line-style>>
									               [ <<line-style-or-repeat>> ]*

		<dfn>&lt;line-style-or-repeat&gt;</dfn>     = [ <<line-style>> | <<repeat-line-style>> ]

		<dfn>&lt;repeat-line-style&gt;</dfn>        = repeat( [ <<integer [1,∞]>> ] , [ <<line-style>> ]+ )

		<dfn>&lt;auto-repeat-line-style&gt;</dfn>   = repeat( auto , [ <<line-style>> ]+ )
	</pre>

	These properties set the styles of <a>gap decorations</a>.
	The <<line-style>> values are interpreted as in the <a href="https://www.w3.org/TR/CSS2/tables.html#collapsing-borders">collapsing border model</a>.

<h3 id="column-row-rule-width">
Gap decoration width: The 'column-rule-width' and 'row-rule-width' properties</h3>

	<pre class='propdef'>
		Name: column-rule-width, row-rule-width
		Value: <<line-width-list>> | <<auto-line-width-list>>
		Initial: medium
		Applies to: <a>grid containers</a>, <a>flex containers</a>, <a>multicol containers</a>, and <a>masonry containers</a>
		Inherited: no
		Computed value: list of absolute lengths, <a>snapped as a border width</a>, or ''0'' under conditions described below
		Animation type: by computed value type
	</pre>

	<pre class='prod'>
		<dfn>&lt;line-width-list&gt;</dfn>          = [ <<line-width-or-repeat>> ]+

		<dfn>&lt;auto-line-width-list&gt;</dfn>     = [ <<line-width-or-repeat>> ]*
									               <<auto-repeat-line-width>>
									               [ <<line-width-or-repeat>> ]*

		<dfn>&lt;line-width-or-repeat&gt;</dfn>     = [ <<line-width>> | <<repeat-line-width>> ]

		<dfn>&lt;repeat-line-width&gt;</dfn>        = repeat( [ <<integer [1,∞]>> ] , [ <<line-width>> ]+ )

		<dfn>&lt;auto-repeat-line-width&gt;</dfn>   = repeat( auto , [ <<line-width>> ]+ )
	</pre>

	This property sets the widths of <a>gap decorations</a>. Negative values are not allowed.

	If the computed value of ''column-rule-style'' is ''border-style/none'' or ''border-style/hidden'',
	then the computed value of ''column-rule-width'' is ''0''.
	This behavior is for backwards compatibility with [[css-multicol-1#crw]].

	Issue: Should the "force to 0" behavior apply when lists of values are involved?
	If so, how should this be handled with unaligned lists?

<h3 id="lists-repeat">
Lists of values and the ''repeat-line-color/repeat()'' notation</h3>

	Each of the properties in this section accepts a space-separated list of values.
	Setting multiple values in this way allows for varying <a>gap decorations</a> within a given container.

	<div class="example">
		An author might specify alternating red and blue column rules as follows:
		<pre>
			column-rule-width: 1px;
			column-rule-style: solid;
			column-rule-color: red blue;
		</pre>
	</div>

	Such a list may contain <dfn for="<repeat-line-color>,<auto-repeat-line-color>,<repeat-line-style>,<auto-repeat-line-style>,<repeat-line-width>,<auto-repeat-line-width>">repeat()</dfn> notations.
	Similar to [[css-grid-1#repeat-notation]], these notations allow a series of <a>gap decorations</a>
	that exhibit a recurring pattern to be written in a more compact form.

	The generic form of the ''repeat-line-color/repeat()'' syntax is, approximately,
	<pre class='prod'>
		repeat( [ <<integer [1,∞]>> | auto ] , &lt;value&gt;+ )
	</pre>

	The first argument to ''repeat-line-color/repeat()'' specifies the number of repetitions.
	<dl>
		<dt><<integer>>
		<dd>
			Specifies an <dfn>integer repeater</dfn>.
			An <a>integer repeater</a> expands out to the list of values in the second argument,
			repeated as many times as specified by the first argument.

			<div class="example">
				An author may write:
				<pre>
					column-rule-color: gray red blue red blue red blue gray;
				</pre>
				Or shorten to the following, which produces the same sequence of colors:
				<pre>
					column-rule-color: gray repeat(3, red blue) gray;
				</pre>
			</div>

		<dt>auto
		<dd>
			Specfies an <dfn>auto repeater</dfn>.
			An <a>auto repeater</a> will be used to fill in values for gaps
			that would not otherwise receive values from other parts of the list.
			At most one ''repeat-line-color/repeat()'' in a given list of values may be an <a>auto repeater</a>.

			<div class="example">
				Continuing from the previous example, if the author does not know how
				many columns will be in the final layout, they might instead write:
				<pre>
					column-rule-color: gray repeat(auto, red blue) gray;
				</pre>
				Which will produce a gray decoration in the first and last column gaps,
				and alternating red and blue decorations in the in-between column gaps.
			</div>
	</dl>

	The second argument to ''repeat-line-color/repeat()'' is a space-separated list of values
	that would be accepted by the property in which the ''repeat-line-color/repeat()'' appears.

	<div algorithm>
		To <dfn>assign gap decoration values</dfn> to a list of |gaps| using a list of |values|:

		<ol>
			<li>
				Replace any <a>integer repeaters</a> in |values| with their expanded-out equivalents.
			</li>

			<li>
				If the list contains no <a>auto repeater</a>, then:
			</li>

				<ol>
					<li>
						Beginning from the first item in |values| and the first item in |gaps|,
						assign each value to the corresponding gap.
						If there are fewer values than gaps,
						repeat beginning from the first item in |values|,
						as many times as needed.
					</li>
					
					<li>
						End this algorithm.
					</li>
				</ol>

			<li>
				|values| contains an <a>auto repeater</a>.
				Let |leading count| be the number of items in |values| before the <a>auto repeater</a>.
				Let |trailing count| be the number of items in |values| after the <a>auto repeater</a>.
			</li>

			<li>
				Partition |gaps| as follows:

				<ol>
					<li>
						Let |leading gaps| contain the first |leading count| items in |gaps|.
					</li>
					<li>
						Let |trailing gaps| contain the last |trailing count| items in |gaps|,
						excluding any items in |leading gaps|.
					</li>
					<li>
						Let |auto gaps| contain any items in |gaps|
						that are not in either |leading gaps| or |trailing gaps|.
					</li>
				</ol>
			
			<li>
				If |leading gaps| is non-empty,
				<a>assign gap decoration values</a> to |leading gaps|
				using the first |leading count| items in |values|.
			</li>
			
			<li>
				If |trailing gaps| is non-empty,
				<a>assign gap decoration values in reverse</a> to |trailing gaps|
				using the last |trailing count| items in |values|.
			</li>
			
			<li>
				If |auto gaps| is non-empty,
				<a>assign gap decoration values</a> to |auto gaps|
				using the list of values in the second argument of the <a>auto repeater</a>.
			</li>
		</ol>
	</div>

	<div algorithm>
		To <dfn>assign gap decoration values in reverse</dfn>
		to a list of <var ignore=''>gaps</var> using a list of <var ignore=''>values</var>,
		follow the same steps as to <a>assign gap decoration values</a>,
		except that in step 2, change all instances of "first" to "last".
	</div>

<h3 id="gap-decoration-shorthands">
Gap decoration shorthands: The 'column-rule' and 'row-rule' properties</h3>

	<pre class='propdef shorthand'>
		Name: column-rule, row-rule
		Value: <<gap-rule-list>> | <<gap-auto-rule-list>>
	</pre>

	<pre class='prod'>
		<dfn>&lt;gap-rule-list&gt;</dfn>        = <<gap-rule-or-repeat>>#

		<dfn>&lt;gap-auto-rule-list&gt;</dfn>   = <<gap-rule-or-repeat>>#? ,
								             <<gap-auto-repeat-rule>> ,
								             <<gap-rule-or-repeat>>#?

		<dfn>&lt;gap-rule-or-repeat&gt;</dfn>   = <<gap-rule>> | <<gap-repeat-rule>>

		<dfn>&lt;gap-repeat-rule&gt;</dfn>      = repeat( <<integer [1,∞]>> , <<gap-rule>># )

		<dfn>&lt;gap-auto-repeat-rule&gt;</dfn> = repeat( auto , <<gap-rule>># )

		<dfn>&lt;gap-rule&gt;</dfn>             = <<line-width>> || <<line-style>> || <<color>>
	</pre>

	These shorthands set the corresponding width, style, and color properties as a set.

<h3 id="rule-bi-directional">
Bi-directional gap decoration shorthands: The 'rule-color', 'rule-style', 'rule-width', and 'rule' properties</h3>

	<pre class='propdef shorthand'>
		Name: rule-color
		Value: <<'column-rule-color'>>
		Inherited: no
		Applies to: Same as 'column-rule-color' and 'row-rule-color'
	</pre>

	<pre class='propdef shorthand'>
		Name: rule-style
		Value: <<'column-rule-style'>>
		Inherited: no
		Applies to: Same as 'column-rule-style' and 'row-rule-style'
	</pre>

	<pre class='propdef shorthand'>
		Name: rule-width
		Value: <<'column-rule-width'>>
		Inherited: no
		Applies to: Same as 'column-rule-width' and 'row-rule-width'
	</pre>

	<pre class='propdef shorthand'>
		Name: rule
		Value: <<'column-rule'>>
		Inherited: no
		Applies to: Same as 'column-rule' and 'row-rule'
	</pre>

	These shorthands set the corresponding column and row properties to the same values.

<h2 id="privacy">
Privacy Considerations</h2>

No new privacy considerations have been reported on this specification.

<h2 id="security">
Security Considerations</h2>

No new security considerations have been reported on this specification.

<h2 id="changes">
Changes</h2>

<h3 id="changes-20250417">
Changes since the <a href="https://www.w3.org/TR/2025/WD-css-gaps-1-20250417/">17 April 2025 Working Draft</a></h3>

	<ul class="non-normative">
		<li>Specified the behavior when gaps are coincident due to track collapsing.
			(<a href="https://github.com/w3c/csswg-drafts/issues/11814">Issue 11814</a>)
	</ul>