CSS Text Decoration Module Level 4

1. Introduction

This subsection is non-normative.

This module covers text decoration, i.e. decorating the glyphs of the text once typeset according to font and typographic rules. (See [CSS-TEXT-3] and [CSS-FONTS-3].) Such features are traditionally used not only for purely decorative purposes, but also in some cases to show emphasis, for honorifics, and to indicate editorial changes such as insertions, deletions, and misspellings.

CSS Levels 1 and 2 only defined very basic line decorations (underlines, overlines, and strike-throughs) appropriate to Western typographical traditions. Level 3 of this module added the ability to change the color, style, position, and continuity of these decorations, and also introduced emphasis marks (traditionally used in East Asian typography), and shadows (which were proposed then deferred from Level 2). Level 4 introduces additional controls over these decorations.

1.1. Module Interactions

This module replaces and extends the text-decorating features defined in [CSS-TEXT-DECOR-3].

All of the properties in this module can be applied to the ::first-line and ::first-letter pseudo-elements.

1.2. Value Definitions

This specification follows the CSS property definition conventions from [CSS2] using the value definition syntax from [CSS-VALUES-3]. Value types not defined in this specification are defined in CSS Values & 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 CSS-wide keywords as their property value. For readability they have not been repeated explicitly.

1.3. Terminology

The terms typographic character unit (character), typographic letter unit (letter), and content language as used in this specification are defined in [CSS-TEXT-3]. Other terminology and concepts used in this specification are defined in [CSS2] and [CSS-WRITING-MODES-4].

2. Line Decoration: Underline, Overline, and Strike-Through

The following properties describe line decorations that are added to the content of an element. When specified on or propagated to an inline box, that box becomes a decorating box for that decoration, applying the decoration to all its box fragments. The decoration is then further propagated to any in-flow block-level boxes that split the inline (see CSS2.1 section 9.2.1.1). When specified on or propagated to a block container that establishes an inline formatting context, the decorations are propagated to an anonymous inline box that wraps all the in-flow inline-level children of the block container. When specified on or propagated to a ruby container, the decorations are propagated only to the ruby base. For all other box types, the decorations are propagated to all in-flow children.

Note that text decorations are not propagated to any out-of-flow descendants, nor to the contents of atomic inline-level descendants such as inline blocks and inline tables. They are also not propagated to inline children of inline boxes, although the decoration is applied to such boxes.

Underlines, overlines, and line-throughs are drawn only for non-replaced inline boxes, and are drawn across all text (including white space, letter spacing, and word spacing) except spacing (white space, letter spacing, and word spacing) at the beginning and end of a line. Atomic inlines, such as images and inline blocks, are not decorated. Margins, borders, and padding of the decorating box are always skipped, however the margins, border, and padding of descendant inline boxes are not.

Note that CSS 2.1 required skipping margins, borders, and padding always. In Level 3 and beyond, by default only the margins, borders, and padding of the decorating box are skipped. In the future CSS2.1 may be updated to match this new default.

Relatively positioning a descendant moves all text decorations applied to it along with the descendant’s text; it does not affect calculation of the decoration’s initial position on that line. The visibility property, text-shadow, filters, and other graphical transformations likewise also affect all text decorations applied to that box—​including decorations propagated from an ancestor box—​and do not affect the calculation of their initial positions or thicknesses. (In the case of line decorations drawn over an atomic inline or across the margins/borders/padding of a non-replaced inline box, they are analogously associated with the affected atomic inline / non-replaced inline box rather than with the decorating box.)

blockquote { text-decoration: underline; color: blue; }
em { display: block; }
cite { color: fuchsia; }

<blockquote>
 <p>
  <span>
   Help, help!
   <em> I am under a hat! </em>

   <cite> —GwieF </cite>
  </span>
 </p>
</blockquote>

div { color: black; font-size: 48px; text-decoration: underline; text-shadow: blue 0px 50px 0px; }
span { font-size: 20px; vertical-align: top; text-shadow: green 0px 100px 0px; }

<div>Help, help! <span>I am under a hat!</span></div>

Note: Line decorations are propagated through the box tree, not through inheritance, and thus have no effect on descendants when specified on an element with display: contents.

2.1. Text Decoration Lines: the text-decoration-line property

This property, which is a sub-property of the text-decoration shorthand, specifies what line decorations, if any, are added by the element. Values other than text-decoration-line cause the element to originate the indicated text decorations, and to apply and propagate it as described above.

Note: Unless it is desired for the color, style, and thickness of the lines to be set by declarations lower in the cascade, it is safer to use the text-decoration shorthand instead of this longhand.

Values have the following meanings:

none

Neither produces nor inhibits text decoration.

underline

Each line of text is underlined.

overline

Each line of text has a line over it (i.e. on the opposite side from an underline).

line-through

Each line of text has a line through the middle.

blink

