From ee91fb345a53ed704619807c8537217e2a337e58 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Mon, 20 Nov 2023 11:38:32 +0100 Subject: [PATCH 1/6] Add examples and structure to docs on typography --- proprietary/assets/font/index.css | 5 + storybook/storybook-docs/src/grid.stories.mdx | 2 +- .../storybook-docs/src/typography.stories.mdx | 186 +++++++++++++----- 3 files changed, 145 insertions(+), 48 deletions(-) diff --git a/proprietary/assets/font/index.css b/proprietary/assets/font/index.css index 7ec8b8806f..86f5c2b165 100644 --- a/proprietary/assets/font/index.css +++ b/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"; diff --git a/storybook/storybook-docs/src/grid.stories.mdx b/storybook/storybook-docs/src/grid.stories.mdx index 2e01b12d28..ccf5efa320 100644 --- a/storybook/storybook-docs/src/grid.stories.mdx +++ b/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. diff --git a/storybook/storybook-docs/src/typography.stories.mdx b/storybook/storybook-docs/src/typography.stories.mdx index a3fdd79d44..4cf6d3c9b5 100644 --- a/storybook/storybook-docs/src/typography.stories.mdx +++ b/storybook/storybook-docs/src/typography.stories.mdx @@ -1,4 +1,4 @@ -import { Meta } from "@storybook/blocks"; +import { Meta, Typeset } from "@storybook/blocks"; @@ -6,79 +6,155 @@ import { Meta } from "@storybook/blocks"; ## 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 + -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. + + +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: + + +Tekst wordt vetgedrukt in titels en decoratieve citaten. + + + +### 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. + -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. + + + +### 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 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. -De Nederlandse taal kent veel lange woorden, zoals 'gemeenteraadsverkiezingen'. +### 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,27 @@ 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. + +In andere gevallen installeer je Amsterdam Sans op 1 van deze 2 manieren: + +1. Kopieer [deze regels CSS](https://amsterdam.nl/publish/pages/1007152/amsterdam_sans_v_0_9.css) naar je applicatie. + Het maakt gebruik van ons snelle CDN. + Dit levert korte laadtijden voor bezoekers. +2. Installeer het npm-pakket `@amsterdam/design-system-assets` en importeer `@amsterdam/design-system-assets/font/index.css` in je applicatie. + +Als het niet mogelijk is Amsterdam Sans te gebruiken pas je het lettertype Arial toe, of het generieke sans-serif lettertype van het apparaat. + +### 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/). From 36c991e0712d63a987dc2b8048ef15b1c0b920b0 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Mon, 20 Nov 2023 13:29:44 +0100 Subject: [PATCH 2/6] Override Storybook typography and margins --- .../storybook-docs/config/preview-head.html | 43 +++++++++++++++++++ .../storybook-react/config/preview-head.html | 43 +++++++++++++++++++ 2 files changed, 86 insertions(+) diff --git a/storybook/storybook-docs/config/preview-head.html b/storybook/storybook-docs/config/preview-head.html index e551040105..6fcf56121b 100644 --- a/storybook/storybook-docs/config/preview-head.html +++ b/storybook/storybook-docs/config/preview-head.html @@ -1,3 +1,46 @@ + + diff --git a/storybook/storybook-react/config/preview-head.html b/storybook/storybook-react/config/preview-head.html index e551040105..6fcf56121b 100644 --- a/storybook/storybook-react/config/preview-head.html +++ b/storybook/storybook-react/config/preview-head.html @@ -1,3 +1,46 @@ + + From 80809c3a6c87c4c7120b32fdb59c66ca292b1477 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Mon, 20 Nov 2023 23:53:35 +0100 Subject: [PATCH 3/6] Extract single stylesheet --- .../storybook-docs/config/preview-head.html | 43 ------------------ storybook/storybook-docs/config/preview.tsx | 1 + storybook/storybook-overrides.css | 44 +++++++++++++++++++ .../storybook-react/config/preview-head.html | 43 ------------------ storybook/storybook-react/config/preview.tsx | 1 + 5 files changed, 46 insertions(+), 86 deletions(-) create mode 100644 storybook/storybook-overrides.css diff --git a/storybook/storybook-docs/config/preview-head.html b/storybook/storybook-docs/config/preview-head.html index 6fcf56121b..e551040105 100644 --- a/storybook/storybook-docs/config/preview-head.html +++ b/storybook/storybook-docs/config/preview-head.html @@ -1,46 +1,3 @@ - - diff --git a/storybook/storybook-docs/config/preview.tsx b/storybook/storybook-docs/config/preview.tsx index 30ec671a86..18db9f8326 100644 --- a/storybook/storybook-docs/config/preview.tsx +++ b/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].*' }, diff --git a/storybook/storybook-overrides.css b/storybook/storybook-overrides.css new file mode 100644 index 0000000000..ec94bd01a9 --- /dev/null +++ b/storybook/storybook-overrides.css @@ -0,0 +1,44 @@ +/* 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) { + font-size: 16px; + line-height: 1.75; +} + +.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: 0; + padding-block: 0; +} + +.sbdocs-content h1 { + margin-block: 1.5em; +} + +.sbdocs-content h2 { + margin-block: 1.5em 0.5em; +} + +.sbdocs-content :is(h3, h4, h5, h6) { + margin-block: 0.25em; +} + +.sbdocs-content :is(p, ul, ol) { + margin-block-end: 1em; +} + +/* stylelint-enable */ diff --git a/storybook/storybook-react/config/preview-head.html b/storybook/storybook-react/config/preview-head.html index 6fcf56121b..e551040105 100644 --- a/storybook/storybook-react/config/preview-head.html +++ b/storybook/storybook-react/config/preview-head.html @@ -1,46 +1,3 @@ - - diff --git a/storybook/storybook-react/config/preview.tsx b/storybook/storybook-react/config/preview.tsx index 9eee3d011a..4ffebcd38f 100644 --- a/storybook/storybook-react/config/preview.tsx +++ b/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 = { From 1f134bc122bc03712792585c68335e9f40513151 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Tue, 21 Nov 2023 00:07:44 +0100 Subject: [PATCH 4/6] Increase whitespace, make intro paragraph larger --- storybook/storybook-overrides.css | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/storybook/storybook-overrides.css b/storybook/storybook-overrides.css index ec94bd01a9..e7b2cdf4ed 100644 --- a/storybook/storybook-overrides.css +++ b/storybook/storybook-overrides.css @@ -6,10 +6,14 @@ } .sbdocs-content :is(p, li, a) { - font-size: 16px; + font-size: 1rem; line-height: 1.75; } +.sbdocs-content h1 + p { + font-size: 1.25rem; +} + .sbdocs-content a { color: #004699; text-decoration: underline; @@ -21,24 +25,28 @@ } .sbdocs-content :is(h1, h2, h3, h4, h5, h6, p, ul, ol) { - margin-block: 0; + margin-block: 1rem 0.25rem !important; padding-block: 0; } .sbdocs-content h1 { - margin-block: 1.5em; + margin-block: 2rem !important; } .sbdocs-content h2 { - margin-block: 1.5em 0.5em; + margin-block-start: 2rem !important; +} + +.sbdocs-content h3 { + margin-block-start: 1.5rem !important; } -.sbdocs-content :is(h3, h4, h5, h6) { - margin-block: 0.25em; +.sbdocs-content h4 { + margin-block-start: 1rem !important; } .sbdocs-content :is(p, ul, ol) { - margin-block-end: 1em; + margin-block: 0 1rem !important; } /* stylelint-enable */ From dbf304985068acb4122a91854142de33ff9aed12 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Tue, 21 Nov 2023 09:48:58 +0100 Subject: [PATCH 5/6] Stop overrides from affecting stories --- storybook/storybook-overrides.css | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/storybook/storybook-overrides.css b/storybook/storybook-overrides.css index e7b2cdf4ed..9a758620db 100644 --- a/storybook/storybook-overrides.css +++ b/storybook/storybook-overrides.css @@ -1,51 +1,52 @@ /* stylelint-disable */ -.sbdocs-content :is(h1, h2, h3, h4, h5, h6, p, li) { +.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(p, li, a), +.sbdocs-content > :is(ol, ul) li { font-size: 1rem; line-height: 1.75; } -.sbdocs-content h1 + p { +.sbdocs-content > h1 + p { font-size: 1.25rem; } -.sbdocs-content a { +.sbdocs-content > a { color: #004699; text-decoration: underline; } -.sbdocs-content a:hover { +.sbdocs-content > a:hover { color: #102e62; text-decoration-thickness: 2px; } -.sbdocs-content :is(h1, h2, h3, h4, h5, h6, p, ul, ol) { +.sbdocs-content > :is(h1, h2, h3, h4, h5, h6, p, ul, ol) { margin-block: 1rem 0.25rem !important; padding-block: 0; } -.sbdocs-content h1 { +.sbdocs-content > h1 { margin-block: 2rem !important; } -.sbdocs-content h2 { - margin-block-start: 2rem !important; +.sbdocs-content > h2 { + margin-block: 2rem 1rem !important; } -.sbdocs-content h3 { +.sbdocs-content > h3 { margin-block-start: 1.5rem !important; } -.sbdocs-content h4 { +.sbdocs-content > h4 { margin-block-start: 1rem !important; } -.sbdocs-content :is(p, ul, ol) { +.sbdocs-content > :is(p, ul, ol) { margin-block: 0 1rem !important; } From 5dd6c162d82fa984565a76bcd58d23ee53a8f262 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Tue, 21 Nov 2023 10:00:39 +0100 Subject: [PATCH 6/6] =?UTF-8?q?Remove=20mention=20of=20=E2=80=98CDN?= =?UTF-8?q?=E2=80=99=20if=20it=E2=80=99s=20just=20amsterdam.nl?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- storybook/storybook-docs/src/typography.stories.mdx | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/storybook/storybook-docs/src/typography.stories.mdx b/storybook/storybook-docs/src/typography.stories.mdx index 4cf6d3c9b5..6ffc5a33b5 100644 --- a/storybook/storybook-docs/src/typography.stories.mdx +++ b/storybook/storybook-docs/src/typography.stories.mdx @@ -175,14 +175,11 @@ Voor verdere informatie: [Wrapping and breaking text op MDN](https://developer.m Als je de React-componenten gebruikt hoef je niets te doen. Deze gebruiken allemaal het juiste lettertype. -In andere gevallen installeer je Amsterdam Sans op 1 van deze 2 manieren: +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`. -1. Kopieer [deze regels CSS](https://amsterdam.nl/publish/pages/1007152/amsterdam_sans_v_0_9.css) naar je applicatie. - Het maakt gebruik van ons snelle CDN. - Dit levert korte laadtijden voor bezoekers. -2. Installeer het npm-pakket `@amsterdam/design-system-assets` en importeer `@amsterdam/design-system-assets/font/index.css` in je applicatie. - -Als het niet mogelijk is Amsterdam Sans te gebruiken pas je het lettertype Arial toe, of het generieke sans-serif lettertype van het apparaat. +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