Overview.bs

<pre class='metadata'>
Title: CSS Text Decoration Module Level 3
Shortname: css-text-decor
Level: 3
Status: ED
Work Status: Testing
Group: csswg
ED: https://drafts.csswg.org/css-text-decor-3/
TR: https://www.w3.org/TR/css-text-decor-3/
Previous Version: https://www.w3.org/TR/2013/CR-css-text-decor-3-20130801/
Previous Version: https://www.w3.org/TR/2013/WD-css-text-decor-3-20130103/
Previous Version: https://www.w3.org/TR/2012/WD-css-text-decor-3-20121113/
Issue Tracking: Tracker http://www.w3.org/Style/CSS/Tracker/products/10
Editor: Elika J. Etemad / fantasai, Invited Expert, 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.
At Risk: The 'text-decoration-skip' property.
At Risk: The line positioning rules.
At Risk: The ability to place both emphasis marks and ruby on the same base text.
At Risk: The ''spelling-error'' and ''grammar-error'' values of the 'text-decoration-line' property.
Link Defaults: css-color-3 (property) color
Use <i> Autolinks: yes
</pre>

<pre class="link-defaults">
spec:css-break-3; type:dfn; text:fragment
</pre>

<h2 id="intro">
Introduction</h2>

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

  <p>This module covers text decoration, i.e. decorating the glyphs
  of the text once typeset according to font and typographic rules.
  (See [[CSS3TEXT]] and [[CSS3-FONTS]].)
  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.

  <p>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 adds the ability to change
  the color, style, position, and continuity of these decorations,
  and also introduces
  <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).

<h3 id="placement">
Module Interactions</h3>

  <p>This module replaces and extends the text-decorating
  features defined in [[!CSS2]] chapter 16.

<h3 id="values">
Values</h3>

  This specification follows the <a href="https://www.w3.org/TR/CSS21/about.html#property-defs">CSS property definition conventions</a> from [[!CSS2]].
  Value types not defined in this specification are defined in CSS Values & Units [[!CSS-VALUES-3]].
  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> keywords as their property value.
  For readability they have not been repeated explicitly.

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

  <p>The terms <dfn><a href="https://www.w3.org/TR/css3-text/#grapheme-cluster">character</a></dfn>,
    <dfn><a href="https://www.w3.org/TR/css3-text/#letter">letter</a></dfn>, and
    <dfn><a href="https://www.w3.org/TR/css3-text/#content-language">content language</a></dfn>
    as used in this specification are defined in [[!CSS3TEXT]].
    Other terminology and concepts used in this specification are defined
    in [[!CSS2]] and [[!CSS-WRITING-MODES-3]].

