Overview.bs

<style>
.example .figure img {
  background-color: white;
  padding: 20px;
  margin: 20px;
}
</style>
<pre class=metadata>
Title: CSS Step Sizing
Shortname: css-step-sizing
Level: 1
Group: CSSWG
Status: ED
Work Status: exploring
Editor: Koji Ishii, Google, kojiishi@gmail.com
ED: https://drafts.csswg.org/css-step-sizing/
Abstract: This module contains CSS features for aligning content size
  to multiple of unit size.
</pre>
<pre class=link-defaults>
spec:css21; type:property; text:max-height
spec:css21; type:property; text:max-width
spec:css21; type:property; text:min-width
</pre>

Introduction {#intro}
=====================

This specification provides features to control sizes of CSS objects
according to the rules desired by use cases.

Controlling sizes of CSS objects to be multiple of a unit
is desired in many cases.
This level of the specification focuses on following cases.

* Adjust heights of line boxes to the multiple of the specified unit.
* Adjust widths of block-level boxes to the multiple of the specified unit.

By controlling heights of line boxes,
lines of text in different fonts can create consistent visuals
to help readability.

Also by stacking such line boxes,
authors can align lines across columns,
pages, scroll-snapped blocks, or multiple blocks placed absolutely,
to produce vertical rhythm.

<div class="figure">
<a href="examples/snap-height.html">
<img src="images/snap-height-sample.png"></a>
<p class="caption">Vertical rhythm kept through pictures and different size of text in a multi-column document.
</div>

Controlling widths of block-level boxes to the multiple of the specified unit
gives the ability to control a block
so that it can fit mono-space characters
without remainders.
One of the use cases this feature addresses is
better readability of East Asian documents.
In Han ideographic-based scripts such as Chinese or Japanese,
most characters have 1em advance,
and due to that nature, most such documents are justified.

Adjusting widths of block-level boxes to the multiple of 1em helps to
minimize cases where justification needs to expand spacing.

Adjusting Line Box Heights: the 'line-height-step' property {#line-height-step}
===============================================================================

<pre class='propdef'>
  Name: line-height-step
  Value: <<length>> <<integer>>?
  Initial: 0px
  Applies to: block containers
  Inherited: yes
  Animatable: no
  Percentages: N/A
  Media: visual
  Computed Value: the absolute length for length, others as specified
</pre>

Values have the following meanings:

<dl dfn-for="line-height-step">
  <dt><<length>>
  <dd>
    This value defines the <dfn>step unit</dfn> for line box heights.
    Non-negative <<length>>s are valid.
  <dt><<integer>>
  <dd>
    This value defines the <dfn>step baseline position</dfn>
    within the <a>step unit</a>.
    Values between 1 and 100 (inclusive) are valid.
</dl>

Issue: Naming under discussion.

Issue: Should the step baseline position be percent?
Not much precision is needed, but
there was one feedback that percent is easier to use.

Stepping Line Box Heights {#height}
-----------------------------------

When the <a>step unit</a> is set to a positive <<length>>,
the line box heights are rounded <i>up</i> to
the multiple of the unit.

[[!CSS21]] <a href="https://drafts.csswg.org/css2/visudet.html#line-height">&#xA7;10.8 Line height calculations</a>
defines how to compute the line box height
after the line box was constructed from inline-level boxes.
The rounding is applied to the computed line box height
by assuming that there is an inline-level box that has adjusted A' and D'
in the line box.

<div class="figure">
  <img src="images/adjust-line-height.svg">
  <p class="caption">Rounding up the computed line box height.
</div>

The <a>step baseline position</a> determines
how the additional spaces are distributed.

* When it is not set,
    the height is rounded up to the closest multiple of the <a>step unit</a>, and
    the space is distributed to
    <a>over</a>-side (T) and <a>under</a>-side (B) equally,
    so that the original line box appears at the center of the
    multiple of <a>step unit</a>.
* When it is set,
    refer to the <a href="#baseline">baseline</a> section below.

<div class="example">
  <div class="figure" style="float:right">
    <img src="images/line-grid-center.svg"
      style="height: 300px"
      >
  </div>

  In the following example,
  the height of line box in each paragraph is rounded up to the <a>step unit</a>.

  <pre class="lang-css">
  :root {
    font-size: 12pt;
    --my-grid: 18pt;
    line-height-step: var(--my-grid);
  }
  h1 {
    font-size: 20pt;
    margin-top: calc(2 * var(--my-grid));
  }
  p {
    margin: 0;
  }
  </pre>

  The line box in <code>&lt;h1&gt;</code> does not fit into one <a>step unit</a>
  and thus occupies two,
  but it is still centered within the two <a>step unit</a>.
</div>

<div class="example">
  Authors can keep margins or other properties to be multiple of <a>step unit</a>
  using ''var()'' and ''calc()'' as in the example above.

  If author prefers,
  tools like Sass can make such declarations shorter.

  <pre class="lang-css">
    $gu: 18px;

    @function gu($n) {
      @return $n * $gu;
    }

    h1 {
      font-size: 20pt;
      margin: gu(1.2) auto gu(1.8);
    }
  </pre>
</div>

<div class="note">
It is usually recommended to set the 'line-height' lower than
the <a>step unit</a>.
The used line height can increase due to several factors such as
the use of 'vertical-align' or font fallback.
</div>

Aligning Baselines {#baseline}
------------------------------

<div class="figure" style="float:right">
  <img src="images/line-grid-baseline.svg"
    >
</div>

When the <a>step baseline position</a> is set,
the additional spaces are distributed using the following formula:

* space-over = P - T % U, add U if the result is negative
* space-under = U - (space-over + T + B) % U

Given:

* U: the <a>step unit</a>.
* P: the <a>step baseline position</a> &times; U / 100.
* T: the distance between the top of the line box and the baseline.
* B: the distance between the bottom of the line box and the baseline.

This formula pushes the baseline of the line box
down to the closest <a>step baseline position</a>,
and the bottom to the next <a>step unit</a>.

<div class="example">
  <div class="figure" style="float:right">
    <img src="images/line-grid-baseline-multicol.svg"
      >
  </div>

  The following CSS sets the <a>step baseline position</a>
  to 14pt (20pt &times; 0.70) within each <a>step unit</a>.

  <pre class="lang-css">
  :root {
    line-height-step: 20pt 70;
  }
  </pre>

  The baseline of the line box is pushed down
  to the closest <a>step baseline position</a>
  by adding the space-over.

  <code>&lt;h1&gt;</code> is as tall as
  its baseline being lower than the second <a>step baseline position</a>
  that it is pushed down to the third <a>step baseline position</a>.
</div>

<div class="note">
  Since the bottom of the line box is rounded to the closest <a>step unit</a>
  next to the descenders of the line box,
  large descenders may result in unintended spaces under the line box.
  Oftentimes changing <a>step baseline position</a> can control such situations.
</div>

Notes on Block-level Boxes {#block-height}
------------------------------------------

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

This level of the specification does not provide features
to adjust heights of block-level boxes.

<div class="example">
  The following CSS turns <code>&lt;h2&gt;</code> to inline-blocks.

  <pre class="lang-css">
  :root {
    line-height-step: 18pt;
  }
  h2 {
    display: inline-block;
    width: 100%;
    line-height-step: 0;
    line-height: 1.2;
  }
  </pre>

  When an <code>&lt;h2&gt;</code> is long enough to wrap,
  text inside the <code>&lt;h2&gt;</code> uses ''line-height: 1.2'', while
  the height of the <code>&lt;h2&gt;</code> block is rounded up
  to the multiple of ''18pt''.
  See <a href="examples/line-height-step.html">a sample in action</a>.
</div>

Stepping Widths: the 'inline-size-step' property {#width}
=========================================================

<pre class='propdef'>
  Name: inline-size-step
  Value: <<length>>
  Initial: 0px
  Applies to: all elements but non-replaced inline elements, table rows, and row groups
  Inherited: no
  Animatable: no
  Percentages: N/A
  Media: visual
  Computed Value: the absolute length
</pre>

Non-negative <<length>>s are valid.

When this property is set to a positive <<length>>
and the <a>available inline size</a> is <a>definite</a>,
the <a>available inline size</a> of the element is rounded <em>down</em>
to the closest multiple of the specified <<length>>
before it is used.

<div class="note">
Since this property only adjusts <a>available inline size</a>,
it does not guarantee that the <a>inline size</a> of child boxes
are the multiple of the specified <<length>>
if there were other constraints.
</div>

When this property is applied to a multi-column element,
the <a>available inline size</a> of the content box is not rounded but
the <a>available inline size</a> of the <a>column box</a> is rounded.

<div class="note">
When using this property with CSS layout features such as tables or flexbox,
authors are expected to apply this property to
item boxes rather than container boxes;
e.g., table cells rather than tables, or
flex-items rather than flex-containers.

However, the special case above is needed because
authors cannot style <a>column boxes</a>.
</div>

<div class="example">
  This property improves the justification
  for Han ideograph-based scripts such as Chinese or Japanese.

  With the following CSS,
  the <code>&lt;article&gt;</code> elements
  and blocks with <code>bodytext</code> class
  are justified,
  but the expansion occurs
  only when there are non-CJK characters in the line
  because their logical widths are
  adjusted to the multiple of 1em.
  <pre class="lang-css">
  article, .bodytext {
    font-size: 12pt;
    text-align: justify;
    inline-size-step: 1em;
  }
  </pre>
</div>

Privacy and Security Considerations {#priv-sec}
===============================================

This specification introduces no new privacy leaks,
or security considerations beyond "implement it correctly".

Acknowledgments {#acks}
=======================
This specification would not have been possible without the help from:
Takao Baba,
Chris Eppstein,
Shinyu Murakami,
Tsutomu Nanjo,
Charlie Neely,
Florian Rivoal,
Hiroshi Sakakibara,
Alan Stearns,
and the CSS Working Group members.