@utrecht/root-css

v4.1.1

Published

15 days ago

Root component for the Municipality of Utrecht based on the NL Design System architecture

0High
0Medium
0Low

Root

Onderlaag waarin basiskeuzes worden gemaakt voor alle componenten die in de website zitten.

Aanbevolen manier

<!DOCTYPE html>
<html class="utrecht-root" dir="ltr" lang="nl">
  <head>
    <meta charset="utf-8" />
    <title>Paginatitel</title>
    <meta name="viewport" content="width=device-width,initial-scale=1" />
  </head>
  <body>
    <!-- ... -->
  </body>
</html>

Richtlijnen voor contentmakers

Via lang="nl" wordt aangegeven dat de tekst op de pagina in het Nederlands is geschreven. Screenreaders gebruiken dit attribuut om de juiste uitspraak en taalinstellingen te selecteren voor gebruikers met een visuele beperking. Is de tekst op de pagina in een andere taal geschreven? Wissel nl dan in voor de juiste taal. Bijvoorbeeld fr voor Frans of es voor Spaans.

Doelen

De afmeting van deze component is de maximaal beschikbare ruimte.
De achtergrondkleur is de basis voor content.
De kleur van de tekst is leesbaar op de achtergrond.
Het lettertype is het standaard neutrale lettertype voor componenten.
Scroll wanneer het nodig is.

Edge cases:

Mag niet horizontaal scrollen wanneer een border op :root wordt gezet (WCAG 1.4.10)

Door het aanbieden van goed root component kunnen 'anti-patterns' voorkomen of genezen worden.

Anti-aliasing wordt vaak aangepast door ongewenste font-smoothing: antialiased;.
Overschrijven van de root font-size, waardoor de rem waarde wordt aangepast.
De <body> element scrollbaar maken in plaats van het <html> element.

Anatomie

HTML variant:

Root
Body

Body en Div variant:

Root

De naamgeving van de Root component is gebaseerd op :root in CSS. De naamgeving van het Body onderdeel is gebaseerd op body in HTML.

HTML

`meta` element

Gebruik altijd een <meta name="viewport"> element met tenminste de volgende instellingen:

width=device-width
initial-scale=1

Je kunt deze instellingen combineren met eigen voorkeuren.

Bijvoorbeeld:

<meta name="viewport" content="width=device-width,initial-scale=1" />

`title` element

Gebruik altijd een <title> element om de paginatitel in te stellen, voor de HTML en Body varianten.

`html` variant

<!DOCTYPE html>
<html class="utrecht-root" lang="nl" dir="ltr">
  <head>
    <!-- ... -->
  </head>
  <body>
    <!-- ... -->
  </body>
</html>

Wanneer je kunt kiezen tussen het html en body element, kies dan altijd het html element.

ARIA

Voor de HTML en Body variant moet je geen role instellen.

Voor de Div variant kan het in heel zeldzame gevallen nodig zijn om role="document" of role="application" te gebruiken, dus dat moet mogelijk zijn met deze component. Lees hier over in het artikel: If you use the WAI-ARIA role "application", please do so wisely! — Marco Zehe

Wanneer je de Div-variant gebruikt om Viewport te simuleren, gebruik dan role="group".

Wanneer je de Dialog variant gebruikt, gebruik het <dialog> element die de impliciete rol dialog heeft.

Design tokens

Er zijn design tokens om de color en background-color in te stellen, die basis-kleuren zijn voor de hele pagina.

Vrijwel alle gebruikers maken eigen keuzes voor color, background-color, font-family, font-weight, font-size en line-height.

De meeste gebruikers maken eigen keuzes voor color, background-color en font-family. De meeste gebruikers gebruiken font-weight 400, maar met de opkomst van variable fonts zal daar meer variatie in komen. De meeste gebruikers stellen font-size in om garantie te hebben dat de font-size is wat ze verwachten, zelfs wanneer de font-size 1rem is. De line-height wordt meestal ingesteld op een grotere waarde dan wat browsers standaard hebben.

Er is een design token font-size-adjust om twee dingen mogelijk te maken:

De font-size van het belangrijkste lettertype gelijk te houden, door een waarde te gebruiken waarbij die font-size gelijk blijft.
Visuele regressies voorkomen door geen gebruik te maken van font-size-adjust, door waarde voor CSS in te stellen op auto.

