Update typography docs and Storybook theming

proprietary/assets/font/index.css

@@ -15,6 +15,7 @@
     url("./woff2/AmsterdamSans-Light.woff2") format("woff2"),
     url("./woff/AmsterdamSans-Light.woff") format("woff");
 }
+
 @font-face {
   font-display: swap;
   font-family: "Amsterdam Sans";
@@ -26,6 +27,7 @@
     url("./woff2/AmsterdamSans-Regular.woff2") format("woff2"),
     url("./woff/AmsterdamSans-Regular.woff") format("woff");
 }
+
 @font-face {
   font-display: swap;
   font-family: "Amsterdam Sans";
@@ -37,6 +39,7 @@
     url("./woff2/AmsterdamSans-Italic.woff2") format("woff2"),
     url("./woff/AmsterdamSans-Italic.woff") format("woff");
 }
+
 @font-face {
   font-display: swap;
   font-family: "Amsterdam Sans";
@@ -48,6 +51,7 @@
     url("./woff2/AmsterdamSans-Bold.woff2") format("woff2"),
     url("./woff/AmsterdamSans-Bold.woff") format("woff");
 }
+
 @font-face {
   font-display: swap;
   font-family: "Amsterdam Sans";
@@ -59,6 +63,7 @@
     url("./woff2/AmsterdamSans-BoldItalic.woff2") format("woff2"),
     url("./woff/AmsterdamSans-BoldItalic.woff") format("woff");
 }
