@graupl/core 1.0.0-beta.22 → 1.0.0-beta.24

package/src/scss/theme/typography/_index.scss

@@ -1,76 +1,227 @@
 // @graupl/core typography theme styles.
+//
+// This module defines typography tokens for body text, small text, and headings.
+//
+// The following selectors are generated by default:
+// - `:root`: Sets root font family and size.
+// - `b`: Applies the bold weight token.
+// - `strong`: Applies the bold weight token.
+// - `body`: Applies body typography tokens.
+// - `p`: Applies paragraph typography tokens.
+// - `small`: Applies small text typography tokens.
+// - `h1`: Applies H1 typography tokens.
+// - `h2`: Applies H2 typography tokens.
+// - `h3`: Applies H3 typography tokens.
+// - `h4`: Applies H4 typography tokens.
+// - `h5`: Applies H5 typography tokens.
+// - `h6`: Applies H6 typography tokens.
+//
+// The following custom properties can be used to customize typography:
+// | Property                         | Description                      | Default Value                                                                                           |
+// | ---                              | ---                              | ---                                                                                                     |
+// | `--graupl-font-size-base`        | Base font size used for scaling. | `1rem`                                                                                                  |
+// | `--graupl-line-height`           | Base line height.                | `1.2em`                                                                                                 |
+// | `--graupl-font-xs`               | XS font size token.              | `calc(0.694 * var(--graupl-font-size-base))`                                                            |
+// | `--graupl-font-sm`               | Small font size token.           | `calc(0.833 * var(--graupl-font-size-base))`                                                            |
+// | `--graupl-font-base`             | Base font size token.            | `var(--graupl-font-size-base)`                                                                          |
+// | `--graupl-font-lg`               | Large font size token.           | `calc(1.2 * var(--graupl-font-size-base))`                                                              |
+// | `--graupl-font-xl`               | XL font size token.              | `calc(1.44 * var(--graupl-font-size-base))`                                                             |
+// | `--graupl-font-2xl`              | 2XL font size token.             | `calc(1.728 * var(--graupl-font-size-base))`                                                            |
+// | `--graupl-font-3xl`              | 3XL font size token.             | `calc(2.074 * var(--graupl-font-size-base))`                                                            |
+// | `--graupl-font-4xl`              | 4XL font size token.             | `calc(2.488 * var(--graupl-font-size-base))`                                                            |
+// | `--graupl-font-5xl`              | 5XL font size token.             | `calc(2.986 * var(--graupl-font-size-base))`                                                            |
+// | `--graupl-font-weight-light`     | Light font weight token.         | `300`                                                                                                   |
+// | `--graupl-font-weight-normal`    | Normal font weight token.        | `400`                                                                                                   |
+// | `--graupl-font-weight-bold`      | Bold font weight token.          | `700`                                                                                                   |
+// | `--graupl-root-font-family`      | Root font family.                | `system-ui, -apple-system, blinkmacsystemfont, "Segoe UI", roboto, "Helvetica Neue", arial, sans-serif` |
+// | `--graupl-root-font-size`        | Root font size.                  | `clamp(0.85rem, calc(0.8rem + 0.5vw), 1.25rem)`                                                         |
+// | `--graupl-body-font-size`        | Body font size.                  | `var(--graupl-font-base)`                                                                               |
+// | `--graupl-body-line-height`      | Body line height.                | `var(--graupl-line-height)`                                                                             |
+// | `--graupl-body-font-weight`      | Body font weight.                | `var(--graupl-font-weight-normal)`                                                                      |
+// | `--graupl-body-color`            | Body text colour.                | `var(--graupl-color)`                                                                                   |
+// | `--graupl-paragraph-font-size`   | Paragraph font size.             | `var(--graupl-body-font-size)`                                                                          |
+// | `--graupl-paragraph-line-height` | Paragraph line height.           | `var(--graupl-body-line-height)`                                                                        |
+// | `--graupl-paragraph-margin`      | Paragraph margin.                | `0 0 var(--graupl-spacer-2) 0`                                                                          |
+// | `--graupl-paragraph-font-weight` | Paragraph font weight.           | `var(--graupl-body-font-weight)`                                                                        |
+// | `--graupl-paragraph-color`       | Paragraph text colour.           | `var(--graupl-body-color)`                                                                              |
+// | `--graupl-small-font-size`       | Small text font size.            | `var(--graupl-font-sm)`                                                                                 |
+// | `--graupl-small-line-height`     | Small text line height.          | `var(--graupl-line-height)`                                                                             |
+// | `--graupl-small-margin`          | Small text margin.               | `0 0 var(--graupl-spacer-2) 0`                                                                          |
+// | `--graupl-small-font-weight`     | Small text font weight.          | `var(--graupl-body-font-weight)`                                                                        |
+// | `--graupl-small-color`           | Small text colour.               | `var(--graupl-body-color)`                                                                              |
+// | `--graupl-heading-font-family`   | Heading font family.             | `var(--graupl-root-font-family)`                                                                        |
+// | `--graupl-heading-line-height`   | Heading line height.             | `var(--graupl-line-height)`                                                                             |
+// | `--graupl-heading-margin`        | Base heading margin.             | `var(--graupl-spacer-5) 0 var(--graupl-spacer-2) 0`                                                     |
+// | `--graupl-heading-font-weight`   | Base heading font weight.        | `var(--graupl-font-weight-bold)`                                                                        |
+// | `--graupl-heading-color`         | Base heading colour.             | `var(--graupl-color)`                                                                                   |
+// | `--graupl-h1-font-size`          | H1 font size.                    | `var(--graupl-font-5xl)`                                                                                |
+// | `--graupl-h1-line-height`        | H1 line height.                  | `var(--graupl-heading-line-height)`                                                                     |
+// | `--graupl-h1-margin`             | H1 margin.                       | `var(--graupl-heading-margin)`                                                                          |
+// | `--graupl-h1-font-family`        | H1 font family.                  | `var(--graupl-heading-font-family)`                                                                     |
+// | `--graupl-h1-font-weight`        | H1 font weight.                  | `var(--graupl-heading-font-weight)`                                                                     |
+// | `--graupl-h1-color`              | H1 colour.                       | `var(--graupl-heading-color)`                                                                           |
+// | `--graupl-h2-font-size`          | H2 font size.                    | `var(--graupl-font-4xl)`                                                                                |
+// | `--graupl-h2-line-height`        | H2 line height.                  | `var(--graupl-heading-line-height)`                                                                     |
+// | `--graupl-h2-margin`             | H2 margin.                       | `var(--graupl-heading-margin)`                                                                          |
+// | `--graupl-h2-font-family`        | H2 font family.                  | `var(--graupl-heading-font-family)`                                                                     |
+// | `--graupl-h2-font-weight`        | H2 font weight.                  | `var(--graupl-heading-font-weight)`                                                                     |
+// | `--graupl-h2-color`              | H2 colour.                       | `var(--graupl-heading-color)`                                                                           |
+// | `--graupl-h3-font-size`          | H3 font size.                    | `var(--graupl-font-3xl)`                                                                                |
+// | `--graupl-h3-line-height`        | H3 line height.                  | `var(--graupl-heading-line-height)`                                                                     |
+// | `--graupl-h3-margin`             | H3 margin.                       | `var(--graupl-heading-margin)`                                                                          |
+// | `--graupl-h3-font-family`        | H3 font family.                  | `var(--graupl-heading-font-family)`                                                                     |
+// | `--graupl-h3-font-weight`        | H3 font weight.                  | `var(--graupl-heading-font-weight)`                                                                     |
+// | `--graupl-h3-color`              | H3 colour.                       | `var(--graupl-heading-color)`                                                                           |
+// | `--graupl-h4-font-size`          | H4 font size.                    | `var(--graupl-font-2xl)`                                                                                |
+// | `--graupl-h4-line-height`        | H4 line height.                  | `var(--graupl-heading-line-height)`                                                                     |
+// | `--graupl-h4-margin`             | H4 margin.                       | `var(--graupl-heading-margin)`                                                                          |
+// | `--graupl-h4-font-family`        | H4 font family.                  | `var(--graupl-heading-font-family)`                                                                     |
+// | `--graupl-h4-font-weight`        | H4 font weight.                  | `var(--graupl-heading-font-weight)`                                                                     |
+// | `--graupl-h4-color`              | H4 colour.                       | `var(--graupl-heading-color)`                                                                           |
+// | `--graupl-h5-font-size`          | H5 font size.                    | `var(--graupl-font-xl)`                                                                                 |
+// | `--graupl-h5-line-height`        | H5 line height.                  | `var(--graupl-heading-line-height)`                                                                     |
+// | `--graupl-h5-margin`             | H5 margin.                       | `var(--graupl-heading-margin)`                                                                          |
+// | `--graupl-h5-font-family`        | H5 font family.                  | `var(--graupl-heading-font-family)`                                                                     |
+// | `--graupl-h5-font-weight`        | H5 font weight.                  | `var(--graupl-heading-font-weight)`                                                                     |
+// | `--graupl-h5-color`              | H5 colour.                       | `var(--graupl-heading-color)`                                                                           |
+// | `--graupl-h6-font-size`          | H6 font size.                    | `var(--graupl-font-lg)`                                                                                 |
+// | `--graupl-h6-line-height`        | H6 line height.                  | `var(--graupl-heading-line-height)`                                                                     |
+// | `--graupl-h6-margin`             | H6 margin.                       | `var(--graupl-heading-margin)`                                                                          |
+// | `--graupl-h6-font-family`        | H6 font family.                  | `var(--graupl-heading-font-family)`                                                                     |
+// | `--graupl-h6-font-weight`        | H6 font weight.                  | `var(--graupl-heading-font-weight)`                                                                     |
+// | `--graupl-h6-color`              | H6 colour.                       | `var(--graupl-heading-color)`                                                                           |
+//
+// The following sass variables can be used to customize typography generation:
+// | Variable                      | Description                                    | Default Value                                   |
+// | ---                           | ---                                            | ---                                             |
+// | `$selector-base`              | The selector base for the component.           | `""`                                            |
+// | `$modifier-selector-base`     | The selector base for component modifiers.     | `"."`                                           |
+// | `$paragraph-selector-base`    | The base selector for the paragraph component. | `$selector-base`                                |
+// | `$paragraph-selector`         | The selector for the paragraph component.      | `"p"`                                           |
+// | `$small-selector-base`        | The base selector for the small component.     | `$selector-base`                                |
+// | `$small-selector`             | The selector for the small component.          | `"small"`                                       |
+// | `$h1-selector-base`           | The base selector for the h1 component.        | `$selector-base`                                |
+// | `$h1-selector`                | The selector for the h1 component.             | `"h1"`                                          |
+// | `$h2-selector-base`           | The base selector for the h2 component.        | `$selector-base`                                |
+// | `$h2-selector`                | The selector for the h2 component.             | `"h2"`                                          |
+// | `$h3-selector-base`           | The base selector for the h3 component.        | `$selector-base`                                |
+// | `$h3-selector`                | The selector for the h3 component.             | `"h3"`                                          |
+// | `$h4-selector-base`           | The base selector for the h4 component.        | `$selector-base`                                |
+// | `$h4-selector`                | The selector for the h4 component.             | `"h4"`                                          |
+// | `$h5-selector-base`           | The base selector for the h5 component.        | `$selector-base`                                |
+// | `$h5-selector`                | The selector for the h5 component.             | `"h5"`                                          |
+// | `$h6-selector-base`           | The base selector for the h6 component.        | `$selector-base`                                |
+// | `$h6-selector`                | The selector for the h6 component.             | `"h6"`                                          |
+// | `$root-selector-base`         | The base selector for the root component.      | `":"`                                           |
+// | `$root-selector`              | The selector for the root component.           | `"root"`                                        |
+// | `$bold-selector-base`         | The base selector for the bold component.      | `$selector-base`                                |
+// | `$bold-selector`              | The selector for the bold component.           | `"b"`                                           |
+// | `$strong-selector-base`       | The base selector for the strong component.    | `$selector-base`                                |
+// | `$strong-selector`            | The selector for the strong component.         | `"strong"`                                      |
+// | `$body-selector-base`         | The base selector for the body component.      | `$selector-base`                                |
+// | `$body-selector`              | The selector for the body component.           | `"body"`                                        |
+// | `$generate-base-font-sizes`   | Flag to generate the base font-size scale.     | `true`                                          |
+// | `$generate-base-font-weights` | Flag to generate the base font-weight scale.   | `true`                                          |
+// | `$font-size-base`             | Base font size for the scale.                  | `1rem`                                          |
+// | `$root-font-size`             | Root font size value.                          | `clamp(0.85rem, calc(0.8rem + 0.5vw), 1.25rem)` |
+// | `$line-height`                | Base line height.                              | `1.2em`                                         |
+// | `$font-size-multipliers`      | Map of size keys to multipliers.               | Minor third scale (see `_defaults.scss`)        |
+// | `$font-weights`               | Map of weight keys to values.                  | `light:300`, `normal:400`, `bold:700`           |
+// | `$root-font-family`           | Root font family stack.                        | System stack                                    |
+//
+// @example
+// <div>
+//   <h1>Heading 1</h1>
+//   <p>Body copy with a <strong>bold</strong> word.</p>
+//   <small>Supporting small text.</small>
+// </div>
 
