steve/just-the-docs
1
0
Fork 0
mirror of https://github.com/snachodog/just-the-docs.git synced 2025-04-15 23:52:23 -06:00
Code Issues Packages Projects Releases Wiki Activity

Fix font-size scaling for text-related CSS properties by using rem instead of fixed px values; deprecate $root-font-size (#1169)

Browse Source 
This PR replaces all uses of `px` in relation to font size (opposed to borders, spacing, etc.) with the equivalent `rem` value when the body font size is `16px`. The intention is to better scale the website when the user changes the font size for `<body>` (often done for accessibility reasons).

This PR is technically a **breaking change**, though it's a minor one (see subheading below). I'm putting this up so that we can discuss it as a community.

(technically closes #1088 and fixes #1073, but let's see if we end up merging this)

## mechanics

To do this, I systematically went through every `px` value for all `.scss` files. Then, I deleted the `rem` function, the `_functions.scss` file (that was the only function there), and removed the import from `support.scss`. A nice side effect of this is that we no longer perform any SASS division.

The only remaining uses of `px` are for either:

- border-related properties
- shadow-related properties
- sizing for "non-text" elements (ex `hr`, `blockquote` decorative spacing)
- `$root-font-size` (see below)

The only pixel value change in this PR is the `padding-left` for `blockquote`, which I've changed from `15px` to `1rem` (which is `16px` in the "stock" theme).

## deprecating `$root-font-size`

There's a SCSS variable called `$root-font-size`. It is used in two places:

1. the `rem()` function
2. the `.site-title` when printing (i.e. a `@print` style)

The changes I listed above let us ignore the first case. The second case seems like it has the intention of matching the body font size, so I replaced it with `1rem`.

We can choose to leave the variable in (in case others use it in custom code - which I'm sure that some do) and leave a deprecation notice, or just remove it now. I'm leaning towards the former, which is less disruptive.

## how users would upgrade

This is a breaking change of *some* sorts, but the change is very straightforward for users:

1. If they do not change `$root-font-size`, they need to do nothing; this PR is a no-op.
2. if they do change `$root-font-size`
    - they should instead set the `font-size` of `body` with the appropriate `px` value
    - optionally, they can replace all custom code that uses `$root-font-size` with `1rem` (find-and-replace works here)
This commit is contained in:
Matt Wang 2023-06-15 19:11:14 -07:00 committed by GitHub
parent ea0d5d8ec7
commit 4151d4614e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 26 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
_sass/base.scss
View File

@ -104,6 +104,6 @@ blockquote {
// resets user-agent stylesheets for blockquotes // resets user-agent stylesheets for blockquotes
margin-block-start: 0; margin-block-start: 0;
margin-inline-start: 0; margin-inline-start: 0;
padding-left: 15px; padding-left: 1rem;
border-left: 3px solid $border-color; border-left: 3px solid $border-color;
} }

2
_sass/print.scss
View File

@ -21,7 +21,7 @@
} }
.site-title { .site-title {
font-size: $root-font-size !important; font-size: 1rem !important;
font-weight: 700 !important; font-weight: 700 !important;
} }

4
_sass/search.scss
View File

@ -42,7 +42,7 @@
width: 100%; width: 100%;
height: 100%; height: 100%;
padding: $sp-2 $gutter-spacing-sm $sp-2 #{$gutter-spacing-sm + $sp-5}; padding: $sp-2 $gutter-spacing-sm $sp-2 #{$gutter-spacing-sm + $sp-5};
font-size: 16px; font-size: 1rem;
color: $body-text-color; color: $body-text-color;
background-color: $search-background-color; background-color: $search-background-color;
border-top: 0; border-top: 0;
@ -53,7 +53,7 @@
@include mq(md) { @include mq(md) {
padding: $sp-2 $gutter-spacing-sm $sp-2 #{$gutter-spacing + $sp-5}; padding: $sp-2 $gutter-spacing-sm $sp-2 #{$gutter-spacing + $sp-5};
font-size: 14px; font-size: 0.875rem;
background-color: $body-background-color; background-color: $body-background-color;
transition: padding-left linear #{$transition-duration * 0.5}; transition: padding-left linear #{$transition-duration * 0.5};
} }

9
_sass/support/_functions.scss
View File

@ -1,9 +0,0 @@
@function rem($size, $unit: "") {
$rem-size: $size / $root-font-size;
@if $unit == false {
@return #{$rem-size};
} @else {
@return #{$rem-size}rem;
}
}

40
_sass/support/_variables.scss
View File

