From 84b051ab658dee0f589104c3f8ab01730fc92f66 Mon Sep 17 00:00:00 2001 From: Myrta Sakellariou Date: Thu, 3 Oct 2024 17:46:58 +0200 Subject: [PATCH 1/2] feat(documentation): Reorganized Accesibility folder and added Form Grouping Controls Section --- .changeset/fast-fans-wash.md | 5 + .../forms.docs.mdx} | 109 ++++++++++-------- .../forms.stories.ts} | 36 +++++- .../liveregion-atomic.sample.html | 0 .../liveregion-bad-angular.sample.html | 0 .../liveregion-good-angular.sample.html | 0 .../liveregion/liveregion.docs.mdx | 51 ++++++++ .../liveregion/liveregion.stories.ts | 17 +++ .../accessibility/regulation.docs.mdx | 17 +++ .../accessibility/regulation.stories.ts | 17 +++ pnpm-lock.yaml | 71 +++--------- 11 files changed, 217 insertions(+), 106 deletions(-) create mode 100644 .changeset/fast-fans-wash.md rename packages/documentation/src/stories/foundation/accessibility/{accessibility.docs.mdx => forms/forms.docs.mdx} (54%) rename packages/documentation/src/stories/foundation/accessibility/{accessibility.stories.ts => forms/forms.stories.ts} (92%) rename packages/documentation/src/stories/foundation/accessibility/{ => liveregion}/liveregion-atomic.sample.html (100%) rename packages/documentation/src/stories/foundation/accessibility/{ => liveregion}/liveregion-bad-angular.sample.html (100%) rename packages/documentation/src/stories/foundation/accessibility/{ => liveregion}/liveregion-good-angular.sample.html (100%) create mode 100644 packages/documentation/src/stories/foundation/accessibility/liveregion/liveregion.docs.mdx create mode 100644 packages/documentation/src/stories/foundation/accessibility/liveregion/liveregion.stories.ts create mode 100644 packages/documentation/src/stories/foundation/accessibility/regulation.docs.mdx create mode 100644 packages/documentation/src/stories/foundation/accessibility/regulation.stories.ts diff --git a/.changeset/fast-fans-wash.md b/.changeset/fast-fans-wash.md new file mode 100644 index 0000000000..c7f1eda9ce --- /dev/null +++ b/.changeset/fast-fans-wash.md @@ -0,0 +1,5 @@ +--- +'@swisspost/design-system-documentation': minor +--- + +Updated the Accessibility documentation, reorganized in mutliple folders and added Grouping Controls section diff --git a/packages/documentation/src/stories/foundation/accessibility/accessibility.docs.mdx b/packages/documentation/src/stories/foundation/accessibility/forms/forms.docs.mdx similarity index 54% rename from packages/documentation/src/stories/foundation/accessibility/accessibility.docs.mdx rename to packages/documentation/src/stories/foundation/accessibility/forms/forms.docs.mdx index c9edb9ac2d..d8ed531f36 100644 --- a/packages/documentation/src/stories/foundation/accessibility/accessibility.docs.mdx +++ b/packages/documentation/src/stories/foundation/accessibility/forms/forms.docs.mdx @@ -1,27 +1,13 @@ import { Meta, Source, Canvas } from '@storybook/blocks'; -import * as AccessibilityStories from './accessibility.stories'; -import liveRegionAtomicSample from './liveregion-atomic.sample.html?raw'; -import liveRegionGoodAngularSample from './liveregion-good-angular.sample.html?raw'; -import liveRegionBadAngularSample from './liveregion-bad-angular.sample.html?raw'; +import * as FormsStories from './forms.stories'; - -# Accessibility + -
-
-

Die Postdienste müssen so angeboten werden, dass Menschen mit Behinderungen -sie in qualitativer, quantitativer und wirtschaftlicher Hinsicht unter vergleichbaren -Bedingungen wie Menschen ohne Behinderungen beanspruchen können.