<h2 id="line-decoration">
Line Decoration: Underline, Overline, and Strike-Through</h2>

  <p>
    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>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 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 <em>applied</em> to such boxes.

  <p>
    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 <i>decorating box</i> 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 this level, by default only the margins, borders, and padding of the <i>decorating box</i> are skipped.
    In the future CSS2.1 may be updated to match this new default.
    Also, control over decorating leading/trailing spaces is expected in Level 4,
    and will be applied by default to the HTML <{ins}> and <{del}> elements.

  <p>
    UAs <em>may</em> interrupt underlines and overlines where the line would cross glyph ink
    and to some distance to either side of the glyph outline;
    this behavior is not controllable in this level,
    but will be further defined in Level 4.
    Line-throughs must remain continuous, however.

  <div class="figure">
    <p><img title="text-decoration-skip: ink"
             alt="An alphabetic underline through Myanmar text skips around descenders and the vertical strokes of combining characters that drop below the alphabetic baseline."
             src="images/decoration-skip-ink.png">
    <p class="caption">Skipping Glyph Ink</p>
  </div>

 <p>When the UA interrupts underlines or overlines at glyph boundaries,
   the shape of the line at that boundary should
   follow the shape of the glyph.

  <div class="note">
    Note, this specification intentionally does not mandate a particular method
    for “following the shape” of the glyph
    so that UAs can take appropriate measures to handle
    aesthetic and performance considerations.
    For example,
    a UA could assume square line endings below a certain size threshold
    for performance reasons;
    or use trapezoidal endings to approximate curves,
    especially on thinner line decorations.
    In terms of aesthetic considerations,
    the UA might also consider what happens when the glyph boundary
    intersects only part of the line thickness
    or is slanted close to the horizontal--
    following the curve exactly
    could result in typographically-awkward wisps of underline.
    Whether to show the line within enclosed areas of a glyph is yet
    another consideration.

    <div class="figure">
      <p><img title="Wispy Leftovers of a Masked-Out Underline"
             alt="Take, for example, the word “goal” with an underline striking through the bottom loop of the “g”.
                  Depending on the position and thickness of the underline,
                  we might see the entire thickness of the underline, or only part of it within the “g”.
                  This example shows a masked-out underline in two positions.
                  In the left pair the underline passes through the center of the bowl of the “g”:
                  the full thickness of the underline shows through the center,
                  filling it.
                  In the right pair the underline is slightly lower,
                  and thus the portion of the underline within the “g” can only show a partial thickness."
             src="images/skip-ink-wisp.png">
      <p class="caption">
      Hiding the portion of the underline within the bowl gives a cleaner look to the type,
      while the curved ends of the underline outside it
      suggest the continuity of the underline through the letter
      by hugging its outer contour.
    </div>

  </div>

  <p>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 affect text decorations as part of the text they're drawn on,
    even if the decorations were specified on 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 <i>decorating box</i>.)

  <div class="example">
    <p>In the following style sheet and document fragment:</p>
    <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>
    <p>...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.</p>
    <p><img src="images/underline-example.png" alt="Sample rendering of the above underline example"></p>
    <p>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.</p>
  </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
  Inherited: no (but see prose, above)
  </pre>

  <p>Specifies what line decorations, if any, are added to the element.
    Values have the following meanings:</p>

  <dl>
    <dt><dfn value for="text-decoration-line">none</dfn>
      <dd>Neither produces nor inhibits text decoration.
    <dt><dfn value for="text-decoration-line">underline</dfn>
      <dd>Each line of text is underlined.
    <dt><dfn value for="text-decoration-line">overline</dfn>
      <dd>Each line of text has a line over it (i.e. on the opposite
      side from an underline).
    <dt><dfn value for="text-decoration-line">line-through</dfn>
      <dd>Each line of text has a line through the middle.
    <dt><dfn value for="text-decoration-line">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 value for="text-tecoration-line">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.
	  <span class=note>It is often rendered as a red wavy underline.</span>
    <dt><dfn value for="text-decoration-line">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.
	  <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 the value of 'text-decoration-line' is either ''spelling-error'' or ''grammar-error'',
    the UA may disregard the values of the other <a>sub-properties</a> of 'text-decoration',
    as well as those of other properties affecting the appearance of the text-decoration such as 'text-underline-position'.
    To the extent that honoring these properties would be meaningful and practical given the UA's chosen rendering,
    the UA should apply them, but is not required to.

    Note: The ''spelling-error'' and ''grammar-error'' values are at risk.


<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
  Inherited: no
  </pre>

  <p>This property specifies the style of the line(s) drawn for
    text decoration specified on the element. Values have the
    same meaning as for the
    <a href="https://www.w3.org/TR/css3-background/#the-border-style">border-style
    properties</a> [[!CSS3BG]]. ''wavy'' indicates a wavy line.</p>

  <p>
    The style of text decorations must remain the same on all decorations originating from a given element,
    even if descendant boxes have different specified styles.


<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
  Inherited: no
  Computed value: the computed color
  Animation type: <a href="https://www.w3.org/TR/css3-transitions/#animtype-color">color</a>
  </pre>

  <p>This property specifies the color of text decoration (underlines
    overlines, and line-throughs) set on the element with
    'text-decoration-line'.</p>

  <p>
    The color of text decorations must remain the same on all decorations originating from a given element,
    even if descendant boxes have different specified colors.


<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-style'>> || <<'text-decoration-color'>>
  </pre>

  <p>This property is a shorthand for setting 'text-decoration-line',
    'text-decoration-color', and 'text-decoration-style' in one declaration.
    Omitted values are set to their initial values. A 'text-decoration'
    declaration that omits both the 'text-decoration-color'
    and 'text-decoration-style' values is backwards-compatible
    with CSS Levels 1 and 2.</p>

  <div class="example">
    <p>The following example underlines unvisited links with a solid blue
    underline in CSS1 and CSS2 UAs and a navy dotted underline in CSS3 UAs.</p>

    <pre><code class="css">