Richtlijnen voor invulling design tokens

De background-color en color moeten tenminste 4,5:1 kleurcontrast hebben.

De font-size moet voldoen aan het de richtlijn van minimum font-size van NL Design System .

De font-size moet gebruik maken van relatieve font-size units, bij voorkeur rem.

De line-height moet tenminste 1 zijn, en gebruik maken van relatieven units. Bij voorkeur een unitless waarde.

De font-size-adjust moet zijn ingesteld op een waarde waarbij de font-size nog voldoende leesbaar is. De minimum x-hoogte is 8px. Voorbeelden:

font-size: 16px met font-size-adjust: 0.42; is onvoldoende
font-size: 24px met font-size-adjust: 0.42; is voldoende

Gebruik als font-family bij voorkeur een lettertype dat voldoet aan de richtlijnen van NL Design System.

Varianten

Er zijn alleen varianten in code, niet in design.

Variant die op een html-element is toegepast
Variant die op een body-element is toegepast
Variant die op een div-element is toegepast

De belangrijkste manier om de Root component te gebruiken is met het html element.

Gebruik de body variant alleen wanneer je eigenlijk de html variant wilt gebruiken, maar dat niet mogelijk is in jouw situatie.

`body` variant

<!DOCTYPE html>
<html lang="nl" dir="ltr">
  <head>
    <!-- ... -->
  </head>
  <body class="utrecht-root">
    <!-- ... -->
  </body>
</html>

`div` variant

<!DOCTYPE html>
<html lang="nl" dir="ltr">
  <head>
    <!-- ... -->
  </head>
  <body>
    <div class="utrecht-root">
      <!-- ... -->
    </div>
  </body>
</html>

WCAG

