feat: add guidance for screenreader-only component

src/en/components/heading/use-case.md

@@ -34,6 +34,6 @@ Use headings to:
 
 <a href="{{ links.text }}" class="link-light">Text</a> for paragraphs displaying non-heading content with matching GC Design System styles.
 
-<a href="{{ links.screenreaderContent }}" class="link-light">Screenreader content</a> for information that's detectable with assistive technologies like screen readers, but invisible to sighted users.
+<a href="{{ links.screenreaderOnly }}" class="link-light">Screenreader-only</a> for information that's detectable with assistive technologies like screen readers, but invisible to sighted users.
 
 </article>

src/en/components/screenreader-only/base.md

@@ -0,0 +1,19 @@
+---
+github: https://github.com/cds-snc/gcds-components/tree/main/packages/web/src/components/gcds-sr-only
+figma:
+permalink: false
+tags: ['screenreaderonlyEN', 'header']
+---
+
+# Screenreader-only <br>`<gcds-sr-only>`
+
+_Also called: visually hidden, assistive text._
+
+The screenreader-only component is text information only accessible with assistive technologies.
+
+{% docLinks locale stage figma github %}
+{% enddocLinks %}
+
+{% componentPreview "Screenreader-only component preview" %}
+<gcds-sr-only>Text only seen by assistive technologies.</gcds-sr-only>
+{% endcomponentPreview %}

src/en/components/screenreader-only/code.md

@@ -0,0 +1,38 @@
+---
+title: Screenreader-only
+layout: 'layouts/component-documentation.njk'
+translationKey: 'screenreaderonlyCode'
+tags: ['screenreaderonlyEN', 'code']
+date: 'git Last Modified'
+---
+
+## Build a screenreader-only
+
+Use screenreader-only for assistive technology-specific text content that communicates information solely available by visual means.
+
+## Coding and Accessibility for screenreader-only
+
+### Write helpful screenreader-only content
+
+- Flag contextual information exclusively communicated through visual styling that's absent from ‌semantic HTML.
+- Keep screenreader-only content clear and very brief. Adding too much text unnecessarily increases the cognitive load.
+- Provide additional text content for assistive technologies only when the interface design relies on visual information to communicate.
+- Avoid including additional information that's unavailable in the interface.
+- Avoid duplicating any information included in descriptive text (alt-text). If the descriptive text already provides the context, the screenreader-only component may not be needed.
+
+### Provide an equitable experience in both Official Languages
+
+- Use the screenreader-only content to make sure the text will be read in the language associated with the component's language tag.
+- Avoid using an `aria-label` attribute to set another language because some assistive technologies will default to page's source language.
+
+{% include "partials/getcode.njk" %}
+
+<iframe
+  title="Overview of gcds-sr-only properties and events."
+  src="https://cds-snc.github.io/gcds-components/iframe.html?viewMode=docs&demo=true&singleStory=true&id=components-screen-reader-only--events-properties&lang=en"
+  width="1200"
+  height="750"
+  style="display: block; margin: 0 auto;"
+  frameBorder="0"
+  allow="clipboard-write"
+></iframe>

src/en/components/screenreader-only/design.md

@@ -0,0 +1,17 @@
+---
+title: Screenreader-only
+layout: 'layouts/component-documentation.njk'
+translationKey: 'screenreaderonlyDesign'
+tags: ['screenreaderonlyEN', 'design']
+date: 'git Last Modified'
+---
+
+## Design and accessibility for the screenreader-only component
+
+### Write helpful screenreader-only content
+
+- Flag contextual information exclusively communicated through visual styling that’s absent from ‌semantic HTML.
+- Keep screenreader-only content clear and very brief. Adding too much text unnecessarily increases the cognitive load.
+- Provide additional text content specifically for assistive technologies only when the interface design relies on visual information to communicate.
+- Avoid including additional information that’s unavailable in the interface.
+- Avoid duplicating any information included in descriptive text (alt-text). If the descriptive text already provides the context, the screenreader-only component may not be needed.

src/en/components/screenreader-only/use-case.md

@@ -0,0 +1,37 @@
+---
+title: Screenreader-only
+layout: 'layouts/component-documentation.njk'
+eleventyNavigation:
+  key: screenreaderonlyEN
+  title: Screenreader-only
+  locale: en
+  parent: componentsEN
+  otherNames: visually hidden, assistive text.
+  description: The screenreader-only component is text information only accessible with assistive technologies.
+  thumbnail: /images/common/components/preview-screenreader-only.svg
+  alt: One blue-grey line with a dotted line border stacked above two grey lines. The colour of all of the lines fades from the left to the right ends. A blue-grey sound icon is superimposed on the two bottom lines.
+  tag: Experimental
+  state: published
+translationKey: 'screenreaderonly'
+tags: ['screenreaderonlyEN', 'usage']
+permalink: /en/components/screenreader-only/
+date: 'git Last Modified'
+---
+
+## Problems screenreader-only solves
+
+Use screenreader-only to:
+
+- Provide context to people using screen reader assistive technologies.
+- Offer a text option to communicate information typically solely available by visual means.
+- Communicate effectively without adding more text to the main content. This helps reduce cognitive load for everyone by only providing content when and where it’s needed.
+- Improve the assistive tech experience when there are no other suitable options in semantic HTML.
+
+<article class="bg-full-width bg-primary text-light pt-500 pb-400 my-500">
+  <h2 class="mt-0 mb-400">Related components</h2>
+
+<a href="{{ links.heading }}" class="link-light">Headings</a> for structuring content by creating levels of hierarchy that organize page content visually and mentally, using GC Design System styles.
+
+<a href="{{ links.text }}" class="link-light">Text</a> for paragraphs displaying non-heading content with matching GC Design System styles.
+
+</article>

