From 84abff0d1900911263ca3c463ec8bda03850d290 Mon Sep 17 00:00:00 2001 From: Kevin Babbitt Date: Wed, 7 Jan 2026 13:29:48 -0800 Subject: [PATCH 1/5] [css-align][css-gaps] Move the gap properties to the Gaps spec --- css-align-3/Overview.bs | 194 ---------------------------------------- css-gaps-1/Overview.bs | 194 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 194 insertions(+), 194 deletions(-) diff --git a/css-align-3/Overview.bs b/css-align-3/Overview.bs index cfdb8ee9ce6..7c8782dc3a8 100644 --- a/css-align-3/Overview.bs +++ b/css-align-3/Overview.bs @@ -2003,200 +2003,6 @@ Default Alignment Shorthand: the 'place-items' property The second value is assigned to 'justify-items'; if omitted, it is copied from the first value. - - - -

-Gaps Between Boxes

- - While 'margin' and 'padding' can be used to specify visual spacing around individual boxes, - it's sometimes more convenient to globally specify spacing - between adjacent boxes within a given layout context, - particularly when the spacing is different between sibling boxes - as opposed to between the first/last box and the container's edge. - - The 'gap' property, - and its 'row-gap' and 'column-gap' sub-properties, - provide this functionality for - multi-column, - flex, - and grid layout. - -

-Row and Column Gutters: the 'row-gap' and 'column-gap' properties

