CSS module: box alignment

files/en-us/glossary/baseline/typography/index.md

@@ -14,6 +14,6 @@ Other writing systems have different baselines. For example, Tibetan and similar
 
 ## See also
 
-- [CSS box alignment](/en-US/docs/Web/CSS/CSS_box_alignment#types_of_alignment)
+- [CSS box alignment](/en-US/docs/Web/CSS/CSS_box_alignment/box_alignment#types_of_alignment)
 - [CSS inline layout](/en-US/docs/Web/CSS/CSS_inline_layout) module
 - [Baseline (Typography)](<https://en.wikipedia.org/wiki/Baseline_(typography)>) on Wikipedia

files/en-us/mozilla/firefox/releases/61/index.md

@@ -36,7 +36,7 @@ _No changes._
 
 - CSS parsing has been parallelized ([Firefox bug 1346988](https://bugzil.la/1346988)).
 - Support for {{cssxref("font-variation-settings")}} and {{cssxref("font-optical-sizing")}} has been enabled by default ([Firefox bug 1447163](https://bugzil.la/1447163)).
-- The `grid-gap`, `grid-row-gap`, and `grid-column-gap` properties have been renamed to {{cssxref("gap")}}, {{cssxref("row-gap")}}, and {{cssxref("column-gap")}}, as they are no longer grid-specific ([Firefox bug 1398482](https://bugzil.la/1398482)). See [Box alignment; Gaps between boxes](/en-US/docs/Web/CSS/CSS_box_alignment#gaps_between_boxes) for additional details. The old names have been kept as aliases for web compatibility purposes.
+- The `grid-gap`, `grid-row-gap`, and `grid-column-gap` properties have been renamed to {{cssxref("gap")}}, {{cssxref("row-gap")}}, and {{cssxref("column-gap")}}, as they are no longer grid-specific ([Firefox bug 1398482](https://bugzil.la/1398482)). See [Box alignment; Gaps between boxes](/en-US/docs/Web/CSS/CSS_box_alignment/box_alignment#gaps_between_boxes) for additional details. The old names have been kept as aliases for web compatibility purposes.
 - The {{cssxref("flex-basis")}} `content` value is now supported ([Firefox bug 1105111](https://bugzil.la/1105111)).
 - Percentage values of {{cssxref("column-gap")}} are now supported in [CSS multi-column layout](/en-US/docs/Web/CSS/CSS_multicol_layout) ([Firefox bug 1398537](https://bugzil.la/1398537)).
 - The CSS {{cssxref(":host")}} pseudo-class is now supported; this selects a custom element from inside its shadow DOM ([Firefox bug 992245](https://bugzil.la/992245)).

files/en-us/web/css/css_box_alignment/box_alignment/index.md

@@ -0,0 +1,292 @@
+---
+title: CSS box alignment
+slug: Web/CSS/CSS_box_alignment/box_alignment
+page-type: guide
+---
+
+{{CSSRef}}
+
+The [CSS box alignment](/en-US/docs/Web/CSS/CSS_box_alignment) module specifies CSS features that relate to the alignment of boxes in the various CSS box layout models. The module aims to create a consistent method of alignment across all of CSS. The CSS box alignment properties provide full horizontal and vertical alignment capabilities. This guide details the general concepts found in this module.
+
+This guide provides an overview. Additional guides provide more information on box alignment in [flexbox](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_flexbox), [grid layout](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_grid_layout), [multiple-column layout](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_multi-column_layout), and [block, absolutely positioned and table layout](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_block_abspos_tables). Alignment of text is covered by the [CSS text module](/en-US/docs/Web/CSS/CSS_text) and [CSS inline module](/en-US/docs/Web/CSS/CSS_inline_layout).
+
+## Key concepts and terminology
+
+The specification details some alignment terminology to make it easier to discuss these alignment properties outside their implementation within a particular layout method. There are also some key concepts which are common to all layout methods.
+
+### Relationship to writing modes
+
+Alignment is linked to writing modes in that when we align an item we do not consider whether we are aligning it to the physical dimensions of top, right, bottom and left. Instead we describe alignment in terms of the start and end of the particular dimension we are working with. This ensures that alignment works in the same way whichever writing mode the document has.
+
+### Two dimensions of alignment
+
+When using the box alignment properties you will align content on one of two axes — the inline (or main) axis, and the block (or cross) axis. The inline axis is the axis along which words in a sentence flow in the writing mode being used — for English, for example, the inline axis is horizontal. The block axis is the axis along which blocks, such as paragraph elements, are laid out and it runs across the Inline axis.
+
+![Inline axis is the left / right, or horizontal, direction. Block axis is vertical, or top / bottom.](two-axes.png)
+
+When aligning items on the inline axis you will use the properties which begin with `justify-`:
+
+- {{cssxref("justify-items")}}
+- {{cssxref("justify-self")}}
+- {{cssxref("justify-content")}}
+
+When aligning items on the block axis you will use the properties that begin `align-`:
+
+- {{cssxref("align-items")}}
+- {{cssxref("align-self")}}
+- {{cssxref("align-content")}}
+
+Flexbox adds an additional complication in that the above is true when {{cssxref("flex-direction")}} is set to `row`. The properties are swapped when flexbox is set to `column`. Therefore, when working with flexbox it is easier to think about the main and cross axis rather than inline and block. The `justify-` properties are always used to align on the main axis, the `align-` properties on the cross axis.
+
+### The alignment subject
+
+The **{{Glossary("alignment subject")}}** is the thing that is being aligned. For `justify-self` or `align-self`, or when setting these values as a group with `justify-items` or `align-items`, this will be the margin box of the element that this property is being used on. The `justify-content` and `align-content` properties differ per layout method.
+
+### The alignment container
+
+The **{{Glossary("alignment container")}}** is the box the subject is being aligned inside. This will typically be the alignment subject's containing block. An alignment container may contain one or many alignment subjects.
+
+The below image shows an alignment container with two alignment subjects inside.
+
+![A box containing two rectangles of the same width but different heights. The two rectangles are top aligned, meaning they both have their top lines about 10px inside the top of the box in which they are contained.](align-container-subjects.png)
+
+### Fallback alignment
+
+If you set an alignment that cannot be fulfilled, then the **{{Glossary("fallback alignment")}}** will come into play and deal with the available space. This fallback alignment is specified individually for each layout method and detailed on the page for that method.
+
+## Types of alignment
+
+There are three different types of alignment that the specification details; these use keyword values.
+
+- [Positional alignment](#positional-alignment)
+- [Baseline alignment](#baseline-alignment)
+- [Distributed alignment](#distributed-alignment)
+
+### Positional alignment
+
+**Positional alignment** is the position of an alignment subject with relation to its alignment container. The positional aligment keyword values are defined for positional alignment, and can be used as values for content alignment with `justify-content` and `align-content` and also for self alignment with `justify-self` and `align-self`.
+
+- `center`
+- `start`
+- `end`
+- `self-start`
+- `self-end`
+- `flex-start` for flexbox only
+- `flex-end` for flexbox only
+- `left`
+- `right`
+
+Other than the physical values of `left` and `right`, which relate to physical attributes of the screen, all of the other values are logical values and relate to the writing mode of the content.
+
+For example, when working in CSS grid layout, if you are working in English and set `justify-content` to `start` this will move the items in the inline dimension to the start, which will be the left as sentences in English start on the left. If you were using Arabic, a right to left language, then the same value of `start` would result in the items moving to the right, as sentences in Arabic start on the right-hand side of the page.
+
+Both of these examples have `justify-content: start`, however the location of start changes according to the writing mode.
+
+![There are two boxes, each with 3 children of differing heights but similar widths. The first box has three children with the letters A, B, and C. These three boxes are all aligned to the left. The second box has three children with arabic letters in them. Those three boxes are all aligned to the right.](writing-mode-start.png)
+
+### Baseline alignment
+
+**Baseline alignment** is the relationship among the baselines of multiple alignment subjects within an alignment context. The Baseline alignment keywords are used to align the baselines of boxes across a group of alignment subjects. They can be used as values for content alignment with `justify-content` and `align-content` and also for self alignment with `justify-self` and `align-self`.
+
+- `baseline`
+- `first baseline`
+- `last baseline`
+
+Baseline content alignment — specifying a baseline alignment value for `justify-content` or `align-content` — works in layout methods that lay items out in rows. The alignment subjects are baseline aligned against each other by adding padding inside the boxes.
+
+Baseline self alignment shifts the boxes to align by baseline by adding a margin outside the boxes. Self alignment is when using `justify-self` or `align-self`, or when setting these values as a group with `justify-items` and `align-items`.
+
+### Distributed alignment
+
+**Distributed alignment** defines alignment as a distribution of space among alignment subjects. The distributed alignment keywords are used with the `align-content` and `justify-content` properties. These keywords define what happens to any additional space after alignment subjects have been displayed. The values are as follows:
+
+- `stretch`
+- `space-between`
+- `space-around`
+- `space-evenly`
+
+For example, in Flex Layout items are aligned with `flex-start` initially. Working in a horizontal top to bottom writing mode such as English, with `flex-direction` as `row` the items start on the far left and any available space after displaying the items is placed after the items.
+
+![Three rectangles of different widths are inside a box. They are all aligned to the left side of the containing box, with about 10px between them, and 10px between the left side of the first rectangle and the parent container.](justify-content-start.png)
+
+If you set `justify-content: space-between` on the flex container, the available space is now shared out and placed between the items.
+
+![Three rectangles of different widths are inside a box. The first rectangle is aligned to the left side of the containing box, the third rectangle is aligned right, and the middle rectangle is equally spaced between the first and last.](justify-content-space-between.png)
+
+There needs to be space available in the dimension you wish to align the items in, in order for these keywords to take effect. With no space, there is nothing to distribute.
+
+### Basic examples
+
+The following examples demonstrate how some of the box alignment properties are applied in [Grid](/en-US/docs/Web/CSS/CSS_grid_layout) and [Flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout).
+
+#### CSS grid layout alignment example
+
+In this grid layout example, there is extra space in the grid container after laying out the fixed width tracks on the inline (main) axis. This space is distributed using {{cssxref("justify-content")}}. On the block (cross) axis the alignment of the items inside their grid areas is controlled with {{cssxref("align-items")}}. The first item overrides the `align-items` value set on the group by setting {{cssxref("align-self")}} to `center`.
+
+```html live-sample___grid-align-items
+<div class="box">
+  <div>One</div>
+  <div>Two</div>
+  <div>Three <br />has <br />extra <br />text</div>
+  <div>Four</div>
+  <div>Five</div>
+  <div>Six</div>
+</div>
+```
+
+```css hidden live-sample___grid-align-items
+body {
+  font: 1.2em sans-serif;
+}
+
+.box {
+  border: 2px dotted rgb(96 139 168);
+}
+
+.box > * {
+  padding: 20px;
+  border: 2px solid rgb(96 139 168);
+  border-radius: 5px;
+  background-color: rgb(96 139 168 / 0.2);
+}
+```
+
+```css live-sample___grid-align-items
+.box {
+  display: grid;
+  grid-template-columns: 120px 120px 120px;
+  align-items: start;
+  justify-content: space-between;
+}
+
+.box :first-child {
+  align-self: center;
+}
+```
+
+{{EmbedLiveSample("grid-align-items", "", "200px")}}
+
+#### Flexbox Alignment Example
+
+In this example, three flex items are aligned on the main axis using `justify-content` and on the Cross Axis using `align-items`. The first item overrides the `align-items` set on the group by setting `align-self` to `center`.
+
+```html live-sample___flex-align-items
+<div class="box">
+  <div>One</div>
+  <div>Two</div>
+  <div>Three <br />has <br />extra <br />text</div>
+</div>
+```
+
+```css hidden live-sample___flex-align-items
+body {
+  font: 1.2em sans-serif;
+}
+
+.box {
+  border: 2px dotted rgb(96 139 168);
+}
+
+.box > * {
+  padding: 20px;
+  border: 2px solid rgb(96 139 168);
+  border-radius: 5px;
+  background-color: rgb(96 139 168 / 0.2);
+}
+```
+
+```css live-sample___flex-align-items
+.box {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+}
+
+.box :first-child {
+  align-self: center;
+}
+```
+
+{{EmbedLiveSample("flex-align-items")}}
+
+## Overflow alignment
+
+The `safe` and `unsafe` keywords help define behavior when an alignment subject is larger than the alignment container. The `safe` keyword will align to `start` in the case of a specified alignment causing an overflow, the aim being to avoid "data loss" where part of the item is outside the boundaries of the alignment container and can't be scrolled to.
+
+If you specify `unsafe` then the alignment will be honoured even if it would cause such data loss.
+
+## Gaps between boxes
+
+The box alignment specification also includes the `gap`, `row-gap`, and `column-gap` properties. These properties enable the setting of a consistent gap between items in a row or column, in any layout method which has items arranged in this way.
+
+The `gap` property is a shorthand for `row-gap` and `column-gap`, which allows us to set these properties at once:
+
+- {{cssxref("row-gap")}}
+- {{cssxref("column-gap")}}
+- {{cssxref("gap")}}
+
+In the below example, a grid layout uses the `gap` shorthand to set a `10px` gap between row tracks, and a `2em` gap between column tracks.
+
+```html live-sample___grid-gap
+<div class="box">
+  <div>One</div>
+  <div>Two</div>
+  <div>Three</div>
+  <div>Four</div>
+  <div>Five</div>
+  <div>Six</div>
+</div>
+```
+
+```css hidden live-sample___grid-gap
+body {
+  font: 1.2em sans-serif;
+}
+
+.box {
+  border: 2px dotted rgb(96 139 168);
+}
+
+.box > * {
+  padding: 20px;
+  border: 2px solid rgb(96 139 168);
+  border-radius: 5px;
+  background-color: rgb(96 139 168 / 0.2);
+}
+```
+
+```css live-sample___grid-gap
+.box {
+  display: grid;
+  grid-template-columns: 1fr 1fr 1fr;
+  gap: 10px 2em;
+}
+
+.box :first-child {
+  align-self: center;
+}
+```
+
+{{EmbedLiveSample("grid-gap")}}
+
+Early grid implementation included `gap` properties prefixed with `grid-`. All browsers support the unprefixed properties, though you may see the following properties in a code-base: {{cssxref("row-gap", "grid-row-gap")}}, {{cssxref("column-gap", "grid-column-gap")}}, and {{cssxref("gap", "grid-gap")}}. The prefixed versions are aliases of the unprefixed ones.
+
+Be aware that other things may increase the visual gap displayed, for example using the space distribution keywords or adding margins to items.
+
+## Box-alignment by layout type
+
+As the CSS box alignment properties are implemented differently depending on the specification they interact with, refer to the following guides for each layout type for details of how to use the alignment properties with it:
+
+- [Box alignment in flexbox](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_flexbox)
+- [Box alignment in CSS grid layout](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_grid_layout)
+- [Box alignment in multiple-column layout](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_multi-column_layout)
+- [Box alignment for block, absolutely positioned and table layout](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_block_abspos_tables)
+
+## See also
+
+- [CSS display](/en-US/docs/Web/CSS/CSS_display) module
+- [CSS flex layout](/en-US/docs/Web/CSS/CSS_flexible_box_layout) module
+- [Basic concepts of flexbox](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Basic_concepts_of_flexbox)
+- [Aligning items in a flex container](/en-US/docs/Web/CSS/CSS_flexible_box_layout/Aligning_items_in_a_flex_container)
+- [CSS grid layout](/en-US/docs/Web/CSS/CSS_grid_layout) module
+- [Box alignment in CSS grid layouts](/en-US/docs/Web/CSS/CSS_grid_layout/Box_alignment_in_grid_layout)

files/en-us/web/css/css_box_alignment/box_alignment_in_block_abspos_tables/index.md

@@ -4,7 +4,7 @@ slug: Web/CSS/CSS_box_alignment/Box_alignment_in_block_abspos_tables
 page-type: guide
 ---
 
-The [box alignment specification](/en-US/docs/Web/CSS/CSS_box_alignment) details how alignment works in various layout methods. In this page we explore how box alignment works in the context of block layout, including floated, positioned, and table elements. As this page aims to detail things which are specific to block layout and box alignment, it should be read in conjunction with the main [box alignment](/en-US/docs/Web/CSS/CSS_box_alignment) page, which details the common features of box alignment across layout methods.
+The [CSS box alignment](/en-US/docs/Web/CSS/CSS_box_alignment) module details how alignment works in various layout methods. In this guide, we explore how box alignment works in the context of block layout, including floated, positioned, and table elements. As this guide aims to detail things which are specific to block layout and box alignment, it should be read in conjunction with the [box alignment](/en-US/docs/Web/CSS/CSS_box_alignment/box_alignment) guide, which details the common features of box alignment across layout methods.
 
 ## align-content and justify-content
 
@@ -75,19 +75,9 @@ For many use cases, turning the block container into a flex item will give you t
 
 {{EmbedLiveSample("intro", "", "320px")}}
 
-## Reference
+## See also
 
-### CSS Properties
-
-- {{cssxref("justify-content")}}
-- {{cssxref("align-content")}}
-- {{cssxref("justify-self")}}
-- {{cssxref("align-self")}}
-
-### Glossary Entries
-
-- [Alignment subject](/en-US/docs/Glossary/Alignment_Subject)
-- [Alignment container](/en-US/docs/Glossary/Alignment_Container)
-- [Fallback alignment](/en-US/docs/Glossary/Fallback_Alignment)
-
-{{CSSRef}}
+- [Box alignment](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment)
+- [Box alignment in flexbox](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_flexbox)
+- [Box alignment in CSS grid layout](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_grid_layout)
+- [Box alignment in multiple-column layout](/en-US/docs/Web/CSS/CSS_box_alignment/Box_alignment_in_multi-column_layout)