-
Notifications
You must be signed in to change notification settings - Fork 709
/
Copy pathOverview.bs
2133 lines (1831 loc) · 85.8 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 4
Shortname: css-text-decor
Level: 4
Status: ED
Work Status: Exploring
Group: csswg
ED: https://drafts.csswg.org/css-text-decor-4/
TR: https://www.w3.org/TR/css-text-decor-4/
Previous Version: https://www.w3.org/TR/2020/WD-css-text-decor-4-20200506/
Issue Tracking: Tracker http://www.w3.org/Style/CSS/Tracker/products/10
Editor: Elika J. Etemad / fantasai, 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.
Link Defaults: css-color-3 (property) color, css-break-3 (dfn) fragment
</pre>
<pre class="link-defaults">
spec:css-text-3; type:dfn; text:character
spec:fill-stroke-3; type:property;
text: fill
text: stroke
</pre>
<h2 id="intro">
Introduction</h2>
<em>This subsection is non-normative.</em>
This module covers text decoration, i.e. decorating the glyphs
of the text once typeset according to font and typographic rules.
(See [[CSS-TEXT-3]] and [[CSS-FONTS-3]].)
Such features are traditionally used not only for purely decorative purposes,
but also in some cases to show emphasis, for honorifics,
and to indicate editorial changes such as insertions, deletions, and misspellings.
CSS Levels 1 and 2 only defined very basic <a href="#line-decoration">line decorations</a>
(underlines, overlines, and strike-throughs)
appropriate to Western typographical traditions.
Level 3 of this module added the ability to change
the color, style, position, and continuity of these decorations,
and also introduced
<a href="#emphasis-marks">emphasis marks</a> (traditionally used in East Asian typography),
and <a href="#text-shadow-property">shadows</a> (which were proposed then deferred from Level 2).
Level 4 introduces additional controls over these decorations.
<h3 id="placement">
Module Interactions</h3>
This module replaces and extends the text-decorating
features defined in [[CSS-TEXT-DECOR-3]].
All of the properties in this module
can be applied to the ''::first-line'' and ''::first-letter'' [=pseudo-elements=].
<h3 id="values">
Value Definitions</h3>
This specification follows the <a href="https://www.w3.org/TR/CSS2/about.html#property-defs">CSS property definition conventions</a> from [[!CSS2]]
using the <a href="https://www.w3.org/TR/css-values-3/#value-defs">value definition syntax</a> from [[!CSS-VALUES-3]].
Value types not defined in this specification are defined in CSS Values & Units [[!CSS-VALUES-3]].
Combination with other CSS modules may expand the definitions of these value types.
In addition to the property-specific values listed in their definitions,
all properties defined in this specification
also accept the <a>CSS-wide keywords</a> as their property value.
For readability they have not been repeated explicitly.
<h3 id="terms">Terminology</h3>
The terms [=typographic character unit=] (<dfn>character</dfn>),
[=typographic letter unit=] ([=letter=]),
and [=content language=]
as used in this specification are defined in [[!CSS-TEXT-3]].
Other terminology and concepts used in this specification are defined
in [[!CSS2]] and [[!CSS-WRITING-MODES-4]].
<h2 id="line-decoration">
Line Decoration: Underline, Overline, and Strike-Through</h2>
The following properties describe line decorations that are added to the content of an element.
When specified on or propagated to an <a>inline box</a>,
that <a>box</a> becomes a <dfn>decorating box</dfn> for that decoration,
applying the decoration to all its <a>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 Level 3 and beyond, by default
only the margins, borders, and padding of the [=decorating box=]
are skipped.
In the future CSS2.1 may be updated to match this new default.
[=Relatively positioning=] a descendant moves all text decorations
applied to it along with the descendant's text; it does not affect
calculation of the decoration's initial position on that line.
The 'visibility' property, 'text-shadow', filters, and other graphical transformations
likewise 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 [=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>
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)
Computed value: specified keyword(s)
Animation type: discrete
</pre>
This property,
which is a <a>sub-property</a> of the 'text-decoration' shorthand,
specifies what line decorations, if any, are added by the element.
Values other than ''text-decoration-line''
cause the element to originate the indicated text decorations,
and to apply and propagate it as described [[#line-decoration|above]].
Note: Unless it is desired for the color, style, and thickness of the lines
to be set by declarations lower in the [=cascade=],
it is safer to use the 'text-decoration' [=shorthand=]
instead of this [=longhand=].
Values have the following meanings:
<dl dfn-type=value dfn-for=text-decoration-line>
<dt><dfn>none</dfn>
<dd>
Neither produces nor inhibits text decoration.
<dt><dfn>underline</dfn>
<dd>
Each line of text is underlined.
<dt><dfn>overline</dfn>
<dd>
Each line of text has a line over it
(i.e. on the opposite side from an underline).
<dt><dfn>line-through</dfn>
<dd>
Each line of text has a line through the middle.
<dt><dfn>blink</dfn>
<dd>
The text blinks (alternates between visible and invisible).
Conforming user agents may simply not blink the text.
Note that not blinking the text is one technique to satisfy
<a href="https://www.w3.org/TR/UAAG/guidelines.html#tech-on-off-blinking-text">checkpoint 3.3 of WAI-UAAG</a>.
This value is <strong>deprecated</strong>
in favor of Animations [[CSS3-ANIMATIONS]].
<dt><dfn>spelling-error</dfn>
<dd>
This value indicates the type of text decoration
used by the User Agent to highlight spelling mistakes.
Its appearance is UA-defined,
and may be platform-dependent.
<span class=note>It is often rendered as a red wavy underline.</span>
<dt><dfn>grammar-error</dfn>
<dd>
This value indicates the type of text decoration
used by the User Agent to highlight grammar mistakes.
Its appearance is UA defined,
and may be platform-dependent.
<span class=note>It is often rendered as a green wavy underline.</span>
</dl>
Note: In <a>vertical writing modes</a>,
'text-underline-position' can cause the underline and overline to switch sides.
This allows the position of underlines to key off of language-specific preferences
automatically.
Since ''spelling-error'' and ''grammar-error'' decorations are entirely UA-defined,
the UA <em>may</em> disregard
the other <a>sub-properties</a> of 'text-decoration',
as well any other properties typically affecting the appearance of line decorations
(such as 'text-underline-position', 'color', 'stroke', or 'fill')
when rendering these decorations.
However,
to the extent that honoring any of these properties
would be meaningful and practical
given the UA's chosen rendering,
the UA <em>should</em> apply them
as modifications to its default styling.
<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,
which is a <a>sub-property</a> of the 'text-decoration' shorthand,
sets the line-drawing style of underlines, overlines, and line-throughs
specified on the element with 'text-decoration-line',
and affects all decorations originating from this element
even if descendant boxes specify a different style.
Values have the same meaning as for the
<a href="https://www.w3.org/TR/css-backgrounds-3/#the-border-style">border-style properties</a> [[!CSS-BACKGROUNDS-3]].
<dfn value for=text-decoration-style>wavy</dfn> indicates a wavy line.
<h3 id="text-decoration-color-property">
Text Decoration Color: the 'text-decoration-color' property</h3>
<pre class="propdef">
Name: text-decoration-color
Value: <<color>>
Initial: currentcolor
Inherited: no
Computed value: computed color
Animation type: by computed value type
</pre>
This property,
which is a <a>sub-property</a> of the 'text-decoration' shorthand,
sets the color of underlines, overlines, and line-throughs
specified on the element with 'text-decoration-line',
and affects all decorations originating from this element
even if descendant boxes specify a different color.
<h3 id="text-decoration-width-property">
Text Decoration Line Thickness: the 'text-decoration-thickness' property</h3>
<pre class="propdef">
Name: text-decoration-thickness
Value: auto | from-font | <<length>> | <<percentage>>
Initial: auto
Applies to: all elements
Inherited: no
Percentages: N/A
Computed value: specified keyword or absolute length
Animation type: by computed value
</pre>
This property,
which is a <a>sub-property</a> of the 'text-decoration' shorthand,
sets the stroke thickness of underlines, overlines, and line-throughs
specified on the element with 'text-decoration-line',
and affects all decorations originating from this element
even if descendant boxes specify a different thickness.
Values have the following meanings:
<dl dfn-for=text-decoration-thickness dfn-type=value>
<dt><dfn>auto</dfn>
<dd>
The UA chooses an appropriate thickness for text decoration lines;
see below.
<dt><dfn>from-font</dfn>
<dd>
If the <a>first available font</a> has
metrics indicating a preferred underline width,
use that width,
otherwise behaves as ''text-decoration-thickness/auto''.
<dt><dfn><<length>></dfn>
<dd>
Specifies the thickness of text decoration lines as a fixed length.
The UA must floor the actual value at one device pixel.
Note: A length will inherit as a fixed value,
and will not scale with the font.
<dt><dfn><<percentage>>
<dd>
<p>Specifies the thickness of text decoration lines as a percentage of ''1em''.
The UA must floor the actual value at one device pixel.
Note: A percentage will inherit as a relative value,
and will therefore scale with changes in the font as it inherits.
</dl>
<h4 id="text-decoration-thickness">
Automatic Thickness of Text Decoration Lines</h4>
Some font formats (such as OpenType) can offer information
about the appropriate thickness of a line decoration.
The UA should use such font-based information
when choosing ''text-decoration-thickness/auto'' line thicknesses
wherever appropriate.
<h3 id="line-position">
Determining the Position and Thickness of Line Decorations</h3>
Issue: This section is copied over from early drafts of Text Decoration Level 3.
It is still under review, and needs integration with 'text-underline-offset' and 'text-decoration-thickness'.
Since line decorations can span elements with varying font sizes and
vertical alignments, the best position for a line decoration is not
necessarily the ideal position dictated by the <a>decorating box</a>.
Instead, it's calculated, per line, from all text decorated by the <a>decorating box</a> on that line,
the <dfn>considered text</dfn>.
However, descendants of the <a>decorating box</a>
that are skipped due to 'text-decoration-skip',
descendant inlines with ''text-decoration-skip: ink'',
and any descendants that do not participate in the <a>decorating box</a>’s inline formatting context
are excluded from the set of <a>considered text</a>.
The line decoration positions are then calculated
per line
as follows
(treating <a>over</a>-positioned underlines</a> as <a>over</a> lines
and <a>under</a>-positioned overlines</a> as <a>under</a> lines):
<dl>
<dt><a>over</a> lines
<dd>
Align the line decoration with respect to the highest
<a>over</a> EM-box edge
of the <a>considered text</a>.
<dt><a>alphabetic</a> underlines
<dd>
The alphabetic underline position is calculated by taking
the ideal offset (from the alphabetic baseline) of each run of <a>considered text</a>,
averaging those, and then using the lowest alphabetic baseline to actually position the line.
(Alphabetic baselines can differ between ''vertical-align/baseline''-aligned boxes
if the dominant baseline is non-alphabetic.)
To prevent superscripts and subscripts from throwing this position off-kilter,
an inline with a non-initial computed 'vertical-align'
is treated as having the ideal underline position of its parent.
<dt>non-alphabetic <a>under</a> lines
<dd>
Position the line decoration with respect to the lowest
<a>under</a> EM-box edge
of the <a>considered text</a>.
<dt>line-throughs
<dd>
Line-throughs essentially use the same sort of averaging as for alphabetic underlines,
but recompute the position when drawing across a descendant with a different computed 'font-size'.
(This ensures that the text remains effectively “crossed out” despite any font size changes.)
For each run of <a>considered text</a> with the same 'font-size',
compute an ideal position averaged from its font metrics.
To prevent superscripts and subscripts from throwing this position off-kilter,
an inline with a non-initial computed 'vertical-align'
is treated as having the ideal underline position of its parent.
Position the portion of the line across each decorated fragment at that position.
<p class='issue'>
For simplicity, line-throughs should draw over each element at that element's preferred/averaged position.
This can produce some undesirable jumpiness,
but there doesn't appear to be any way to avoid that which is correct in all instances,
and all attempts are worryingly complex.
What position should line-throughts adopt over elements that have a different font-size,
but no <a>considered text</a>?
</dl>
CSS does not define the thickness of line decorations.
In determining the thickness of text decoration lines,
user agents may consider the font sizes, faces, and weights of descendants
to provide an appropriately averaged thickness.
<div class="example">
The following figure shows the averaging for underline:
<p><img alt="In the first rendering of the underlined text '1st a'
with 'st' as a superscript, both the '1st' and the 'a'
are rendered in a small font. In the second rendering,
the 'a' is rendered in a larger font. In the third, both
'1st' and 'a' are large."
height="105" src="images/underline-averaging.gif" width="326">
In the three fragments of underlined text, the underline is drawn
consecutively lower and thicker as the ratio of large text to small
text increases.</p>
Using the same example, a line-through would in the second fragment,
instead of averaging the two font sizes,
split the line-through into two segments:
<p><img alt="" src="images/linethrough-averaging.gif">
In both cases, however, the superscript, due to the vertical-alignment shift,
has no effect on the position of the line.
</div>
<h3 id="text-decoration-property">
Text Decoration Shorthand: the 'text-decoration' property</h3>
<pre class="propdef shorthand">
Name: text-decoration
Value: <<'text-decoration-line'>> || <<'text-decoration-thickness'>> || <<'text-decoration-style'>> || <<'text-decoration-color'>>
</pre>
This property is a shorthand for setting
'text-decoration-line',
'text-decoration-thickness',
'text-decoration-style',
and 'text-decoration-color'
in one declaration.
Omitted values are set to their initial values.
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 | [ from-font | under ] || [ left | right ]
Initial: auto
Inherited: yes
Computed value: specified keyword(s)
Animation type: discrete
</pre>
This property,
which is <em>not</em> a <a>sub-property</a> of the 'text-decoration' shorthand,
sets the position of an underline with respect to the text,
and defines its [=zero position=] for further adjustment by 'text-underline-offset'.
It affects all decorations originating from this element,
even if descendant boxes specify a different position.
It does not affect underlines specified by ancestor elements.
<div class="example">
The following example styles modern Chinese, Japanese, and Korean
texts with the appropriate underline positions in both horizontal
and vertical text:
<pre>
:root:lang(ja), [lang|=ja], :root:lang(ko), [lang|=ko] { text-underline-position: under right; }
:root:lang(zh), [lang|=zh] { text-underline-position: under left; }
</pre>
</div>
If ''text-underline-position/left'' or ''text-underline-position/right'' is specified alone,
''text-underline-position/auto'' is also implied.
Values have the following meanings:
<dl dfn-type=value dfn-for=text-underline-position>
<dt><dfn id="underline-auto">auto</dfn>
<dd>
The user agent may use any algorithm to determine the
underline's position; however it must be placed at or under
the alphabetic baseline.
Note: It is suggested that the default underline position
be close to the alphabetic baseline,
unless that would either cross subscripted (or otherwise lowered) text
or draw over glyphs from Asian scripts such as Han or Tibetan
for which an alphabetic underline is too high:
in such cases, shifting the underline lower
or aligning to the em box edge as described for ''text-underline-position/under''
may be more appropriate.
<div class="figure">
<img title="text-underline-position: alphabetic"
alt="In a typical Latin font, the underline is positioned slightly
below the alphabetic baseline, leaving a gap between the line
and the bottom of most Latin letters, but crossing through
descenders such as the stem of a 'p'."
src="images/underline-position-alphabetic.png" >
<p class="caption">A typical “alphabetic” underline is positioned just below the alphabetic baseline
</div>
<dt><dfn>from-font</dfn>
<dd>
If the <a>first available font</a> has
metrics indicating a preferred underline offset,
use that offset,
otherwise behaves as ''text-underline-offset/auto''.
<dt><dfn id="underline-under">under</dfn>
<dd>
The underline is positioned <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">
<img title="text-underline-position: under"
alt="In a typical Latin font, the underline is far enough
below the text that it does not cross the bottom of a 'g'."
src="images/underline-position-under.png">
<p class="caption">''text-underline-position: under''
</div>
<div class="example">
Because 'text-underline-position' inherits, and is not reset
by the 'text-decoration' shorthand, the following example
switches the document to use ''text-underline-position/under'' underlining, which can
be more appropriate for writing systems with long, complicated
descenders. It is also often useful for mathematical or chemical
texts that use many subscripts.
<pre>:root { text-underline-position: under; }</pre>
</div>
Note: The ''text-decoration/under'' value does not guarantee
that the underline will not conflict with glyphs,
as some fonts have descenders or diacritics
that extend below the font’s descent metrics.
<dt><dfn id="underline-left">left</dfn>
<dd>
In vertical <a>typographic modes</a>, the underline is aligned as for
''text-underline-position/under'', except it is always aligned to the left edge of the text.
If this causes the underline to be drawn on the "over" side of
the text, then an overline also switches sides and is drawn on
the "under" side.
<dt><dfn id="underline-right">right</dfn>
<dd>
In vertical <a>typographic modes</a>, the underline is aligned as for
''text-underline-position/under'', except it is always aligned to the right edge of the text.
If this causes the underline to be drawn on the "over" side of
the text, then an overline also switches sides and is drawn on
the "under" side.
</dl>
<div class="figure" id="fig-text-underline-position">
<table>
<tr>
<td>
<img alt="In mixed Japanese-Latin vertical text, 'text-underline-position: left'
places the underline on the left side of the text."
title="text-underline-position: left"
src="images/underline-position-left.png">
<td>
<img alt="In mixed Japanese-Latin vertical text, 'text-underline-position: right'
places the underline on the right side of the text."
title="text-underline-position: right"
src="images/underline-position-right.png">
<tr>
<td>''text-underline-position/left''
<td>''text-underline-position/right''
</table>
<p class="caption">In vertical <a>typographic modes</a>, the 'text-underline-position'
values ''text-underline-position/left'' and ''text-underline-position/right'' allow placing the underline on either
side of the text. (In horizontal <a>typographic modes</a>, both values are
treated as ''text-underline-position/auto''.)
</div>
<h3 id="underline-offset">
Text Underline Offset: the 'text-underline-offset' property</h3>
<pre class="propdef">
Name: text-underline-offset
Value: auto | <<length>> | <<percentage>>
Initial: auto
Applies to: all elements
Inherited: yes
Percentages: N/A
Computed value: specified keyword or absolute length
Animation type: by computed value
</pre>
This property,
which is <em>not</em> a <a>sub-property</a> of the 'text-decoration' shorthand,
sets the offset of underlines from their [=zero position=].
Positive offsets represent distances outward from the text;
negative offsets inward.
It affects all decorations originating from this element,
even if descendant boxes specify a different position.
It does not affect underlines specified by ancestor elements.
Values have the following meanings:
<dl dfn-for=text-underline-offset dfn-type=value>
<dt><dfn>auto</dfn>
<dd>
<p>The UA chooses an appropriate offset for underlines.
However, this offset must be zero
if ''text-underline-position/from-font'' was specified
and the UA was able to extract an appropriate metric to use
from the font.
<dt><dfn><<length>>
<dd>
<p>Specifies the offset of underlines as a fixed length.
Note: A length will inherit as a fixed value,
and will not scale with the font.
<dt><dfn><<percentage>>
<dd>
<p>Specifies the offset of underlines as a percentage of ''1em''.
Note: A percentage will inherit as a relative value,
and will therefore scale with changes in the font as it inherits.
</dl>
When the value of the 'text-decoration-line' property is either
''spelling-error'' or ''grammar-error'',
the UA may ignore the value of 'text-underline-position'.
<h4 id="line-offset-zero">
Underline Offset Origin (Zero Position)</h4>
The <dfn lt="underline zero position" local-lt="zero position">zero position</dfn> of the underline
depends on the value of 'text-underline-position'
as detailed below.
<table class="data">
<caption>Interaction of 'text-underline-position' and 'text-underline-offset'
<thead>
<tr>
<th>'text-underline-position'
<th>Zero Position
<th>Positive Direction
<tbody>
<tr>
<td>''text-underline-position/auto''
<td>alphabetic baseline
<td><a>under</a>
<tr>
<td>''text-underline-position/from-font''
<td>position specified by the font metrics, falling back to alphabetic baseline
<td><a>under</a>
<tr>
<td>''text-underline-position/under''
<td>text-under edge
<td><a>under</a>
<tr>
<td>''text-underline-position/left''
<td>text-under (left) edge
<td><a>under</a>
<tr>
<td>''text-underline-position/right''
<td>text-over (right) edge
<td><a>over</a>
</table>
The underline is aligned to the outside of the specified position
(extending its thickness in the positive direction only).
Any automatic adjustments made to accommodate descendant content are maintained;
the 'text-underline-offset' is in addition to those.
<h4 id="line-auto-offset">
Using Font Metrics for Automatic Positioning</h4>
Some font formats (such as OpenType) can offer information
about the appropriate position of a line decoration.
The UA should use such font-based information
in its choice of ''text-underline-offset/auto'' offset
wherever appropriate,
and must use such information
when ''text-underline-position/from-font'' is specified for 'text-underline-position'.
Note: Typically, OpenType font metrics give the position
of an ''text-underline-position/alphabetic'' underline;
in some cases (especially in CJK fonts),
it gives the position of a ''under left'' underline.
(In this case, the font's underline metrics typically
touch the bottom edge of the em box).
The UA may but is not required to correct for incorrect font metrics.
<h3 id="text-line-constancy">
Text Decoration Line Uniformity</h3>
The exact position and thickness of line decorations
depends on the values of
'text-underline-position', 'text-underline-offset', and 'text-decoration-thickness'
as defined above,
and is otherwise UA-defined.
However, for underlines and overlines
the UA must use a single thickness and position on each line
for the decorations deriving from a single <i>decorating box</i>.
<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 <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-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 <i>decorating boxes</i> 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 <i>decorating box</i> that are so styled
(even though it <em>may</em> adjust the position
to accommodate descendants that are not so styled,
such as those merely typeset in a different font size as noted above).
This allows superscripts and subscripts to be properly decorated
(underlined, struck through, etc.)
but prevents them from distorting or breaking the positioning of such decorations on their 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>
<h3 id="text-decoration-skipping">
Text Decoration Line Continuity: the 'text-decoration-skip' shorthand and its sub-properties</h3>
Issue: The CSSWG resolved to be split skipping functionality into individual properties
along the lines of 'text-decoration-skip-ink',
to improve its cascading behavior.
See <a href="https://github.com/w3c/csswg-drafts/issues/843">discussion</a>
and <a href="https://lists.w3.org/Archives/Public/www-style/2017Feb/0049.html">resolution</a>.
This section is a rough draft and has not yet been vetted by the CSSWG
<pre class="propdef">
Name: text-decoration-skip
Value: none | auto
Initial: See individual properties
Applies to: all elements
Inherited: yes
Percentages: N/A
Computed value: See individual properties
Animation type: discrete
</pre>
The 'text-decoration-skip' property and its sub-properties
('text-decoration-skip-self',
'text-decoration-skip-box',
'text-decoration-skip-inset',
'text-decoration-skip-spaces',
'text-decoration-skip-ink')
control interruptions in line decorations
for which the element or an ancestor is the [=decorating box=].
The <dfn value for=text-decoration-skip>none</dfn> value
sets all sub-properties to ''text-decoration-skip/none'',
and the <dfn value for=text-decoration-skip>auto</dfn> value
sets all sub-properties to their initial values.
ISSUE: Is this ''text-decoration-skip/none'' definition Web-compatible?
Do we also need to add an <css>ink</css> value for Web-compat?
<p class="note">Note that these properties inherit
and that descendant elements can have a different setting.</p>
The following addition is made to the default UA stylesheet for HTML:
<pre><code class="lang-css">
ins, del { text-decoration-skip: none; }
</code></pre>
When the value of the 'text-decoration-line' property is either
''spelling-error'' or ''grammar-error'',
the UA may ignore any or all of these properties.
<h4 id="text-decoration-skip-self-property">
Skipping Spaces: the 'text-decoration-skip-self' property</h4>
<pre class="propdef">
Name: text-decoration-skip-self
Value: none | objects
Initial: objects
Applies to: all elements
Inherited: yes
Percentages: N/A
Computed value: specified keyword(s)
Animation type: discrete
</pre>
Issue: The CSSWG resolved to split 'text-decoration-skip' into sub-properties,
but this value set has not yet been vetted by the CSSWG.
This property specifies whether
any text decoration lines drawn by its ancestors
are propagated to or drawn across the element.
Values have the following meanings:</p>
<dl dfn-type=value dfn-for=text-decoration-skip-self>
<dt><dfn>none</dfn></dt>
<dd>
Skip nothing: line decorations from ancestor [=decorating boxes=]
are propagated to or drawn across this box, as appropriate.
<dt><dfn>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>all</dfn></dt>
<dd>
Skip this element (its entire margin box).
Don't draw across it,
don't propagate to it.
-->
</dl>
<h4 id="text-decoration-skip-box-property">
Skipping Spaces: the 'text-decoration-skip-box' property</h4>
<pre class="propdef">
Name: text-decoration-skip-box
Value: none | all
Initial: none
Applies to: all elements
Inherited: yes
Percentages: N/A
Computed value: specified keyword(s)
Animation type: discrete
</pre>
Issue: The CSSWG resolved to split 'text-decoration-skip' into sub-properties,
but this value set has not yet been vetted by the CSSWG.
This property specifies what parts of the element's box area
any text decoration affecting the element must skip over.
It controls only text decoration lines drawn by its ancestors.
Values have the following meanings:</p>
<dl dfn-type=value dfn-for=text-decoration-skip-box>
<dt><dfn>none</dfn></dt>
<dd>
Skip nothing: line decorations from ancestor [=decorating boxes=]
are drawn from margin edge to margin edge.
<dt><dfn>all</dfn>
<dd>
When drawing text decoration lines applied to an ancestor [=decorating box=],
skip over the box's own margin, border, and padding areas
and only draw line decorations within its content area.
This value only has an effect for decorations imposed by an ancestor;
a <a>decorating box</a> never draws over its own box decoration.
</dl>
<h4 id="text-decoration-skip-inset-property">
Inset Edges: the 'text-decoration-skip-inset' property</h4>
<pre class="propdef">
Name: text-decoration-skip-inset
Value: none | auto
Initial: none
Applies to: all elements
Inherited: yes
Percentages: N/A
Computed value: specified keyword(s)
Animation type: discrete
</pre>
Issue: The CSSWG resolved to split 'text-decoration-skip' into sub-properties,
but this value set has not yet been vetted by the CSSWG.
This property specifies what parts of the element's box area
any text decoration affecting the element must skip over.
It controls all text decoration lines drawn by the element,
but not any text decoration lines drawn by its ancestors.
Values have the following meanings:</p>
<dl dfn-type=value dfn-for=text-decoration-skip-inset>
<dt><dfn>none</dfn></dt>
<dd>
Skip nothing: text-decoration is drawn from box edge to box edge.
<dt><dfn>auto</dfn></dt>
<dd>
The UA must place the start and end of the line inwards slightly
from the content edge of the <a>decorating box</a> so that,
e.g. two underlined elements side-by-side do not appear to have a single underline.
The size of the inset is up to the User Agent
(e.g. half a line thickness)
but must not be zero.
(This is important in Chinese, where underlining is a form of punctuation.)
<div class="figure">
<p><img title="text-decoration-skip-inset: auto"
alt="An underline below a series of Chinese characters has a gap between two adjacent underlining elements."
src="images/decoration-skip-inset.png">
<p class="caption">''text-decoration-skip-inset: auto'' for <code><u>石井</u><u>艾俐俐</u></code>
</p>
</div>
</dl>