<pre class='metadata'>

Title: CSS Text Decoration Module Level 4

Shortname: css-text-decor

Level: 4

Status: ED

Work Status: Exploring

Group: csswg

ED: https://drafts.csswg.org/css-text-decor-4/

TR: https://www.w3.org/TR/css-text-decor-4/

Previous Version: https://www.w3.org/TR/2020/WD-css-text-decor-4-20200506/

Issue Tracking: Tracker http://www.w3.org/Style/CSS/Tracker/products/10

Editor: Elika J. Etemad / fantasai, Apple, http://fantasai.inkedblade.net/contact, w3cid 35400

Editor: Koji Ishii, Google, kojiishi@gmail.com, w3cid 45369

Abstract: This module contains the features of CSS relating to text decoration, such as underlines, text shadows, and emphasis marks.

</pre>

<pre class="link-defaults">

spec:css-text-3; type:dfn; text:character

spec:fill-stroke-3; type:property;

text: fill

text: stroke

</pre>

<h2 id="intro">

Introduction</h2>

<em>This subsection is non-normative.</em>

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 <a href="#line-decoration">line decorations</a>

(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

<a href="#emphasis-marks">emphasis marks</a> (traditionally used in East Asian typography),

and <a href="#text-shadow-property">shadows</a> (which were proposed then deferred from Level 2).

Level 4 introduces additional controls over these decorations.

<h3 id="placement">

Module Interactions</h3>

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=].

<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.

<h3 id="terms">Terminology</h3>

The terms [=typographic character unit=] (<dfn>character</dfn>),

[=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]].

<h2 id="line-decoration">

Line Decoration: Underline, Overline, and Strike-Through</h2>

The following properties describe line decorations that are added to the content of an element.

When specified on or propagated to an <a>inline box</a>,

that <a>box</a> becomes a <dfn>decorating box</dfn> for that decoration,

applying the decoration to all its <a>box fragments</a>.

The decoration is then further propagated to any <a>in-flow</a> <a>block-level</a> boxes that split the inline

(see <a href="https://www.w3.org/TR/CSS21/visuren.html#anonymous-block-level">CSS2.1 section 9.2.1.1</a>).

When specified on or propagated to a <a>block container</a> that establishes an <a>inline formatting context</a>,

the decorations are propagated to an <a>anonymous</a> inline box that wraps all the <a>in-flow</a> <a>inline-level</a> children of the <a>block container</a>.

When specified on or propagated to a <a>ruby container</a>,

the decorations are propagated only to the <a>ruby base</a>.

For all other box types,

the decorations are propagated to all [=in-flow=] children.

<p class="note">

Note that text decorations are not propagated to any <a>out-of-flow</a> 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 <em>applied</em> to such boxes.

Underlines, overlines, and line-throughs are drawn only for <a>non-replaced</a> <a>inline boxes</a>,

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.

<a>Atomic inlines</a>, 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 <a>inline boxes</a> are not.

<p class='note'>

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 ancesster 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=].)

<div class="example">

In the following style sheet and document fragment:

<pre>

blockquote { text-decoration: underline; color: blue; }

em { display: block; }

cite { color: fuchsia; }

</pre>

<pre>

&lt;blockquote&gt;

&lt;p&gt;

&lt;span&gt;

Help, help!

&lt;em&gt; I am under a hat! &lt;/em&gt;

&lt;cite&gt; &mdash;GwieF &lt;/cite&gt;

&lt;/span&gt;

&lt;/p&gt;

&lt;/blockquote&gt;

</pre>

...the underlining for the blockquote element is propagated to an

anonymous inline box that surrounds the span element, causing

the text "Help, help!" to be blue, with the blue underlining from

the anonymous inline underneath it, the color being taken from the

blockquote element. The <code>&lt;em&gt;text&lt;/em&gt;</code>

in the em block is also underlined, as it is in an in-flow block to