src/en/components/text/use-case.md

@@ -32,7 +32,7 @@ Use the text component to:
 
 <a href="{{ links.heading }}" class="link-light">Headings</a> for structuring content by creating levels of hierarchy that organize page content visually and mentally, using GC Design System styles.
 
-<a href="{{ links.screenreaderContent }}" class="link-light">Screenreader content</a> for information that is accessible for assistive technologies like screen readers, but invisible for sighted users.
+<a href="{{ links.screenreaderOnly }}" class="link-light">Screenreader-only</a> for information that is accessible for assistive technologies like screen readers, but invisible for sighted users.
 
 </article>
 

src/en/en.json

@@ -36,7 +36,7 @@
     "link": "/en/components/link",
     "pagination": "/en/components/pagination",
     "radio": "/en/components/radio",
-    "screenreaderContent": "/en/coming-soon",
+    "screenreaderOnly": "/en/components/screenreader-only",
     "search": "/en/components/search",
     "select": "/en/components/select",
     "sideNav": "/en/components/side-navigation",

src/fr/composants/masquage-accessible/base.md

@@ -0,0 +1,19 @@
+---
+github: https://github.com/cds-snc/gcds-components/tree/main/packages/web/src/components/gcds-sr-only
+figma:
+permalink: false
+tags: ['screenreaderonlyFR', 'header']
+---
+
+# Masquage accessible <br>`<gcds-sr-only>`
+
+_Autres noms : masquage visuel, lecteur d'écran uniquement._
+
+Le masquage accessible est une façon de rendre l'information textuelle uniquement accessible à des technologies d’assistance.
+
+{% docLinks locale stage figma github %}
+{% enddocLinks %}
+
+{% componentPreview "Aperçu du composant de masquage accessible" %}
+<gcds-sr-only>Texte consultable seulement par les technologies d'assistance.</gcds-sr-only>
+{% endcomponentPreview %}

src/fr/composants/masquage-accessible/case-dusage.md

@@ -0,0 +1,36 @@
+---
+title: Masquage accessible
+layout: 'layouts/component-documentation.njk'
+eleventyNavigation:
+  key: screenreaderonlyFR
+  title: Masquage accessible
+  locale: fr
+  parent: componentsFR
+  otherNames: masquage visuel, lecteur d'écran uniquement.
+  description: Le masquage accessible est une façon de rendre l'information textuelle uniquement accessible à des technologies d'assistance.
+  thumbnail: /images/common/components/preview-screenreader-only.svg
+  alt: Une ligne bleu-gris avec bordure en pointillé au-dessus de deux lignes grises. Sur chaque ligne, la couleur s'efface au blanc de gauche à droite. Une icône de haut-parleur est superposée sur les deux lignes du bas.
+  state: published
+translationKey: 'screenreaderonly'
+tags: ['screenreaderonlyFR', 'usage']
+permalink: /fr/composants/masquage-accessible/
+date: 'git Last Modified'
+---
+
+## Problèmes résolus par le masquage accessible
+
+Utilisez le masquage accessible pour :
+
+- Fournir du contexte aux personnes utilisant des technologies d'assistance de type lecteur d'écran.
+- Offrir une option textuelle pour communiquer des informations généralement exprimées par des moyens visuels uniquement.
+- Communiquer efficacement sans ajouter de texte au contenu principal. Le fait de fournir du contenu seulement à l'endroit et au moment où il le faut permet de réduire la charge cognitive pour tout le monde.
+- Améliorer l'expérience d'utilisation d'une technologie d'assistance quand il n'y a pas d'autre option adéquate dans le HTML sémantique.
+
+<article class="bg-full-width bg-primary text-light pt-500 pb-400 my-500">
+  <h2 class="mt-0 mb-400">Composants connexes</h2>
+
+<a href="{{ links.heading }}" class="link-light">Titre</a> pour structurer le contenu en créant des niveaux hiérarchiques qui permettent l'organisation visuelle et mentale du contenu de la page à l'aide des styles de Système de design GC.
+
+<a href="{{ links.text }}" class="link-light">Texte</a> pour des paragraphes affichant du contenu autre qu'un en-tête avec les styles correspondants de Système de design GC.
+
+</article>