feat(documentation): accessibility (#3835)

.changeset/fifty-dodos-wait.md

@@ -0,0 +1,5 @@
+---
+'@swisspost/design-system-documentation': minor
+---
+
+Updated the Accessibility documentation section with Form Labels guidelines.

packages/documentation/src/stories/foundation/accessibility/forms/forms-invisible-labels.sample.html

@@ -0,0 +1,9 @@
+<form>
+    <input type="text" aria-label="Username" placeholder="Enter your username">
+
+    <input type="email" aria-label="Email" placeholder="Enter your email">
+
+    <input type="password" aria-label="Password" placeholder="Enter your password">
+
+    <button type="submit">Submit</button>
+  </form>

packages/documentation/src/stories/foundation/accessibility/forms/forms-reference-labels.sample.html

@@ -0,0 +1,12 @@
+<form>
+  <div role="group" aria-labelledby="complex-label">
+    <p id="complex-label">Select your favorite fruits:</p>
+    <input type="checkbox" id="apple" aria-labelledby="complex-label apple-label" />
+    <label id="apple-label" for="apple">Apple</label>
+    <input type="checkbox" id="banana" aria-labelledby="complex-label banana-label" />
+    <label id="banana-label" for="banana">Banana</label>
+    <input type="checkbox" id="orange" aria-labelledby="complex-label orange-label" />
+    <label id="orange-label" for="orange">Orange</label>
+  </div>
+  <button type="submit">Submit</button>
+</form>

packages/documentation/src/stories/foundation/accessibility/forms/forms-visible-labels.sample.html

@@ -0,0 +1,12 @@
+<form>
+    <label for="username">Username</label>
+    <input type="text" id="username" name="username" placeholder="Enter your username">
+
+    <label for="email">Email</label>
+    <input type="email" id="email" name="email" placeholder="Enter your email">
+
+    <label for="password">Password</label>
+    <input type="password" id="password" name="password" placeholder="Enter your password">
+
+    <button type="submit">Submit</button>
+  </form>

packages/documentation/src/stories/foundation/accessibility/forms/forms.docs.mdx

@@ -1,6 +1,10 @@
 import { Meta, Source, Canvas } from '@storybook/blocks';
 import * as FormsStories from './forms.stories';
 
+import visibleLabels from './forms-visible-labels.sample.html?raw';
+import invisibleLabels from './forms-invisible-labels.sample.html?raw';
+import referenceLabels from './forms-reference-labels.sample.html?raw';
+
 <Meta of={FormsStories} />
 
 # Forms
@@ -158,6 +162,28 @@ Disabled states of input fields or buttons pose many accessibility issues.
 
 <Canvas of={FormsStories.FormGoodExample} />
 
+## Labels
+
+Labels are crucial in ensuring accessibility in web forms, as they provide necessary information about form elements for all users, especially those using assistive technologies like screen readers.
+
+### Visible Labels
+
+Use the `<label>` element along with the `for` attribute to create a link between a `<label>` and an `<input>` field. The value of the `for` attribute must match the `id` of the corresponding `<input>` element, allowing screen readers to associate them correctly.
+
+<Source code={visibleLabels} language="html" />
+
+### Invisible Labels with `aria-label`
+
+Make a hidden `<label>` element available for assistive technologies using the `aria-label` for labeling form elements. The `aria-label` attribute can be used to assign an accessible label to any form element that might not have a visible label.
+
+<Source code={invisibleLabels} language="html" />
+
+### Referencing Labels with `aria-labelledby`
+
+The `aria-labelledby` attribute allows you to reference the `id` of another element that serves as the `<label>`. This is especially useful when the `<label>` is complex or spans multiple elements. Hidden elements can also be referenced using `aria-labelledby`, allowing screen readers to announce the associated label even though it is not displayed visually.
+
+<Source code={referenceLabels} language="html" />
+
 ## Controls Grouping
 
 When grouping `<form controls>`, the `<fieldset>`and `<legend>` elements play a critical role in providing context to screen readers. However, improper usage of these elements can lead to confusion for users with disabilities.