<!-- -->: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 */
<!-- -->}</code></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 | [ under || [ left | right ] ]
  Initial: auto
  Inherited: yes
  </pre>

  <p>This property sets the position of an underline specified on the element.
    (It does not affect underlines specified by ancestor elements.)
    If ''text-underline-position/left'' or ''text-underline-position/right'' is specified alone,
    ''text-underline-position/auto'' is also implied.

  <div class="example">
    <p>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>
    <p>(Note that these rules are part of the suggested
      <a href="#default-stylesheet">default UA style sheet</a>.)
  </div>

  <p>Values have the following meanings:

  <dl>
    <dt><dfn id="underline-auto" value for="text-underline-position">auto</dfn></dt>
    <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.
      <p class="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">
        <p><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 id="underline-under" value for="text-underline-position">under</dfn></dt>
    <dd>The underline is positioned <i>under</i> 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">
        <p><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''</p>
      </div>
      <div class="example">
        <p>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" value for="text-underline-position">left</dfn></dt>
    <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" value for="text-underline-position">right</dfn></dt>
    <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.</dd>
  </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/under''.)</p>
  </div>

  <p>The exact position and thickness of line decorations is UA-defined in this level.
    However, for underlines and overlines
    the UA must use a single thickness and position on each line
    for the decorations deriving from a single <i>decorating box</i>.

  <div class="figure">
    <p><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">
    <p>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 <i>decorating box</i>.
    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-3]])
    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">
      <p><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>

  <p>UAs <em>must</em> adjust line positions
    to match the shifted metrics of <i>decorating boxes</i> shifted
    with 'vertical-align' values other than ''vertical-align/baseline'' [[!CSS2]]
    or subscripted/superscripted via 'font-variant-position' [[!CSS3-FONTS]],
    but <em>must not</em> adjust the line position or thickness
    in response to descendants of a <i>decorating box</i> that are so styled.
    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 ancestors.

  <div class="figure">
    <p><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<sup>B</sup><big>C</big>D</span></u>
      <u>A</u><sup><u>B</u></sup><big><u>C</u></big><u>D</u>
      <u style='font-weight: bold'>1<sup><u>st</u></sup></u>
    -->
  </div>

<!--
<h3 id="line-position">
Determining the Position and Thickness of Line Decorations</h3>

  <p>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 <i>decorating box</i>.
    Instead, it's calculated, per line, from all text decorated by the <i>decorating box</i> on that line,
    the <dfn>considered text</dfn>.
    However, descendants of the <i>decorating box</i>
    that are skipped due to 'text-decoration-skip',
    descendant inlines with ''text-decoration-skip: ink'',
    and any descendants that do not participate in the <i>decorating box</i>’s inline formatting context
    are excluded from the set of <i>considered text</i>.

  <p>
    The line decoration positions are then calculated
    per line
    as follows
    (treating <a href="#underline-left"><i>over</i>-positioned underlines</a> as <i>over</i> lines
    and <a href="#underline-left"><i>under</i>-positioned overlines</a> as <i>under</i> lines):

  <dl>
    <dt><a href="https://www.w3.org/TR/css-writing-modes/#over"><i>over</i></a> lines
    <dd>
      Align the line decoration with respect to the highest
      <a href="https://www.w3.org/TR/css-writing-modes/#over"><i>over</i></a> EM-box edge
      of the <i>considered text</i>.

    <dt><a href="#underline-alphabetic"><i>alphabetic</i></a> underlines
    <dd>
      <p>The alphabetic underline position is calculated by taking
      the ideal offset (from the alphabetic baseline) of each run of <i>considered text</i>,
      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.

    <dt>non-alphabetic <a href="https://www.w3.org/TR/css-writing-modes/#under"><i>under</i></a> lines
    <dd>
      Position the line decoration with respect to the lowest
      <a href="https://www.w3.org/TR/css-writing-modes/#under"><i>under</i></a> EM-box edge
      of the <i>considered text</i>.

    <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 <i>considered text</i> 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-throughts adopt over elements that have a different font-size,
        but no <i>considered text</i>?
  </dl>

  <p>
    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">
    <p>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">
    <p>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>
    <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">
    <p>In both cases, however, the superscript, due to the vertical-alignment shift,
    has no effect on the position of the line.
  </div>
