docs: Accessibility (a11y)

README.md

@@ -61,6 +61,7 @@ Follow the step-by-step [getting started instructions](docs/getting-started.md).
 All documentation is located in [`docs/`](docs/):
 
 - [Getting Started](docs/getting-started.md)
+- [Accessibility (a11y)](docs/accessibility.md)
 - [Blocks and Components](docs/blocks-and-components.md)
 - [CMS Content Modelling](docs/cms-content-modelling.md)
 - [CMS Data Loading](docs/cms-data-loading.md)

docs/accessibility.md

@@ -0,0 +1,39 @@
+# Accessibility (a11y)
+
+**Head Start aims to provide an accessible baseline, by providing helper classes and components.**
+
+## CSS helper classes
+
+Head Start provides CSS helper classes for improved accessibility:
+
+```astro
+---
+import '@assets/a11y.css';
+---
+
+<span class="a11y-sr-only">
+  This element is visually hidden, while its content is still 
+  accessible by assistive technology like screen readers (sr).
+</span>
+
+<a href="..." class="a11y-kb-only">
+  This element is visually hidden, and appears 
+  only when element has keyboard (kb) focus.
+</a>
+```
+
+## Skip Link component
+
+Head Start provides a [Skip Link component](../src/components/SkipLink/README.md) that enables keyboard users and users of assistive technology to jump over parts of the UI that are repeated. It's pre-configured in the [Default template](../src/layouts/Default.astro).
+
+## Best practices
+
+Head Start aims to stay close to the web standards. Here's a few tips to help keep it accessible:
+
+- Use semantic HTML as a baseline.
+- Use native elements for interaction like `<form>`s, `<label>`led `<input>`s, `<output>`s, `<dialog>`, `<details>` with `<summary>` and native API's like the [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API).
+- Add relevant ARIA roles and attributes on custom interactive components.
+- Require `alt` texts on assets in the CMS and use their value in templates.
+- Test manually using only your keyboard and a screen reader like VoiceOver.
+- Test regularly with tools like [Google Lighthouse](https://developer.chrome.com/docs/lighthouse/overview/) and [WebAIM WAVE](https://wave.webaim.org/).
+- When adding automated tests, consider [Cypress Axe](https://www.npmjs.com/package/cypress-axe#cychecka11y) or [Playwright Axe](https://playwright.dev/docs/accessibility-testing).

src/assets/a11y.css

@@ -0,0 +1,22 @@
+.a11y-sr-only,
+.a11y-kb-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  border: 0;
+  margin: -1px;
+  clip: rect(0 0 0 0);
+  overflow: hidden;
+  white-space: nowrap;
+}
+
+.a11y-kb-only:active,
+.a11y-kb-only:focus {
+  position: static;
+  width: auto;
+  height: auto;
+  margin: 0;
+  clip: auto;
+  overflow: visible;
+}

src/components/Icon/Icon.astro

@@ -1,5 +1,5 @@
 ---
-import type { IconName } from '../../assets/icon-sprite';
+import type { IconName } from '@assets/icon-sprite';
 
 interface Props {
   name: IconName;
@@ -8,7 +8,7 @@ interface Props {
 const { name, ...props } = Astro.props;
 ---
 
-<svg {...props} data-icon={name}>
+<svg {...props} aria-hidden data-icon={name}>
   <use xlink:href={`#${name}`} />
 </svg>
 

src/components/LocaleSelector/LocaleSelector.astro

@@ -2,6 +2,7 @@
 import { getLocale, locales, t } from '@lib/i18n';
 import type { SiteLocale } from '@lib/types/datocms';
 import type { PageUrl } from '@lib/seo';
+import '@assets/a11y.css';
 
 const activeLocale = getLocale();
 
@@ -19,7 +20,7 @@ const getPageHref = (locale: SiteLocale) => {
 ---
 <locale-selector>
   <nav aria-labelledby="locale-selector-title">
-    <span id="locale-selector-title" class="sr-only">
+    <span id="locale-selector-title" class="a11y-sr-only">
       { t('select_language') }
     </span>
     <ul role="list" style="list-style: none;">
@@ -39,20 +40,6 @@ const getPageHref = (locale: SiteLocale) => {
 <script src="./LocaleSelector.client.ts"></script>
 
 <style>
-  /* functional styling */
-  .sr-only {
-    /* @see https://tailwindcss.com/docs/screen-readers */
-    position: absolute;
-    width: 1px;
-    height: 1px;
-    padding: 0;
-    margin: -1px;
-    overflow: hidden;
-    clip: rect(0, 0, 0, 0);
-    white-space: nowrap;
-    border-width: 0;
-  }
-
   /* basic styling, can be removed */
   ul {
     margin: 0;

src/components/SkipLink/SkipLink.astro

@@ -1,28 +1,20 @@
 ---
 import { t } from '@lib/i18n';
+import '@assets/a11y.css';
 
 interface Props {
   targetId: string;
 }
 const { targetId } = Astro.props;
 ---
-<a href={`#${targetId}`}>
+<a href={`#${targetId}`} class="a11y-kb-only">
   <slot>{ t('skip_to_content') }</slot>
 </a>
 
 <style>
-/* functional styling */
-a {
-  position: absolute;
-  top: 1rem;
-  left: -9999rem;
-}
-a:focus {
-  left: 1rem;
-}
-
 /* basic styling, can be removed */
-a {
+a:focus {
+  position: absolute;
   background: white;
   padding: .5em;
 }

src/layouts/Default.astro

@@ -11,6 +11,7 @@ import LocaleSelector from '@components/LocaleSelector/LocaleSelector.astro';
 import PreviewModeProvider from '@components/PreviewMode/PreviewModeProvider.astro';
 import SeoHead from '@components/SeoHead.astro';
 import SkipLink from '@components/SkipLink/SkipLink.astro';
+import '@assets/a11y.css';
 
 interface Props {
   pageUrls: PageUrl[];

tsconfig.json

@@ -3,6 +3,7 @@
   "compilerOptions": {
     "baseUrl": ".",
     "paths": {
+      "@assets/*": ["src/assets/*"],
       "@blocks/*": ["src/blocks/*"],
       "@components/*": ["src/components/*"],
       "@layouts/*": ["src/layouts/*"],