1.1.1 Niet-tekstuele content
- Niet van toepassing, in het algemeen.
- Misschien: doe geen watermerk als achtergrond-afbeelding, zoals "Concept" of "Specimen"?
1.2.1 Louter-geluid en louter-videobeeld (vooraf opgenomen): Niet van toepassing.
1.2.2 Ondertitels voor doven en slechthorenden (vooraf opgenomen): Niet van toepassing.
1.2.3 Audiodescriptie of media-alternatief (vooraf opgenomen): Niet van toepassing.
1.2.4 Ondertitels voor doven en slechthorenden (live): Niet van toepassing.
1.2.5 Audiodescriptie (vooraf opgenomen): Niet van toepassing.
1.2.6 Gebarentaal (vooraf opgenomen): Niet van toepassing.
1.2.7 Verlengde audiodescriptie (vooraf opgenomen): Niet van toepassing.
1.2.8 Media-alternatief (vooraf opgenomen): Niet van toepassing.
1.2.9 Louter-geluid (live): Niet van toepassing.
1.3.1 Info en relaties
- Misschien: role="group", role="document" of role="application" wanneer er nog content buiten de root staat?
1.3.2 Betekenisvolle volgorde
- Stel dir="ltr" of dir="rtl" attribuut in op het html element, wanneer de Root component daarop wordt toegepast.
- Gebruik CSS logical properties voor de implementatie van de component.
1.3.3 Zintuiglijke eigenschappen
1.3.4 Weergavestand
- Gebruik niet de screen.orientation.lock API om te voorkomen dat de weergavestand wordt aangepast.
- Gebruik geen media query om de pagina 90 graden te kantelen om het aanpassen van de weergavestand ongedaan te maken.
1.3.5 Identificeer het doel van de input: Niet van toepassing.
1.3.6 Identificeer het doel: Niet van toepassing.
1.4.1 Gebruik van kleur
- Mensen kunnen altijd gekke dingen doen: waarschuwing door een rode border?
1.4.2 Geluidsbediening: Niet van toepassing.
1.4.3 Contrast (minimum)
- TODO: Van toepassing
1.4.4 Herschalen van tekst
- TODO: Van toepassing
1.4.5 Afbeeldingen van tekst: Niet van toepassing.
1.4.6 Contrast (versterkt)
- TODO: Van toepassing
1.4.7 Weinig of geen achtergrondgeluid: Niet van toepassing.
1.4.8 Visuele presentatie:
- TODO: Onderzoeken
1.4.9 Afbeeldingen van tekst (geen uitzondering): Niet van toepassing.
1.4.10 Reflow
- TODO: van toepassing
1.4.11 Contrast van niet-tekstuele content: Niet van toepassing.
1.4.12 Tekstafstand
- TODO: van toepassing
1.4.13 Content bij hover of focus: Niet van toepassing.
2.1.1 Toetsenbord
- Wanneer de Root een scrollbar heeft, dan moet het scrollen met de gebruikelijke toetsen bediend kunnen worden. Mogelijk moet de Root dan ook focusbaar zijn.
2.1.2 Geen toetsenbordval: Niet van toepassing.
2.1.3 Toetsenbord (geen uitzondering): Niet van toepassing.
2.1.4 Enkel teken sneltoetsen: Niet van toepassing.
2.2.1 Timing aanpasbaar: Niet van toepassing.
2.2.2 Pauzeren, stoppen, verbergen: Niet van toepassing.
2.2.3 Geen timing: Niet van toepassing.
2.2.4 Onderbrekingen: Niet van toepassing.
2.2.5 Herauthentisering: Niet van toepassing.
2.2.6 Time-outs: Niet van toepassing.
2.3.1 Drie flitsen of beneden drempelwaarde: Niet van toepassing.
2.3.2 Drie flitsen: Niet van toepassing.
2.3.3 Animatie uit interacties:
- van toepassing bij scrollen
2.4.1 Blokken omzeilen
- Misschien een goed idee om <html id="top"> te gebruiken?
2.4.2 Paginatitel: stel altijd een paginatitel in voor de HTML en Body varianten.
2.4.3 Focus volgorde
- focus-volgorde misschien ook van toepassing door scroll-to-top link
2.4.4 Linkdoel (in context): Niet van toepassing.
2.4.5 Meerdere manieren: Niet van toepassing.
2.4.6 Koppen en labels: Niet van toepassing.
2.4.7 Focus zichtbaar
- wanneer de Root component een scroll container is, dan moet je scroll-padding properties in kunnen stellen als je sticky components hebt.
- misschien: zou een root element een inset focus ring moeten hebben?
2.4.8 Locatie
- Mogelijk van toepassing door de inhoud van de paginatitel. Bijvoorbeeld: als er een onjuiste locatie in de paginatitel staat. Bijvoorbeeld: <title>Homepage - Enter Your Site Name Here</title>
2.4.9 Linkdoel (alleen link): Niet van toepassing.
2.4.10 Paragraafkoppen: Niet van toepassing.
2.4.11 Focus niet bedekt (minimum)
- door een default focus ring met z-index: 1 draagt de Root component hier aan bij
- van toepassing doordat op de Root component scroll-padding ingesteld moet worden
2.4.12 Focus niet bedekt (uitgebreid)
- van toepassing doordat op de Root component scroll-padding ingesteld moet worden
2.4.13 Focusweergave
- als je de root uitzoomt, dan moet de focus ring nog steeds voldoende duidelijk zijn
2.5.1 Aanwijzergebaren: Niet van toepassing.
2.5.2 Aanwijzerannulering: Niet van toepassing.
2.5.3 Label in Naam
- Van toepassing op dialogs, etc.
2.5.4 Bewegingsactivering: Niet van toepassing.
2.5.5 Grootte van het aanwijsgebied (uitgebreid): Niet van toepassing.
2.5.6 Input gelijktijdige invoermechanismen: Niet van toepassing.
2.5.7 Sleepbewegingen: Niet van toepassing.
2.5.8 Grootte van het aanwijsgebied (minimum): Niet van toepassing.
3.1.1 Taal van de pagina
- Stel het lang attribuut in op het html element, wanneer de Root component daarop wordt toegepast. Daarnaast wordt de leesbaarheid van de tekst beter wanneer de browser een passend woordenboek kan gebruiken voor woordafbreking.
3.1.2 Taal van onderdelen
- Stel het lang attribut in op het html element, zodat de <title> ook de juiste language heeft.
- Todo: Wat als de paginatitel Engelstalig is, en de paginatitel bevat ook een andere taal? Bijvoorbeeld: <title>To be, or not to be — gemeente Voorbeeld</title>. Wil je dan <title lang="en">To be, or not to be — gemeente Voorbeeld</title>? Wordt dat uberhaupt ondersteund door voorleessoftware?
3.1.3 Ongebruikelijke woorden
3.1.4 Afkortingen
- Van toepassing op de paginatitel.
3.1.5 Leesniveau
- Van toepassing op de paginatitel.
3.1.6 Uitspraak: Niet van toepassing.
3.2.1 Bij focus: Niet van toepassing.
3.2.2 Bij input: Niet van toepassing.
3.2.3 Consistente navigatie
3.2.4 Consistente identificatie
- Paginatitel moet consistent werken.
3.2.5 Verandering op verzoek: Niet van toepassing.
3.2.6 Consistente hulp: Niet van toepassing.
3.3.1 Foutidentificatie
- Je kunt in de paginatitel weergeven dat er een fout is, bijvoorbeeld: <title>Fout! - Contactformulier - gemeente Voorbeeld</title>
- Wanneer Fout! in de paginatitel blijft staan wanneer de fout is opgelost, dan voldoet dit ook niet.
3.3.2 Labels of instructies: Niet van toepassing.
3.3.3 Foutsuggestie: Niet van toepassing.
3.3.4 Foutpreventie (wettelijk, financieel, gegevens): Niet van toepassing.
3.3.5 Hulp: Niet van toepassing.
3.3.6 Foutpreventie (alle): Niet van toepassing.
3.3.7 Overbodige invoer: Niet van toepassing.
3.3.8 Toegankelijke authenticatie (minimum): Niet van toepassing.
3.3.9 Toegankelijke authenticatie (uitgebreid): Niet van toepassing.
4.1.1 Parsen: Niet van toepassing.
4.1.2 Naam, rol, waarde:
- naam en rol zijn van toepassing, wanneer je role="dialog", role="group", role="application" of role="document" gebruikt.
4.1.3 Statusberichten: Niet van toepassing.