-->
  <p>Some font formats (such as OpenType) can offer information
    about the appropriate position of a line decoration.
    The UA should use such information
    (such as the underline thickness,
    or appropriate alphabetic underline position)
    from the font wherever appropriate.

  <p class="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.

<h2 id="emphasis-marks">
Emphasis Marks</h2>

  <p>East Asian documents traditionally use small symbols next to each glyph to emphasize
    a run of text. For example:</p>

  <div class="figure">
    <p>
      <img alt="Example of emphasis in Japanese appearing over the text"
           class="example" src="images/text-emphasis-ja.gif" height="28" width="225"></p>
    <p class="caption">Accent emphasis (shown in blue for clarity) applied to Japanese text</p>
  </div>

  <p>The 'text-emphasis' shorthand, and its 'text-emphasis-style' and 'text-emphasis-color' longhands,
  can be used to apply such marks to the text.
  The 'text-emphasis-position' property, which inherits separately,
  allows setting the emphasis marks’ position with respect to the text.

<h3 id="text-emphasis-style-property">
Emphasis Mark Style: the 'text-emphasis-style' property</h3>

  <pre class="propdef">
  Name: text-emphasis-style
  Value: none | [ [ filled | open ] || [ dot | circle | double-circle | triangle | sesame ] ] | <<string>>
  Initial: none
  Inherited: yes
  Computed value: ''text-emphasis-style/none'', a pair of keywords representing the shape and fill, or a string
  </pre>

  <p>This property applies emphasis marks to the element's text.
    Values have the following meanings:</p>

  <dl>
    <dt><dfn value for="text-text-emphasis-style">none</dfn></dt>
      <dd>No emphasis marks.</dd>
    <dt><dfn value for="text-text-emphasis-style">filled</dfn></dt>
      <dd>The shape is filled with solid color.</dd>
    <dt><dfn value for="text-text-emphasis">open</dfn></dt>
      <dd>The shape is hollow.</dd>
    <dt><dfn value for="text-text-emphasis-style">dot</dfn></dt>
      <dd>Display small circles as marks.
        The filled dot is U+2022 '&#x2022;', and the open dot is U+25E6 '&#x25e6;'.</dd>
    <dt><dfn value for="text-text-emphasis-style">circle</dfn></dt>
      <dd>Display large circles as marks.
        The filled circle is U+25CF '&#x25cf;', and the open circle is U+25CB '&#x25cb;'.</dd>
    <dt><dfn value for="text-text-emphasis-style">double-circle</dfn></dt>
      <dd>Display double circles as marks.
        The filled double-circle is U+25C9 '&#x25c9;', and the open double-circle is U+25CE '&#x25ce;'.</dd>
    <dt><dfn value for="text-text-emphasis-style">triangle</dfn></dt>
      <dd>Display triangles as marks.
        The filled triangle is U+25B2 '&#x25b2;', and the open triangle is U+25B3 '&#x25b3;'.</dd>
    <dt><dfn value for="text-text-emphasis-style">sesame</dfn></dt>
      <dd>Display sesames as marks.
        The filled sesame is U+FE45 '&#xfe45;', and the open sesame is U+FE46 '&#xfe46;'.</dd>
    <dt><dfn value for="text-text-emphasis-style"><<string>></dfn></dt>
      <dd>Display the given string as marks.
        Authors should not specify more than one <i>character</i> in &lt;string&gt;.
        The UA may truncate or ignore strings consisting of more than one grapheme cluster.</dd>
  </dl>

  <p>If a shape keyword is specified but neither of ''filled'' nor ''open'' is
    specified, ''filled'' is assumed. If only ''filled'' or ''open'' is specified,
    the shape keyword computes to ''circle'' in horizontal <a>typographic modes</a> and
    ''sesame'' in vertical <a>typographic modes</a>.</p>

  <p>The marks should be drawn using the element's font settings
    with the addition of the ''font-variant-east-asian/ruby'' feature
    and the size scaled down 50%.
    However, since not all fonts have all these glyphs,
    and some fonts use inappropriate sizes for emphasis marks in these code points,
    the UA may opt to use a font known to be good for emphasis marks,
    or the marks may instead be synthesized by the UA.
    Marks must remain upright in vertical <a>typographic modes</a>:
    like CJK characters, they do not rotate to match the writing mode.
    The orientation of marks in horizontal <a>typographic modes</a> of vertical <a>writing modes</a>
    is undefined in this level
    (but may be defined in a future level if definitive use cases arise).

  <p class="note">
      One example of good fonts for emphasis marks is Adobe's opensource project,
      <a href="http://sourceforge.net/adobe/kenten-generic/">Kenten Generic OpenType Font</a>,
      which is specially designed for the emphasis marks.
  </p>

  <p>The marks are drawn once for each <a>typographic character unit</a>.
    However, emphasis marks are not drawn for <a>characters</a> that are:
  <ul>
    <li><a href="https://www.w3.org/TR/css3-text/#word-separator">Word separators</a> or that
      belong to the Unicode separator classes (Z*).
      (But note that emphasis marks <em>are</em> drawn for a space
       that combines with any combining characters.)</li>
    <li>Characters belonging to the Unicode classes for control codes
      and unassigned characters (Cc, Cf, Cn).</li>
  </ul>