The text blinks (alternates between visible and invisible). Conforming user agents may simply not blink the text. Note that not blinking the text is one technique to satisfy checkpoint 3.3 of WAI-UAAG. This value is deprecated in favor of Animations [CSS3-ANIMATIONS].

spelling-error

This value indicates the type of text decoration used by the user agent to highlight spelling mistakes. Its appearance is UA-defined, and may be platform-dependent. It is often rendered as a red wavy underline.

grammar-error

This value indicates the type of text decoration used by the user agent to highlight grammar mistakes. Its appearance is UA defined, and may be platform-dependent. It is often rendered as a green wavy underline.

Note: In vertical writing modes, text-underline-position can cause the underline and overline to switch sides. This allows the position of underlines to key off of language-specific preferences automatically.

When spelling-error or grammar-error apply, the user agent must disregard the other sub-properties of text-decoration, as well any other properties typically affecting the appearance of line decorations (such as text-underline-position, color, stroke, or fill) when rendering these decorations. However, the user agent may take into account the accent-color property.

2.2. Text Decoration Style: the text-decoration-style property

This property, which is a sub-property of the text-decoration shorthand, sets the line-drawing style of underlines, overlines, and line-throughs specified on the element with text-decoration-line, and affects all decorations originating from this element even if descendant boxes specify a different style.

Values have the same meaning as for the border-style properties [CSS-BACKGROUNDS-3]. wavy indicates a wavy line.

2.3. Text Decoration Color: the text-decoration-color property

This property, which is a sub-property of the text-decoration shorthand, sets the color of underlines, overlines, and line-throughs specified on the element with text-decoration-line, and affects all decorations originating from this element even if descendant boxes specify a different color.

2.4. Text Decoration Line Thickness: the text-decoration-thickness property

This property, which is a sub-property of the text-decoration shorthand, sets the stroke thickness of underlines, overlines, and line-throughs specified on the element with text-decoration-line, and affects all decorations originating from this element even if descendant boxes specify a different thickness.

Values have the following meanings:

auto

The UA chooses an appropriate thickness for text decoration lines; see below.

from-font

If the first available font has metrics indicating a preferred underline width, use that width, otherwise behaves as auto.

<length>

Specifies the thickness of text decoration lines as a fixed length. The UA should round the actual value to the nearest integer device pixel, and ensure it is at least one device pixel.

Note: A length will inherit as a fixed value, and will not scale with the font.

<percentage>

Specifies the thickness of text decoration lines as a percentage of 1em. The UA should round the actual value to the nearest integer device pixel, and ensure it is at least one device pixel.

Note: A percentage will inherit as a relative value, and will therefore scale with changes in the font as it inherits.

2.4.1. Automatic Thickness of Text Decoration Lines

Some font formats (such as OpenType) can offer information about the appropriate thickness of a line decoration. The UA should use such font-based information when choosing auto line thicknesses wherever appropriate.

2.5. Determining the Position and Thickness of Line Decorations

This section is copied over from early drafts of Text Decoration Level 3. It is still under review, and needs integration with text-underline-offset and text-decoration-thickness.

Since line decorations can span elements with varying font sizes and vertical alignments, the best position for a line decoration is not necessarily the ideal position dictated by the decorating box. Instead, it’s calculated, per line, from all text decorated by the decorating box on that line, the considered text. However, descendants of the decorating box that are skipped due to text-decoration-skip, descendant inlines with text-decoration-skip: ink, and any descendants that do not participate in the decorating box’s inline formatting context are excluded from the set of considered text.

The line decoration positions are then calculated per line as follows (treating over-positioned underlines as over lines and under-positioned overlines as under lines):

over lines

Align the line decoration with respect to the highest over EM-box edge of the considered text.

alphabetic underlines

The alphabetic underline position is calculated by taking the ideal offset (from the alphabetic baseline) of each run of considered text, averaging those, and then using the lowest alphabetic baseline to actually position the line. (Alphabetic baselines can differ between baseline-aligned boxes if the dominant baseline is non-alphabetic.) To prevent superscripts and subscripts from throwing this position off-kilter, an inline with a non-initial computed vertical-align is treated as having the ideal underline position of its parent.

non-alphabetic under lines

Position the line decoration with respect to the lowest under EM-box edge of the considered text.

line-throughs

Line-throughs essentially use the same sort of averaging as for alphabetic underlines, but recompute the position when drawing across a descendant with a different computed font-size. (This ensures that the text remains effectively “crossed out” despite any font size changes.) For each run of considered text with the same font-size, compute an ideal position averaged from its font metrics. To prevent superscripts and subscripts from throwing this position off-kilter, an inline with a non-initial computed vertical-align is treated as having the ideal underline position of its parent. Position the portion of the line across each decorated fragment at that position.

