Amsterdam · alimpens · Mar 26, 2024 · Mar 14, 2024 · Mar 20, 2024 · Mar 20, 2024
diff --git a/packages/css/README.md b/packages/css/README.md
@@ -49,3 +49,25 @@ To use the compact mode, import the compact css **after** theme css, like so:
 import "@amsterdam/design-system-tokens/dist/index.css";
 import "@amsterdam/design-system-tokens/dist/compact.css";
 ```
+
+## Global styles
+
+Some elements of your document are out of reach for the Design System components.
+However, their styles can influence the appearance of the components.
+
+### Base font size
+
+Do not change the base font-size – e.g. through `html { font-size: 62.5% }`.
+This interferes with users choosing a different default font size in their browser.
+Out typography system also expects `1rem` to be the browser default of 16 pixels.
+
+If your application does use a rule like this and you can’t easily remove it, you may adopt the Design System components gradually by setting `font-size: 100%` on the parts that use them.
+
+### Remove body margin
+
+If you haven’t removed the margin on the `<body>` element that browsers set by default, you can add our `ams-body` to it to do so.
+
+### Use our extra bold font weight
+
+We only use the regular and extra bold weights of our font, Amsterdam Sans.
+Apply `font-weight: var(--ams-text-font-weight-bold)` to elements that display bold text, e.g. `b`, `strong`, and `dt`.
diff --git a/packages/css/documentation/coding-conventions.md b/packages/css/documentation/coding-conventions.md
@@ -35,3 +35,11 @@ Still, we define its thickness and offset for the initial state.
   }
 }
 ```
+
+## Use mixins for patterns and resets
+
+We use Sass mixins to extract common patterns, especially if they need more than 1 declaration.
+We collect reset styles in mixins as well.
+Both the name of the mixins and their documentation help explain the approach.
+Mixins sit at the end of the declaration block to ensure their effect.
+The general ‘reset’ mixin is the very last.
diff --git a/packages/css/src/common/text-rendering.scss b/packages/css/src/common/text-rendering.scss
@@ -0,0 +1,15 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+/**
+ * Prioritizes legibility over speed when rendering text
+ * and disables text inflation on some mobile devices.
+ */
+@mixin text-rendering {
+  text-rendering: optimizeLegibility;
+  -moz-text-size-adjust: none;
+  -webkit-text-size-adjust: none;
+  text-size-adjust: none;
+}
diff --git a/packages/css/src/components/accordion/accordion.scss b/packages/css/src/components/accordion/accordion.scss
@@ -3,16 +3,14 @@
  * Copyright Gemeente Amsterdam
  */
 
+@import "../../common/text-rendering";
+
 .ams-accordion__header {
   display: flex;
   margin-block: 0;
   margin-inline: 0;
 }
 
-@mixin reset {
-  -webkit-text-size-adjust: 100%;
-}
-
 .ams-accordion__button {
   background-color: transparent;
   border: 0;
@@ -45,7 +43,7 @@
     }
   }
 
-  @include reset;
+  @include text-rendering;
 }
 
 .ams-accordion__button[aria-expanded="true"] svg {

diff --git a/packages/css/src/components/blockquote/blockquote.scss b/packages/css/src/components/blockquote/blockquote.scss
@@ -4,12 +4,12 @@
  */
 
 @import "../../common/hyphenation";
+@import "../../common/text-rendering";
 
 @mixin reset {
   box-sizing: border-box;
   margin-block: 0;
   margin-inline: 0;
-  -webkit-text-size-adjust: 100%;
 }
 
 .ams-blockquote {
@@ -30,6 +30,7 @@
   }
 
   @include hyphenation;
+  @include text-rendering;
   @include reset;
 }
 

diff --git a/packages/css/src/components/breadcrumb/breadcrumb.scss b/packages/css/src/components/breadcrumb/breadcrumb.scss
@@ -3,11 +3,12 @@
  * Copyright Gemeente Amsterdam
  */
 
+@import "../../common/text-rendering";
+
 @mixin reset {
   box-sizing: border-box;
   margin-block: 0;
   padding-inline: 0;
-  -webkit-text-size-adjust: 100%;
 }
 
 .ams-breadcrumb {
@@ -21,6 +22,7 @@
   break-after: avoid;
   break-inside: avoid;
 
+  @include text-rendering;
   @include reset;
 }
 

diff --git a/packages/css/src/components/button/button.scss b/packages/css/src/components/button/button.scss
@@ -3,9 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-@mixin reset {
-  -webkit-text-size-adjust: 100%;
-}
+@import "../../common/text-rendering";
 
 .ams-button {
   border: none;
@@ -25,7 +23,7 @@
     cursor: var(--ams-button-disabled-cursor);
   }
 
-  @include reset;
+  @include text-rendering;
 }
 
 @mixin ams-button-forced-color-mode {

diff --git a/packages/css/src/components/checkbox/checkbox.scss b/packages/css/src/components/checkbox/checkbox.scss
@@ -5,6 +5,7 @@
 
 @import "../../common/input-label-focus";
 @import "../../common/hide-input";
+@import "../../common/text-rendering";
 
 .ams-checkbox__input {
   @include hide-input;
@@ -32,10 +33,6 @@
   }
 }
 
-@mixin reset {
-  -webkit-text-size-adjust: 100%;
-}
-
 .ams-checkbox__label {
   color: var(--ams-checkbox-color);
   cursor: pointer;
@@ -59,7 +56,7 @@
     }
   }
 
-  @include reset;
+  @include text-rendering;
 }
 
 // Default checked