-
-
- §14.7 Swiss postal law -
-
-## Forms +# Forms -### Disabled state +## Disabled state Disabled states of input fields or buttons pose many accessibility issues. @@ -102,51 +88,74 @@ Disabled states of input fields or buttons pose many accessibility issues. ### Form bad example - + ### Form good example - + -## Live region -A live region allows you to notify the user about a dynamic change without requiring the page to reload e.g. alert, loading status, chat logs, update of a product cart, feeds, etc. -They are defined either by using the `aria-live` attribute or some specific `role` attributes such as `role=status`, `role=alert`, `role=log`, etc. +## Controls Grouping -### Implicit aria-live attribute with role attribute +When grouping form controls for accessibility, the `
`and `` 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. -`role=status`, `role=log` and `role=alert` have an implicit default `aria-live` attribute, however for a maximum compatibility, it is recommended to add it as well (except for `role=alert`). Source: [Roles with implicit live region attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions#roles_with_implicit_live_region_attributes) - -### Choose the appropriate value for the aria-live attribute - -`aria-live` attribute can be either: -* `polite`: message will be announced after the screen reader is idle. -* `assertive`: message will interrupt any announcement immediately. It should be used sparingly. - -### Announce the whole Live region on change - -By default, screen readers will only announce the part that changed. However, it's often better to repeat the context of the change. -To do so, we can add `aria-atomic=true` attribute on the live region. This attribute force screen readers to read the whole text. - -For example on a shopping website, you want to announce to the user that a product was added to the shopping basket. If you announce only the product name, it's not enough to be comprehensive. - - - -### Add or remove dynamically a live region +
+ + + + + + + + + + + + + + + + + + + + + + + +
Common use cases and how to handle them.
The `` element is not a direct child of the `
`
+
    +
    ❌
  • A div or other element is incorrectly used as the first child of a `
    ` with the `` nested inside this element. However, improper usage of these elements can lead to confusion for screen readers.
    • +
+ + 		+
    +
    ✔️
  • Always place the `` before any other content within the `
    `to preserve the association.
    • +
+
A `
` is used for grouping instead of `
`
+
    +
    ❌
  • For visual reasons, a `
    ` is used for grouping controls instead of `
    `. No ARIA roles or attributes are set, failing to provide the necessary semantic meaning on assistive technologies.
    • +
+ + 		+
    +
    ✔️
  • Assign the role="group" to the `
    ` element inorder to provide it with the semantic meaning of a fieldset. Use 'aria-labelledby' or 'aria-describedby' to associate any descriptive text with the grouping container to ensure that screen readers can provide context to users.
    • +
+
+
-As a best practice, live region should be present on the page load and only the content inside it should change. -#### Example with a spinner on Angular +### The wrong way -When adding, for example, a spinner above a section, the live region container should be rendered initially while you can use `ng-container` to show and hide the spinner when you need it. + -##### Good example +### Recommended ways - +#### Standard -##### Bad example + -You shouldn't add the whole region dynamically as the accessibility bindings might not be [updated with some screen readers](https://www.scottohara.me/blog/2022/02/05/are-we-live.html#non-normative-rule-for-common-live-region-use-case). +#### Alternative using div - + \ No newline at end of file diff --git a/packages/documentation/src/stories/foundation/accessibility/accessibility.stories.ts b/packages/documentation/src/stories/foundation/accessibility/forms/forms.stories.ts similarity index 92% rename from packages/documentation/src/stories/foundation/accessibility/accessibility.stories.ts rename to packages/documentation/src/stories/foundation/accessibility/forms/forms.stories.ts index 832d2170e1..978a4716d3 100644 --- a/packages/documentation/src/stories/foundation/accessibility/accessibility.stories.ts +++ b/packages/documentation/src/stories/foundation/accessibility/forms/forms.stories.ts @@ -3,8 +3,8 @@ import { MetaExtended } from '@root/types'; import { html } from 'lit'; const meta: MetaExtended = { - id: '46da78e8-e83b-4ca1-aaf6-bbc662efef14', - title: 'Foundations/Accessibility', + id: 'cb34361c-7d3f-4c21-bb9c-874c73e82578', + title: 'Foundations/Accessibility/Forms', parameters: { badges: [], }, @@ -299,3 +299,35 @@ export const FormBadExample: Story = { addInputChangeListener(); `, }; + + +export const FieldsetDontExample: Story = { + render: () => html`
+
+ Gender + Male + Female +
+
`, +}; + + + +export const FieldsetDoExample: Story = { + render: () => html`
+ Gender + Male + Female +
`, +}; + + + + +export const DivForGroupingExample: Story = { + render: () => html`
+ Gender + Male + Female +
`, +}; \ No newline at end of file diff --git a/packages/documentation/src/stories/foundation/accessibility/liveregion-atomic.sample.html b/packages/documentation/src/stories/foundation/accessibility/liveregion/liveregion-atomic.sample.html similarity index 100% rename from packages/documentation/src/stories/foundation/accessibility/liveregion-atomic.sample.html rename to packages/documentation/src/stories/foundation/accessibility/liveregion/liveregion-atomic.sample.html diff --git a/packages/documentation/src/stories/foundation/accessibility/liveregion-bad-angular.sample.html b/packages/documentation/src/stories/foundation/accessibility/liveregion/liveregion-bad-angular.sample.html similarity index 100% rename from packages/documentation/src/stories/foundation/accessibility/liveregion-bad-angular.sample.html rename to packages/documentation/src/stories/foundation/accessibility/liveregion/liveregion-bad-angular.sample.html diff --git a/packages/documentation/src/stories/foundation/accessibility/liveregion-good-angular.sample.html b/packages/documentation/src/stories/foundation/accessibility/liveregion/liveregion-good-angular.sample.html similarity index 100% rename from packages/documentation/src/stories/foundation/accessibility/liveregion-good-angular.sample.html rename to packages/documentation/src/stories/foundation/accessibility/liveregion/liveregion-good-angular.sample.html diff --git a/packages/documentation/src/stories/foundation/accessibility/liveregion/liveregion.docs.mdx b/packages/documentation/src/stories/foundation/accessibility/liveregion/liveregion.docs.mdx new file mode 100644 index 0000000000..6b4bdb8408 --- /dev/null +++ b/packages/documentation/src/stories/foundation/accessibility/liveregion/liveregion.docs.mdx @@ -0,0 +1,51 @@ +import { Meta, Source, Canvas } from '@storybook/blocks'; +import * as LiveRegionStories from './liveregion.stories'; +import liveRegionAtomicSample from './liveregion-atomic.sample.html?raw'; +import liveRegionGoodAngularSample from './liveregion-good-angular.sample.html?raw'; +import liveRegionBadAngularSample from './liveregion-bad-angular.sample.html?raw'; + + + + +# Live region + +A live region allows you to notify the user about a dynamic change without requiring the page to reload e.g. alert, loading status, chat logs, update of a product cart, feeds, etc. + +They are defined either by using the `aria-live` attribute or some specific `role` attributes such as `role=status`, `role=alert`, `role=log`, etc. + +## Implicit aria-live attribute with role attribute + +`role=status`, `role=log` and `role=alert` have an implicit default `aria-live` attribute, however for a maximum compatibility, it is recommended to add it as well (except for `role=alert`). Source: [Roles with implicit live region attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions#roles_with_implicit_live_region_attributes) + +## Choose the appropriate value for the aria-live attribute + +`aria-live` attribute can be either: +* `polite`: message will be announced after the screen reader is idle. +* `assertive`: message will interrupt any announcement immediately. It should be used sparingly. + +## Announce the whole Live region on change + +By default, screen readers will only announce the part that changed. However, it's often better to repeat the context of the change. +To do so, we can add `aria-atomic=true` attribute on the live region. This attribute force screen readers to read the whole text. + +For example on a shopping website, you want to announce to the user that a product was added to the shopping basket. If you announce only the product name, it's not enough to be comprehensive. + + + +### Add or remove dynamically a live region + +As a best practice, live region should be present on the page load and only the content inside it should change. + +### Example with a spinner on Angular + +When adding, for example, a spinner above a section, the live region container should be rendered initially while you can use `ng-container` to show and hide the spinner when you need it. + +#### Good example + + + +#### Bad example + +You shouldn't add the whole region dynamically as the accessibility bindings might not be [updated with some screen readers](https://www.scottohara.me/blog/2022/02/05/are-we-live.html#non-normative-rule-for-common-live-region-use-case). + + diff --git a/packages/documentation/src/stories/foundation/accessibility/liveregion/liveregion.stories.ts b/packages/documentation/src/stories/foundation/accessibility/liveregion/liveregion.stories.ts new file mode 100644 index 0000000000..afabeb73a2 --- /dev/null +++ b/packages/documentation/src/stories/foundation/accessibility/liveregion/liveregion.stories.ts @@ -0,0 +1,17 @@ +import { StoryObj } from '@storybook/web-components'; +import { MetaExtended } from '@root/types'; +import { html } from 'lit'; + +const meta: MetaExtended = { + id: '548d973c-679c-4a02-96cd-70f82aec5f65', + title: 'Foundations/Accessibility/LiveRegion', + parameters: { + badges: [], + }, +}; + +export default meta; + +type Story = StoryObj; + +export const Default: Story = {}; diff --git a/packages/documentation/src/stories/foundation/accessibility/regulation.docs.mdx b/packages/documentation/src/stories/foundation/accessibility/regulation.docs.mdx new file mode 100644 index 0000000000..52c0b5edf7 --- /dev/null +++ b/packages/documentation/src/stories/foundation/accessibility/regulation.docs.mdx @@ -0,0 +1,17 @@ +import { Meta, Source, Canvas } from '@storybook/blocks'; +import * as RegulationStories from './regulation.stories'; + + + +# Accessibility + +
+
+

Die Postdienste müssen so angeboten werden, dass Menschen mit Behinderungen +sie in qualitativer, quantitativer und wirtschaftlicher Hinsicht unter vergleichbaren +Bedingungen wie Menschen ohne Behinderungen beanspruchen können.

+
+
+ §14.7 Swiss postal law +
+
diff --git a/packages/documentation/src/stories/foundation/accessibility/regulation.stories.ts b/packages/documentation/src/stories/foundation/accessibility/regulation.stories.ts new file mode 100644 index 0000000000..05f5ac861b --- /dev/null +++ b/packages/documentation/src/stories/foundation/accessibility/regulation.stories.ts @@ -0,0 +1,17 @@ +import { StoryObj } from '@storybook/web-components'; +import { MetaExtended } from '@root/types'; +import { html } from 'lit'; + +const meta: MetaExtended = { + id: '759a427c-7884-474e-b6b7-de32d3acf5df', + title: 'Foundations/Accessibility/Regulation', + parameters: { + badges: [], + }, +}; + +export default meta; + +type Story = StoryObj; + +export const Default: Story = {}; diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 7609a281c6..c2b1de02c4 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -167,7 +167,7 @@ importers: devDependencies: '@angular-devkit/build-angular': specifier: 18.1.3 - version: 18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/localize@18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8))))(@types/node@20.14.14)(chokidar@3.6.0)(jest-environment-jsdom@29.7.0)(jest@29.7.0(@types/node@20.14.14)(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)))(karma@6.4.4)(ng-packagr@18.1.0(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(tailwindcss@3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)))(tslib@2.6.3)(typescript@5.5.4))(tailwindcss@3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)))(typescript@5.5.4) + version: 18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/localize@18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8))))(@types/node@20.14.14)(chokidar@3.6.0)(jest-environment-jsdom@29.7.0)(jest@29.7.0(@types/node@20.14.14))(karma@6.4.4)(ng-packagr@18.1.0(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(tailwindcss@3.4.7)(tslib@2.6.3)(typescript@5.5.4))(tailwindcss@3.4.7)(typescript@5.5.4) '@angular-eslint/builder': specifier: 18.2.0 version: 18.2.0(eslint@8.57.0)(typescript@5.5.4) @@ -218,7 +218,7 @@ importers: version: 2.1.0(jasmine-core@5.2.0)(karma-jasmine@5.1.0(karma@6.4.4))(karma@6.4.4) ng-packagr: specifier: 18.1.0 - version: 18.1.0(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(tailwindcss@3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)))(tslib@2.6.3)(typescript@5.5.4) + version: 18.1.0(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(tailwindcss@3.4.7)(tslib@2.6.3)(typescript@5.5.4) typescript: specifier: 5.5.4 version: 5.5.4 @@ -845,7 +845,7 @@ importers: devDependencies: '@angular-devkit/build-angular': specifier: 18.1.3 - version: 18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/localize@18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8))))(@types/node@20.14.14)(chokidar@3.6.0)(jest-environment-jsdom@29.7.0)(jest@29.7.0(@types/node@20.14.14)(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)))(karma@6.4.4)(ng-packagr@18.1.0(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(tailwindcss@3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)))(tslib@2.6.3)(typescript@5.5.4))(tailwindcss@3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)))(typescript@5.5.4) + version: 18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/localize@18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8))))(@types/node@20.14.14)(chokidar@3.6.0)(jest-environment-jsdom@29.7.0)(jest@29.7.0(@types/node@20.14.14))(karma@6.4.4)(ng-packagr@18.1.0(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(tailwindcss@3.4.7)(tslib@2.6.3)(typescript@5.5.4))(tailwindcss@3.4.7)(typescript@5.5.4) '@angular-eslint/builder': specifier: 18.2.0 version: 18.2.0(eslint@8.57.0)(typescript@5.5.4) @@ -899,7 +899,7 @@ importers: version: 2.1.0(jasmine-core@5.2.0)(karma-jasmine@5.1.0(karma@6.4.4))(karma@6.4.4) ng-packagr: specifier: 18.1.0 - version: 18.1.0(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(tailwindcss@3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)))(tslib@2.6.3)(typescript@5.5.4) + version: 18.1.0(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(tailwindcss@3.4.7)(tslib@2.6.3)(typescript@5.5.4) rimraf: specifier: 6.0.1 version: 6.0.1 @@ -1149,7 +1149,7 @@ importers: devDependencies: '@angular-devkit/build-angular': specifier: 18.1.3 - version: 18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/localize@18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8))))(@types/node@20.14.14)(chokidar@3.6.0)(jest-environment-jsdom@29.7.0)(jest@29.7.0(@types/node@20.14.14)(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)))(karma@6.4.4)(ng-packagr@18.1.0(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(tailwindcss@3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)))(tslib@2.6.3)(typescript@5.5.4))(tailwindcss@3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)))(typescript@5.5.4) + version: 18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/localize@18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8))))(@types/node@20.14.14)(chokidar@3.6.0)(jest-environment-jsdom@29.7.0)(jest@29.7.0(@types/node@20.14.14))(karma@6.4.4)(ng-packagr@18.1.0(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(tailwindcss@3.4.7)(tslib@2.6.3)(typescript@5.5.4))(tailwindcss@3.4.7)(typescript@5.5.4) '@angular/cli': specifier: 18.1.3 version: 18.1.3(chokidar@3.6.0) @@ -1179,7 +1179,7 @@ importers: version: 2.1.0(jasmine-core@5.2.0)(karma-jasmine@5.1.0(karma@6.4.4))(karma@6.4.4) ng-packagr: specifier: 18.1.0 - version: 18.1.0(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(tailwindcss@3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)))(tslib@2.6.3)(typescript@5.5.4) + version: 18.1.0(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(tailwindcss@3.4.7)(tslib@2.6.3)(typescript@5.5.4) npm-run-all2: specifier: 6.2.2 version: 6.2.2 @@ -11165,13 +11165,13 @@ snapshots: - utf-8-validate - webpack-cli - '@angular-devkit/build-angular@18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/localize@18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8))))(@types/node@20.14.14)(chokidar@3.6.0)(jest-environment-jsdom@29.7.0)(jest@29.7.0(@types/node@20.14.14)(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)))(karma@6.4.4)(ng-packagr@18.1.0(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(tailwindcss@3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)))(tslib@2.6.3)(typescript@5.5.4))(tailwindcss@3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)))(typescript@5.5.4)': + '@angular-devkit/build-angular@18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/localize@18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8))))(@types/node@20.14.14)(chokidar@3.6.0)(jest-environment-jsdom@29.7.0)(jest@29.7.0(@types/node@20.14.14))(karma@6.4.4)(ng-packagr@18.1.0(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(tailwindcss@3.4.7)(tslib@2.6.3)(typescript@5.5.4))(tailwindcss@3.4.7)(typescript@5.5.4)': dependencies: '@ampproject/remapping': 2.3.0 '@angular-devkit/architect': 0.1801.3(chokidar@3.6.0) '@angular-devkit/build-webpack': 0.1801.3(chokidar@3.6.0)(webpack-dev-server@5.0.4(webpack@5.92.1(esbuild@0.21.5)))(webpack@5.92.1(esbuild@0.21.5)) '@angular-devkit/core': 18.1.3(chokidar@3.6.0) - '@angular/build': 18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/localize@18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8))))(@types/node@20.14.14)(chokidar@3.6.0)(less@4.2.0)(postcss@8.4.38)(tailwindcss@3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)))(terser@5.29.2)(typescript@5.5.4) + '@angular/build': 18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/localize@18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8))))(@types/node@20.14.14)(chokidar@3.6.0)(less@4.2.0)(postcss@8.4.38)(tailwindcss@3.4.7)(terser@5.29.2)(typescript@5.5.4) '@angular/compiler-cli': 18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4) '@babel/core': 7.24.7 '@babel/generator': 7.24.7 @@ -11235,11 +11235,11 @@ snapshots: optionalDependencies: '@angular/localize': 18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8))) esbuild: 0.21.5 - jest: 29.7.0(@types/node@20.14.14)(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)) + jest: 29.7.0(@types/node@20.14.14) jest-environment-jsdom: 29.7.0 karma: 6.4.4 - ng-packagr: 18.1.0(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(tailwindcss@3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)))(tslib@2.6.3)(typescript@5.5.4) - tailwindcss: 3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)) + ng-packagr: 18.1.0(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(tailwindcss@3.4.7)(tslib@2.6.3)(typescript@5.5.4) + tailwindcss: 3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.6.2)) transitivePeerDependencies: - '@rspack/core' - '@swc/core' @@ -11415,7 +11415,7 @@ snapshots: - supports-color - terser - '@angular/build@18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/localize@18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8))))(@types/node@20.14.14)(chokidar@3.6.0)(less@4.2.0)(postcss@8.4.38)(tailwindcss@3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)))(terser@5.29.2)(typescript@5.5.4)': + '@angular/build@18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/localize@18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8))))(@types/node@20.14.14)(chokidar@3.6.0)(less@4.2.0)(postcss@8.4.38)(tailwindcss@3.4.7)(terser@5.29.2)(typescript@5.5.4)': dependencies: '@ampproject/remapping': 2.3.0 '@angular-devkit/architect': 0.1801.3(chokidar@3.6.0) @@ -11450,7 +11450,7 @@ snapshots: '@angular/localize': 18.1.3(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8))) less: 4.2.0 postcss: 8.4.38 - tailwindcss: 3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)) + tailwindcss: 3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.6.2)) transitivePeerDependencies: - '@types/node' - chokidar @@ -20881,7 +20881,7 @@ snapshots: - supports-color optional: true - ng-packagr@18.1.0(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(tailwindcss@3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)))(tslib@2.6.3)(typescript@5.5.4): + ng-packagr@18.1.0(@angular/compiler-cli@18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4))(tailwindcss@3.4.7)(tslib@2.6.3)(typescript@5.5.4): dependencies: '@angular/compiler-cli': 18.1.3(@angular/compiler@18.1.3(@angular/core@18.1.3(rxjs@7.8.1)(zone.js@0.14.8)))(typescript@5.5.4) '@rollup/plugin-json': 6.1.0(rollup@4.18.1) @@ -20910,7 +20910,7 @@ snapshots: typescript: 5.5.4 optionalDependencies: rollup: 4.18.1 - tailwindcss: 3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)) + tailwindcss: 3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.6.2)) transitivePeerDependencies: - supports-color @@ -21638,15 +21638,6 @@ snapshots: ts-node: 10.9.2(@types/node@20.12.7)(typescript@5.5.4) optional: true - postcss-load-config@4.0.2(postcss@8.4.40)(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)): - dependencies: - lilconfig: 3.1.2 - yaml: 2.5.0 - optionalDependencies: - postcss: 8.4.40 - ts-node: 10.9.2(@types/node@20.14.14)(typescript@5.5.4) - optional: true - postcss-load-config@4.0.2(postcss@8.4.40)(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.6.2)): dependencies: lilconfig: 3.1.2 @@ -23334,34 +23325,6 @@ snapshots: - ts-node optional: true - tailwindcss@3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)): - dependencies: - '@alloc/quick-lru': 5.2.0 - arg: 5.0.2 - chokidar: 3.6.0 - didyoumean: 1.2.2 - dlv: 1.1.3 - fast-glob: 3.3.2 - glob-parent: 6.0.2 - is-glob: 4.0.3 - jiti: 1.21.6 - lilconfig: 2.1.0 - micromatch: 4.0.7 - normalize-path: 3.0.0 - object-hash: 3.0.0 - picocolors: 1.0.1 - postcss: 8.4.40 - postcss-import: 15.1.0(postcss@8.4.40) - postcss-js: 4.0.1(postcss@8.4.40) - postcss-load-config: 4.0.2(postcss@8.4.40)(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.5.4)) - postcss-nested: 6.2.0(postcss@8.4.40) - postcss-selector-parser: 6.1.1 - resolve: 1.22.8 - sucrase: 3.35.0 - transitivePeerDependencies: - - ts-node - optional: true - tailwindcss@3.4.7(ts-node@10.9.2(@types/node@20.14.14)(typescript@5.6.2)): dependencies: '@alloc/quick-lru': 5.2.0 @@ -23431,7 +23394,7 @@ snapshots: term-size@2.2.1: {} - terser-webpack-plugin@5.3.10(esbuild@0.21.5)(webpack@5.92.1): + terser-webpack-plugin@5.3.10(esbuild@0.21.5)(webpack@5.92.1(esbuild@0.21.5)): dependencies: '@jridgewell/trace-mapping': 0.3.25 jest-worker: 27.5.1 @@ -24261,7 +24224,7 @@ snapshots: neo-async: 2.6.2 schema-utils: 3.3.0 tapable: 2.2.1 - terser-webpack-plugin: 5.3.10(esbuild@0.21.5)(webpack@5.92.1) + terser-webpack-plugin: 5.3.10(esbuild@0.21.5)(webpack@5.92.1(esbuild@0.21.5)) watchpack: 2.4.1 webpack-sources: 3.2.3 transitivePeerDependencies: From 2fc639ba3af0accdeaae40cf54c8a2a0f166b897 Mon Sep 17 00:00:00 2001 From: Myrta Sakellariou Date: Fri, 4 Oct 2024 09:11:39 +0200 Subject: [PATCH 2/2] feat(documentation): Updated the Accessibility Form Controls Grouping section with minor text changes and corrected the div example --- .changeset/proud-moons-impress.md | 5 +++++ .../foundation/accessibility/forms/forms.docs.mdx | 12 ++++++------ .../foundation/accessibility/forms/forms.stories.ts | 8 +++++--- .../foundation/accessibility/regulation.stories.ts | 1 - 4 files changed, 16 insertions(+), 10 deletions(-) create mode 100644 .changeset/proud-moons-impress.md diff --git a/.changeset/proud-moons-impress.md b/.changeset/proud-moons-impress.md new file mode 100644 index 0000000000..3a4278245e --- /dev/null +++ b/.changeset/proud-moons-impress.md @@ -0,0 +1,5 @@ +--- +'@swisspost/design-system-documentation': patch +--- + +Updated the text of the Accessibility Forms Control Grouping section and corrected the last example diff --git a/packages/documentation/src/stories/foundation/accessibility/forms/forms.docs.mdx b/packages/documentation/src/stories/foundation/accessibility/forms/forms.docs.mdx index d8ed531f36..cf830c0334 100644 --- a/packages/documentation/src/stories/foundation/accessibility/forms/forms.docs.mdx +++ b/packages/documentation/src/stories/foundation/accessibility/forms/forms.docs.mdx @@ -98,11 +98,11 @@ Disabled states of input fields or buttons pose many accessibility issues. ## Controls Grouping -When grouping form controls for accessibility, the `
`and `` 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. +When grouping `
`, the `
`and `` 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.
- + @@ -114,13 +114,13 @@ When grouping form controls for accessibility, the `
`and `` el
@@ -136,7 +136,7 @@ When grouping form controls for accessibility, the `
`and `` el
@@ -158,4 +158,4 @@ When grouping form controls for accessibility, the `
`and `` el #### Alternative using div - \ No newline at end of file + \ No newline at end of file diff --git a/packages/documentation/src/stories/foundation/accessibility/forms/forms.stories.ts b/packages/documentation/src/stories/foundation/accessibility/forms/forms.stories.ts index 978a4716d3..3aea5ed520 100644 --- a/packages/documentation/src/stories/foundation/accessibility/forms/forms.stories.ts +++ b/packages/documentation/src/stories/foundation/accessibility/forms/forms.stories.ts @@ -314,7 +314,8 @@ export const FieldsetDontExample: Story = { export const FieldsetDoExample: Story = { - render: () => html`
+ render: () => html`Please select your gender: +
Gender Male Female @@ -325,8 +326,9 @@ export const FieldsetDoExample: Story = { export const DivForGroupingExample: Story = { - render: () => html`
- Gender + render: () => html`Please select your gender: +
+ Gender Male Female
`, diff --git a/packages/documentation/src/stories/foundation/accessibility/regulation.stories.ts b/packages/documentation/src/stories/foundation/accessibility/regulation.stories.ts index 05f5ac861b..f74f8dc62d 100644 --- a/packages/documentation/src/stories/foundation/accessibility/regulation.stories.ts +++ b/packages/documentation/src/stories/foundation/accessibility/regulation.stories.ts @@ -1,6 +1,5 @@ import { StoryObj } from '@storybook/web-components'; import { MetaExtended } from '@root/types'; -import { html } from 'lit'; const meta: MetaExtended = { id: '759a427c-7884-474e-b6b7-de32d3acf5df',
Common use cases and how to handle them.Common mistakes and how to avoid them.
    -
    ❌
  • A div or other element is incorrectly used as the first child of a `
    ` with the `` nested inside this element. However, improper usage of these elements can lead to confusion for screen readers.
    • +
    ❌
  • A `
    ` or other element is incorrectly used as the first child of a `
    ` with the `` nested inside this element.
    -
    ✔️
  • Always place the `` before any other content within the `
    `to preserve the association.
    • +
    ✔️
  • Always place the `` right after the `
    ` to preserve the association.
    -
    ✔️
  • Assign the role="group" to the `
    ` element inorder to provide it with the semantic meaning of a fieldset. Use 'aria-labelledby' or 'aria-describedby' to associate any descriptive text with the grouping container to ensure that screen readers can provide context to users.
    • +
    ✔️
  • Assign the `role="group"` to the `
    ` element to provide it with the semantic meaning of a `
    `. Use `aria-labelledby` or `aria-describedby` to associate any descriptive text with the grouping container to ensure that screen readers can provide context to users.