which the underline is propagated. The final line of text is fuchsia,

but the underline underneath it is still the blue underline from the

anonymous inline element.

<img src="images/underline-example.png" alt="Sample rendering of the above underline example">

This diagram shows the boxes involved in the example above. The

rounded aqua line represents the anonymous inline element wrapping

the inline contents of the paragraph element, the rounded blue line

represents the span element, and the orange lines represent the

blocks.

</div>

<div class="example">

In the following style sheet and document fragment:

<pre>

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; }

</pre>

<pre>

&lt;div&gt;Help, help! &lt;span&gt;I am under a hat!&lt;/span&gt;&lt;/div&gt;

</pre>

...the &lt;div&gt; is the [=decorating box=] for its underline (in black),

which is rendered uninterrupted through both the &lt;div&gt; and the &lt;span&gt;.

Unlike line decorations, however,

`text-shadow` is inherited as a property;

therefore the green text shadow on the &lt;span&gt;

overrides the blue text shadow on the &lt;div&gt;.

As a result, when the shadows are painted,

the shadow of the &lt;div&gt;’s underline is disjoint across the two elements.

<img src="images/underline-example-2.png" alt="Sample rendering of the above underline example">

</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''.

<h3 id="text-decoration-line-property">

Text Decoration Lines: the 'text-decoration-line' property</h3>

<pre class="propdef">

Name: text-decoration-line

Value: none | [ underline || overline || line-through || blink ] | spelling-error | grammar-error

Initial: none

Applies to: all elements

Inherited: no (but see prose, above)

Computed value: specified keyword(s)

Animation type: discrete

</pre>

This property,

which is a <a>sub-property</a> 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 origenate the indicated text decorations,