Privacy en security

Je kunt de privacy en security van je pagina verbeteren door metadata toe te voegen in de <head> van je pagina.

In de <head> van de pagina kun je een Content-Security-Policy element toevoegen, waarmee je de veiligheid van je pagina kunt verbeteren.

Veelvoorkomende fouten

Toegankelijkheid:

Kleurcontrast van tekst wordt lager gemaakt door font-smoothing in te stellen op antialiased of grayscale.
scroll-behavior: smooth wordt ingesteld zonder een uitzondering te maken op basis van prefers-reduced-motion.
CSS Logical Properties worden nog niet gebruikt.
Taal van de pagina is niet ingesteld.
De paginatitel is niet duidelijk.
De font-size van het html element wordt ingesteld, waardoor 1rem niet meer de user preference volgt.
De font-size van het html element is ingesteld met een absolute waarde, waardoor de gebruiker niet meer de tekst kan vergroten.
Er is wel een tekstkleur ingesteld, maar geen achtergrondkleur, waardoor de tekst onleesbaar wordt wanneer de gebruiker dark mode gebruikt.
Lange woorden hebben geen woordafbreking, waardoor op kleinere schermen de tekst niet volledig leesbaar is zonder heen en weer te scrollen.
Default focus ring wordt gebruikt, waardoor de focus indicator niet zichtbaar is op alle achtergronden.
De kleuren zwart en wit zijn gebruikt voor background-color en color, waardoor het contrast zo hoog is dat sommige mensen er last van hebben.

Gebruiksvriendelijkheid:

Wanneer je hele pagina is gemaakt met CSS Logical properties, dan kun je de layout spiegelen wanneer een script herkent dat Google Translate naar een right-to-left taal vertaalt.

Kwaliteit:

body { padding: 0; } wordt nog vaak gebruikt, terwijl dat in moderne browsers niet nodig is.
De html en body elementen op een pagina worden niet ingesteld om de maximale beschikbare ruimte te gebruiken, waardoor de footer niet onderaan het scherm staat.
De font-size van het html element is ingesteld op 62.5%, waardoor de pagina niet goed samenwerkt met componenten die uitgaan van 1rem = 16px.
De leesbaarheid van de tekst is niet optimaal doordat meerdere lettertypes door elkaar gebruikt worden, waarvan de x-hoogte niet overeenkomt.
Er moet complexe CSS gemaakt worden om een position: sticky elementen op de juiste plek te krijgen.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme