8000 csswg-drafts/css-text-decor/Overview.bs at 91f2ea7b5f0d53ef07e8450420e2cf556e2b0155 · w3c/csswg-drafts · GitHub
Skip to content

Overview.bs

Latest commit

 

History

History
1239 lines (1105 loc) · 49.9 KB

Overview.bs

File metadata and controls

1239 lines (1105 loc) · 49.9 KB
<h1>CSS Text Decoration Module Level 3</h1>
<pre class='metadata'>
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: <a href="http://www.w3.org/Style/CSS/Tracker/products/10">http://www.w3.org/Style/CSS/Tracker/products/10</a>
Editor: Elika J. Etemad / fantasai, Invited Expert, http://fantasai.inkedblade.net/contact
Editor: Koji Ishii, Google, kojiishi@gmail.com
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.
Link Defaults: css-color-3 (property) color
</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 [[!CSS21]] chapter 16.
<h3 id="values">
Values</h3>
<p>This specification follows the
<a href="https://www.w3.org/TR/CSS21/about.html#property-defs">CSS property
definition conventions</a> from [[!CSS21]]. Value types not defined in
this specification are defined in CSS Level 2 Revision 1 [[!CSS21]].
Other CSS modules may expand the definitions of these value types: for
example [[CSS3COLOR]], when combined with this module, expands the
definition of the &lt;color&gt; value type as used in this specification.</p>
<p>In addition to the property-specific values listed in their definitions,
all properties defined in this specification also accept the
<a href="https://www.w3.org/TR/CSS21/cascade.html#value-def-inherit">inherit</a>
keyword as their property value. For readability it has 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 [[!CSS21]] and [[!CSS3-WRITING-MODES]].
<h2 id="line-decoration">
Line Decoration: Underline, Overline, and Strike-Through</h2 93CD >
<p>
The following properties describe line decorations that are added to the content of an element.
When specified on or propagated to an inline box,
that box becomes a <dfn>decorating box</dfn> for that decoration,
applying the decoration to all its fragments.
The decoration is then further propagated to any in-flow block-level 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 block container that establishes an inline formatting context,
the decorations are propagated to an anonymous inline box that wraps all the in-flow inline-level children of the block container.
When specified on or propagated to a ruby box,
the decorations are propagated only to the ruby base.
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>
By default underlines, overlines, and line-throughs are applied only to non-replaced inline boxes,
and are drawn across all text (including white space, letter spacing, and word spacing).
Atomic inlines, such as images, are not decorated.
The 'text-decoration-skip' property can be used to modify this behavior,
for example allowing atomic inlines to be underlined
or requiring that white space be skipped.
Margins, borders, and padding of the <i>decorating box</i> are always skipped.
<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="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>
<h3 id="text-decoration-line-property">
Text Decoration Lines: the 'text-decoration-line' property</h3>
<table class="propdef">
<tr>
<th>Name:
<td><dfn>text-decoration-line</dfn>
<tr>
<th><a href="#values">Value</a>:
<td>none | [ underline || overline || line-through || blink ]
<tr>
<th>Initial:
<td>none
<tr>
<th>Applies to:
<td>all elements
<tr>
<th>Inherited:
<td>no (but see prose)
<tr>
<th>Percentages:
<td>N/A
<tr>
<th>Media:
<td>visual
<tr>
<th>Computed&#160;value:
<td>as specified
<tr>
<th>Animatable:
<td>no
</table>
<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]].
</dl>
<h3 id="text-decoration-color-property">
Text Decoration Color: the 'text-decoration-color' property</h3>
<table class="propdef">
<tr>
<th>Name:
<td><dfn>text-decoration-color</dfn>
<tr>
<th><a href="#values">Value</a>:
<td><a href="https://www.w3.org/TR/css3-color/#color0"><span class="value-inst-color">&lt;color&gt;</span></a>
<tr>
<th>Initial:
<td><a href="https://www.w3.org/TR/css3-color/#currentcolor">currentColor</a>
<tr>
<th>Applies to:
<td>all elements
<tr>
<th>Inherited:
<td>no
<tr>
<th>Percentages:
<td>N/A
<tr>
<th>Media:
<td>visual
<tr>
<th>Computed&#160;value:
<td>the computed color
<tr>
<th>Animatable:
<td>as <a href="https://www.w3.org/TR/css3-transitions/#animtype-color">color</a>
</table>
<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-style-property">
Text Decoration Style: the 'text-decoration-style' property</h3>
<table class="propdef">
<tr>
<th>Name:
<td><dfn>text-decoration-style</dfn>
<tr>
<th><a href="#values">Value</a>:
<td>solid | double | dotted | dashed | wavy
<tr>
<th>Initial:
<td>solid
<tr>
<th>Applies to:
<td>all elements
<tr>
<th>Inherited:
<td>no
<tr>
<th>Percentages:
<td>N/A
<tr>
<th>Media:
<td>visual
<tr>
<th>Computed&#160;value:
<td>as specified
<tr>
<th>Animatable:
<td>no
</table>
<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-property">
Text Decoration Shorthand: the 'text-decoration' property</h3>
<table class="propdef">
<tr>
<th>Name:
<td><dfn>text-decoration</dfn>
<tr>
<th><a href="#values">Value</a>:
<td><var><<'text-decoration-line'>></var> ||
<var><<'text-decoration-style'>></var> ||
<var><<'text-decoration-color'>></var>
<tr>
<th>Initial:
<td>none
<tr>
<th>Applies to:
<td>all elements
<tr>
<th>Inherited:
<td>no
<tr>
<th>Percentages:
<td>N/A
<tr>
<th>Media:
<td>visual
<tr>
<th>Computed&#160;value:
<td>see individual properties
<tr>
<th>Animatable:
<td>see individual properties
</table>
<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>
<h3 id="text-decoration-skip-property">
Text Decoration Line Continuity: the 'text-decoration-skip' property</h3>
<table class="propdef">
<tr>
<th>Name:
<td><dfn>text-decoration-skip</dfn>
<tr>
<th><a href="#values">Value</a>:
<td>none | [ objects || spaces || ink || edges || box-decoration ]
<tr>
<th>Initial:
<td>objects
<tr>
<th>Applies to:
<td>all elements
<tr>
<th>Inherited:
<td>yes
<tr>
<th>Percentages:
<td>N/A
<tr>
<th>Media:
<td>visual
<tr>
<th>Computed&#160;value:
<td>as specified
<tr>
<th>Animatable:
<td>no
</table>
Note: Level 4 of this specification
defines additional values (''leading-spaces'' and ''trailing-spaces''),
and uses them in the initial value of this property.
At the time of writing,
this is experimental and may still change,
which is why it has not been incorporated into this level.
<p>This property specifies what parts of the element's content
any text decoration affecting the element must skip over. It
controls all text decoration lines drawn by the element
and also any text decoration lines drawn by its ancestors.
Values have the following meanings:</p>
<dl>
<dt><dfn value for="text-decoration-skip">none</dfn></dt>
<dd>Skip nothing: text-decoration is drawn for all text content
and across atomic inline-level boxes.</dd>
<dt><dfn value for="text-decoration-skip">objects</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 value for="text-decoration-skip">spaces</dfn></dt>
<dd>Skip all spacing, i.e. all <i>characters</i> with the Unicode White_Space property [[UAX44]]
and all <a href="https://www.w3.org/TR/css3-text/#word-separator">word separators</a>,
plus any adjacent 'letter-spacing' or 'word-spacing'.
<dt><dfn value for="text-decoration-skip">ink</dfn></dt>
<dd>Skip over where glyphs are drawn:
interrupt the decoration line to let the shape of the text show through
where the text decoration would otherwise cross over a glyph.
The UA must skip a small distance to either side of the glyph outline.
<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="decoration-skip-ink.png"
>
<p class="caption">''text-decoration-skip: ink''</p>
</div>
<dt><dfn value for="text-decoration-skip">edges</dfn></dt>
<dd>The UA should place the start and end of the line inwards slightly
(e.g. by half a line thickness)
from the content edge of the <i>decorating box</i> so that,
e.g. two underlined elements side-by-side 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: edges"
alt="An underline below a series of Chinese characters has a gap between two adjacent underlining elements."
src="decoration-skip-edges.png"
>
<p class="caption">''text-decoration-skip: edges'' for <code>&lt;u>石井&lt;/u>&lt;u>艾俐俐&lt;/u></code>
</p>
</div>
<dt><dfn value for="text-decoration-skip">box-decoration</dfn>
<dd>
Skip over the box's margin, border, and padding areas.
Note that this only has an effect on decorations imposed by an ancestor;
a <i>decorating box</i> never draws over its own box decoration.
</dl>
<p class="note">Note that this property inherits and that descendant
elements can have a different setting.</p>
<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.
<h3 id="text-underline-position-property">
Text Underline Position: the 'text-underline-position' property</h3>
<table class="propdef">
<tr>
<th>Name:
<td><dfn>text-underline-position</dfn>
<tr>
<th><a href="#values">Value</a>:
<td>auto | [ under || [ left | right ] ]
<tr>
<th>Initial:
<td>auto
<tr>
<th>Applies to:
<td>all elements
<tr>
<th>Inherited:
<td>yes
<tr>
<th>Percentages:
<td>N/A
<tr>
<th>Media:
<td>visual
<tr>
<th>Computed&#160;value:
<td>as specified
<tr>
<th>Animatable:
<td>no
</table>
<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/under'' 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="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 writing modes.
<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="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>
<dt><dfn id="underline-left" value for="text-underline-position">left</dfn></dt>
<dd>In vertical writing modes, 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 writing modes, 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="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="underline-position-right.png"
>
<tr>
<td>''text-underline-position/left''
<td>''text-underline-position/right''
</table>
<p class="caption">In vertical writing modes, 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 writing modes, 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="underline-single.png"
alt="A single underline drawn under varying font sizes and vertical positions must be a single line.">
vs.
<img src="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 to the central baseline by default)
an underline will cut through descendant text of a larger font-size.
<div class="figure">
<p><img src="leftline-cross.png" alt="">
</div>
</div>
<p>UAs <em>must</em> adjust line positions to match the shifted metrics of <i>decorating boxes</i> positioned with 'vertical-align' [[!CSS21]]
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="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' 1337 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="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="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 ''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="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>
<table class="propdef">
<tr>
<th>Name:
<td><dfn>text-emphasis-style</dfn>
<tr>
<th><a href="#values">Value</a>:
<td>none |
[ [ filled | open ] || [ dot | circle | double-circle | triangle | sesame ] ] |
<a class="noxref" href="https://www.w3.org/TR/CSS21/syndata.html#value-def-string"><span class="value-inst-string">&lt;string&gt;</span></a>
<tr>
<th>Initial:
<td>none
<tr>
<th>Applies to:
<td>all elements
<tr>
<th>Inherited:
<td>yes
<tr>
<th>Percentages:
<td>N/A
<tr>
<th>Media:
<td>visual
<tr>
<th>Computed&#160;value:
<td>''text-emphasis-style/none'', a pair of keywords representing the shape and fill, or
a string
<tr>
<th>Animatable:
<td>no
</table>
<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"><var>&lt;string&gt;</var></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 writing mode and
''sesame'' in vertical writing mode.</p>
<p>The marks should be drawn using the element's font settings with its
size scaled down to 50%. However, 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 writing modes: like CJK
characters, they do not rotate to match the writing mode.</p>
<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 <i>character</i>. However,
emphasis marks are not drawn for characters that are:</p>
<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>
<table class="propdef">
<tr>
<th>Name:
<td><dfn>text-emphasis-color</dfn>
<tr>
<th><a href="#values">Value</a>:
<td>&lt;color&gt;
<tr>
<th>Initial:
<td><a href="https://www.w3.org/TR/css3-color/#currentcolor">currentColor</a>
<tr>
<th>Applies to:
<td>all elements
<tr>
<th>Inherited:
<td>yes
<tr>
<th>Percentages:
<td>N/A
<tr>
<th>Media:
<td>visual
<tr>
<th>Computed&#160;value:
<td>as specified
<tr>
<th>Animatable:
<td>as <a href="https://www.w3.org/TR/css3-transitions/#animtype-color">color</a>
</table>
<p>This property specifies the foreground color of the emphasis marks.</p>
<p class="note">
The <dfn value for=text-emphasis-color>currentcolor</dfn> 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>
<table class="propdef">
<tr>
<th>Name:
<td><dfn>text-emphasis</dfn>
<tr>
<th><a href="#values">Value</a>:
<td><<'text-emphasis-style'>> || <<'text-emphasis-color'>>
<tr>
<th>Initial:
<td>see individual properties
<tr>
<th>Applies to:
<td>all elements
<tr>
<th>Inherited:
<td>yes
<tr>
<th>Percentages:
<td>N/A
<tr>
<th>Media:
<td>visual
<tr>
<th>Computed&#160;value:
<td>see individual properties
<tr>
<th>Animatable:
<td>see individual properties
</table>
<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>
<table class="propdef">
<tr>
<th>Name:
<td><dfn>text-emphasis-position</dfn>
<tr>
<th><a href="#values">Value</a>:
<td>[ over | under ] && [ right | left ]
<tr>
<th>Initial:
<td>over right
<tr>
<th>Applies to:
<td>all elements
<tr>
<th>Inherited:
<td>yes
<tr>
<th>Percentages:
<td>N/A
<tr>
<th>Media:
<td>visual
<tr>
<th>Computed&#160;value:
<td>as specified
<tr>
<th>Animatable:
<td>no
</table>
<p>This property describes where emphasis marks are drawn at.
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 writing mode.</dd>
<dt><dfn value for="text-text-emphasis-position">under</dfn></dt>
<dd>Draw marks under the text in horizontal writing mode.</dd>
<dt><dfn value for="text-text-emphasis-position">right</dfn></dt>
<dd>Draw marks to the right of the text in vertical writing mode.</dd>
<dt><dfn value for="text-text-emphasis-position">left</dfn></dt>
<dd>Draw marks to the left of the text in vertical writing mode.</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.
<p>The effect of emphasis marks on the line height is the same as for
ruby text.</p>
<div class="note">
View remainder of file in raw view