<h3 id="text-emphasis-color-property">
Emphasis Mark Color: the 'text-emphasis-color' property</h3>

  <pre class="propdef">
  Name: text-emphasis-color
  Value: <<color>>
  Initial: currentcolor
  Inherited: yes
  Animation type: <a href="https://www.w3.org/TR/css3-transitions/#animtype-color">color</a>
  </pre>

  <p>This property specifies the foreground color of the emphasis marks.</p>

  <p class="note">
    The ''currentcolor'' keyword computes to itself
    and is resolved to the value of 'color' after inheritance is performed.
    This means 'text-emphasis-color' by default matches the text 'color'
    even as 'color' changes across elements.

<h3 id="text-emphasis-property">
Emphasis Mark Shorthand: the 'text-emphasis' property</h3>

  <pre class="propdef shorthand">
  Name: text-emphasis
  Value: <<'text-emphasis-style'>> || <<'text-emphasis-color'>>
  </pre>

  <p>This property is a shorthand for setting
    'text-emphasis-style' and 'text-emphasis-color'
    in one declaration.
    Omitted values are set to their initial values.</p>

  <p class="note">Note that 'text-emphasis-position' is not reset in this
    shorthand. This is because typically the shape and color vary, but the
    position is consistent for a particular language throughout the document.
    Therefore the position should inherit independently.</p>

