Forem: Erik Kroes

Accessibility is not binary

Erik Kroes — Fri, 22 Sep 2023 07:47:47 +0000

Often when people talk about accessibility, it appears to be this binary thing. Something either is or isn’t accessible. And that’s true, but it also isn’t.

Is it accessible?

I learned a lot about accessibility with this mindset. I’ve always thought of accessibility as a bridge. You can fix 99% of the bridge, but if one section is missing, people still can’t cross. A bridge with holes isn’t a finished bridge. There’s still work to do!

When you think of accessibility as a subject for business, it’s probably true! Let’s frame it as a user story: As a business I want to comply with WCAG 2.1 AA so I can avoid law suits.

And that’s the thing right? For a lot of people(/businesses) being accessible means being compliant with WCAG (Web Content Accessibility Guidelines) 2.1 AA. And yes, the question “Is this compliant?” can be answered with a hard yes or no.

And that’s where audits come in. An audit is when a specialist inspects your website (or app?). Often they follow the methodology WCAG-EM. Their findings go into a big report that states wether you’re accessible (complying with WCAG 2.1 AA) or not, and what you need to fix.

In a world where goals and targets are decided by those in management, compliance will often be the target. And in such a situation, an audit is very logical.

Is it valuable?

But do I believe that is what accessibility is about? It’s the frame I always had but no, accessibility is a spectrum. Even when you’re not fully accessible (WCAG 2.1 AA compliant), you can still be more accessible than other iterations/the competition.

You might still be excluding people, but that doesn’t mean there are no improvements. I’d still aim for WCAG-compliance. There’s a reason these guidelines end up in regulations all over the world: they’re pretty good. But it also a minimum. It’s the legal requirement in many situations that will avoid getting you sued. It’s not the ideal standard that will ensure everybody will have a great time interacting with your website.

But don’t forget to be proud when you’re making steps -towards- compliance. When your product is audited, and you’ve fixed previous issues... that’s improvement! You’re including -more- people than before. And that’s valuable! Be proud of what you’ve achieved and what you’ve learned!

Concluding

Audits are a great tool for compliance. They’re an external collection of findings. Taking the point of view of somebody building something, it might not be the most valuable feedback. A modern workflow start with components and does not revolve around the delivered pages. So you want your feedback to be shaped like that as well.

If you’re going for something that’s not just compliance, I would advice looking from the ground up. Make accessibility part of the requirements, incorporate it in your foundations (like design systems and component libraries), focus on it during design, make it part of your handovers, consider it while building and double-check it when delivering.

Something as foundational as accessibility can be judged with an audit, but just looking at the end-result won’t fix it. Even when you aim for compliance, it’ll be hard to reach from an audit.

Color and contrast, what does it mean?

Erik Kroes — Tue, 07 Sep 2021 07:44:41 +0000

The color contrast ratios mentioned in WCAG can give you an insight in how usable your color palette is. How that works isn't very transparent. Learn more about how the color contrast ratio is determined, and what that means for you (and your palette).

Originally posted on erikKroes.nl. Questions are also welcome on Twitter

How it used to be

When I started auditing websites and designs, my life was still simple.

I'd grab a color picker tool like the Colour Contrast Analyser.
For pieces of text, I'd pick the background color.
And separately I'd pick the foreground color.
The tool would spit out a number for me; the contrast ratio.
I'd apply WCAG Succes Criterion 1.4.3: Contrast (Minimum). In short, if the ratio is below 3.0:1, it would lack contrast. If it's above 4.5:1, it would be fine. If it's inbetween, I'd have to check the text size. Large text (at least 19px and bold, or at least 24px) would still pass. Fail for anything else. This all assuming an audit at level AA.

Problably no big surprises for many people reading this. A small recap to make sure. I use a tool to measure the contrast between text and its background. WCAG gives us a ratio as a minimum requirement. Large text gets a bit of slack.

I didn't question the numbers, and the numbers didn't question me. Until I did.

The fabric store

This all changed because I ran an online fabric store with my wife. An online store needs a website. We had one, but it was WordPress, and WooCommerce, and a theme, and a child theme, lots of extensions, and two versions of bootstrap at the same time. Let's say there was room for improvement in how things were built.

So I went for an adequete amount of exaggeration and thought, why not start with the basics? Why not start with... an accessible color palette?

And that's when things got interesting. I always learn things when I put myself in the shoes of people I usually communicate with. In this case, I dove into something designers usually do. And (spoiler) it's not easy to make such a color palette!

Color, it's pretty complicated

Studying photography has taught me color is not an easy subject. You quickly touch on subjects like:

How do eyes work?
How does the brain interpret what it sees?
How do we display color?

It's a colorful rabbit hole, but still a rabbit hole.

Color models

Red, Green and Blue

If you're reading this, I'm assuming you know something about computers. On computers we traditionally define colors with Red, Green and Blue. Why? Because displays work with tiny red, green and blue lights. And together they can be any (sort of) color. An RGB-notation can be used for this.

In CSS there is a scale of 0 to 255 for color values. 255, 0, 0 means all the red, no green and no blue. This results in red. A harsh blue would be 0, 0, 255. Orange is full red and half green: 255, 127, 0. White is 255, 255, 255. Black is 0, 0, 0. The value is from 0 to 255 because thats 256 and 2 to the power of 8 is 256 and a byte and.. before you know it I start ranting about color again.

But nevermind. WCAG works differently.

Hue, Saturation and Lightness

There's also HSL (instead of RGB). It works with Hue, Saturation and Lightness. You might've seen (haha) it before. Hue is like having all tints in a circle. It starts with 0 (degrees) for red. Rotate to 30 and you get orange. Rotate to 60 for yellow. 120 is green. 240 is blue. 360 or 0 (full circle) is red again. Feels much more intuitive to me!