+
 @font-face {
   font-display: swap;
   font-family: "Amsterdam Sans";

storybook/storybook-docs/config/preview.tsx

@@ -1,5 +1,6 @@
 import '@amsterdam/design-system-tokens/dist/root.css'
 import '@amsterdam/design-system-assets/font/index.css'
+import '../../storybook-overrides.css'
 
 export const parameters = {
   actions: { argTypesRegex: '^on[A-Z].*' },

storybook/storybook-docs/src/grid.stories.mdx

@@ -164,7 +164,7 @@ In het grid zijn dus zowel de breedte van de kolommen, de witruimtes als de marg
 Ook de [tekstgroottes](?path=/docs/docs-designrichtlijnen-typografie--docs) reageren op de vensterbreedte.
 Dat zorgt ervoor dat content op zo veel mogelijk vensterbreedtes en met diverse persoonlijke instellingen goed tot zijn recht komt.
 
-Op dit moment reageert de typografie nog op één breakpoint bij een vensterbreedte van 854 pixels.
+Op dit moment reageert de typografie nog op 1 breakpoint bij een vensterbreedte van 854 pixels.
 Nu het grid doorontwikkeld is, stemmen we de typografie daar weer op af.
 Dit aparte breakpoint komt dus snel te vervallen.
 

storybook/storybook-docs/src/typography.stories.mdx

@@ -1,84 +1,160 @@
-import { Meta } from "@storybook/blocks";
+import { Meta, Typeset } from "@storybook/blocks";
 
 <Meta title="Docs/Designrichtlijnen/Typografie" />
 
 # Typografie
 
 ## Lettertype
 
-We gebruiken het lettertype Amsterdam Sans.
-De _fallback_ lettertypes zijn Arial en sans-serif.
+De gemeente gebruikt de Amsterdam Sans als beeldbepalend lettertype.
 
-We gebruiken 2 varianten:
+Dat is een letterfamilie met een helder, open tekstbeeld dat goed bij de Andreaskruisen past.
+Het lettertype is zowel offline als online goed leesbaar.
+Daarom wordt het in alle communicatiemiddelen ingezet.
 
-- Amsterdam Sans Regular
-- Amsterdam Sans ExtraBold
+Deze zin demonstreert alle letters van het Latijnse alfabet en cijfers in de Amsterdam Sans:
 
-## Fluïde typografie
+<Typeset
+  fontFamily="Amsterdam Sans, Arial, sans-serif"
+  fontSizes={[24]}
+  fontWeight={400}
+  sampleText="Jouw typograaf biedt mij zulke exquise schreven 012345689"
+/>
 
-Online gebruiken we fluïde typografie, wat inhoudt dat de grootte van de tekst afhankelijk is van de breedte van het scherm of venster van de gebruiker.
-Hoe breder het venster, des te groter wordt de tekst.
-Hiermee zorgen we ervoor dat de tekst er in vensters van alle breedtes goed uitziet.
+## Tekstgrootte
 
-### Tekstniveaus
+De grootte van de tekst is afhankelijk van de breedte van het venster.
+Hiermee zorgen we ervoor dat tekst op schermen van alle afmetingen prettig leesbaar is.
 
-We hebben 8 tekstniveaus gedefinieerd.
+Er zijn 8 niveaus van tekstgrootte en bijbehorende regelhoogte.
 Alle typografische componenten maken er gebruik van.
+Dit overzicht toont de maximale tekstgrootte voor elk niveau.
 
-Een tekstniveau definieert de tekstgrootte op de minimale vensterbreedte (320 pixels) waaronder de tekst niet kleiner wordt, de tekstgrootte op de maximale vensterbreedte (1440 pixels) waarboven de tekst niet groter wordt, de tekst op het breekpunt (854 pixels) en de regelhoogte.
-De tekstgrootte op het breekpunt is de minimale waarde + 2/3 van het verschil tussen de minimale en maximale waarde.
+<Typeset
+  fontFamily="Amsterdam Sans, Arial, sans-serif"
+  fontSizes={[80, 56, 40, 32, 28, 25, 22, 18]}
+  fontWeight={400}
+  sampleText="Jouw typograaf biedt mij zulke exquise schreven"
+/>
+
+Elk tekstniveau heeft een minimale tekstgrootte (bij een vensterbreedte van 320 pixels) en een maximale (bij 1440 pixels).
+Tussen beide stijgt de tekst linear, met een knik op een extra breakpoint van 854 pixels.
+Eerst stijgt de grootte sneller, daarna langzamer.
+
+Op dit moment reageert de typografie nog op 1 breakpoint bij een vensterbreedte van 854 pixels.
+Nu het grid doorontwikkeld is, stemmen we de typografie daar weer op af.
+Dit aparte breakpoint komt dus snel te vervallen.
 
 In de tabel hieronder vind je deze waardes in pixels:
 
-| niveau                     |   0 |   1 |   2 |   3 |   4 |   5 |   6 |   7 |
+| Niveau                     |   0 |   1 |   2 |   3 |   4 |   5 |   6 |   7 |
 | :------------------------- | --: | --: | --: | --: | --: | --: | --: | --: |
 | minimale tekstgrootte      |  32 |  32 |  28 |  24 |  20 |  22 |  18 |  16 |
 | tekstgrootte op breakpoint |  64 |  48 |  36 |  29 |  23 |  26 |  21 |  17 |
 | maximale tekstgrootte      |  80 |  56 |  40 |  32 |  25 |  28 |  22 |  18 |
 | relatieve regelhoogte      | 1.1 | 1.2 | 1.3 | 1.4 | 1.4 | 1.5 | 1.6 | 1.6 |
 
+Tekst op niveau 5 is groter dan op niveau 4.
+Dat is omdat titel niveau 4 kleinere letters heeft dan paragrafen met grote letters.
+Het alternatief om Heading 4 tekstniveau 5 te geven leek ons nog verwarrender.
+
 Voorbeelden van componenten en hun tekstniveaus:
 
-| level | componenten                          |
-| ----: | :----------------------------------- |
-|     0 | Page heading                         |
-|     1 | Heading 1                            |
-|     2 | Heading 2                            |
-|     3 | Heading 3, Blockquote                |
-|     4 | Heading 4, Top Task Link             |
-|     5 | Paragraph large                      |
-|     6 | Paragraph, alle Links behalve inList |
-|     7 | Paragraph small, inList Link         |
+| Componenten                                          | Niveau |
+| :--------------------------------------------------- | -----: |
+| Page heading                                         |      0 |
+| Heading 1                                            |      1 |
+| Heading 2                                            |      2 |
+| Heading 3, Blockquote                                |      3 |
+| Heading 4, Top Task Link                             |      4 |
+| Large Paragraph, Alert Title                         |      5 |
+| Paragraph, Button, Link behalve InList               |      6 |
+| Small Paragraph, InList Link, Form Label, Breadcrumb |      7 |
 
-## Contrast
+## Accentuering
 
-Het contrast tussen tekst en achtergrondkleur moet voldoen aan [de laatste wettelijke toegankelijkheidseisen van de WCAG-niveau AA](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html).
+Er zijn verschillende manieren om tekst te accentueren.
+Hierin hebben we de volgende keuzes gemaakt.
 
-## Uitlijning
+### Gewicht
 
-Het aantal karakters op een regel is maximaal 80.
-En de tekst wordt altijd links uitgelijnd.
-Dit is vanwege leesbaarheid.
+Online gebruiken we 2 gewichten: ‘regular’ en ‘extra bold’.
 
-Uitzonderingen:
+<Typeset
+  fontFamily="Amsterdam Sans, Arial, sans-serif"
+  fontSizes={[24]}
+  fontWeight={400}
+  sampleText="Jouw typograaf biedt mij zulke exquise schreven"
+/>
+
+Tekst wordt vetgedrukt in titels en decoratieve citaten.
+
+<Typeset
+  fontFamily="Amsterdam Sans, Arial, sans-serif"
+  fontSizes={[24]}
+  fontWeight={800}
+  sampleText="Jouw typograaf biedt mij zulke exquise schreven"
+/>
+
+### Stijl
 
-- Op knoppen worden labels gecentreerd.
-- In tabellen kan de inhoud van kolommen, afhankelijk van de inhoud, ook gecentreerd of rechts uitgelijnd worden.
+Gebruik de cursieve weergave uitsluitend om fragmenten in tekst te accentueren.
+Cursieve tekst is minder goed leesbaar dan reguliere of vetgedrukte tekst.
 
-## Vormgeving
+Pas het niet toe op hele tekstblokken.
+Er zijn betere manieren om lange teksten nadruk te geven.
 
-Vermijd zo veel mogelijk cursieve teksten, deze zijn niet goed te lezen op sommige beeldschermen.
-Gebruik ze uitsluitend om tekst te accentueren, niet voor hele tekstblokken.
+<Typeset
+  fontFamily="Amsterdam Sans, Arial, sans-serif"
+  fontSizes={[24]}
+  sampleText="Jouw typograaf biedt mij zulke exquise schreven"
+  style={{ fontStyle: "italic" }}
+/>
 
-Vermijd het onderlijnen van tekst.
-Reserveer het onderlijnen van tekst voor interactieve links.
+### Onderstreping
+
+Uitsluitend de tekst van een hyperlink wordt onderstreept.
+Rond staartletters wordt de lijn onderbroken voor betere leesbaarheid.
+
+Onderstreepte tekst zonder hyperlink geeft toch de suggestie van een link.
+Dat is verwarrend en daarom niet toegestaan.
+Gebruik een andere manier om te accentueren.
+
+<Typeset
+  fontFamily="Amsterdam Sans, Arial, sans-serif"
+  fontSizes={[24]}
+  sampleText="Jouw typograaf biedt mij zulke exquise schreven"
+  style={{ color: "#004699", textDecoration: "underline" }}
+/>
+
+### Overhang
 
 De ruimte tussen letters (kerning) is geoptimaliseerd in het lettertype.
 Het is niet toegestaan om de kerning aan te passen.
 
-## Woorden afbreken
+## Andere eigenschappen
+
+### Contrast
+
+Het contrast tussen tekst en achtergrondkleur moet voldoen aan de laatste wettelijke toegankelijkheidseisen van [de WCAG, niveau AA](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html).
 
-De Nederlandse taal kent veel lange woorden, zoals 'gemeenteraadsverkiezingen'.
+De meeste tekst in het design system is puur zwart op puur wit en dat voldoet daar ruim aan.
+Op de meeste donkere achtergronden maken we tekst wit; ook dat biedt voldoende contrast.
+Voor sommige achtergrondkleuren is ook zwarte tekst goed leesbaar.
+Raadpleeg de betreffende componenten voor specifieke richtlijnen.
+
+### Uitlijning
+
+Tekst wordt nagenoeg altijd links uitgelijnd.
+
+Uitzonderingen:
+
+1. Het label van een knop wordt gecentreerd.
+2. In een tabel kan het beter zijn tekst te centreren of rechts uit te lijnen.
+
+### Woordafbreking
+
+De Nederlandse taal kent veel lange woorden, zoals ‘gemeenteraadsverkiezingen’.
 Zorg er in je applicatie voor dat deze woorden netjes afgebroken worden en niet uit hun container breken of verborgen worden.
 Een manier om dat te doen is met de volgende _css snippet_, waarin `hyphens` en `word-break` gecombineerd worden:
 
@@ -94,11 +170,24 @@ Een manier om dat te doen is met de volgende _css snippet_, waarin `hyphens` en
 
 Voor verdere informatie: [Wrapping and breaking text op MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_text/Wrapping_breaking_text)
 
-## Hoe te gebruiken?
+## Het lettertype installeren
+
+Als je de React-componenten gebruikt hoef je niets te doen.
+Deze gebruiken allemaal het juiste lettertype.
+
+Werk je met andere technologie, maar wel met npm, dan installeer je `@amsterdam/design-system-assets` en importeer je `@amsterdam/design-system-assets/font/index.css`.
+
+Ook kun je het lettertype zelf hosten en opnemen in je applicatie, vraag het dan aan via het formulier hieronder.
+Als het helemaal niet mogelijk is Amsterdam Sans te gebruiken pas je het lettertype Arial toe, of het generieke sans-serif lettertype van het apparaat.
+In alle gevallen voer je die alternatieven op voor als het downloaden van het font voor de gebruiker niet lukt, of terwijl dat bezig is: `font-family: "'Amsterdam Sans', Arial, sans-serif"`.
+
+### Licentie en aanvraag
+
+Het lettertype is uitdrukkelijk niet vrij beschikbaar.
+Amsterdam Sans is uitsluitend te gebruiken door medewerkers van de gemeente Amsterdam en amsterdam&partners, en door leveranciers werkend voor deze organisaties.
+
+Vraag de lettertypebestanden aan via het formulier [Amsterdam Sans aanvragen](https://formulier.amsterdam.nl/thema/huisstijl/amsterdam-sans-aanvragen).
 
-Er zijn twee manieren om Amsterdam Sans te gebruiken in je applicatie:
+## Meer informatie
 
-- Download en gebruik [deze css](https://amsterdam.nl/publish/pages/1007152/amsterdam_sans_v_0_9.css) in je applicatie om het juiste lettertype in te laden.
-  Dit levert de snelste laadtijden voor bezoekers.
-  Het maakt gebruik van ons snelle CDN.
-- Installeer het NPM pakket `@amsterdam/design-system-assets` en importeer `@amsterdam/design-system-assets/font/index.css` in je applicatie.
+- Alle informatie over het lettertype vind je op de pagina [Typografie op Stijlweb](https://amsterdam.nl/stijlweb/basiselementen/typografie/).

storybook/storybook-overrides.css

@@ -0,0 +1,53 @@
+/* stylelint-disable */
+
+.sbdocs-content > :is(h1, h2, h3, h4, h5, h6, p, li) {
+  color: #000000;
+  font-family: "Amsterdam Sans", Arial, sans-serif;
+}
+
+.sbdocs-content > :is(p, li, a),
+.sbdocs-content > :is(ol, ul) li {
+  font-size: 1rem;
+  line-height: 1.75;
+}
+
+.sbdocs-content > h1 + p {
+  font-size: 1.25rem;
+}
+
+.sbdocs-content > a {
+  color: #004699;
+  text-decoration: underline;
+}
+
+.sbdocs-content > a:hover {
+  color: #102e62;
+  text-decoration-thickness: 2px;
+}
+
+.sbdocs-content > :is(h1, h2, h3, h4, h5, h6, p, ul, ol) {
+  margin-block: 1rem 0.25rem !important;
+  padding-block: 0;
+}
+
+.sbdocs-content > h1 {
+  margin-block: 2rem !important;
+}
+
+.sbdocs-content > h2 {
+  margin-block: 2rem 1rem !important;
+}
+
+.sbdocs-content > h3 {
+  margin-block-start: 1.5rem !important;
+}
+
+.sbdocs-content > h4 {
+  margin-block-start: 1rem !important;
+}
+
+.sbdocs-content > :is(p, ul, ol) {
+  margin-block: 0 1rem !important;
+}
+
+/* stylelint-enable */

storybook/storybook-react/config/preview.tsx

@@ -1,6 +1,7 @@
 import '@amsterdam/design-system-tokens/dist/root.css'
 import '@amsterdam/design-system-assets/font/index.css'
 import '@amsterdam/design-system-css/dist/index.css'
+import '../../storybook-overrides.css'
 import { viewports } from './viewports'
 
 export const parameters = {