<h3 id="text-emphasis-position-property">
Emphasis Mark Position: the 'text-emphasis-position' property</h3>

  <pre class="propdef">
  Name: text-emphasis-position
  Value: [ over | under ] && [ right | left ]?
  Initial: over right
  Inherited: yes
  </pre>

  <p>This property describes where emphasis marks are drawn at.
    If ''[ right | left ]'' is omitted, it defaults to ''text-emphasis-position/right''.
    The values have following meanings:</p>

  <dl>
    <dt><dfn value for="text-text-emphasis-position">over</dfn></dt>
      <dd>Draw marks over the text in horizontal <a>typographic modes</a>.</dd>
    <dt><dfn value for="text-text-emphasis-position">under</dfn></dt>
      <dd>Draw marks under the text in horizontal <a>typographic modes</a>.</dd>
    <dt><dfn value for="text-text-emphasis-position">right</dfn></dt>
      <dd>Draw marks to the right of the text in vertical <a>typographic modes</a>.</dd>
    <dt><dfn value for="text-text-emphasis-position">left</dfn></dt>
      <dd>Draw marks to the left of the text in vertical <a>typographic modes</a>.</dd>
  </dl>

  <p>Emphasis marks are drawn exactly as if each character was
    assigned the mark as its ruby annotation text with the ruby position
    given by 'text-emphasis-position' and the ruby alignment as centered.
    Note that this position may be adjusted if it would conflict
    with underline or overline decorations.

  <p>The effect of emphasis marks on the line height is the same as for
    ruby text.</p>

  <div class="note">
    <p>Note, the preferred position of emphasis marks depends on the
      language. In Japanese for example, the preferred position is
      ''over right''. In Chinese, on the other hand, the preferred
      position is ''under right''.
      The informative table below summarizes the preferred
      emphasis mark positions for Chinese and Japanese:</p>

    <table class="data">
      <caption>Preferred emphasis mark and ruby position</caption>
      <thead>
        <tr>
          <th scope="col" rowspan=2>Language
          <th scope="col" colspan=2>Preferred position
          <th scope="col" colspan=2 rowspan=2>Illustration
        <tr>
          <th>Horizontal
          <th>Vertical
      </thead>
      <tbody>
        <tr>
          <td scope="row">Japanese
          <td rowspan="3">over
          <td rowspan="3">right
          <td rowspan="3">
              <img alt="Emphasis marks appear over each emphasized character in horizontal Japanese text."
                  title="Emphasis (shown in blue for clarity) applied above a fragment of Japanese text"
                  src="images/text-emphasis-ja.gif" height="28" width="225">

          <td rowspan="4">
              <img alt="Emphasis marks appear on the right of each emphasized character in vertical Japanese text."
                  title="Emphasis applied on the right of a fragment of Japanese text"
                  src="images/text-emphasis-v.gif" height="89" width="34">
        <tr>
          <td scope="row">Korean
        <tr>
          <td scope="row">Mongolian
        <tr>
          <td scope="row">Chinese
          <td>under
          <td>right
          <td>
            <img alt="Emphasis marks appear below each emphasized character in horizontal Simplified Chinese text."
                  title="Emphasis (shown in blue for clarity) applied below a fragment of Chinese text"
                  src="images/text-emphasis-zh.gif" height="28" width="133">
      </tbody>
    </table>
  </div>

  <p>If emphasis marks are applied to characters
    for which ruby is drawn in the same position as the emphasis mark,
    the emphasis marks are placed outside the ruby.
    This includes <a href="https://www.w3.org/TR/css-ruby-1/#autohide">auto-hidden</a>
    and empty <a>ruby annotations</a>.

  <div class="figure">
    <p><img
      alt="In this example, emphasis marks are applied to 4 characters, two of which have ruby.
           The dots are placed above each character (aligned with the ruby) for the bare characters,
           and above the ruby text for the annotated characters."
      src="images/text-emphasis-ruby.png" width="134" height="50"></p>
    <p class="caption">Emphasis marks applied to 4 characters, with ruby also on 2 of them</p>
  </div>

  <div class="example">
    <p>Some editors prefer to hide emphasis marks when they conflict with ruby.
    In HTML, this can be done with the following style rule:
    <pre>ruby { text-emphasis: none; }</pre>
    <p>Some other editors prefer to hide ruby when they conflict with emphasis marks.
    In HTML, this can be done with the following pattern:
    <pre>em { text-emphasis: dot; } /* Set text-emphasis for &lt;em> elements */
<!--  -->em rt { display: none; }   /* Hide ruby inside &lt;em> elements */</pre>
  </div>

<h2 id="text-shadow-property">
Text Shadows: the 'text-shadow' property</h2>

  <pre class="propdef">
  Name: text-shadow
  Value: none | [ <<color>>? && <<length>>{2,3} ]#
  Initial: none
  Inherited: yes
  Computed value: any <<length>> made absolute; any specified color computed; otherwise as specified
  Animation type: <a href="https://www.w3.org/TR/css3-transitions/#animtype-shadow-list">shadow list</a>
  </pre>

  <p>This property accepts a comma-separated list of shadow effects to
    be applied to the text of the element. Values are interpreted as for
    'box-shadow'
    [[!CSS3BG]].
    (But note that spread values and the ''box-shadow/inset'' keyword are not allowed.)
    Each layer shadows the element's text and all its text decorations
    (composited together).
    If the color of the shadow is not specified,
    it defaults to ''currentColor'',
    i.e. the shadow’s color is taken from the element’s 'color' property.

  <p>The shadow effects are applied front-to-back: the first shadow is on
    top. The shadows may thus overlay each other, but they never overlay
    the text itself. The shadow must be painted at a stack level between
    the element's border and/or background, if present, and the elements
    text and text decoration. UAs should avoid painting text shadows over
    text in adjacent elements belonging to the same stack level and stacking
    context. (This may mean that the exact stack level of the shadows depends
    on whether the element has a border or background: the exact stacking
    behavior of text shadows is thus UA-defined.)
    It is undefined whether a given shadow layer shadows
    each glyph or decoration independently
    or if the text and/or decorations are flattened and then shadowed.

  <p>Unlike 'box-shadow', text shadows are not clipped to the shadowed
    shape and may show through if the text is partially-transparent.
    Like 'box-shadow', text shadows do not influence layout, and do not
    trigger scrolling or increase the size of the scrollable area.

  <p class="note">The painting order of shadows defined here is the opposite
    of that defined in the 1998
    <a href="https://www.w3.org/TR/1998/REC-CSS2-19980512">CSS2 Recommendation</a>.</p>

  <p>The ''text-shadow'' property applies to both the
    <code>::first-line</code> and <code>::first-letter</code>
    pseudo-elements.</p>