Saturation is how saturated or full a color is. 100 (percent) for full color and 0 for none. The L is for Lightness. How light an image is with 100 (percent) being white and 0 being black.

That sounds much more understandable and readable than RGB. It's almost usable! But of course, it's not. Making things easy would be... too easy? Compare the two colors in this image.

It's a blue (240, 100, 50 in HSL) and a yellow (60, 100, 50) in HSL. The only difference is the hue. But to our eyes and in our perception, the blue is much darker than the yellow.

To put it in further perspective. These are three red squares. The first and brightest is 0, 100, 68. It has a contrast ratio of 3.0:1 on white. The second is 0, 100, 47 and a ratio of 4.5:1. The third is 0, 100, 36 and has a ratio of 7.0:1. The ratios were picked because they're practical in a WCAG-context. Don't read too much into them.

Now what happens if we make a grid with the same saturation, these three luminosities but different hues?

We get red, yellow, green, cyan, blue and magenta. They're evenly spaced on the hue-scale. They are not, however, evenly scaled in contrast. Where red a nice 3.0, 4.5 and 7.0, yellow is 1.1, 1.2 and 2.1. Much lower numbers! So the L-value is the same, but the contrast isn't. Blue is much like the opposite of yellow in this case with contrasts of 4.8, 9.3 and 12.4. Where the darkest yellow is not contrasty enough (according to WCAG) for large text (it's less than 3.0), the lightest blue is dark enough (more than 4.5) for small text even!

Check out all the contrast ratios in this table.

Red	Yellow	Green	Cyan	Blue	Magenta
3.0	1.1	1.3	1.2	4.8	2.6
4.5	1.2	1.6	1.4	9.3	3.5
7.0	2.1	2.7	2.5	12.4	5.6

Is that all?

Maybe you know some other models as well. There's RGBA and HSLA, which include opacity. There's HSB (Hue, Saturation and Brightness) used by tools like photoshop. There's CMYK (Cyan, Magenta, Yellow and Key/blacK) for print. Plenty of options!

And I'm not even going into Color Spaces yet here. I told you color can get complicated!

WCAG?

Yeah sorry. WCAG uses none of those really. Contrast in WCAG is based on ITU-R Recommendation BT.709. What? ITU-R Recommendation BT.709. That's not very clear.

ITU-R Recommendation BT.709, more commonly known by the abbreviations Rec. 709 or BT.709, standardizes the format of high-definition television, having 16:9 (widescreen) aspect ratio. The first edition of the standard was approved in 1990.

That doesn't help much either probably. Sorry about that. Some things that stand out:

It's a television standard (of course, why not?)
It has the same color coverage as sRGB (a much used color space, relevant to computer screens)
It has a component called Luma (component like R in RGB or H in HSL)
It's a way to measure brightness in sRGB that takes the human eye in account

Trying to get back to why all of this is relevant. You don't measure RGB values when you use a color contrast tool. What's relevant in the end is the Luma-component. This component can be calculated from RGB (sRGB usually). The contrast is about 72% based on green (because our eyes are generally sensitive to green), 21% based on red and about 7% based on blue. Your eyes don't care much about blue.

We have Luma!

Now we have this value, it's used to calculate the contrast. As you may have noticed in contrast tools, the value varies from 1:1 to 21:1. It's never below 1 or above 21. That's due to the formula WCAG uses. It's a practical choice as far as I know.

So if black is 1, then white is 21. White is 21 times as bright as black in this system. And black is 21 times as dark as white. The implication here, that was the big eye-opener for me, is that it's a ratio with a clearly defined range.

If black is 1, and a color X has a ratio of 3.0:1 on black.. then X has a ratio of (21/3=7) 7.0:1 on white.

Trying to phrase this in multiple ways because it took me a bit for the coin to drop. If black is 1, X is 3, and white is 21. Then white/X (21/3) is 7.

If you have a color Y that's 4.5:1 on black, then it's also (21/4.5=4.67) 4.67:1 on white.

What does that mean for color palettes?

If you are aiming for a minimum contrast of 3.0:1 between shades, then there can be only 3. You've got black at 1. Your shade at (at least) 3.0:1. And the next shade would be at (at least) 9.0:1. Because 9.0 has a contrast of 3.0:1 to 3.0. But, you can't triple 9.0 once again. Then you'd get 27. And 27 is more than 21. You can't create something brighter than white.

The same goes when you want a minimum of 4.5:1. You can do 1, 4.5 and 20.25 (4.5 times 4.5) but multiply it more and you go beyond 21. Not an option.

If you're going for a higher contrast like 7.0:1 (relevant for text when looking at WCAG AAA), you can't even fit 3 shades. You can do 1, 7 but 7 times 7 is way too high.

What's the practical impact on palettes?

Everybody seems to be working on dark mode these days. It's useful to know that if you want to pick one text color that works on both black and white, you don't have many options. Ideally you pick something with a ratio between 4.5:1 and 4.67:1. There's not a lot of space. It's good to be aware of how WCAG contrast influences your palette.

Conclusion

Math is hard. The best way to understand all written here is probably by trying some tools. One of my favorites is Contrast Grid by Eightshapes. You can insert an entire palette and see what color combinations offer acceptable contrasts. You can use this pretty usable palette by me as a starting point. It aims to offers many usable color combinations (but feel more than free to aim higher).

Another tool I enjoy is Leonardo. It's a tool to generate great palettes with lots of control over contrast and other options. Probably a good step before trying Contrast Grid.

And yes, WCAG 3 will quite likely provide a new way to calculate contrast. That's great news but we're all working with WCAG 2 for now.

Let me know if my ranting has helped you, and if you have favorite tools of your own!

Oh, and we sold the fabric store. I never ended up making a whole Design System for our little shop. Probably better that way.

Resources

A photographer’s view on alt text

Erik Kroes — Thu, 05 Aug 2021 07:51:18 +0000

Images are visual communication. Consider what you're trying to communicate before you do.

The "cover image" of this writing is from a project I did while studying photography. I wanted to discuss photography but not specific photos. I discovered it's almost impossible to talk about photos, without discussing what's in the photos. So I created images that "felt" like photos but didn't have a clear subject. I wrote a script that grabs random blobs of images from Flickr and turns them into a sort of subjectless collage.

Originally posted on erikKroes.nl. Questions are also welcome on Twitter

What is alt text?

When I say alt text I’m usually talking about the alt-attribute for the img-element in HTML. But most of what I say goes for other text alternatives as well. So maybe the question should be, what is a text alternative?

An image says more than a thousand words. But if you can't see an image, well, then it doesn't say much does it? A way to compensate for this is to add a text alternative; a bit of text that serves the same purpose as the image.

What's the purpose of the image?

This is the big question if you'd ask me. Wether you add an image to an article you're writing, or you're adding it as an icon to a button, you can't avoid this question. What is the purpose? Why are you adding this image? What are you trying to communicate?

In the end, an image is "just" a way of getting something across. When you write, you pick certain words. You write your sentences in a certain way. You can be aware of how you're communicating and what you're bringing across. An image isn't much different in my experience.

When you pick an image, ask yourself the same questions. What am I trying to communicate? (Notice this question is very much focussed on the person creating the content and not on what a user wants.)

What does that mean in practice?

Let's take this image as an example. What does it denote? And I'm picking this word because it is one I picked up during my study in photography. The literal meaning of something is its denotation. In this case it could be something like the pretty generic alt text I added in the code: "President Obama speaking from behind a pedestal". The denotation is also right up the alley of image recognition by artifical intelligence (AI). You literally describe what's in the image. Although you could easily go for an even more literal description here like: "A man in a suit behind a pedestal".

Stating it's President Obama is already more of a connotation. It's an interpretation of what we see. It's a cultural addition. Other connotations could include mentioning it's the first black president, that it's a former president or that he's talking about Donald Trump here.

And this is where the purpose of the image plays a role. If you're writing an article on the achievements of black people in the USA, you might add Obama as the first black president. If you're writing a course on public speaking, you might add Obama to illustratie that public speaking is very important for presidents. If the image is to supplement information about pedestals, then you might want to focus on highlighting details on the pedestal in the picture. It all about the purpose. Why are you adding the image?

The denotation has value but the connotation is often why we add an image. When somebody adds a description of an image into the file (like discussed in this Twitter thread), it might be enough to derive a connotation from it. But to really get the message across, write your own text alternative.

Some more tips

Don't include that it's an image. Or a picture, a graphic, a visual, etc. That only adds noise as it's already clear from the context.
Write out text.
Don't stylize text. Italic and bold text don't change the message (and might not even be communicated). The same goes for anything beyond basic punctuation.
"Null" the alt of a decorative image. In HTML, if an image is decorative, add an empty alt like <img alt> or <img alt="">. And I do mean empty. No spaces or other text like "image" (I'm looking at you Twitter 👀).

Why I care

For the past few years, I've been working as a specialist in digital accessibility and inclusive design. In this role I work with WCAG, and the addition of text alternatives is pretty much the first thing I check in an audit. Through this role, I've formed an opinion on text alternatives.

Before this job, I was a photographer. I had 5 years of formal education in this direction. Visual communication is awesome and I wish the theory had stuck with me even more.

Concluding

Studying photography has taught me that it's all "just" visual communication. Wether it's text or imagery. Think about the message you're trying to communicate, and shape your communication accordingly.

Resources

Semantics, what does it mean?

Erik Kroes — Tue, 19 Jan 2021 08:10:10 +0000

When people talk about the quality of HTML code, it is often about semantics. But what are semantics? What is semantic HTML, and why should you care about it?

What is Semantic HTML?
Wat do semantics do?
How should I do it?
1. What do I want to communicate?
2. Is my page structure clear?
Is that it?

What is Semantic HTML?

Semantics is communicating your intention through your chosen HTML. This does not guarantee the correct outcome, but if you communicate a different intention than the outcome, then it is not correct anyway.
A well-known HTML tag is, for example, the <h1>. This tag is often used for the most important heading (heading 1) on a page.
<h1> Semantics, what does it mean? </h1>

The tag or element communicates the intention: this is the main heading, this is what the page is about. If (for example due to an error in the CMS) there is an entire article in a <h1> then the result does not match the intention.
In the same way, you can create a link (<a>) that goes nowhere, or a button (<button>) that does nothing. With semantic HTML you indicate your intention. That is the first step. The next step is to match the result.
You can compare it with TypeScript or other languages that contain typing. These can not only contain data, but also say something about the data they contain.

What do semantics do?

As indicated, semantics express the intention of an element. If tools can rely on this intention (the semantics indeed say something about the data in the elements) then they can use the content of the elements for all kinds of purposes.
Some examples:

Readability tools - There are now many ways to read texts in a more readable format. Sometimes they are stand alone like Pocket and Instapaper. In Firefox and Safari there are tools built in. You can present an existing web page in a different (more readable) way.
Translation tools - Tools like Google Translate can make use of the context that you communicate as a developer.
Assistive technology - Software such as screen readers inform their users of the semantic value of the HTML they are reading. This way a user can understand whether something is important or only secondary, and whether something is a paragraph or a list.
People Reading Your Code - It may sound obvious, but readable code is nice code to work with. You often write HTML code not only for yourself but for others, or even for yourself at a different time. Clearly written HTML is more readable and more future-proof.
Custom CSS, adblocking, etc - Basically anything that "hooks" into your code benefits from readable, resilient and robust code. If a visitor has Custom CSS for readable headings, then there need to be headings first!
SEO - Search engines are like actual people sometimes. They also want to know what information you provide and what the context of that information is. By creating structure in your code you do not end up with something disjointed. It provides guidance for everyone who has to work with it: developers, visitors and automated tools.

How should I do it?

Does this mean you need to memorize all HTML elements? No, thankfully. Even though there aren’t really that many.
It is nice to find out which elements you know though! Have you tried the HTML Tags Memory Test yet?

What do I want to communicate?

This question is very valuable in many situations. If you are writing HTML and you add an element, ask yourself if the element represents your intention correctly. Are you writing a paragraph? Then it makes sense to use a <p>. Are you doing something for purely visual reasons, without wanting to communicate a specific intention? Then you might be fine with a <div> or a <span> (these elements don't communicate any intention).
On the other hand, do you use a <div> or a <span> while you want to convey a specific intention? Maybe you want to check the list of all HTML elements whether there is a suitable alternative.

Is my page structure clear?

Every page benefits from a good structure. A newspaper relies on sections, columns and clear headlines. A page on the web (and the underlying HTML) aren’t very different from that.
See if you can organize your page with clear HTML landmarks such as <header>, <main>, <aside> and <footer>. A landmark works just like a landmark in real life. If a village has five church towers it becomes difficult to say "go left at the church tower".
You can also use headings (just like with a newspaper). The <h1> is the main page header; this indicates what the whole page is about. Technically, all content is covered. If you want to use a heading under the <h1>, use the <h2>. Everything that falls under the <h2> in the code should logically also fall under this in the content. You create a hierarchy with your headings. Do not skip headings (don't go from <h2> to <h4>) and only place something under a heading if it logically falls under it.

Is that it?

Yes, kind of actually. Communicate as clearly as possible what the intention of your code is (meta data) and do not let your intention be an empty promise.

Extending a component library and it’s documentation for speedy design system

Erik Kroes — Wed, 02 Dec 2020 10:00:31 +0000

Lion is a set of white label cross-platform Web Components with accessibility and performance built-in. You can extend them with your own styling to create a complete Design System with little effort.

Styling is extremely flexible

This blog will demonstrate that extending Lion is not limited to components. Documentation and demos can be reused as well. This removes duplicate work such as writing and maintaining documentation.

A naming convention that is similar to Lion for class names and lion- for tag names is required for this to work. For this demo, we use the the names ExampleButton and example-button.

Setting up, and Extending Lion
Select documentation to re-use
Change input paths
Remove, add and replace sections
Conclusion

Setting up, and extending Lion

This article assumes some basic terminal knowledge, and a working installation of npm. Yarn can work as well.

Create a new folder for our components using the terminal. ExampleButton and example-button.

mkdir example-components

Enter the folder example-components and run the following command to scaffold a new project using open-wc.

npm init @open-wc

When presented with a menu, pick (at least) the following options.

What would you like to do today? › Scaffold a new project
✔ What would you like to scaffold? › Web Component
✔ What would you like to add? › Demoing (storybook)
✔ Would you like to use typescript? › No
✔ Would you like to scaffold examples files for? › Demoing (storybook)
✔ What is the tag name of your application/web component? example-button

Enter the folder example-compponents and run the following command to make lion-button a dependency. It is the component we will be extending.

npm i @lion/button --save

Within the folder src, open the following file:

example-button/src/ExampleButton.js

Replace the content with the following:

import { css } from 'lit-element';
import { LionButton } from '@lion/button';

export class ExampleButton extends LionButton {
  static get styles() {
    return [
      super.styles,
      css`
        /* our styles can go here */
      `
    ];
  }

  connectedCallback() {
    super.connectedCallback();
    this._setupFeature();
  }

  _setupFeature() {
    // our code can go here
  }
}

You have now extended <lion-button> and created <example-button> from it. The component can be experienced in the browser by running npm run storyboook inside the example-button-folder.
Feel free to add styles and make it your own. This can be the start of a whole set of Web Components for your Design System.

For this article we assume you set up the project like mentioned before, using Prebuilt Storybook with MDJS. If you already have a repository, you can also add Storybook using open-wc. Enter the following:

npm init @open-wc

And pick ‘upgrade an existing project’. Or install it manually by entering the following:

npm i @open-wc/demoing-storybook --save-dev

Select documentation to re-use

We need to specify which stories to load in .storybook/main.js.

Change the following line:

stories: ['../stories/**/*.stories.{js,md,mdx}'],

to add the Lion readme

stories: ['../stories/**/*.stories.{js,md,mdx}', '../node_modules/@lion/button/README.md'],

This is where we extend the documentation of LionButton, for our own ExampleButton. This step, by itself, gives us the LionButton docs inside our own Storybook.

Change input paths

We can change the import paths from LionButton to the new paths of ExampleButton. We use Providence for this. This tool has a command that creates a full map of all the import paths of a reference project (Lion) and can replace them with the correct paths of a target project (Example).

Navigate the terminal to example-button and install this tool by adding it to our package.json:

npm i providence-analytics --save-dev

We can use it by adding a script to our package.json:

"scripts": {
  "providence:extend": "providence extend-docs -r 'node_modules/@lion/*' --prefix-from lion --prefix-to example"
}

The --prefix-from is the prefix of the project you extend from (in this case lion). --prefix-to is the prefix of our own project (in this case example).
It will look for the classnames Lion and Example, and for the tagnames lion- and example-.

As we only use a single component from Lion, we can reduce the time the tool needs for analysis. Specify the single package by replacing -r 'node_modules/@lion/* with -r 'node_modules/@lion/button'.

We can review all from/to information in providence-extend-docs-data.json. Providence creates this critical file.

Replacing paths and names

With the information in the JSON-file, we can start transforming the LionButton documentation to ExampleButton documentation. We created a babel-plugin called babel-plugin-extend-docs for this.

This plugin will analyse the content of the markdown files, and transform it on the fly in es-dev-server and when building with Rollup for production.

To install this plugin, we navigate the terminal back to example-button and install this plugin by adding it to our package.json:

npm i babel-plugin-extend-docs --save-dev

A babel.config.js in the root of our project is also needed. It should contain:

const path = require('path');
const providenceExtendConfig = require('./providence-extend-docs-data.json');

const extendDocsConfig = {
  rootPath: path.resolve('.'),
  changes: providenceExtendConfig,
};

module.exports = {
  overrides: [
    {
      test: ['./node_modules/@lion/*/README.md', './node_modules/@lion/*/docs/*.md'],
      plugins: [['babel-plugin-extend-docs', extendDocsConfig]],
    },
  ],
};

We import the providence output file (providence-extend-docs-data.json) and pass it to the plugin options as the changes property.

The babel plugin runs for the files that we specify in the testproperty, replaces the imports, and replaces the tag names inside JavaScript code snippets!

It will only transform JavaScript snippets that use MDJS syntax such as js script, js story and js preview-story

We also have to add Babel to our es-dev-server configuration to make it work with Storybook.

Create a .storybook/main.js with the following content:

module.exports = {
  stories: ['../node_modules/@lion/button/README.md', '../packages/**/!(*.override)*.md'],
  esDevServer: {
    nodeResolve: true,
    watch: true,
    open: true,
    babel: true,
  },
};

We should now see the LionButton instances transformed into our own ExampleButton!

Remove, add and replace sections

We might not want to show all examples of how to use a component. Sometimes information is Lion specific, or perhaps in your Design System people are not allowed to use a certain feature that we documented in Lion.

In our example, we will remove the Rationale section that we would normally inherit from the Lion documentation.

We assume a folder structure here /packages/<package>/... here. When updating an existing repository, it might be different.

For this step we make use of a remark plugin for the MD content, similar to how we use a babel plugin for JS content. It is called Remark extend. It lets us add, remove or replace sections or specific words.

Remark extend needs the following content added to .storybook/main.js:

const fs = require('fs');
const { remarkExtend } = require('remark-extend');

function isLion(filePath) {
  return filePath.indexOf('@lion/') !== -1;
}

function getLocalOverridePath(filePath, root = process.cwd()) {
  const rel = filePath.substring(filePath.indexOf('/@lion/') + 7, filePath.length - 3);
  return `${root}/packages/${rel}.override.md`;
}

module.exports = {
  [...],
  setupMdjsPlugins: (plugins, filePath) => {
    if (!isLion(filePath)) {
      return plugins;
    }
    const newPlugins = [...plugins];
    const markdownIndex = newPlugins.findIndex(plugin => plugin.name === 'markdown');
    const overridePaths = [`${process.cwd()}/.storybook/all.override.md`];
    overridePaths.push(getLocalOverridePath(filePath));

    let i = 0;
    for (const overridePath of overridePaths.reverse()) {
      if (fs.existsSync(overridePath)) {
        const extendMd = fs.readFileSync(overridePath, 'utf8');
        newPlugins.splice(markdownIndex, 0, {
          name: `remarkExtend${i}`,
          plugin: remarkExtend.bind({}),
          options: { extendMd, filePath, overrideFilePath: overridePath },
        });
      }
      i += 1;
    }
    return newPlugins;
  },
  [...],
};

In the code example mentioned, we have two places in where we can do overrides: ./.storybook/all.override.md for generic overrides and via getLocalOverridePath for each component. When needed, the rel needs to be the same in lion and our own project to be able to override the right file.

In each file we need to specify which section we want to override. We want to load example-button in the project:

```
::addMdAfter(':root')
```

```js script
import '../example-button.js';
```

And then replace each button with it.

```js ::replaceFrom(':root')
module.exports.replaceSection = node => {
  if (node.type === 'code' && node.value) {
    let newCode = node.value;
    newCode = newCode.replace(/<lion-button/g, '<example-button');
    node.value = newCode;
  }
  return node;
};
```

We can remove content by targeting a specific heading:

```
::removeFrom('heading:has([value=Usage with native form])')
```

Or we can add an extra paragraph below the content:

```
::addMdAfter(':scope:last-child')
```

The documentation of Remark extend has many more options and insights

Conclusion

Writing good extensive documentation can be hard and time consuming. Being able to extend both code (components) and documentation will increase your work speed.

We set up and adjusted the documentation to fit our extended component. please contact us if this article doesn’t answer your questions.

Solid Start

Erik Kroes — Tue, 04 Aug 2020 10:18:44 +0000

Are you a person that makes digital things for other people? Awesome—because this page is all about making things for people. There are four ways you can improve your creation for everybody. All four are testable, fixable and they improve usability for everybody.

This is a copy of solidStart.info and might be less up-to-date. It's meant as a resource to be shared with others. Thanks for taking it to heart!

Four things to get started
1. Keyboard
2. Contrast
3. Alternatives
4. Sizing
Inclusive Design
Contributions
Resources

Four things to get started

There is one big assumption in this guide. It assumes you know the basics of your tools. Validate your code.

1. Keyboard

You are not building for you.

Not everybody uses a mouse, so you shouldn’t test with just a mouse. The most universal device to test with is a keyboard. A lot of people either use a keyboard, or use something that interacts with your creation like a keyboard.

Pressing the Tab key should take you to every interactive element in an intuitive order. Pressing Shift+Tab should take you the opposite way. If you can reach and use every bit of functionality, you’re off to a good start.

People might feel lost when they don’t know where they are. Make sure it is clear which element is focused.

2. Contrast

It can be hard to communicate if your content isn’t visible to people. Contrast can help with this.

There are many tools to measure contrast by providing a ratio. The Color Contrast Analyser is used by a lot of people. You can also pick a tool from the resources, or one that might already be inside your favorite environment. Each tool will give you a contrast ratio between two colors, like a foreground and background color. The visibility of a higher contrast ratio is better. Pure black and white can be too harsh for people.

User interface components and states should have a contrast ratio of at least 3.0:1. Measure this ratio against their surrounding colors. The contrast ratio of large text (at least 24px, or at least 19px and bold) should be 3.0:1 or more. All other text should be at least 4.5:1. These are minimum requirements, not goals.

3. Alternatives

Ever tried to watch a movie in a busy place, or listen to a podcast without headphones? When you can’t see or hear, a text is a nice alternative to have!

Offer captions for video. Offer a transcript for podcasts. For images, offer text alternatives. Text alternatives should convey the purpose of the image or the content of the image. A decorative image needs no alternative.

4. Sizing

Compare a mobile phone to a tablet, a laptop or a PC. No screen size is the same. Make sure that what you make offers the same content and functionality to all sizes. Let people experience it at whatever size they want or need.

Inclusive Design

Congratulations! Follow these steps and you're helping a lot of people.

This is also just a first step, and there’s more you can do. Want to know more about Inclusive Design and WCAG (Web Content Accessibility Guidelines)? Check the resources!

Contributions

This page is not a collaboration without contributions. It has been created by Erik Kroes with the help of Eric Bailey, Ashley Bischoff, Eric Eggert, Pascal Schilp and others. Your help can make it even better. Create inclusively.

Contribute on GitHub
Join a weekly accessibility stream on Twitch
Follow on Twitter

Resources

WCAG Quick Reference
Color Contrast Analyser
Contrast Grid - A great tool for color palettes
An alt Decision Tree - A W3C tool to determine the type of text alternative for images.
The WebAIM Million - An annual accessibility analysis of the top 1,000,000 home pages
Axe - An open source automated tool for testing partial web accessibility. Great for learning and awareness.
Screen Reader Reference

Courses

Accessible HTML Toggle Button (Switch)

Erik Kroes — Mon, 29 Jun 2020 10:34:40 +0000

Everybody loves toggle switch on mobile, or so I've heard. But if you're building a website, how do you reproduce this without excluding people.

Originally posted on erikKroes.nl. Questions are also welcome on Twitter or Twitch (I stream about accessibility weekly).

The result

Let's start with the most important part. This is the end result as featured on Codepen:

What is this?

When I use my phone, I expect a Switch (that's how android calls them) to instantly change a setting. It won't just be selecting an option (like with a checkbox) but the selection will also be submitted instantly.
The web is full of examples on how to style checkboxes to look like a switch, but that doesn't help me much further when I want something more like mobile.

Bit by bit

HTML

Looking at the HTML code, you might first notice the label. By default, a button will take its contents to create an accessible name. Using a <label> and referencing it by using for= and the id of the <button>, overrides this default behaviour. The content of the <label> becomes the accessible name of the <button>.
It also makes sure that people can click, press, touch or lick the <label> to activate the resulting Switch, just like on Android.

Then the radical part of this creation, I'm using a <button>. Why? Because I want something to change instantly which a checkbox (<input type=checkbox>) really should not be doing. In my experience, checkboxes that change things often clash with WCAG Criterion 3.2.1: On Focus. A <button> aligns better with the goal of instant change.

The first attribute is type=button. This should not matter, because we override the semantics later with a role, but we sure don't want this to be a submit button.

The id is needed to create a programmatic relationship between the <label> and the <button>. Not doing so would clash with WCAG Criterion 1.3.1: Info and Relationships, would pretty much defeat the purpose of the <label> in the first place, and should properly annoy people that use assistive technology (voice commands, screen readers, and more).

The role="switch" is where much of the magic happens. It is a WAI-ARIA Attribute. It can communicate semantics that might not be natively present within HTML, and should be used as little as possible. A Switch like this is a perfect example for such a use case.

Whenever you use the role="switch", there is another required WAI-ARIA Attribute. You have to add aria-checked which takes either a true or false value. This makes sure that you're not just communicating the name and role in code, but also the value of the Switch (on or off). This helps you pass WCAG Criterion 4.1.2: Name, Role, Value.

Then within the <button> we have 2 <span>s. They toggle visibly between on and off. If there's one thing that really annoys me with switches; it's how confusing they can be. They're like the USB-plug of HTML. I often have to turn them on and off a few times before I understand which settings is which. That's why we communicate the state in the code (with aria-checked), by changing colour between grey and green, and by switching between the 'on' and 'off' visual label.

CSS

The CSS is about as minimal as I thought would be possible. It makes everything nice and rounded. It does not make it animated, or possible to slide between 'on' and 'off'. But feel free to add that yourself. The colours should meet the WCAG contrast requirements though.

The CSS does make sure that in 1 state, the first <span> in the <button> has the same color for text and background. And in the other state, the second <span> has those colours. This way it looks like the text disappears, but that's only visual.

JavaScript

The JavaScript finds the button in the code, adds an eventListener to it and makes aria-checked toggle between 'true' and 'false'. It could also remove the aria-checked instead of toggle to 'false'. I chose not to, to make the code slightly more readable and less bloated.

The Guide to Accessible Web Components

Erik Kroes — Wed, 24 Jun 2020 07:31:33 +0000

Web Components are a newly supported standard. They're a great match for Design Systems because they're futureproof and work with any framework. Building proper UI Web Components can be quite a task though, especially if you want them to be accessible. Here are some pointers on what to look out for.

Originally posted on erikKroes.nl. Questions are also welcome on Twitter or Twitch (I stream about accessibility weekly).

Throughout this article I'll use Lion a few times as an example. Lion is a collection of white label UI Web Components. There's more information about Lion in the conclusion.

What are Web Components?
What is shadow DOM, and light DOM?
Extending elements
Accessible UI Components
- Focusable
- Keyboard interaction
- Visible states
- Functional states and properties
- Semantics
- Accessible name
- Relationships
- Global standards and conventions
- Browser bugs and variations
The Accessibility Object Model
Conclusion
Further reading

What are Web Components?

Web Components are a set of standards:

Custom Elements: A way to create your own HTML elements
ES Modules: Self-contained modules of JavaScript code that can be reused and extended
HTML Templates: Reusable fragments of DOM
Shadow DOM: Encapsulation of DOM

Together these standards enable "Reusable extendable encapsulated self-contained components for the web". That's quite a mouthful, but not very clear.

In practice, this means you can create your own HTML elements. These elements have their own bit of encapsulated DOM. In this, and many web-related cases, DOM stands for Document Object Model. The DOM is how we see an HTML or XML document. MDN states "The DOM represents the document as nodes and objects." MDN has a rather good explanation.
It means the HTML element you make can't be touched or influenced by whatever is outside of the element. They can't be accidentally styled, and they won't mess with your global styles either. And because it's an ES Module, the whole element can be distributed and extended. All these aspects together make up a Web Component.
ES Module stands for EcmaScript Module. It's how JavaScript works with modules and a standard that's supported by all modern browsers. 🎉

A practical example would be a Google Maps Web Component. This Web Component shows a full interactive map on your page with only a few lines of code. You would have to import some JavaScript on your page that defines the component:

<script src="good-map.js" async defer></script>

After that, you can use your custom element anywhere on the page.

<good-map api-key="AIzaSyAQuo91bcoB-KwWXaANroTrzpNZRFcNJ1k"
    latitude="52.1664"
    longitude="5.9075" zoom="3"></good-map>

Notice how the element name has a dash? That's part of the Custom Elements specification and makes it easier for the browser to recognize them.

A not so practical example would be a spacer-gif Web Component. (A spacer-gif is an old an redundant technique that does not need a remake.)

<spacer-gif height="1" width="1"></spacer-gif>

A Lion example could be lion-switch.

<lion-switch label="Label Text" help-text="Help text"></lion-switch>

And all that goodness is based on widely supported web standards.

What is shadow DOM, and light DOM?

"Indeed, that sounds pretty good so far, but what's the catch?"

As the British will soon discover, there are some downsides to isolating yourself. Let's say you make a card component. The interface for using it (what you see in your editor or browser) could look like this:

  <my-card>This is the card content</my-card>

The component, when inspected in the browser, could look like this:

  <my-card>
    #shadow-root (open)
      <div class="card-wrapper">
        <div class="card-header">
          Presenting the card content:
        </div>
        <div class="card-content">
          <slot>
            <#text>↴
          </slot>
        </div>
      </div>

    This is the card content
  </my-card>

A whole chunk of DOM ("The DOM represents the document as nodes and objects." Remember from before?) is rendered by the component and put into the shadow-root section. Inside the <slot> it refers to the content we put into the element in the first place. All the DOM that is added, is shadow DOM. All the other "normal" DOM, is what we call light DOM. It's the part that's always visible.
As the shadow DOM is completely encapsulated and isolated, it is also completely disconnected. It's almost like it's a completely different document like an iframe. Thankfully, keyboard navigation does work through Shadow DOM boundaries. Which means you can <TAB> in and out of Shadow DOM.

This becomes a challenge when you want to point a label to an input to create an explicit relationship. In plain HTML, this would be:

  <label for="example-input">Label text</label>
  <input id="example-input" type="text">

When one of both (the label or the input) is in the shadow DOM, they're in a completely different context. This makes it impossible to refer to eachother.
This same dillema also goes for WAI-ARIA attributes like aria-labelledby, aria-describedby and other that reference an ID. You need either both elements in the shadow DOM, or both of them in the light DOM. Light DOM does not mean that they both have to be in the same slot though. Light DOM is basically all the DOM that isn't shadow DOM.

In the lion-input we let the developer declare a label in the label slot. This label ends up in the light DOM.

<lion-input>
  <label slot="label">Label text</label>
</lion-input>

The component places an input in a slot="input", help text in slot="help-text" and feedback in slot="feedback". This means the input can be connected to the label, but also that we can use aria-describedby to connect the input to help text like instructions and feedback like error messages.

Extending elements

As it stands right now, it is only possible to create a Web Component by extending a generic HTML element (HTMLElement) or another Web Component (which should be somewhere deep down, also an extension of HTMLElement).

For accessibility, it could have been a big win if we could extend any element. Imagine you could, for example, extend a native button (HTMLButtonElement). You would inherit all its behaviour and it's semantics, and you would only add on to that. You'd have a solid fundament upon which you could build.

The specification exists but Safari has stated to not support this feature. Part of the beauty of Web Components is that it's a supported standard. So even though there is a Polyfill for Safari, it creates a path with future uncertainty.

Accessible UI Components

The most popular usecase for Web Components is probably that of creating custom user interface controls. As we can't extend any native elements, we often end up with either wrapping a native element, or recreating its behaviour by ourselves. Wrapping is often the easiest and most solid solution. Recreating is basically the same as taking a <div> as a starting point.
There are so many aspects that come together in a single components, that it is really easy to overlook a feature or behaviour. And when you forget or fail to implement something, you end up creating something that's lacking compared to a native element. That's probably the exact opposite of what you're trying to achieve.

Here is an overview of aspects that need special attention when creating an accessible user interface control. These points are not specific to Web Components. They are just as relevent for React, Vue, Svelte or any other framework.

Focusable

If your custom control is interactive, make sure it is keyboard focusable. For simple controls with a single interactive element, this means adding tabindex='0' to your control. For more complex controls you might need to implement a roving tabindex or use aria-activedescendant.

Keyboard interaction

Users should be able to use your interactive control with a keyboard. For many design patterns, suggested keyboard interactions can be found in the WAI ARIA Authoring Practices.

Visible states

Interactive controls have several states like focus, hover and active. These should all be clearly visible, and, preferably, each have their own distinctive styling.

Functional states and properties

An interactive control can have functional states as well. For example, a disclosure widget (or expandable, accordion, expando, ...) can be open or closed. This state needs to be not just visual, but communicated in code as well. This can be done by toggling aria-expanded on your control.
The same goes for properties like aria-multiline. They communicate properties that might be implicit in native elements, that have to be added manually for assistive technology when you're building custom controls. WAI-ARIA has many states and properties to aid in this.

Semantics

Native HTML elements have a semantic meaning and are mapped to WAI-ARIA roles. Their semantics are implicit and always there.
A custom element starts out with no role at all, but you can assign one explicitly. WAI-ARIA offers a wide range of roles that should cover all use cases. WAI ARIA is more explicit than native semantics though. It's more bolt-on than built-in.
You might notice when using Windows High Contrast Mode, a special tool for Windows. It does not care for your ARIA attributes.

Accessible name

Interactive controls must have a name for them to be identified by. For example, a <button> with the text "Save" can be presented by assistive technology as "Save, button". In this case "Save" is the accessible name of the element. The name is determined by the Accessible Name and Description Calculation and there are multiple ways of adding an accessible name.

Relationships

Visually, it might be clear that certain elements have a relationship. For example, a short text next to an input will likely be the label of that input. Not clarifying those relationships in code can make it impossible for assistive technology to recognize them though. WCAG Success Criterion 1.3.1 mentions quite some sufficient techniques to cover this issue.

Global standards and conventions

Creating custom elements requires awareness of global standards and conventions. Users expect components to work in a certain way. Reinventing the wheel often leads to a confusing user experience. Following standards and conventions will prevent confusion and create a consistent experience for users.

Browser bugs and variations

To create an element that works the same way on each browser and platform is a big challenge. Some native elements even fail to do so. For example, when I use a <select> in Firefox on Mac OS, it will behave differently from when I open it in Chrome. There will even be a difference between Chrome on Mac OS and Chrome on Windows. The nuances and details of making elements work consistently across platforms is a really big challenge.
Bugs can be even harder to find or circumvent. For example, the WAI ARIA Authoring Practices 1.1 recommends using aria-activedescendant to control focus when using a role="combobox". That sounds great, untill you discover that this combination doesn't actually work in all browsers.

The Accessibility Object Model

The Accessibility Object Model (AOM) is a proposed addition to the web platform to make the accessibility API of browsers more transparant and usable for developers. Support for the AOM in browsers would be of great value for Web Components. But as it is still under development and largely unsupported, I'll leave further explanation to others like Hidde de Vries.

Conclusion

It is very much possible to create accessible Web Components. They are ideal for large organizations where a specialized team can make the best building blocks, and give both their developers and users a great consistent experience. It takes a lot of time, knowledge and effort to build these components though. If you'd ask me...

Everybody should use Web Components
Few people should build them

To ease some of that pain, the Web Components I work on professionaly have an open source base layer called Lion. This is a collection of white-label Web Components that you can easily extend, style and customize. They have been built with all the considerations mentioned above. You can view a live demo of all the components, or check them out on GitHub. If you find anything that could be improved, please create an issue and maybe even fix it yourself. All accessibility issues are my responsibility.

Forem: Erik Kroes

Accessibility is not binary

Is it accessible?

Is it valuable?

Concluding

Color and contrast, what does it mean?

How it used to be

The fabric store

Color, it's pretty complicated

Color models

Red, Green and Blue

Hue, Saturation and Lightness

Is that all?

WCAG?

We have Luma!

What does that mean for color palettes?

What's the practical impact on palettes?

Conclusion

Resources

A photographer’s view on alt text

What is alt text?

What's the purpose of the image?

What does that mean in practice?

Some more tips

Why I care

Concluding

Resources

Semantics, what does it mean?

Table of Contents

What is Semantic HTML?

What do semantics do?

How should I do it?

What do I want to communicate?

Is my page structure clear?

Is that it?

Extending a component library and it’s documentation for speedy design system

Table of Contents

Setting up, and extending Lion

Select documentation to re-use

Change input paths

Replacing paths and names

Remove, add and replace sections

Conclusion

Solid Start

Table of Contents

Four things to get started

1. Keyboard

2. Contrast

3. Alternatives

4. Sizing

Inclusive Design

Contributions

Resources

Courses

Accessible HTML Toggle Button (Switch)

The result

What is this?

Bit by bit

HTML

CSS

JavaScript

Further reading

The Guide to Accessible Web Components

Contents

What are Web Components?

What is shadow DOM, and light DOM?

Extending elements

Accessible UI Components

Focusable

Keyboard interaction

Visible states

Functional states and properties

Semantics

Accessible name

Relationships

Global standards and conventions

Browser bugs and variations

The Accessibility Object Model

Conclusion

Further reading