-
Notifications
You must be signed in to change notification settings - Fork 657
/
Overview.bs
1117 lines (952 loc) · 47.4 KB
/
Overview.bs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<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/2018/CR-css-text-decor-3-20180703/
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/
Editor: Elika J. Etemad / fantasai, Apple, http://fantasai.inkedblade.net/contact, w3cid 35400
Editor: Koji Ishii, Google, kojiishi@gmail.com, w3cid 45369
Implementation Report: https://wpt.fyi/results/css/css-text-decor
Abstract: This module contains the features of CSS relating to text decoration, such as underlines, text shadows, and emphasis marks.
At Risk: The ability to place both emphasis marks and ruby on the same base text.
Link Defaults: css-color-3 (property) color
</pre>
<pre class="link-defaults">
spec:css-break-3; type:dfn; text:fragment
spec:css-display-3; type:property; text:display
</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 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>
This module replaces and extends the text-decorating
features defined in [[!CSS2]] chapter 16.
<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 & 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 <a href="https://www.w3.org/TR/css-text-3/#grapheme-cluster">character</a>,
<a href="https://www.w3.org/TR/css-text-3/#letter">letter</a>, and
<a href="https://www.w3.org/TR/css-text-3/#content-language">content language</a>
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>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.
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 this level, 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.
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.
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">
<img title="Skipping Descenders When Drawing an Underline"
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
</div>
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">
<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>
Relatively positioning a descendant moves all text decorations
applied to it along with the descendant's text; it does not affect
calculation of the decoration's initial position on that line.
The 'visibility' property, 'text-shadow', filters, and other graphical transformations
likewise also affect all text decorations applied to that box--
including decorations propagated from an ancestor box--
and do not affect the calculation of their initial positions or thicknesses.
(In the case of line decorations drawn over an atomic inline
or across the margins/borders/padding of a non-replaced inline box,
they are analogously associated with the affected atomic inline / non-replaced inline box
rather than with the [=decorating box=].)
<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>
<blockquote>
<p>
<span>
Help, help!
<em> I am under a hat! </em>
<cite> —GwieF </cite>
</span>
</p>
</blockquote>
</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><em>text</em></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>
<div>Help, help! <span>I am under a hat!</span></div>
</pre>
...the <div> is the [=decorating box=] for its underline (in black),
which is rendered uninterrupted through both the <div> and the <span>.
Unlike line decorations, however,
`text-shadow` is inherited as a property;
therefore the green text shadow on the <span>
overrides the blue text shadow on the <div>.
As a result, when the shadows are painted,
the shadow of the <div>’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 ]
Initial: none
Inherited: no (but see prose, above)
Computed value: specified keyword(s)
Animation type: discrete
</pre>
Specifies what line decorations, if any, are added to the element.
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 [[CSS-ANIMATIONS-1]].
</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.
<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
Computed value: specified keyword
Animation type: discrete
</pre>
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/css-backgrounds-3/#the-border-style">border-style
properties</a> [[!CSS-BACKGROUNDS-3]]. ''wavy'' indicates a wavy line.
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: computed color
Animation type: by computed value type
</pre>
This property specifies the color of text decoration (underlines
overlines, and line-throughs) set on the element with
'text-decoration-line'.
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>
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.
Note: 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.
<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 | [ under || [ left | right ] ]
Initial: auto
Inherited: yes
Computed value: specified keyword(s)
Animation type: discrete
</pre>
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">
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>
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 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>
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 [=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><u>A<sup>B</sup><big>C</big>D</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.
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">
<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>
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.
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>
East Asian documents traditionally use small symbols next to each glyph to emphasize
a run of text. For example:
<div class="figure">
<img alt="Example of emphasis in Japanese appearing over the text"
src="images/text-emphasis-ja.png" height="39" width="208">
<p class="caption">Accent emphasis (shown in blue for clarity) applied to Japanese text
</div>
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
Applies to: text
Inherited: yes
Computed value: the keyword ''text-emphasis-style/none'', a pair of keywords representing the shape and fill, or a string
Animation type: discrete
</pre>
This property applies emphasis marks to the element's text.
Values have the following meanings:
<dl dfn-type=value dfn-for=text-emphasis-style>
<dt><dfn>none</dfn>
<dd>No emphasis marks.
<dt><dfn>filled</dfn>
<dd>The shape is filled with solid color.
<dt><dfn value for="text-text-emphasis">open</dfn>
<dd>The shape is hollow.
<dt><dfn>dot</dfn>
<dd>Display small circles as marks.
The filled dot is U+2022 '•', and the open dot is U+25E6 '◦'.
<dt><dfn>circle</dfn>
<dd>Display large circles as marks.
The filled circle is U+25CF '●', and the open circle is U+25CB '○'.
<dt><dfn>double-circle</dfn>
<dd>Display double circles as marks.
The filled double-circle is U+25C9 '◉', and the open double-circle is U+25CE '◎'.
<dt><dfn>triangle</dfn>
<dd>Display triangles as marks.
The filled triangle is U+25B2 '▲', and the open triangle is U+25B3 '△'.
<dt><dfn>sesame</dfn>
<dd>Display sesames as marks.
The filled sesame is U+FE45 '﹅', and the open sesame is U+FE46 '﹆'.
<dt><dfn><<string>></dfn>
<dd>Display the given string as marks.
Authors should not specify more than one [=character=] in <string>.
The UA may truncate or ignore strings consisting of more than one grapheme cluster.
</dl>
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>.
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).
Note: One example of good fonts for emphasis marks is Adobe's open source
<a href="https://github.com/adobe-fonts/kenten-generic">Kenten Generic OpenType Font</a>,
which is specially designed for the emphasis marks.
The marks are drawn once for each <a>typographic character unit</a>.
However, emphasis marks are <em>not</em> drawn for:
<ul>
<li><a href="https://www.w3.org/TR/css-text-3/#word-separator">Word separators</a>
or other <a>characters</a> 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>Punctuation--specifically,
any <a>characters</a> that belong to the
Unicode P* <a>general category</a> and
do not <code>NFKD</code> normalize [[!UAX15]] to
any of the following symbols:
<table class="data">
<tr><td># <td>U+0023 <td>NUMBER SIGN
<tr><td>% <td>U+0025 <td>PERCENT SIGN
<tr><td>‰ <td>U+2030 <td>PER MILLE SIGN
<tr><td>‱ <td>U+2031 <td>PER TEN THOUSAND SIGN
<tr><td>٪ <td>U+066A <td>ARABIC PERCENT SIGN
<tr><td>؉ <td>U+0609 <td>ARABIC-INDIC PER MILLE SIGN
<tr><td>؊ <td>U+060A <td>ARABIC-INDIC PER TEN THOUSAND SIGN
<tr><td>& <td>U+0026 <td>AMPERSAND
<tr><td>⁊ <td>U+204A <td>TIRONIAN SIGN ET
<tr><td>@ <td>U+0040 <td>COMMERCIAL AT
<tr><td>§ <td>U+00A7 <td>SECTION SIGN
<tr><td>¶ <td>U+00B6 <td>PILCROW SIGN
<tr><td>⁋ <td>U+204B <td>REVERSED PILCROW SIGN
<tr><td>⁓ <td>U+2053 <td>SWUNG DASH
<tr><td>〽️ <td>U+303D <td>PART ALTERNATION MARK
</table>
<li>Characters belonging to the Unicode classes for control codes
and unassigned characters (Cc, Cf, Cn).
</ul>
Note: Control over which characters are marked will be added in Level 4.
(The list of punctuation may also be further refined,
particularly for non-CJK punctuation.)
<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
Applies to: text
Inherited: yes
Computed value: computed color
Animation type: by computed value type
</pre>
This property specifies the foreground color of the emphasis marks.
Note: ''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>
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 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.
<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
Applies to: text
Inherited: yes
Computed value: specified keyword(s)
Animation type: discrete
</pre>
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:
<dl dfn-type=value dfn-for=text-emphasis-position>
<dt><dfn>over</dfn>
<dd>Draw marks over the text in horizontal <a>typographic modes</a>.
<dt><dfn>under</dfn>
<dd>Draw marks under the text in horizontal <a>typographic modes</a>.
<dt><dfn>right</dfn>
<dd>Draw marks to the right of the text in vertical <a>typographic modes</a>.
<dt><dfn>left</dfn>
<dd>Draw marks to the left of the text in vertical <a>typographic modes</a>.
</dl>
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.
The effect of emphasis marks on the line height is the same as for
ruby text.
<div class="note">
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:
<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>
<th 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.png" height="39" width="209">
<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="79" width="34">
<tr>
<th scope="row">Korean
<tr>
<th scope="row">Mongolian
<tr>
<th 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.png" height="39" width="140">
</tbody>
</table>
</div>
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">
<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 class="caption">Emphasis marks applied to 4 characters, with ruby also on 2 of them
</div>
<div class="example">
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>
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 <em> elements */
em rt { display: none; } /* Hide ruby inside <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
Applies to: text
Inherited: yes
Computed value: either the keyword ''box-shadow/none'' or
a list, each item consisting of three absolute lengths
plus a computed color
Animation type: <a href="https://www.w3.org/TR/web-animations-1/#animating-shadow-lists">as shadow list</a>
</pre>
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' [[!CSS-BACKGROUNDS-3]].
(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).
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.
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 <a>scrollable overflow area</a>.
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>.
The ''text-shadow'' property applies to both the
<code>::first-line</code> and <code>::first-letter</code>
pseudo-elements.
<h2 id="painting">
Painting Text Decorations</h2>
<h3 id="painting-order">
Painting Order of Text Decorations</h3>
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>
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).
<h3 id="overflow">
Overflow of Text Decorations</h3>
Text decorations that leak outside a <a>box</a>
are considered <a>ink overflow</a>:
they do not extend the <a>scrollable overflow area</a>.
[[css-overflow-3]]
<h2 class="no-num" id="acknowledgements">
Appendix A: Acknowledgements</h2>
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.
<h2 class="no-num" id="default-stylesheet">
Appendix B: Default UA Stylesheet</h2>
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: right; }
:root:lang(zh), [lang|=zh] { text-underline-position: left; }
/* auto is chosen (implied) above instead of under
due to content-compatibility concerns */
</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>