@ -3,7 +3,7 @@
$body-font-family: system-ui, -apple-system, blinkmacsystemfont, "Segoe UI", $body-font-family: system-ui, -apple-system, blinkmacsystemfont, "Segoe UI",
roboto, "Helvetica Neue", arial, sans-serif !default; roboto, "Helvetica Neue", arial, sans-serif !default;
$mono-font-family: "SFMono-Regular", menlo, consolas, monospace !default; $mono-font-family: "SFMono-Regular", menlo, consolas, monospace !default;
$root-font-size: 16px !default; // Base font-size for rems $root-font-size: 16px !default; // DEPRECATED: previously base font-size for rems
$body-line-height: 1.4 !default; $body-line-height: 1.4 !default;
$content-line-height: 1.6 !default; $content-line-height: 1.6 !default;
$body-heading-line-height: 1.25 !default; $body-heading-line-height: 1.25 !default;
@ -11,18 +11,18 @@ $body-heading-line-height: 1.25 !default;
// Font size // Font size
// `-sm` suffix is the size at the small (and above) media query // `-sm` suffix is the size at the small (and above) media query
$font-size-1: 9px !default; $font-size-1: 0.5625rem !default;
$font-size-1-sm: 10px !default; $font-size-1-sm: 0.625rem !default;
$font-size-2: 11px !default; // h4 - uppercased!, h6 not uppercased, text-small $font-size-2: 0.6875rem !default; // h4 - uppercased!, h6 not uppercased, text-small
$font-size-3: 12px !default; // h5 $font-size-3: 0.75rem !default; // h5
$font-size-4: 14px !default; $font-size-4: 0.875rem !default;
$font-size-5: 16px !default; // h3 $font-size-5: 1rem !default; // h3
$font-size-6: 18px !default; // h2 $font-size-6: 1.125rem !default; // h2
$font-size-7: 24px !default; $font-size-7: 1.5rem !default;
$font-size-8: 32px !default; // h1 $font-size-8: 2rem !default; // h1
$font-size-9: 36px !default; $font-size-9: 2.25rem !default;
$font-size-10: 42px !default; $font-size-10: 2.625rem !default;
$font-size-10-sm: 48px !default; $font-size-10-sm: 3rem !default;
// Colors // Colors
@ -95,22 +95,22 @@ $border-color: $grey-lt-100 !default;
$gutter-spacing: $sp-6 !default; $gutter-spacing: $sp-6 !default;
$gutter-spacing-sm: $sp-4 !default; $gutter-spacing-sm: $sp-4 !default;
$nav-width: 264px !default; $nav-width: 16.5rem !default;
$nav-width-md: 248px !default; $nav-width-md: 15.5rem !default;
$nav-list-item-height: $sp-6 !default; $nav-list-item-height: $sp-6 !default;
$nav-list-item-height-sm: $sp-8 !default; $nav-list-item-height-sm: $sp-8 !default;
$nav-list-expander-right: true; $nav-list-expander-right: true;
$content-width: 800px !default; $content-width: 50rem !default;
$header-height: 60px !default; $header-height: 3.75rem !default;
$search-results-width: $content-width - $nav-width !default; $search-results-width: $content-width - $nav-width !default;
$transition-duration: 400ms; $transition-duration: 400ms;
// Media queries in pixels // Media queries in pixels
$media-queries: ( $media-queries: (
xs: 320px, xs: 20rem,
sm: 500px, sm: 31.25rem,
md: $content-width, md: $content-width,
lg: $content-width + $nav-width, lg: $content-width + $nav-width,
xl: 1400px, xl: 87.5rem,
) !default; ) !default;

2
_sass/support/mixins/_layout.scss
View File

@ -12,7 +12,7 @@
// If the key exists in the map // If the key exists in the map
@if $value { @if $value {
// Prints a media query based on the value // Prints a media query based on the value
@media (min-width: rem($value)) { @media (min-width: $value) {
@content; @content;
} }
} @else { } @else {

1
_sass/support/support.scss
View File

@ -1,3 +1,2 @@
@import "./variables"; @import "./variables";
@import "./functions";
@import "./mixins/mixins"; @import "./mixins/mixins";

2
_sass/tables.scss
View File

@ -21,7 +21,7 @@ th,
td { td {
@include fs-3; @include fs-3;
min-width: 120px; min-width: 7.5rem;
padding: $sp-2 $sp-3; padding: $sp-2 $sp-3;
background-color: $table-background-color; background-color: $table-background-color;
border-bottom: $border rgba($border-color, 0.5); border-bottom: $border rgba($border-color, 0.5);