+@use "defaults";
 @use "variables" as *;
 @use "../../mixins/layer" as *;
 @use "sass:map";
 
 @include layer(base) {
-  p {
+  // p
+  #{defaults.$paragraph-selector-base}#{defaults.$paragraph-selector} {
     margin: $paragraph-margin;
   }
 
-  small {
+  // small
+  #{defaults.$small-selector-base}#{defaults.$small-selector} {
     margin: $small-margin;
   }
 
-  h1 {
+  // h1
+  #{defaults.$h1-selector-base}#{defaults.$h1-selector} {
     margin: $h1-margin;
   }
 
-  h2 {
+  // h2
+  #{defaults.$h2-selector-base}#{defaults.$h2-selector} {
     margin: $h2-margin;
   }
 
-  h3 {
+  // h3
+  #{defaults.$h3-selector-base}#{defaults.$h3-selector} {
     margin: $h3-margin;
   }
 
-  h4 {
+  // h4
+  #{defaults.$h4-selector-base}#{defaults.$h4-selector} {
     margin: $h4-margin;
   }
 
-  h5 {
+  // h5
+  #{defaults.$h5-selector-base}#{defaults.$h5-selector} {
     margin: $h5-margin;
   }
 
-  h6 {
+  // h6
+  #{defaults.$h6-selector-base}#{defaults.$h6-selector} {
     margin: $h6-margin;
   }
 }
 
 @include layer(theme) {
-  :root {
+  // :root
+  #{defaults.$root-selector-base}#{defaults.$root-selector} {
     font-family: $root-font-family;
     font-size: $root-font-size;
   }
 
-  b,
-  strong {
+  // b, strong
+  #{defaults.$bold-selector-base}#{defaults.$bold-selector},
+  #{defaults.$strong-selector-base}#{defaults.$strong-selector} {
     font-weight: $font-weight-bold;
   }
 
-  body {
+  // body
+  #{defaults.$body-selector-base}#{defaults.$body-selector} {
     color: $body-color;
     font-size: $body-font-size;
     font-weight: $body-font-weight;
     line-height: $body-line-height;
   }
 
-  p {
+  // p
+  #{defaults.$paragraph-selector-base}#{defaults.$paragraph-selector} {
     color: $paragraph-color;
     font-size: $paragraph-font-size;
     font-weight: $paragraph-font-weight;
     line-height: $paragraph-line-height;
   }
 
-  small {
+  // small
+  #{defaults.$small-selector-base}#{defaults.$small-selector} {
     color: $small-color;
     font-size: $small-font-size;
     font-weight: $small-font-weight;
     line-height: $small-line-height;
   }
 
-  h1 {
+  // h1
+  #{defaults.$h1-selector-base}#{defaults.$h1-selector} {
     color: $h1-color;
     font-family: $h1-font-family;
     font-size: $h1-font-size;
@@ -78,7 +229,8 @@
     line-height: $h1-line-height;
   }
 
-  h2 {
+  // h2
+  #{defaults.$h2-selector-base}#{defaults.$h2-selector} {
     color: $h2-color;
     font-family: $h2-font-family;
     font-size: $h2-font-size;
@@ -86,7 +238,8 @@
     line-height: $h2-line-height;
   }
 
-  h3 {
+  // h3
+  #{defaults.$h3-selector-base}#{defaults.$h3-selector} {
     color: $h3-color;
     font-family: $h3-font-family;
     font-size: $h3-font-size;
@@ -94,7 +247,8 @@
     line-height: $h3-line-height;
   }
 
-  h4 {
+  // h4
+  #{defaults.$h4-selector-base}#{defaults.$h4-selector} {
     color: $h4-color;
     font-family: $h4-font-family;
     font-size: $h4-font-size;
@@ -102,7 +256,8 @@
     line-height: $h4-line-height;
   }
 
-  h5 {
+  // h5
+  #{defaults.$h5-selector-base}#{defaults.$h5-selector} {
     color: $h5-color;
     font-family: $h5-font-family;
     font-size: $h5-font-size;
@@ -110,7 +265,8 @@
     line-height: $h5-line-height;
   }
 
-  h6 {
+  // h6
+  #{defaults.$h6-selector-base}#{defaults.$h6-selector} {
     color: $h6-color;
     font-family: $h6-font-family;
     font-size: $h6-font-size;