- - 
-	Name: row-gap, column-gap
-	Value: normal | <>
-	Initial: normal
-	Applies to: multi-column containers, flex containers, grid containers
-	Inherited: no
-	Percentages: see [[#gap-percent]]
-	Computed value: specified keyword, else a computed <> value
-	Animation type: by computed value type
-
- - These properties specify fixed-length gutters - between items in the container, - adding space between them-- - in a manner similar to the ''justify-content/space-between'' keyword - of the content-distribution properties, - but of a fixed size instead of as a fraction of remaining space. - The 'column-gap' property specifies spacing between “columns”, - separating boxes in the container's inline axis - similar to inline-axis margin; - while 'row-gap' indicates spacing between “rows”, - separating boxes in the container's block axis. - - Values have the following meanings: - -
- : <> - :: - Specifies a gap between “rows” or “columns”, - as defined by the layout modes to which it applies; - see subsections below for details. - - Negative values are invalid. - For percentages, - see [[#gap-percent]]. - - : normal - :: The value ''gap/normal'' represents - a used value of ''1em'' on multi-column containers, - and a used value of ''0px'' in all other contexts. -
- - Gutters effect a minimum spacing between items: - additional spacing may be added by 'justify-content'/'align-content'. - Such additional space effectively increases the size of these gutters. - - The exact handling of these properties varies by layout container: - -
-
multi-column containers -
- 'column-gap' specifies the [=gutter=] between adjacent column boxes, - see [[CSS-MULTICOL-1]]. - 'row-gap' specifies the [=gutter=] between the rows of [=column boxes=] established by 'column-height', - see [[CSS-MULTICOL-2]]. - -
flex containers -
- When applied to the main axis - (e.g. 'column-gap' in a ''flex-flow/row'' flex container), - indicates the [=gutter=] between items - (as if an additional fixed-size margin were inserted - between adjacent flex items - in a single line). - - When applied to the cross axis - (e.g. 'row-gap' in a ''flex-flow/row'' flex container), - indicates the [=gutter=] between adjacent flex lines. - -
grid containers -
- The 'row-gap' and 'column-gap' properties, - when specified on a grid container, - define the [=gutters=] between grid rows and grid columns, - respectively. - See [[css-grid-1#gutters]] for precise details. -
- - In all cases, the [=gutter=] disappears when it coincides with - a [=fragmentation break=]. [[CSS-BREAK-3]] - - Note: Table boxes do not use the 'gap' properties - to specify separation between their cells. - Instead, they use the 'border-spacing' property, - which has slightly different functionality: - it inherits, - and it also specifies the additional spacing between the outermost cells - and the border of the table - (similar to ''space-evenly'' rather than ''space-between''). - -

-Gap Shorthand: the 'gap' property

- - 
-	Name: gap
-	Value: <<'row-gap'>> <<'column-gap'>>?
-	Initial: see individual properties
-	Applies to: multi-column containers, flex containers, grid containers
-	Inherited: no
-	Percentages: refer to corresponding dimension of the content area
-	Computed value: see individual properties
-	Animation type: by computed value type
-
- - This property is a shorthand that sets 'row-gap' and 'column-gap' in one declaration. - If <<'column-gap'>> is omitted, - it's set to the same value as <<'row-gap'>>. - -
-
- A diagram showing how margins and padding add to the visible gutter size -
- - Note: The 'gap' property is only one component of the visible “gutter” or “alley” created between boxes. - Margins, padding, or the use of distributed alignment - may increase the visible separation between boxes - beyond what is specified in 'gap'. -
- -

-Percentages In 'gap' Properties

- - In general, - gaps introduced by the 'gap' properties - are intended to act like an empty item/track/etc - with the gap's size; - in other words, - an author should be able to reproduce the effects of 'gap' - by just inserting additional empty items/tracks/etc - into the container. - - 'gap' always resolves percentages against - the corresponding size of the [=content box=] - of the element. - When this size is definite, - the behavior is well-defined - and consistent across layout modes. - But since different layout modes treat [=cyclic percentage sizes=] for items/tracks/etc differently, - 'gap' does as well: - - : In Grid Layout - :: - As in the min size properties and margins/paddings [[CSS-SIZING-3]], - [=cyclic percentage sizes=] resolve against zero - for determining intrinsic size contributions, - but resolve against the box’s content box - when laying out the box’s contents. - - : In Flex Layout - :: - [=Cyclic percentage sizes=] resolve against zero in all cases. - -

-Legacy Gap Properties: the 'grid-row-gap', 'grid-column-gap', and 'grid-gap' properties

- - The Grid Layout module was originally written with its own set of [=gutter=] properties, - before all such properties were unified into the existing 'row-gap'/'column-gap' naming. - For compatibility with legacy content, - these grid-prefixed names must be supported as follows: - - * grid-row-gap as a [=legacy name alias=] of the 'row-gap' property - * grid-column-gap as a [=legacy name alias=] of the 'column-gap' property - * grid-gap as a [=legacy name alias=] of the 'gap' property - + +

+Gaps Between Boxes

+ + While 'margin' and 'padding' can be used to specify visual spacing around individual boxes, + it's sometimes more convenient to globally specify spacing + between adjacent boxes within a given layout context, + particularly when the spacing is different between sibling boxes + as opposed to between the first/last box and the container's edge. + + The 'gap' property, + and its 'row-gap' and 'column-gap' sub-properties, + provide this functionality for + multi-column, + flex, + and grid layout. + +

+Row and Column Gutters: the 'row-gap' and 'column-gap' properties

+ + 
+	Name: row-gap, column-gap
+	Value: normal | <>
+	Initial: normal
+	Applies to: multi-column containers, flex containers, grid containers
+	Inherited: no
+	Percentages: see [[#gap-percent]]
+	Computed value: specified keyword, else a computed <> value
+	Animation type: by computed value type
+
+ + These properties specify fixed-length gutters + between items in the container, + adding space between them-- + in a manner similar to the ''justify-content/space-between'' keyword + of the content-distribution properties, + but of a fixed size instead of as a fraction of remaining space. + The 'column-gap' property specifies spacing between “columns”, + separating boxes in the container's inline axis + similar to inline-axis margin; + while 'row-gap' indicates spacing between “rows”, + separating boxes in the container's block axis. + + Values have the following meanings: + +
+ : <> + :: + Specifies a gap between “rows” or “columns”, + as defined by the layout modes to which it applies; + see subsections below for details. + + Negative values are invalid. + For percentages, + see [[#gap-percent]]. + + : normal + :: The value ''gap/normal'' represents + a used value of ''1em'' on multi-column containers, + and a used value of ''0px'' in all other contexts. +
+ + Gutters effect a minimum spacing between items: + additional spacing may be added by 'justify-content'/'align-content'. + Such additional space effectively increases the size of these gutters. + + The exact handling of these properties varies by layout container: + +
+
multi-column containers +
+ 'column-gap' specifies the [=gutter=] between adjacent column boxes, + see [[CSS-MULTICOL-1]]. + 'row-gap' specifies the [=gutter=] between the rows of [=column boxes=] established by 'column-height', + see [[CSS-MULTICOL-2]]. + +
flex containers +
+ When applied to the main axis + (e.g. 'column-gap' in a ''flex-flow/row'' flex container), + indicates the [=gutter=] between items + (as if an additional fixed-size margin were inserted + between adjacent flex items + in a single line). + + When applied to the cross axis + (e.g. 'row-gap' in a ''flex-flow/row'' flex container), + indicates the [=gutter=] between adjacent flex lines. + +
grid containers +
+ The 'row-gap' and 'column-gap' properties, + when specified on a grid container, + define the [=gutters=] between grid rows and grid columns, + respectively. + See [[css-grid-1#gutters]] for precise details. +
+ + In all cases, the [=gutter=] disappears when it coincides with + a [=fragmentation break=]. [[CSS-BREAK-3]] + + Note: Table boxes do not use the 'gap' properties + to specify separation between their cells. + Instead, they use the 'border-spacing' property, + which has slightly different functionality: + it inherits, + and it also specifies the additional spacing between the outermost cells + and the border of the table + (similar to ''space-evenly'' rather than ''space-between''). + +

+Gap Shorthand: the 'gap' property

+ + 
+	Name: gap
+	Value: <<'row-gap'>> <<'column-gap'>>?
+	Initial: see individual properties
+	Applies to: multi-column containers, flex containers, grid containers
+	Inherited: no
+	Percentages: refer to corresponding dimension of the content area
+	Computed value: see individual properties
+	Animation type: by computed value type
+
+ + This property is a shorthand that sets 'row-gap' and 'column-gap' in one declaration. + If <<'column-gap'>> is omitted, + it's set to the same value as <<'row-gap'>>. + +
+
+ A diagram showing how margins and padding add to the visible gutter size +
+ + Note: The 'gap' property is only one component of the visible “gutter” or “alley” created between boxes. + Margins, padding, or the use of distributed alignment + may increase the visible separation between boxes + beyond what is specified in 'gap'. +
+ +

+Percentages In 'gap' Properties

+ + In general, + gaps introduced by the 'gap' properties + are intended to act like an empty item/track/etc + with the gap's size; + in other words, + an author should be able to reproduce the effects of 'gap' + by just inserting additional empty items/tracks/etc + into the container. + + 'gap' always resolves percentages against + the corresponding size of the [=content box=] + of the element. + When this size is definite, + the behavior is well-defined + and consistent across layout modes. + But since different layout modes treat [=cyclic percentage sizes=] for items/tracks/etc differently, + 'gap' does as well: + + : In Grid Layout + :: + As in the min size properties and margins/paddings [[CSS-SIZING-3]], + [=cyclic percentage sizes=] resolve against zero + for determining intrinsic size contributions, + but resolve against the box’s content box + when laying out the box’s contents. + + : In Flex Layout + :: + [=Cyclic percentage sizes=] resolve against zero in all cases. + +

+Legacy Gap Properties: the 'grid-row-gap', 'grid-column-gap', and 'grid-gap' properties

+ + The Grid Layout module was originally written with its own set of [=gutter=] properties, + before all such properties were unified into the existing 'row-gap'/'column-gap' naming. + For compatibility with legacy content, + these grid-prefixed names must be supported as follows: + + * grid-row-gap as a [=legacy name alias=] of the 'row-gap' property + * grid-column-gap as a [=legacy name alias=] of the 'column-gap' property + * grid-gap as a [=legacy name alias=] of the 'gap' property +