<h2 id="painting-order">
Painting Order of Text Decorations</h2>

  <p>
    As in [[!CSS2]], text decorations are drawn immediately over/under the text they decorate,
    in the following order (bottommost first):
  <ul>
    <li>shadows ('text-shadow')
    <li>underlines ('text-decoration')
    <li>overlines ('text-decoration')
    <li>text
    <li>emphasis marks ('text-emphasis')
    <li>line-through ('text-decoration')
  </ul>

  <p>
    Where line decorations are drawn across box decorations or atomic inlines,
    they are drawn over non-positioned content and just below any positioned descendants
    (immediately below layer #8 in CSS2.1 Appendix E).

<h2 class="no-num" id="acknowledgements">
  Appendix A: Acknowledgements</h2>

  <p>This specification would not have been possible without the help from:
    Ayman Aldahleh, Bert Bos, Tantek Çelik, Stephen Deach, John Daggett,
    Martin Dürst,
    Laurie Anna Edlund, Ben Errez, Yaniv Feinberg, Arye Gittelman, Ian
    Hickson, Martin Heijdra, Richard Ishida, Masayasu Ishikawa,
    Michael Jochimsen, Eric LeVine, Ambrose Li, Håkon Wium Lie, Chris Lilley,
    Ken Lunde, Nat McCully, Shinyu Murakami, Paul Nelson, Chris Pratley, Marcin Sawicki,
    Arnold Schrijver, Rahul Sonnad, Michel Suignard, Takao Suzuki,
    Frank Tang, Chris Thrasher, Etan Wexler, Chris Wilson, Masafumi Yabe
    and Steve Zilles.</p>

<h2 class="no-num" id="default-stylesheet">
Appendix B: Default UA Stylesheet</h2>

    <p>
      This appendix is informative,
      and is to help UA developers to implement default stylesheet,
      but UA developers are free to ignore or change.

    <div class="example">
      <pre><code class="css">
        /* typical styling of HTML */
        blink {
          text-decoration-line: blink;
        }
        s, strike, del {
          text-decoration: line-through;
        }
        u, ins, :link, :visited {
          text-decoration: underline;
        }
        abbr[title], acronym[title] {
          text-decoration: dotted underline;
        }

        /* disable inheritance of text-emphasis marks to ruby text:
          emphasis marks should only apply to base text */
        rt { text-emphasis: none; }

        /* set language-appropriate default emphasis mark position */
        :root:lang(zh), [lang|=zh] { text-emphasis-position: under right; }
        [lang|=ja], [lang|=ko]     { text-emphasis-position: over right; }

        /* set language-appropriate default underline position */
        :root:lang(ja), [lang|=ja],
        :root:lang(mn), [lang|=mn],
        :root:lang(ko), [lang|=ko] { text-underline-position: auto right; }
        :root:lang(zh), [lang|=zh] { text-underline-position: auto left;  }
        /* auto is used above instead of under due to content-compatibility concerns */
        [lang]:not([lang|=zh], [lang|=ja], [lang|=ko], [lang|=mn]) {
           text-underline-position: auto;
        }
      </code></pre>
    </div>

    <p class="issue">
      If you find any issues, recommendations to add, or corrections,
      please send the information to <a href="mailto:www-style@w3.org">www-style@w3.org</a>
      with <kbd>[css-text-decor]</kbd> in the subject line.

    <div class='example'>
      <p>
        While ''text-decoration-line: blink'' can't be fully reproduced with other existing properties,
        authors can achieve a very similar effect with the following CSS:

      <pre>
        @keyframes blink {
          0% {
            visibility: hidden;
            animation-timing-function: step-end;
          }
          25%, 100% {
            visibility: visible;
          }
        }
        blink {
          animation: blink 1s infinite;
        }</pre>
    </div>

<h2 class="no-num" id="changes">Appendix C:
Changes</h2>

  <h3 class="no-num" id="recent-changes">
  Changes since the <a href="https://www.w3.org/TR/2013/CR-css-text-decor-3-20130801/">August 2013 Candidate Recommendation</a></h3>

  <p>Significant changes include:</p>

  <ul>
    <li>Deferred <css>text-decoration-skip</css> to Level 4 to allow for major changes.
        Defined behavioral defaults in prose.
        (<a href="https://drafts.csswg.org/css-text-decor-3/issues-cr-2013#issue-1">Issue 1</a>,
         <a href="https://drafts.csswg.org/css-text-decor-3/issues-cr-2013#issue-22">Issue 22</a>,
         <a href="https://drafts.csswg.org/css-text-decor-3/issues-cr-2013#issue-26">Issue 26</a>)
    <li>Specified that line-throughs are unaffected by ink-skipping feature.
        (<a href="https://drafts.csswg.org/css-text-decor-3/issues-cr-2013#issue-24">Issue 24</a>)
    <li>Recommended that when ink is skipped, line endings conform to the glyph shape.
        (<a href="https://drafts.csswg.org/css-text-decor-3/issues-cr-2013#issue-30">Issue 30</a>)
    <li>Updated writing-mode&ndash;sensitive conditions to depend on <a>typographic mode</a>,
        to account for addition of ''sideways-lr'' and ''sideways-rl'' values to 'writing-mode' property.
        Marked orientation of emphasis marks under ''sideways-lr'' and ''sideways-rl'' undefined.
        (<a href="https://drafts.csswg.org/css-text-decor-3/issues-cr-2013#issue-10">Issue 10</a>, <a href="https://drafts.csswg.org/css-text-decor-3/issues-cr-2013#issue-20">Issue 20</a>)
    <li>Made ''[ right | left ]'' option of 'text-emphasis-position' optional,
        defaulting to ''text-emphasis-position/right''.
        (<a href="https://drafts.csswg.org/css-text-decor-3/issues-cr-2013#issue-17">Issue 17</a>)
    <li>Made 'text-underline-position' imply ''text-underline-position/auto''
        instead of ''text-underline-position/under''
        when only ''text-underline-position/left'' or ''text-underline-position/right'' is specified.
        (<a href="https://drafts.csswg.org/css-text-decor-3/issues-cr-2013#issue-18">Issue 18</a>)
    <li>Changed text decoration to skip leading and trailing spaces.
        (<a href="https://drafts.csswg.org/css-text-decor-3/issues-cr-2013#issue-6">Issue 6</a>)
    <li>Changed initial value of 'text-shadow' to be <code>currentColor</code>.
        (<a href="https://drafts.csswg.org/css-text-decor-3/issues-cr-2013#issue-28">Issue 28</a>)
    <li>Fixed “Computed value” line for 'text-shadow'.
        (<a href="https://drafts.csswg.org/css-text-decor-3/issues-cr-2013#issue-7">Issue 7</a>)
    <li>Various corrections to the default UA rules for 'text-emphasis-position' and 'text-underline-position'.
        (<a href="https://drafts.csswg.org/css-text-decor-3/issues-cr-2013#issue-11">Issue 11</a>, <a href="https://drafts.csswg.org/css-text-decor-3/issues-cr-2013#issue-18">Issue 18</a>, <a href="https://drafts.csswg.org/css-text-decor-3/issues-cr-2013#issue-19">Issue 19</a>, <a href="https://drafts.csswg.org/css-text-decor-3/issues-cr-2013#issue-36">Issue 36</a>)
    <li>Added rule to apply ''font-variant-east-asian/ruby'' to emphasis marks' font.
        (<a href="https://drafts.csswg.org/css-text-decor-3/issues-cr-2013#issue-13">Issue 13</a>)
    <li>Added the ''spelling-error'' and ''grammar-error'' values to 'text-decoration' (marked at risk).
  </ul>