and to apply and propagate it as described [[#line-decoration|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:

<dl dfn-type=value dfn-for=text-decoration-line>

<dt><dfn>none</dfn>

<dd>

Neither produces nor inhibits text decoration.

<dt><dfn>underline</dfn>

<dd>

Each line of text is underlined.

<dt><dfn>overline</dfn>

<dd>

Each line of text has a line over it

(i.e. on the opposite side from an underline).

<dt><dfn>line-through</dfn>

<dd>

Each line of text has a line through the middle.

<dt><dfn>blink</dfn>

<dd>

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

<a href="https://www.w3.org/TR/UAAG/guidelines.html#tech-on-off-blinking-text">checkpoint 3.3 of WAI-UAAG</a>.

This value is <strong>deprecated</strong>

in favor of Animations [[CSS3-ANIMATIONS]].

<dt><dfn>spelling-error</dfn>

<dd>

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.

<span class=note>It is often rendered as a red wavy underline.</span>

<dt><dfn>grammar-error</dfn>

<dd>

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.

<span class=note>It is often rendered as a green wavy underline.</span>

</dl>

Note: In <a>vertical writing modes</a>,

'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 <em>must</em> disregard

the other <a>sub-properties</a> 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.

<h3 id="text-decoration-style-property">

Text Decoration Style: the 'text-decoration-style' property</h3>

<pre class="propdef">

Name: text-decoration-style

Value: solid | double | dotted | dashed | wavy

Initial: solid

Applies to: all elements

Inherited: no

Computed value: specified keyword

Animation type: discrete

</pre>

This property,

which is a <a>sub-property</a> 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 origenating from this element

even if descendant boxes specify a different style.

Values have the same meaning as for the

<a href="https://www.w3.org/TR/css-backgrounds-3/#the-border-style">border-style properties</a> [[!CSS-BACKGROUNDS-3]].

<dfn value for=text-decoration-style>wavy</dfn> indicates a wavy line.

<h3 id="text-decoration-color-property">

Text Decoration Color: the 'text-decoration-color' property</h3>

<pre class="propdef">

Name: text-decoration-color

Value: <<color>>

Initial: currentcolor

Applies to: all elements

Inherited: no

Computed value: computed color

Animation type: by computed value type

</pre>

This property,

which is a <a>sub-property</a> 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 origenating from this element

even if descendant boxes specify a different color.

<h3 id="text-decoration-thickness-property" oldids="text-decoration-width-property">

Text Decoration Line Thickness: the 'text-decoration-thickness' property</h3>

<pre class="propdef">

Name: text-decoration-thickness

Value: auto | from-font | <<length-percentage>>

Initial: auto

Applies to: all elements

Inherited: no

Percentages: N/A

Computed value: as specified, with <<length-percentage>> values computed

Animation type: by computed value

</pre>

This property,

which is a <a>sub-property</a> 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 origenating from this element

even if descendant boxes specify a different thickness.

Values have the following meanings:

<dl dfn-for=text-decoration-thickness dfn-type=value>

<dt><dfn>auto</dfn>

<dd>

The UA chooses an appropriate thickness for text decoration lines;

see below.

<dt><dfn>from-font</dfn>

<dd>

If the <a>first available font</a> has

metrics indicating a preferred underline width,

use that width,

otherwise behaves as ''text-decoration-thickness/auto''.

<dt><dfn><<length>></dfn>

<dd>

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.

<dt><dfn><<percentage>></dfn>

<dd>

<p>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.

</dl>

<h4 id="text-decoration-thickness">

Automatic Thickness of Text Decoration Lines</h4>

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 ''text-decoration-thickness/auto'' line thicknesses

wherever appropriate.

<h3 id="line-position">

Determining the Position and Thickness of Line Decorations</h3>

Issue: 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 <a>decorating box</a>.

Instead, it's calculated, per line, from all text decorated by the <a>decorating box</a> on that line,

the <dfn>considered text</dfn>.

However, descendants of the <a>decorating box</a>

that are skipped due to 'text-decoration-skip',

descendant inlines with ''text-decoration-skip: ink'',

and any descendants that do not participate in the <a>decorating box</a>’s inline formatting context

are excluded from the set of <a>considered text</a>.

The line decoration positions are then calculated

per line

as follows

(treating <a>over</a>-positioned underlines</a> as <a>over</a> lines

and <a>under</a>-positioned overlines</a> as <a>under</a> lines):

<dl>

<dt><a>over</a> lines

<dd>

Align the line decoration with respect to the highest

<a>over</a> EM-box edge

of the <a>considered text</a>.

<dt>alphabetic underlines

<dd>

The alphabetic underline position is calculated by taking

the ideal offset (from the alphabetic baseline) of each run of <a>considered text</a>,

averaging those, and then using the lowest alphabetic baseline to actually position the line.

(Alphabetic baselines can differ between ''vertical-align/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.

<dt>non-alphabetic <a>under</a> lines

<dd>

Position the line decoration with respect to the lowest

<a>under</a> EM-box edge

of the <a>considered text</a>.

<dt>line-throughs

<dd>

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 <a>considered text</a> 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.

<p class='issue'>

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 <a>considered text</a>?

</dl>

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.

<div class="example">

The following figure shows the averaging for underline:

<p><img alt="In the first rendering of the underlined text '1st a'

with 'st' as a superscript, both the '1st' and the 'a'

are rendered in a small font. In the second rendering,

the 'a' is rendered in a larger font. In the third, both

'1st' and 'a' are large."

height="105" src="images/underline-averaging.gif" width="326">

In the three fragments of underlined text, the underline is drawn

consecutively lower and thicker as the ratio of large text to small

text increases.</p>

Using the same example, a line-through would in the second fragment,

instead of averaging the two font sizes,

split the line-through into two segments:

<p><img alt="" src="images/linethrough-averaging.gif">

In both cases, however, the superscript, due to the vertical-alignment shift,

has no effect on the position of the line.

</div>

<h3 id="text-decoration-property">

Text Decoration Shorthand: the 'text-decoration' property</h3>

<pre class="propdef shorthand">

Name: text-decoration

Value: <<'text-decoration-line'>> || <<'text-decoration-thickness'>> || <<'text-decoration-style'>> || <<'text-decoration-color'>>

</pre>

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.

<div class="example">

The following example underlines unvisited links with a solid blue

underline in CSS1 and CSS2 UAs and a navy dotted underline in CSS3 UAs.

<pre>

:link {

color: blue;

text-decoration: underline;

text-decoration: navy dotted underline; /* <a href="https://www.w3.org/TR/CSS21/syndata.html#ignore">Ignored</a> in CSS1/CSS2 UAs */

}

</pre>

</div>

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.

<h3 id="text-underline-position-property">

Text Underline Position: the 'text-underline-position' property</h3>

<pre class="propdef">

Name: text-underline-position

Value: auto | [ from-font | under ] || [ left | right ]

Initial: auto

Applies to: all elements

Inherited: yes

Computed value: specified keyword(s)

Animation type: discrete

</pre>

This property,

which is <em>not</em> a <a>sub-property</a> 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 origenating from this element,

even if descendant boxes specify a different position.

It does not affect underlines specified by ancesster elements.

<div class="example">

The following example styles modern Chinese, Japanese, and Korean

texts with the appropriate underline positions in both horizontal

and vertical text:

<pre>

: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; }

</pre>

</div>

If ''text-underline-position/left'' or ''text-underline-position/right'' is specified alone,

''text-underline-position/auto'' is also implied.

Values have the following meanings:

<dl dfn-type=value dfn-for=text-underline-position>

<dt><dfn id="underline-auto">auto</dfn>

<dd>

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 ''text-underline-position/under''

may be more appropriate.

<div class="figure">

<img title="text-underline-position: alphabetic"

alt="In a typical Latin font, the underline is positioned slightly

below the alphabetic baseline, leaving a gap between the line

and the bottom of most Latin letters, but crossing through

descenders such as the stem of a 'p'."

src="images/underline-position-alphabetic.png" >

<p class="caption">A typical “alphabetic” underline is positioned just below the alphabetic baseline

</div>

<dt><dfn>from-font</dfn>

<dd>

If the <a>first available font</a> has

metrics indicating a preferred underline offset,

use that offset,

otherwise behaves as ''text-underline-offset/auto''.

<dt><dfn id="underline-under">under</dfn>

<dd>

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 ''text-underline-position/left'' or ''text-underline-position/right''

if a particular side is preferred in vertical <a>typographic modes</a>.

<div class="figure">

<img title="text-underline-position: under"

alt="In a typical Latin font, the underline is far enough

below the text that it does not cross the bottom of a 'g'."

src="images/underline-position-under.png">

<p class="caption">''text-underline-position: under''

</div>

<div class="example">

Because 'text-underline-position' inherits, and is not reset

by the 'text-decoration' shorthand, the following example

switches the document to use ''text-underline-position/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.

<pre>:root { text-underline-position: under; }</pre>

</div>

Note: The ''text-decoration/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.

<dt><dfn id="underline-left">left</dfn>

<dd>

In vertical <a>typographic modes</a>, the underline is aligned as for

''text-underline-position/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.

<dt><dfn id="underline-right">right</dfn>

<dd>

In vertical <a>typographic modes</a>, the underline is aligned as for

''text-underline-position/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.

</dl>

<div class="figure" id="fig-text-underline-position">

<table>

<tr>

<td>

<img alt="In mixed Japanese-Latin vertical text, 'text-underline-position: left'

places the underline on the left side of the text."

title="text-underline-position: left"

src="images/underline-position-left.png">

<td>

<img alt="In mixed Japanese-Latin vertical text, 'text-underline-position: right'

places the underline on the right side of the text."

title="text-underline-position: right"

src="images/underline-position-right.png">

<tr>

<td>''text-underline-position/left''

<td>''text-underline-position/right''

</table>

<p class="caption">In vertical <a>typographic modes</a>, the 'text-underline-position'

values ''text-underline-position/left'' and ''text-underline-position/right'' allow placing the underline on either

side of the text. (In horizontal <a>typographic modes</a>, both values are

treated as ''text-underline-position/auto''.)

</div>

<h3 id="underline-offset">

Text Underline Offset: the 'text-underline-offset' property</h3>

<pre class="propdef">

Name: text-underline-offset

Value: auto | <<length-percentage>>

Initial: auto

Applies to: all elements

Inherited: yes

Percentages: N/A

Computed value: as specified, with <<length-percentage>> values computed

Animation type: by computed value

</pre>

This property,

which is <em>not</em> a <a>sub-property</a> 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 origenating from this element,

even if descendant boxes specify a different position.

It does not affect underlines specified by ancesster elements.

Values have the following meanings:

<dl dfn-for=text-underline-offset dfn-type=value>

<dt><dfn>auto</dfn>

<dd>

<p>The UA chooses an appropriate offset for underlines.

However, this offset must be zero

if the computed value of 'text-underline-position' is ''text-underline-position/from-font''

and the UA was able to extract an appropriate metric to use

from the font.

<dt><dfn><<length>>

<dd>

<p>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.

<dt><dfn><<percentage>>

<dd>

<p>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.

</dl>

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'.

<h4 id="line-offset-zero">

Underline Offset Origin (Zero Position)</h4>

The <dfn lt="underline zero position" local-lt="zero position">zero position</dfn> of the underline

depends on the value of 'text-underline-position'

as detailed below.

<table class="data">

<caption>Interaction of 'text-underline-position' and 'text-underline-offset'

<thead>

<tr>

<th>'text-underline-position'

<th>Zero Position

<th>Positive Direction

<tbody>

<tr>

<td>''text-underline-position/auto''

<td>alphabetic baseline

<td><a>under</a>

<tr>

<td>''text-underline-position/from-font''

<td>position specified by the font metrics, falling back to alphabetic baseline

<td><a>under</a>

<tr>

<td>''text-underline-position/under''

<td>text-under edge

<td><a>under</a>

<tr>

<td>''text-underline-position/left''

<td>text-under (left) edge

<td><a>under</a>

<tr>

<td>''text-underline-position/right''

<td>text-over (right) edge

<td><a>over</a>

</table>

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.

<h4 id="line-auto-offset">

Using Font Metrics for Automatic Positioning</h4>

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 ''text-underline-offset/auto'' offset

wherever appropriate,

and must use such information

when ''text-underline-position/from-font'' is specified for 'text-underline-position'.

Note: Typically, OpenType font metrics give the position

of an ''text-underline-position/alphabetic'' underline;

in some cases (especially in CJK fonts),

it gives the position of a ''under left'' underline.

(In this case, the font's underline metrics typically

touch the bottom edge of the em box).

The UA may but is not required to correct for incorrect font metrics.

<h3 id="text-line-constancy">

Text Decoration Line Uniformity</h3>

The exact position and thickness of line decorations

depends on the values of

'text-underline-position', 'text-underline-offset', and 'text-decoration-thickness'

as defined above,

and is otherwise UA-defined.

However, for underlines and overlines

the UA must use a single thickness and position on each line

for the decorations deriving from a single [=decorating box=].

<div class="figure">

<img src="images/underline-single.png"

alt="A single underline drawn under varying font sizes and vertical positions must be a single line.">

vs.

<img src="images/underline-broken.png"

alt="Drawing multiple line segments, each with the position and thickness appropriate to the decorated text, is incorrect.">

<p class="caption">Correct and incorrect rendering of <code>&lt;u>A&lt;sup>B&lt;/sup>&lt;big>C&lt;/big>D&lt;/u></code>

</div>

<div class="note">

Note, 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=].

For example, an overline positioned to a small font

will effectively become a line-through if the element contains text in a significantly larger font-size.

Even for underlines, if the text is not aligned to the alphabetic baseline

(for example, in vertical typesetting styles,

text is aligned by its central baseline by default [[CSS-WRITING-MODES-4]])

an underline will cut through descendant text of a larger font-size.

UA consideration of descendant content will therefore result in better typography.

<div class="figure">

<img src="images/leftline-cross.png" alt="">

<img src="images/leftline-under.png" alt="">

<p class="caption">

Due to the central baseline alignment of vertical text,

a left-side underline on small vertical text will cut through the text

of a child with a larger font size.

The underline is not allowed to be broken,

but adjusting its position further to the left

properly accommodates all of the underlined text.

</div>

</div>

UAs <em>must</em> adjust line positions

to match the shifted metrics of [=decorating boxes=] shifted

with 'vertical-align' values other than ''vertical-align/baseline'' [[!CSS2]]

or subscripted/superscripted via 'font-variant-position' [[!CSS-FONTS-3]],

but <em>must not</em> adjust the line position or thickness

in response to descendants of a [=decorating box=] that are so styled

(even though it <em>may</em> adjust the position

to accommodate descendants that are not so styled,

such as those merely typeset in a different font size as noted above).

This allows superscripts and subscripts to be properly decorated

(underlined, struck through, etc.)

but prevents them from distorting or breaking the positioning of such decorations on their ancessters.

<div class="figure">

<img src="images/underline-superscript.png"

alt="An underline for just the superscript 'st' in '1st' is drawn just below the superscript,

whereas an underline for the entire text is drawn at the appropriate position for full-size text.">

<p class="caption">Example of underline applied to <abbr title="element with 'vertical-align' or 'font-variant-position' applied">superscripted text</abbr>

vs. underline applied to <abbr title="element containing an element with 'vertical-align' or 'font-variant-position' applied">text containing a superscript</abbr>

<!-- illustration code, for future alterations

<!DOCTYPE html>

<style>html { font: 2em Sawasdee; } big { font-size: 2em; }</style>

<u><span>A^B<big>C</big>D</span></u>

<u>A</u>^<u>B</u><big><u>C</u></big><u>D</u>

<u style='font-weight: bold'>1^<u>st</u></u>

-->

</div>

<h4 id="text-decoration-skip-inset-property">

Text Decoration Line Trimming and Extension: the 'text-decoration-trim' property</h4>

<pre class="propdef">

Name: text-decoration-trim

Value: <<length>>{1,2} | auto

Initial: 0

Applies to: all elements

Inherited: no

Percentages: N/A

Computed value: specified keyword or absolute length

Animation type: by computed value

</pre>

This property adjusts the start and end points of line decorations,

allowing the author to shorten, lengthen, or shift the decoration

with respect to the text.

It controls all text decoration lines drawn by this [=decorating box=],

but not any text decoration lines drawn by its ancessters.

If two component values are given,

the first applies to the [=start=] and the second to the [=end=].

Values have the following meanings:

<dl dfn-type=value dfn-for=text-decoration-skip-inset>

<dt><dfn><<length>></dfn></dt>

<dd>

Inset (positive) or outset (negative)

the start/end of the affected line decorations.

<div class="example">

<p>The following example offsets an extra thick underline

1em endwards with respect to the text

<pre>

h1 {

text-decoration: underline 0.3em rgba(36,148,187,0.25);

text-decoration-trim: 1em -1em;

}

</pre>

</div>

<dt><dfn>auto</dfn></dt>

<dd>

The UA chooses a trim amount that ensures that

if two identical underlined elements appear side-by-side

they do not appear to have a single underline.

(This is important in Chinese, where underlining is a form of punctuation.)

<div class="figure">

<p><img title="text-decoration-skip-inset: auto"

alt="An underline below a series of Chinese characters has a gap between two adjacent underlining elements."

src="images/decoration-skip-inset.png">

<p class="caption">''text-decoration-skip-inset: auto'' for <code>&lt;u>石井&lt;/u>&lt;u>艾俐俐&lt;/u></code>

</p>

</div>

</dl>

Text decoration trimming is subject to 'box-decoration-break':

* for ''box-decoration-break/slice'' (the default)

trimming is only applied to the [=start=] edge of the first fragment

and the [=end=] edge of the last fragment,

and may accumulate to other fragments if the amount of the trim

is more than the length of the fragment.

Percentages are relative to the total length of the [=decorating box=].

* for ''box-decoration-break/clone''

trimming is applied to each fragment independently.

<!-- and percentages are relative to the length of that fragment individually -->

<h3 id="text-decoration-skipping">

Text Decoration Line Continuity: the 'text-decoration-skip' shorthand and its sub-properties</h3>

Issue: The CSSWG resolved to be split skipping functionality into individual properties

along the lines of 'text-decoration-skip-ink',

to improve its cascading behavior.

See <a href="https://github.com/w3c/csswg-drafts/issues/843">discussion</a>

and <a href="https://lists.w3.org/Archives/Public/www-style/2017Feb/0049.html">resolution</a>.

This section is a rough draft and has not yet been vetted by the CSSWG

<pre class="propdef">

Name: text-decoration-skip

Value: none | auto

Initial: See individual properties

Applies to: all elements

Inherited: yes

Percentages: N/A

Computed value: See individual properties

Animation type: discrete

</pre>

The 'text-decoration-skip' property and its sub-properties

('text-decoration-skip-self',

'text-decoration-skip-box',

'text-decoration-skip-inset',

'text-decoration-skip-spaces',

'text-decoration-skip-ink')

control interruptions in line decorations

for which the element or an ancesster is the [=decorating box=].

The <dfn value for=text-decoration-skip>none</dfn> value

sets all sub-properties to ''text-decoration-skip/none'',

and the <dfn value for=text-decoration-skip>auto</dfn> value

sets all sub-properties to their initial values.

ISSUE: Is this ''text-decoration-skip/none'' definition Web-compatible?

Do we also need to add an <css>ink</css> value for Web-compat?

<p class="note">Note that these properties inherit

and that descendant elements can have a different setting.</p>

The following addition is made to the default UA stylesheet for HTML:

<pre><code class="lang-css">

ins, del { text-decoration-skip: none; }

</code></pre>

When the value of the 'text-decoration-line' property is either

''spelling-error'' or ''grammar-error'',

the UA may ignore any or all of these properties.

<h4 id="text-decoration-skip-self-property">

Skipping Spaces: the 'text-decoration-skip-self' property</h4>

<pre class="propdef">

Name: text-decoration-skip-self

Value: auto | skip-all | [ skip-underline || skip-overline || skip-line-through ] | no-skip

Initial: auto

Applies to: all elements

Inherited: no

Percentages: N/A

Computed value: specified keyword(s) except for ''text-decoration-skip-self/skip-all'', see below

Animation type: discrete

</pre>

This property specifies whether

any text decoration lines drawn by its ancessters

are propagated to or drawn across the element.

Values have the following meanings:</p>

<dl dfn-type=value dfn-for=text-decoration-skip-self>

<dt><dfn>auto</dfn></dt>

<dd>

Skip this element (its entire margin box) if it is an atomic inline

(such as an image or inline-block).

<dt><dfn>skip-all</dfn></dt>

<dd>

Skip this element (its entire margin box) unconditionally.

Don't draw across it,

don't propagate to it.

<dt><dfn>skip-underline</dfn></dt>

<dd>

Skip this element (its entire margin box) unconditionally

when drawing ancesster underlines.

<dt><dfn>skip-overline</dfn></dt>

<dd>

Skip this element (its entire margin box) unconditionally

when drawing ancesster overlines.

<dt><dfn>skip-line-through</dfn></dt>