Add description guideline new setup

docs/richtlijnen/README.md

@@ -62,4 +62,24 @@ _label-no-activate.md
 _label-text-visibility.md
 ```
 
+### Namen voor partials
+
+We willen de namen liefst niet meer veranderen, en dus toekomstbestendig maken (vanuit de ‘cool URI's don't change’ gedachte).
+
+Enkele richtlijnen:
+
+- gebruik enkelvoud tenzij meervoud noodzakelijk is
+- gebruik keywords uit HTML/CSS/SVG voor IDs/slugs/filenames
+- gebruik prefixes en hiërarchie in prefixes zodat door sorteren automatisch groepjes ontstaan
+
+Voorbeelden van namen voor label-gerelateerde partials:
+
+```
+_label-position.md
+_label-text.md
+_label-visibility.md
+_label-no-activate.md
+_label-text-visibility.md
+```
+
 <!-- TODO! -->

docs/richtlijnen/formulieren/00-alle-richtlijnen/02-descriptions.mdx

@@ -0,0 +1,55 @@
+---
+title: Descriptions in een formulier | Richtlijnen | NL Design System
+hide_title: true
+hide_table_of_contents: false
+sidebar_label: Descriptions
+pagination_label: Descriptions in een formulier
+description: Richtlijnen voor het toepassen van descriptions in een formulier.
+keywords:
+  - labels
+  - formulier
+  - design
+  - code
+---
+
+<!-- @license CC0-1.0 -->
+
+import DescriptionPlacement from "./_description-placement.md";
+import DescriptionPlacementCode from "./_description-placement-code.mdx";
+import DescriptionAssociated from "./_description-associated.md";
+import DescriptionAssociatedCode from "./_description-associated-code.mdx";
+import DescriptionMultiple from "./_description-multiple.md";
+import DescriptionMultipleCode from "./_description-multiple-code.mdx";
+import DescriptionFieldset from "./_description-fieldset.md";
+import DescriptionFieldsetCode from "./_description-fieldset-code.mdx";
+import DescriptionTargetSize from "./_description-target-size.md";
+import DescriptionTargetSizeCode from "./_description-target-size-code.mdx";
+import DescriptionLength from "./_description-length.md";
+import DescriptionLengthCode from "./_description-length-code.mdx";
+import FormFooterInfo from "./_form_footer_info.md";
+
+# Descriptions in een formulier
+
+Bij een formulierveld kun je extra informatie plaatsen, met bijvoorbeeld uitleg over hoe een veld in te vullen, de eisen voor een wachtwoord, foutmeldingen of waarschuwingen.
+
+We geven deze extra informatie hier de verzamelnaam "descriptions", om aan te sluiten bij de term [“accessible description”](https://www.w3.org/TR/wai-aria-1.2/#dfn-accessible-description), die in toegankelijkheidsstandaarden wordt gebruikt.
+
+<DescriptionAssociated />
+<DescriptionAssociatedCode />
+
+<DescriptionPlacement />
+<DescriptionPlacementCode />
+
+<DescriptionMultiple />
+<DescriptionMultipleCode />
+
+<DescriptionFieldset />
+<DescriptionFieldsetCode />
+
+<DescriptionTargetSize />
+<DescriptionTargetSizeCode />
+
+<DescriptionLength />
+<DescriptionLengthCode />
+
+<FormFooterInfo />

docs/richtlijnen/formulieren/00-alle-richtlijnen/_description-associated-code.mdx

@@ -0,0 +1,20 @@
+<!-- @license CC0-1.0 -->
+
+import { Canvas } from "@site/src/components/Canvas/Canvas";
+import { Guideline } from "@site/src/components/Guideline";
+
+<Guideline appearance="do" title="Koppel een description aan het formulierveld, met aria-describedby.">
+  <Canvas language="html">
+    <label for="wachtwoord">Nieuw wachtwoord</label>
+    <p id="description-wachtwoord">Kies een wachtwoord van minimaal 8 karakters lang.</p>
+    <input id="wachtwoord" type="password" name="nieuw-wachtwoord" aria-describedby="description-wachtwoord" />
+  </Canvas>
+</Guideline>
+
+<Guideline appearance="dont" title="Koppeling weglaten.">
+  <Canvas language="html">
+    <label for="wachtwoord0">Nieuw wachtwoord</label>
+    <p>Kies een wachtwoord van minimaal 8 karakters lang.</p>
+    <input id="wachtwoord0" type="password" name="nieuw-wachtwoord" />
+  </Canvas>
+</Guideline>

docs/richtlijnen/formulieren/00-alle-richtlijnen/_description-associated.md

@@ -0,0 +1,14 @@
+## Koppel een description aan het formulierveld
+
+Voor screenreadergebruikers is het belangrijk dat de description samen wordt voorgelezen met het formulierveld. Dat kan door deze twee aan elkaar te koppelen via aria-describedby.
+
+**Let op:** De gebruikte ID’s moeten uniek zijn voor de pagina, anders worden de verkeerde descriptions bij de velden voorgelezen.
+
+Opzet in de HTML:
+
+- Geef description een ID: `id="description-wachtwoord"`.
+- Verwijs in het formulierveld naar dat ID:`aria-describedby="description-wachtwoord"`.
+
+Hierdoor wordt naast de labeltekst ook de description voorgelezen, wanneer een screen reader gebruiker het formulierveld focus geeft.
+
+Lees ook: [MDN over aria-describedby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby).

docs/richtlijnen/formulieren/00-alle-richtlijnen/_description-fieldset-code.mdx

@@ -0,0 +1,21 @@
+<!-- @license CC0-1.0 -->
+
+import { Canvas } from "@site/src/components/Canvas/Canvas";
+import { Guideline } from "@site/src/components/Guideline";
+
+<Guideline appearance="do" title="Koppel een description aan de legend van de fieldset, met aria-describedby.">
+  <Canvas language="html">
+    <fieldset aria-describedby="description-inloggen">
+      <legend>Wilt u inloggen?</legend>
+      <p id="description-inloggen">Als u inlogt worden uw gegevens al ingevuld en kunnen we u makkelijker helpen.</p>
+      <div>
+        <input id="inloggen-ja" type="radio" name="inloggen" value="ja" />
+        <label for="inloggen-ja"> Ja</label>
+      </div>
+      <div>
+        <input id="inloggen-nee" type="radio" name="inloggen" value="nee" />
+        <label for="inloggen-nee"> Nee</label>
+      </div>
+    </fieldset>
+  </Canvas>
+</Guideline>

docs/richtlijnen/formulieren/00-alle-richtlijnen/_description-fieldset.md

@@ -0,0 +1,3 @@
+## Fieldset: Plaats descriptions tussen legend en eerste item
+
+Radiobuttons en checkboxes worden gegroepeerd in een fieldset. De "vraag" staat in de legend. Plaats de description dan onder de legend vlak boven het eerste label/formulierveld. De description kan aan de fieldset worden gekoppeld.

docs/richtlijnen/formulieren/00-alle-richtlijnen/_description-length-code.mdx

@@ -0,0 +1,4 @@
+<!-- @license CC0-1.0 -->
+
+import { Canvas } from "@site/src/components/Canvas/Canvas";
+import { Guideline } from "@site/src/components/Guideline";

docs/richtlijnen/formulieren/00-alle-richtlijnen/_description-length.md

@@ -0,0 +1,7 @@
+## Houd de description kort en to-the-point.
+
+Heb je erg veel tekst nodig om het formulier goed in te vullen, vermeld deze tekst dan boven het formulier of op een introductiepagina voordat een gebruiker het formulier gaat invullen.
+
+Als informatie als losse tekstblokken tussen de vragen staat, bestaat de kans dan een screenreadergebruiker deze informatie mist.
+
+Gebruik liever geen tooltips, dan maak je het voor de gebruiker moeilijker om belangrijke informatie te lezen. Het vergt een extra klik (of toetsenbordaanslagen) en wordt niet door alle gebruikers goed begrepen. Als het echt belangrijk is, laat de informatie dan meteen zien.

docs/richtlijnen/formulieren/00-alle-richtlijnen/_description-multiple-code.mdx

@@ -0,0 +1,18 @@
+<!-- @license CC0-1.0 -->
+
+import { Canvas } from "@site/src/components/Canvas/Canvas";
+import { Guideline } from "@site/src/components/Guideline";
+
+<Guideline appearance="do" title="Koppel alle descriptions aan het formulierveld.">
+  <Canvas language="html">
+    <label for="wachtwoord5">Nieuw wachtwoord</label>
+    <div id="description-wachtwoord5">Kies een wachtwoord van minimaal 8 karakters lang.</div>
+    <div id="error-wachtwoord5">Je gekozen wachtwoord is te kort.</div>
+    <input
+      id="wachtwoord5"
+      type="password"
+      name="nieuw-wachtwoord"
+      aria-describedby="description-wachtwoord5 error-wachtwoord5"
+    />
+  </Canvas>
+</Guideline>

docs/richtlijnen/formulieren/00-alle-richtlijnen/_description-multiple.md

@@ -0,0 +1,7 @@
+<!-- @license CC0-1.0 -->
+
+## Meerdere descriptions koppelen
+
+Je kunt meerdere descriptions koppelen aan een formulierveld. Bijvoorbeeld als er een ook nog een foutmelding is.
+
+Geef dan `aria-describedby` twee waardes (IDs), mee gescheiden door een spatie. De volgorde van de ID's meegegeven in de `aria-describedby` is de volgorde waarin het voorgelezen wordt.

docs/richtlijnen/formulieren/00-alle-richtlijnen/_description-placement-code.mdx

@@ -0,0 +1,56 @@
+<!-- @license CC0-1.0 -->
+
+import { Canvas } from "@site/src/components/Canvas/Canvas";
+import { Guideline } from "@site/src/components/Guideline";
+
+<Guideline
+  appearance="do"
+  title="Plaats alle descriptions op een consistente plek, liefst tussen het label en het formulierveld."
+>
+  <Canvas language="html">
+    <label for="wachtwoord1">Nieuw wachtwoord</label>
+    <p id="description-wachtwoord1">Kies een wachtwoord van minimaal 8 karakters lang.</p>
+    <input id="wachtwoord1" type="password" name="nieuw-wachtwoord" aria-describedby="description-wachtwoord1" />
+  </Canvas>
+</Guideline>
+
+<Guideline appearance="do" title="Plaats alle descriptions, ook de foutmeldingen, op een consistente plek, liefst tussen het label en het formulierveld.">
+  <Canvas language="html">
+    <label for="wachtwoord2">Nieuw wachtwoord</label>
+    <p id="description-wachtwoord2">
+      Kies een wachtwoord van minimaal 8 karakters lang.
+    </p>
+    <p id="error-wachtwoord2">
+      Je gekozen wachtwoord is te kort.
+    </p>
+    <input
+      id="wachtwoord2"
+      type="password"
+      name="nieuw-wachtwoord"
+      aria-describedby="description-wachtwoord2 error-wachtwoord2"
+    />
+
+  </Canvas>
+</Guideline>
+
+<Guideline appearance="dont" title="Description onder het formulierveld plaatsen.">
+  <Canvas language="html">
+    <label for="wachtwoord3">Nieuw wachtwoord</label>
+    <input id="wachtwoord3" type="password" name="nieuw-wachtwoord" aria-describedby="description-wachtwoord3" />
+    <p id="description-wachtwoord3">Kies een wachtwoord van minimaal 8 karakters lang.</p>
+  </Canvas>
+</Guideline>
+
+<Guideline appearance="dont" title="Description boven het formulierveld en foutmelding eronder plaatsen.">
+  <Canvas language="html">
+    <label for="wachtwoord4">Nieuw wachtwoord</label>
+    <p id="description-wachtwoord4">Kies een wachtwoord van minimaal 8 karakters lang.</p>
+    <input
+      id="wachtwoord4"
+      type="password"
+      name="nieuw-wachtwoord"
+      aria-describedby="description-wachtwoord4 error-wachtwoord4"
+    />
+    <p id="error-wachtwoord4">Je gekozen wachtwoord is te kort.</p>
+  </Canvas>
+</Guideline>

docs/richtlijnen/formulieren/00-alle-richtlijnen/_description-placement.md

@@ -0,0 +1,5 @@
+## Plaats descriptions tussen label en formulierveld
+
+Plaats alle descriptions op een consistente plek, liefst tussen het label en het formulierveld. Omdat de gebruiker van boven naar beneden leest, komt deze informatie na het label op een logisch moment in de leesvolgorde.
+
+Ook is dan de kans dat de informatie overlapt met bijvoorbeeld browserpopups kleiner. Lees hiervoor het artikel [Avoid Messages Under Fields](https://adrianroselli.com/2017/01/avoid-messages-under-fields.html) van Adrian Roselli.

docs/richtlijnen/formulieren/00-alle-richtlijnen/_description-target-size-code.mdx

@@ -0,0 +1,4 @@
+<!-- @license CC0-1.0 -->
+
+import { Canvas } from "@site/src/components/Canvas/Canvas";
+import { Guideline } from "@site/src/components/Guideline";

docs/richtlijnen/formulieren/00-alle-richtlijnen/_description-target-size.md

@@ -0,0 +1,11 @@
+## Houd het aanklikbare gedeelte groot genoeg
+
+Bij een goede koppeling tussen het label en het formulierveld, zijn beide elementen aanklikbaar. Dat maakt het aanklikbare gedeelte groot.
+
+Een description ertussen verkleint de aanklikbare ruimte. Zorg er daarom voor dat het aanklikbare gedeelte van een formulierveld **tenminste** 24 bij 24 pixels is, liever nog groter waar mogelijk. Zodat gebruikers met dikke vingertoppen op een mobiel of met trillende handen met een muis toch een formulierveld kunnen selecteren.
+
+Een minimale grootte van het aanklikbare gedeelte is een vereiste volgens WCAG-succescriterium [2.5.8 (Niveau A): Minimale grootte van het aanwijsgebied](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html).
+
+![Formfield met textbox van 48 pixels hoog, en formfield met radiobuttons van 24 pixels hoog.](https://raw.githubusercontent.com/nl-design-system/documentatie/assets/richtlijnen_formulier_description_size.png)
+
+Voor het 'Voorbeeld thema' maken we gebruik van een grootte van 24x24 bij checkboxes en radio buttons. En houden we een grootte van 48x48px aan voor componenten zoals buttons en text inputs. Dit sluit mooi aan bij de spacing scale van het voorbeeld thema.

src/components/Guideline.module.css

@@ -12,6 +12,9 @@ p + .nlds-guideline {
   box-shadow: 4px 4px 0px rgba(0, 0, 0, 0.1);
   margin-block-end: 40px;
 }
+.nlds-guideline + .nlds-guideline {
+  margin-block-start: -20px;
+}
 
 .nlds-guideline__description {
   padding: 24px;

src/css/custom.css

@@ -657,7 +657,13 @@ abbr[title] {
   border: 2px solid #cc0000;
 }
 
-.docs-doc-page input[type="text"] {
+.docs-doc-page .utrecht-html label,
+.docs-doc-page .utrecht-html legend {
+  font-weight: bold;
+}
+
+.docs-doc-page input[type="text"],
+.docs-doc-page input[type="password"] {
   display: block;
 }
 
@@ -714,6 +720,11 @@ pre > code {
   /* avoid double spacing */
 }
 
+ul + div[class*="language-"],
+ul + .nlds-guideline_src-components-Guideline-module {
+  margin-block-start: var(--nlds-code-block-margin-inline-start, 1.5em);
+}
+
 pre[class*="language-"]::-moz-selection,
 pre[class*="language-"] ::-moz-selection,
 code[class*="language-"]::-moz-selection,