Skip to content

Commit

Permalink
rustdoc: tweak line and ¶ spacing for a11y
Browse files Browse the repository at this point in the history 
The W3C Web Content Accessibility Guidelines specify a minimum line
spacing of 1.5 and a minimum paragraph spacing of 1.5 times the line
spacing. Our current line spacing (implemented by line-height) is 1.4,
so it's a small bump to go up to 1.5. Similarly, we have a paragraph
spacing of 0.6em. Bump that to 0.75em (which is 1.5 times the 0.5em
distance between lines).

Also, fix all the font sizes so instead of being round-ish numbers in
rem (like 1.1rem, 1.2rem), they are round numbers in pixels. Ensure each
font size is at least 2 pixels different than the nearest other font
size, so distinctions can be clearly seen. Overall the font-sizes are
mostly staying the same, being rounded up or down as appropriate.

Remove a few unused styles.

Simplify the display of the mobile-topbar location, by setting its
margins to auto rather than trying to size it exactly to the topbar.
  • Loading branch information
@jsha
jsha committed Feb 8, 2022
1 parent 03b17b1 commit dd5ff42
Show file tree
Hide file tree
Showing 9 changed files with 96 additions and 106 deletions.
112 changes: 52 additions & 60 deletions src/librustdoc/html/static/css/rustdoc.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,9 @@ html {
/* General structure and fonts */

body {
font: 1rem/1.4 "Source Serif 4", NanumBarunGothic, serif;
/* Line spacing at least 1.5 per Web Content Accessibility Guidelines
https://www.w3.org/WAI/WCAG21/Understanding/visual-presentation.html */
font: 1rem/1.5 "Source Serif 4", NanumBarunGothic, serif;
margin: 0;
position: relative;
/* We use overflow-wrap: break-word for Safari, which doesn't recognize
Expand All @@ -124,13 +126,13 @@ body {
}

h1 {
font-size: 1.5rem;
font-size: 1.5rem; /* 24px */
}
h2 {
font-size: 1.4rem;
font-size: 1.375rem; /* 22px */
}
h3 {
font-size: 1.3rem;
font-size: 1.25rem; /* 20px */
}
h1, h2, h3, h4, h5, h6 {
font-weight: 500;
Expand Down Expand Up @@ -170,7 +172,7 @@ h2,
border-bottom: 1px solid;
}
h3.code-header {
font-size: 1.1rem;
font-size: 1.125rem; /* 18px */
}
h4.code-header {
font-size: 1rem;
Expand Down Expand Up @@ -221,19 +223,18 @@ a.srclink,
font-family: "Fira Sans", Arial, NanumBarunGothic, sans-serif;
}

.content ul.crate a.crate {
font-size: 1rem/1.6;
}

ol, ul {
padding-left: 25px;
padding-left: 24px;
}
ul ul, ol ul, ul ol, ol ol {
margin-bottom: .6em;
margin-bottom: .625em;
}

p {
margin: 0 0 .6em 0;
/* Paragraph spacing at least 1.5 times line spacing per Web Content Accessibility Guidelines.
Line-height is 1.5rem, so line spacing is .5rem; .75em is 1.5 times that.
https://www.w3.org/WAI/WCAG21/Understanding/visual-presentation.html */
margin: 0 0 .75em 0;
}

summary {
Expand Down Expand Up @@ -303,7 +304,7 @@ code, pre, a.test-arrow, .code-header {
}
.docblock code, .docblock-short code {
border-radius: 3px;
padding: 0 0.1em;
padding: 0 0.125em;
}
.docblock pre code, .docblock-short pre code {
padding: 0;
Expand Down Expand Up @@ -364,7 +365,7 @@ nav.sub {
}

.sidebar {
font-size: 0.9rem;
font-size: 0.875rem;
width: 250px;
min-width: 200px;
overflow-y: scroll;
Expand Down Expand Up @@ -476,8 +477,8 @@ nav.sub {
.block a,
h2.location a {
display: block;
padding: 0.3rem;
margin-left: -0.3rem;
padding: 0.25rem;
margin-left: -0.25rem;

text-overflow: ellipsis;
overflow: hidden;
Expand All @@ -497,7 +498,7 @@ h2.location a {
}

.sidebar h3 {
font-size: 1.1rem;
font-size: 1.125rem; /* 18px */
font-weight: 500;
padding: 0;
margin: 0;
Expand Down Expand Up @@ -598,18 +599,18 @@ h2.location a {
white-space: pre-wrap;
}

.top-doc .docblock h2 { font-size: 1.3rem; }
.top-doc .docblock h3 { font-size: 1.15rem; }
.top-doc .docblock h2 { font-size: 1.375rem; }
.top-doc .docblock h3 { font-size: 1.25; }
.top-doc .docblock h4,
.top-doc .docblock h5 {
font-size: 1.1rem;
font-size: 1.125rem;
}
.top-doc .docblock h6 {
font-size: 1rem;
}

.docblock h5 { font-size: 1rem; }
.docblock h6 { font-size: 0.95rem; }
.docblock h6 { font-size: 0.875rem; }

.docblock {
margin-left: 24px;
Expand All @@ -623,12 +624,12 @@ h2.location a {

.content .out-of-band {
flex-grow: 0;
font-size: 1.15rem;
font-size: 1.125rem;
font-weight: normal;
float: right;
}

.method > .code-header, .trait-impl > .code-header, .invisible > .code-header {
.method > .code-header, .trait-impl > .code-header {
max-width: calc(100% - 41px);
display: block;
}
Expand Down Expand Up @@ -664,7 +665,7 @@ h2.location a {
.content td { vertical-align: top; }
.content td:first-child { padding-right: 20px; }
.content td p:first-child { margin-top: 0; }
.content td h1, .content td h2 { margin-left: 0; font-size: 1.1rem; }
.content td h1, .content td h2 { margin-left: 0; font-size: 1.125rem; }
.content tr:first-child td { border-top: 0; }

.docblock table {
Expand Down Expand Up @@ -713,7 +714,7 @@ h2.location a {
.content .fn .where,
.content .where.fmt-newline {
display: block;
font-size: 0.8rem;
font-size: 0.875rem;
}

.content .methods > div:not(.notable-traits):not(.method) {
Expand All @@ -736,7 +737,7 @@ h2.location a {
}

.content .item-info code {
font-size: 0.81rem;
font-size: 0.875rem;
}

.content .item-info {
Expand Down Expand Up @@ -839,15 +840,6 @@ h2.small-section-header > .anchor {
text-decoration: underline;
}

.invisible > .srclink,
.method > .code-header + .srclink {
position: absolute;
top: 0;
right: 0;
font-size: 1.0625rem;
font-weight: normal;
}

.block a.current.crate { font-weight: 500; }

/* In most contexts we use `overflow-wrap: anywhere` to ensure that we can wrap
Expand Down Expand Up @@ -885,7 +877,7 @@ table,
display: table-cell;
}
.item-left {
padding-right: 1.2rem;
padding-right: 1.25rem;
}

.search-container {
Expand All @@ -907,8 +899,8 @@ table,
#crate-search {
min-width: 115px;
margin-top: 5px;
margin-left: 0.2em;
padding-left: 0.3em;
margin-left: 0.25em;
padding-left: 0.3125em;
padding-right: 23px;
border: 0;
border-radius: 4px;
Expand Down Expand Up @@ -942,7 +934,7 @@ table,
border: 1px solid;
border-radius: 2px;
padding: 5px 8px;
font-size: 1.0625rem;
font-size: 1rem;
transition: border-color 300ms ease;
width: 100%;
}
Expand Down Expand Up @@ -1054,15 +1046,15 @@ body.blur > :not(#help) {
.stab {
padding: 3px;
margin-bottom: 5px;
font-size: 0.9rem;
font-size: 0.875rem;
font-weight: normal;
}
.stab p {
display: inline;
}

.stab .emoji {
font-size: 1.2rem;
font-size: 1.25rem;
}

/* Black one-pixel outline around emoji shapes */
Expand All @@ -1078,10 +1070,10 @@ body.blur > :not(#help) {
.import-item .stab {
border-radius: 3px;
display: inline-block;
font-size: 0.8rem;
font-size: 0.875rem;
line-height: 1.2;
margin-bottom: 0;
margin-left: .3em;
margin-left: 0.3125em;
padding: 2px;
vertical-align: text-bottom;
}
Expand All @@ -1107,9 +1099,6 @@ body.blur > :not(#help) {
font-weight: normal;
font-size: 1rem;
}
.impl .srclink {
font-size: 1.0625rem;
}

.rightside {
float: right;
Expand Down Expand Up @@ -1141,7 +1130,7 @@ a.test-arrow {
position: absolute;
padding: 5px 10px 5px 10px;
border-radius: 5px;
font-size: 1.3rem;
font-size: 1.375rem;
top: 5px;
right: 5px;
z-index: 1;
Expand Down Expand Up @@ -1179,7 +1168,7 @@ a.test-arrow:hover{

h3.variant {
font-weight: 600;
font-size: 1.1rem;
font-size: 1.125rem;
margin-bottom: 10px;
border-bottom: none;
}
Expand Down Expand Up @@ -1391,7 +1380,7 @@ pre.rust {
left: 0;
cursor: pointer;
font-weight: bold;
font-size: 1.2rem;
font-size: 1.25rem;
border-bottom: 1px solid;
display: flex;
height: 40px;
Expand Down Expand Up @@ -1516,12 +1505,9 @@ kbd {
}
.table-display .out-of-band {
position: relative;
font-size: 1.1875rem;
font-size: 1.125rem;
display: block;
}
#implementors-list > .impl-items .table-display .out-of-band {
font-size: 1.0625rem;
}

.table-display td:hover .anchor {
display: block;
Expand Down Expand Up @@ -1562,7 +1548,7 @@ div.name.expand + .children {
div.name::before {
content: "\25B6";
padding-left: 4px;
font-size: 0.7rem;
font-size: 0.625rem;
position: absolute;
left: -16px;
top: 4px;
Expand Down Expand Up @@ -1595,8 +1581,8 @@ details.rustdoc-toggle > summary.hideme > span {
details.rustdoc-toggle > summary::before {
content: "";
cursor: pointer;
width: 17px;
height: max(17px, 1.1em);
width: 16px;
height: 16px;
background-repeat: no-repeat;
background-position: top left;
display: inline-block;
Expand Down Expand Up @@ -1643,7 +1629,7 @@ details.rustdoc-toggle > summary.hideme::before {
details.rustdoc-toggle > summary:not(.hideme)::before {
position: absolute;
left: -24px;
top: 3px;
top: 4px;
}

.impl-items > details.rustdoc-toggle > summary:not(.hideme)::before {
Expand Down Expand Up @@ -1680,8 +1666,8 @@ details.undocumented > summary::before, details.rustdoc-toggle > summary::before

details.rustdoc-toggle[open] > summary::before,
details.rustdoc-toggle[open] > summary.hideme::before {
width: 17px;
height: max(17px, 1.1em);
width: 16px;
height: 16px;
background-repeat: no-repeat;
background-position: top left;
display: inline-block;
Expand Down Expand Up @@ -1808,8 +1794,14 @@ details.rustdoc-toggle[open] > summary.hideme::after {
width: 0;
}

.mobile-topbar .location a {
padding: 0;
margin: 0;
}

.mobile-topbar .location {
border: none;
padding: 0;
margin: auto 0.5em auto auto;
text-overflow: ellipsis;
overflow: hidden;
Expand All @@ -1818,7 +1810,7 @@ details.rustdoc-toggle[open] > summary.hideme::after {
height is specified in pixels, this also has to be specified in
pixels to avoid overflowing the topbar when the user sets a bigger
font size. */
font-size: 22.4px;
font-size: 24px;
}

.mobile-topbar .logo-container {
Expand Down
2 changes: 1 addition & 1 deletion src/test/rustdoc-gui/docblock-big-code-mobile.goml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,4 @@ goto: file://|DOC_PATH|/test_docs/long_code_block/index.html
show-text: true // We need to enable text draw to be able to have the "real" size
// Little explanations for this test: if the text wasn't displayed on two lines, it would take
// around 20px (which is the font size).
assert-property: (".docblock p > code", {"offsetHeight": "42"})
assert-property: (".docblock p > code", {"offsetHeight": "44"})
Loading

0 comments on commit dd5ff42

Please sign in to comment.