diff --git a/packages/css/src/components/document/document.scss b/packages/css/src/components/document/document.scss
@@ -0,0 +1,14 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+@mixin reset-body {
+  margin-block: 0;
+  margin-inline: 0;
+}
+
+// Add this class if you haven’t removed the default margin on the `<body>` element.
+.ams-body {
+  @include reset-body;
+}
diff --git a/packages/css/src/components/fieldset/fieldset.scss b/packages/css/src/components/fieldset/fieldset.scss
@@ -4,6 +4,7 @@
  */
 
 @import "../../common/hyphenation";
+@import "../../common/text-rendering";
 
 @mixin reset {
   border: none;
@@ -16,9 +17,8 @@
   @include reset;
 }
 
-@mixin legend-reset {
+@mixin reset-legend {
   padding-inline: 0;
-  -webkit-text-size-adjust: 100%;
 }
 
 .ams-fieldset__legend {
@@ -30,5 +30,6 @@
   margin-block-end: 1rem; /* Because of a bug in Chrome we can’t use display grid or flex for this gap */
 
   @include hyphenation;
-  @include legend-reset;
+  @include text-rendering;
+  @include reset-legend;
 }
diff --git a/packages/css/src/components/form-field-character-counter/form-field-character-counter.scss b/packages/css/src/components/form-field-character-counter/form-field-character-counter.scss
@@ -3,9 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-@mixin reset {
-  -webkit-text-size-adjust: 100%;
-}
+@import "../../common/text-rendering";
 
 .ams-form-field-character-counter {
   color: var(--ams-form-field-character-counter-color);
@@ -14,7 +12,7 @@
   font-weight: var(--ams-form-field-character-counter-font-weight);
   line-height: var(--ams-form-field-character-counter-line-height);
 
-  @include reset;
+  @include text-rendering;
 }
 
 .ams-form-field-character-counter--error {

diff --git a/packages/css/src/components/form-label/form-label.scss b/packages/css/src/components/form-label/form-label.scss
@@ -4,10 +4,7 @@
  */
 
 @import "../../common/hyphenation";
-
-@mixin reset {
-  -webkit-text-size-adjust: 100%;
-}
+@import "../../common/text-rendering";
 
 .ams-form-label {
   color: var(--ams-form-label-color);
@@ -17,5 +14,5 @@
   line-height: var(--ams-form-label-line-height);
 
   @include hyphenation;
-  @include reset;
+  @include text-rendering;
 }
diff --git a/packages/css/src/components/heading/heading.scss b/packages/css/src/components/heading/heading.scss
@@ -4,11 +4,11 @@
  */
 
 @import "../../common/hyphenation";
+@import "../../common/text-rendering";
 
 @mixin reset {
   box-sizing: border-box;
   margin-block: 0;
-  -webkit-text-size-adjust: 100%;
 }
 
 .ams-heading {
@@ -19,6 +19,7 @@
   font-weight: var(--ams-heading-font-weight);
 
   @include hyphenation;
+  @include text-rendering;
   @include reset;
 }
 

diff --git a/packages/css/src/components/index.scss b/packages/css/src/components/index.scss
@@ -4,6 +4,7 @@
  */
 
 /* Append here */
+@import "./document/document";
 @import "./avatar/avatar";
 @import "./form-field-character-counter/form-field-character-counter";
 @import "./row/row";

diff --git a/packages/css/src/components/link-list/link-list.scss b/packages/css/src/components/link-list/link-list.scss
@@ -4,20 +4,21 @@
  */
 
 @import "../../common/hyphenation";
+@import "../../common/text-rendering";
 
 @mixin reset-list {
   box-sizing: border-box;
   list-style: none;
   margin-block: 0;
   padding-inline-start: 0;
-  -webkit-text-size-adjust: 100%;
 }
 
 .ams-link-list {
-  @include reset-list;
-
   display: grid;
   gap: var(--ams-link-list-gap);
+
+  @include text-rendering;
+  @include reset-list;
 }
 
 .ams-link-list__link {

diff --git a/packages/css/src/components/link/link.scss b/packages/css/src/components/link/link.scss
@@ -3,9 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-@mixin reset {
-  -webkit-text-size-adjust: 100%;
-}
+@import "../../common/text-rendering";
 
 .ams-link {
   color: var(--ams-link-color);
@@ -17,7 +15,7 @@
     color: var(--ams-link-hover-color);
   }
 
-  @include reset;
+  @include text-rendering;
 }
 
 .ams-link--standalone {

diff --git a/packages/css/src/components/ordered-list/ordered-list.scss b/packages/css/src/components/ordered-list/ordered-list.scss
@@ -3,21 +3,23 @@
  * Copyright Gemeente Amsterdam
  */
 
+@import "../../common/text-rendering";
+
 /** Apply border box sizing, reset white space and list styles. */
 @mixin reset {
   box-sizing: border-box;
   list-style-type: none;
   margin-block: 0;
   padding-inline-start: 0;
-  -webkit-text-size-adjust: 100%;
 }
 
 /** A list is a grid column with a gap between items. */
 .ams-ordered-list {
-  @include reset;
-
   display: grid;
   gap: var(--ams-ordered-list-gap);
+
+  @include text-rendering;
+  @include reset;
 }
 
 /** A list with markers sets typography for its text content. */

diff --git a/packages/css/src/components/page-heading/page-heading.scss b/packages/css/src/components/page-heading/page-heading.scss
@@ -4,11 +4,11 @@
  */
 
 @import "../../common/hyphenation";
+@import "../../common/text-rendering";
 
 @mixin reset {
   box-sizing: border-box;
   margin-block: 0;
-  -webkit-text-size-adjust: 100%;
 }
 
 .ams-page-heading {
@@ -21,6 +21,7 @@
   line-height: var(--ams-page-heading-line-height);
 
   @include hyphenation;
+  @include text-rendering;
   @include reset;
 }