For simplicity, line-throughs should draw over each element at that element’s preferred/averaged position. This can produce some undesirable jumpiness, but there doesn’t appear to be any way to avoid that which is correct in all instances, and all attempts are worryingly complex. What position should line-throughs adopt over elements that have a different font-size, but no considered text?

CSS does not define the thickness of line decorations. In determining the thickness of text decoration lines, user agents may consider the font sizes, faces, and weights of descendants to provide an appropriately averaged thickness.

2.6. Text Decoration Shorthand: the text-decoration property

This property is a shorthand for setting text-decoration-line, text-decoration-thickness, text-decoration-style, and text-decoration-color in one declaration. Omitted values are set to their initial values.

:link {
  color: blue;
  text-decoration: underline;
  text-decoration: navy dotted underline; /* Ignored in CSS1/CSS2 UAs */
}

Note: The shorthand purposefully omits the text-underline-position property, which is a language/writing-system–dependent setting that keys off the content, so that it can cascade and inherit independently from the (uninherited) stylistic settings of the text-decoration shorthand.

2.7. Text Underline Position: the text-underline-position property

This property, which is not a sub-property of the text-decoration shorthand, sets the position of an underline with respect to the text, and defines its zero position for further adjustment by text-underline-offset. It affects all decorations originating from this element, even if descendant boxes specify a different position. It does not affect underlines specified by ancestor elements.

:root:lang(ja), [lang|=ja], :root:lang(ko), [lang|=ko] { text-underline-position: under right; }
:root:lang(zh), [lang|=zh] { text-underline-position: under left; }

If left or right is specified alone, auto is also implied. Values have the following meanings:

auto

The user agent may use any algorithm to determine the underline’s position; however it must be placed at or under the alphabetic baseline.

Note: It is suggested that the default underline position be close to the alphabetic baseline, unless that would either cross subscripted (or otherwise lowered) text or draw over glyphs from Asian scripts such as Han or Tibetan for which an alphabetic underline is too high: in such cases, shifting the underline lower or aligning to the em box edge as described for under may be more appropriate.

A typical “alphabetic” underline is positioned just below the alphabetic baseline

from-font

If the first available font has metrics indicating a preferred underline offset, use that offset, otherwise behaves as auto.

under

The underline is positioned under the element’s text content. In this case the underline usually does not cross the descenders. (This is sometimes called “accounting” underline.) This value can be combined with left or right if a particular side is preferred in vertical typographic modes.

text-underline-position: under

Because text-underline-position inherits, and is not reset by the text-decoration shorthand, the following example switches the document to use under underlining, which can be more appropriate for writing systems with long, complicated descenders. It is also often useful for mathematical or chemical texts that use many subscripts.

:root { text-underline-position: under; }

Note: The under value does not guarantee that the underline will not conflict with glyphs, as some fonts have descenders or diacritics that extend below the font’s descent metrics.

left

In vertical typographic modes, the underline is aligned as for under, except it is always aligned to the left edge of the text. If this causes the underline to be drawn on the "over" side of the text, then an overline also switches sides and is drawn on the "under" side.

right

In vertical typographic modes, the underline is aligned as for under, except it is always aligned to the right edge of the text. If this causes the underline to be drawn on the "over" side of the text, then an overline also switches sides and is drawn on the "under" side.

left	right

In vertical typographic modes, the text-underline-position values left and right allow placing the underline on either side of the text. (In horizontal typographic modes, both values are treated as auto.)

2.8. Text Underline Offset: the text-underline-offset property

This property, which is not a sub-property of the text-decoration shorthand, sets the offset of underlines from their zero position. Positive offsets represent distances outward from the text; negative offsets inward. It affects all decorations originating from this element, even if descendant boxes specify a different position. It does not affect underlines specified by ancestor elements.

Values have the following meanings:

auto

The UA chooses an appropriate offset for underlines.

However, this offset must be zero if the computed value of text-underline-position is from-font and the UA was able to extract an appropriate metric to use from the font.

<length>

Specifies the offset of underlines as a fixed length.

Note: A length will inherit as a fixed value, and will not scale with the font.

<percentage>

Specifies the offset of underlines as a percentage of 1em.

Note: A percentage will inherit as a relative value, and will therefore scale with changes in the font as it inherits.

When the value of the text-decoration-line property is either spelling-error or grammar-error, the UA must ignore the value of text-underline-position.

2.8.1. Underline Offset Origin (Zero Position)

The zero position of the underline depends on the value of text-underline-position as detailed below.

The underline is aligned to the outside of the specified position (extending its thickness in the positive direction only).

Any automatic adjustments made to accommodate descendant content are maintained; the text-underline-offset is in addition to those.

2.8.2. Using Font Metrics for Automatic Positioning

Some font formats (such as OpenType) can offer information about the appropriate position of a line decoration. The UA should use such font-based information in its choice of auto offset wherever appropriate, and must use such information when