DEV Community: Suzanne Aitchison

What Cypress E2E testing has taught us about our code

Suzanne Aitchison — Wed, 18 May 2022 16:24:40 +0000

A little over a year ago Forem introduced End to End testing to the app using Cypress. Since that time we've definitely evolved our understanding of Cypress, but we've also learned a lot about our app too. So much so, that I wanted to share some of the things Cypress testing has taught us 😄

Some background

We use Cypress alongside cypress-rails and Cypress Testing Library.

Testing Library gives us a range of enhanced queries that help us focus on testing in a way that closely mirrors how users interact with the app. Instead of targeting page elements with e.g. CSS selectors or IDs, we lean towards finding elements by their role and accessible name.

When I talk about testing with Cypress at Forem, I mean specifically testing with Cypress and Cypress Testing Library 😄

A greater awareness of accessibility

I've made no secret of personally being a huge fan of Testing Library for the impact it can have on accessibility testing and awareness. It therefore isn't a surprise to me that we have learned a lot about the accessibility of our app since introducing E2E tests with Cypress.

Uniqueness of elements

One of the challenges we've had with testing some older views in Cypress is discovering that the same element/name combination is present multiple times.

A great example of this is the "Follow" buttons throughout the app. We tried to target a Follow button in test with cy.findByRole('button', { name: 'Follow' } and found it incredibly difficult to target the one we wanted.

This immediately flagged itself up as an accessibility issue - users of screen readers would hear every follow button announced as "Follow"... but, follow who? 😅 Just as we were struggling to target the right button in test, a screen reader user would struggle to target the button of the user they wanted to follow.

Big shout out to community member @keshavbiswa for making improvements to the follow buttons accessible names after we discovered this!

The power of landmarks

We take advantage of Cypress' scoping abilities by writing code like:

cy.findByRole("main").within(() => {
  // Everything in here is scoped to the "main" element only
  cy.findByRole('heading', { name: "Dashboard" });
});

In the example above, the within helper allows us to scope the test to all the HTML inside the main landmark. This can be really handy and powerful! For example, when we wanted to test the main feed navigation, we could do:

cy.findByRole('navigation', { name: 'View posts by' }).within(() => {
  cy.findByRole('link', { name: 'Relevant' }).as('relevant');
  cy.get('@relevant').should('have.attr', 'aria-current', 'page');
});

We were able to go directly to the feed navigation landmark with ease. This is cool for testing, but it's also been great for building awareness and understanding of how important landmarks and their labels can be for screen reader users. Just like we could skip directly to the "View posts by" navigation in Cypress, screen reader users can skip directly there with their screen reader too! Great news for anyone that wants to get straight to the latest posts 😄

Headings, headings, headings

Headings play an important role in accessibility (I have an older post that digs into this a bit), and they've become really important to our tests too.

One struggle we had with Cypress was that sometimes when we followed a link to a new page, the new page wouldn't have loaded yet before Cypress tried to click some button/check for some behaviour.

For example, we had some test code:

cy.findByRole("main").findByRole("link", { name: "Test article" }).click();
// After clicking the link we can _sometimes_ accidentally get a reference to the 'main' element on the page we just left
cy.findByRole("main").findByRole("button", { name: "Share post" });
// Cypress fails to find the 'Share post' button inside the previous page's `main` element, and the test fails

Since a main existed on both the first and the second page, Cypress would occasionally get a reference to the wrong one 🙈

One way that we prevent this type of flake now is to make sure we look for an element that is unique to the new page, before continuing our test steps. The example above would become:

cy.findByRole("main").findByRole("link", { name: "Test article" }).click();
// Wait for the correct h1 element
cy.findByRole("heading", { name: "Test article", level: 1 });
// Now we can be sure the main below is the right one!
cy.findByRole("main").findByRole("button", { name: "Share post" });

Needless to say, this in turn has made us more aware of pages missing headings, or headings with the wrong level, duplicated, etc. All of which is helping us tighten up our accessibility.

Javascript races 🏁

Aside from these accessibility concerns, we've also become very aware of some side effects of how we handle our Javascript.

We try our best to make sure our pages load quickly, with Javascript asynchronously layered on after the first page load to enhance functionality. In reality, this means it takes some amount of time before some elements on the page are fully initialized and clickable.

For example, when the logged out version of the home feed first becomes visible, the author names don't yet have a click handler to trigger the appearance of the profile preview card - we initialize this functionality after the page first loads.

As a human, it's pretty hard to click the button before it's initialized (largely because the page load is pretty fast 😄), but it's technically possible. Certainly Cypress is speedy enough to do this sometimes!

We've been working around this with a variety of solutions, including using cypress-pipe which lets us retry a click until a certain condition is met. For example, in the case of the feed preview cards we can do:

cy.findByRole('button', { name: 'Admin McAdmin profile details' })
  .pipe(click)
  .should('have.attr', 'aria-expanded', 'true')

This tells Cypress - click this button until aria-expanded is equal to 'true' (meaning the preview card has opened). Don't worry - it won't retry forever - Cypress has a default waiting period for a condition to become true, and pipe will only retry for that long.

It's definitely made us think a lot more about progressive enhancement, and what is and isn't usable from the very first moment of page load.

Want to know more about E2E testing at Forem?

We've been adding to our E2E testing docs as we learn and evolve our approach, including the "gotchas" we've found along the way - feel free to check it out!

I'd love to hear about your experiences with Cypress and Testing Library too!

Assistive technologies your users might be using

Suzanne Aitchison — Fri, 25 Mar 2022 08:12:56 +0000

I've found that when developers talk about accessibility, we often make the assumption that accessibility === screen readers. In reality, not all users with disabilities use assistive technologies, and not all assistive technologies are screen readers!

This post collects some demo videos I've found helpful in learning how some of the most popular assistive technologies help users access our apps and engage with our code.

If you know any other good demos, please do link them in the comments!

Screen reader

Reads the content of the screen aloud
Provides shortcuts to skip to certain parts of the page or perform certain actions
Provides contextual information about control types and state
Popular screen readers include JAWS (Windows), NVDA (Windows), VoiceOver (macOS and iOS) and Talkback (android mobile).

In this video, Léonie Watson discusses and demonstrates how she uses a screen reader:

Refreshable braille display

Can be used in conjunction with a screen reader, with screen reader output translated into braille
May also support typing in braille
Some devices have their own integrated apps for e.g. note-taking, calculations

Check out this demonstration and Q & A with a braille display user:

Screen magnification software

Allows users to control the size of text and graphics on the screen
Allows users to change cursor size, focus styles, and the colors used on the screen
Some magnification software has basic screen reading capabilities built-in too

This video demonstrates (an old version of) ZoomText, a popular screen magnification tool:

Switch controls

Primarily used by users with motor disabilities
Multiple formats, but commonly a large button
"Sip and puff" and movement sensors are also common formats of switch controls
A focus indicator moves through items on the screen, pressing the switch activates the control
Multiple switches can be used in combination
Some mobile devices now have gesture-based switches using the camera

Check out Christopher Hills using a two switch set up with an iPhone:

Speech input software

Provides a speech-operated method for typing and controlling the computer
Allows users to execute actions using voice commands

See a demo of the popular Dragon NaturallySpeaking:

You can also check out Josh W Comeau's write up on their experience using speech input for software development: "Hands-Free Coding".

Do you have any others to share?

If you've seen any other great demos of assistive tech, please do drop them in the comments!

5 years in tech, and she's still coding

Suzanne Aitchison — Tue, 08 Mar 2022 13:29:07 +0000

The #shecoded prompt this year made me realise that 2022 officially marks 5 years in tech for me! What better time to reflect on my experience so far 😄

The career switch

Back in 2016 I was doing well for myself career-wise. I'd pretty successfully turned a wandering few years as an English as a Foreign Language (EFL) teacher into a career in supporting overseas students to study in the UK. I'd been promoted regularly, managed a great team, and felt like I was genuinely helping some people. But I just felt so "meh" about my work, and had done for such a long time. I didn't want to feel that way about something I did for 40 hours a week.

I spent such a long time analysing what I enjoyed, what I was good at, and where the intersection of those two things lay (spoiler: I am not great at many things I enjoy 😄). I knew I wanted to make things, but I knew that my talents weren't really artistic, more logical/analytical (I'd previously pivoted away from a career in puzzle editing!).

I had a little lightbulb moment remembering how I used to love creating geocities websites (I think the first one was a Will Smith fan site 😆). A few months of ploughing through Codecademy tutorials and I was convinced - I was going to be a Software Developer.

Better late than never

My high school ran Computer Science classes that I never enrolled in. Instead I was pushed toward "Office and Information Skills" (i.e. making spreadsheets and word processor docs). It kinda makes me sad to think I could have started in tech so much earlier, if people had recognised how well suited I was to Comp Sci. I'm gonna add as well - I made my school a website, and still nobody thought to suggest Computer Science to me 🙃

I don't think anyone actively tried to exclude me from that Comp Sci class, but I'm also pretty sure if I wasn't a girl I would have ended up in it. Any subconscious bias that existed in my teachers also existed in me - it's not like I was beating down the door of that class. I just didn't know it could be for me 🤷‍♀️

Our conditioning into what's "for" us starts so early, and breaking the bias requires conscious effort. It's great to see the work Girls Who Code and so many other similar organisations are doing in this area.

My five years in tech

On the whole, the last 5 years has been amazing, and I have zero regrets about career-changing into tech. However I've definitely come up against some challenges that I believe are symptomatic of bias in the industry. Let's have a quick run-down...

The bad stuff: a - thankfully - brief list

Very often being noticeably the only woman in a room (one time in particular sticks in my mind - 11 men, and little ol' me presenting some work to them)
Having questions directed at a (male) colleague, after I'd presented and demonstrated the code I worked on
Being assumed to take notes in a meeting
Being asked to make teas and coffees for others in a meeting
Being mistaken for a designer, despite having introduced myself with my job title
Having my (dismissed) ideas reframed by a man in the same meeting
Having a male client give me what can only be described as an uninvited "in person" code review
Having my own code explained back to me as if I didn't just write it 😆
Being told that although a promotion would match up with my current responsibilities it "wouldn't be credible" to anyone looking in from the outside
Getting one or two creepy DMs any time I give a meet up talk/workshop/etc

The good stuff

On the whole I've been pretty blessed with great colleagues throughout my tech journey.

That time a question got fired at my male colleague instead of me, the presenter? My colleague simply passed the mic to me, pointing out I was the one in the know.

That time my ideas got reframed by a man in the same meeting? Another male colleague pointed out what had just happened, the person was mortified and apologetic and in the end we all laughed.

The teas and coffees? I pointed it out to my manager (the CEO of the company) who then made a point of always doing this himself, for every client meeting.

Oh and that time I was told a promotion wasn't credible? Well, I left that job and got a tidy pay raise to go somewhere else 😝

Breaking the bias

I know it isn't such a smooth path for everyone, but what I want to stress in this post is the positive impact many of my colleagues have had throughout my journey. I've been lucky to have people around me to call out bias when they see it, listen and make changes to their own behaviour, and advocate for others that might be getting overlooked.

I strive to do the same for others, and hope you will too ❤️

Feature update: tag selector

Suzanne Aitchison — Fri, 21 Jan 2022 10:31:16 +0000

Hello DEV community!

Just a quick update to let you know about a new feature we've rolled out: a new tag selector for the V2 editor 🎉

How does it work?

The base functionality of the selector hasn't changed too much - you should be able to click into the tags field, see suggestions of "Top tags" and type to search for the tag you want.

Adding a tag

You can add a tag to your post by doing one of the following:

Clicking a tag that appears as a suggestion in the dropdown
Using the Up/Down arrow keys to highlight a suggestion and pressing Enter
Typing a , or space after your tag name (e.g. typing "javascript,"
Typing your tag name and simply clicking elsewhere in the page to "move away" from the selector

Editing or removing a tag

Once your tag is added, it should be clearly reflected in the UI as a set of buttons. Clicking the 'X' will remove the tag, and clicking the tag's text will put it into "edit mode" for you to make any changes.

If you are currently typing a long list of tags, you can also pop your previously added tag into "edit mode" by pressing Backspace while you're in the empty text field.

What problems does it solve?

We've had reports of various issues with the previous tag selector, which we believe this new version resolves. Particularly:

It wasn't very clear when a tag had been successfully added
If you added a lot of long tags, the field scrolled horizontally and became hard to read/edit
The old selector created a "focus trap" on the page - when you used the keyboard to navigate through the form you would get stuck in the tags field
It didn't provide any feedback to screen reader users, and didn't conform to a lot of accessibility best practices for this kind of component

Future plans

The new tag selector is built using a new component: <MultiSelectAutocomplete /> which is designed to be reusable in other areas, including with items other than tags. In the near future you should start to see this component pop up in other places in DEV!

That's it!

If you'd like to check out the code, have a look at this epic in GitHub which links to the incremental PRs that rolled this out. You'll also find the component in our Storybook, including documentation on how to implement it.

We look forward to hearing how folks find the new tag selection experience, and if you have any feedback or questions please let us know!

How we made the markdown toolbar

Suzanne Aitchison — Thu, 02 Dec 2021 14:53:08 +0000

You might have seen a new feature arrive in the editor this week - the markdown toolbar:

Feature update: Markdown Toolbar

Amy Lin for The DEV Team ・ Nov 29 '21

#meta #product #ux #changelog

As a follow up to Amy's post, I wanted to share a little bit about how we approached the development of the toolbar component, and some of the technical considerations we've had in mind during the implementation.

Quick contents:

Storybook for sandboxed development
Core functionality: insert and undo formatting
Thinking about keyboard interactions
Changes to image upload
Final thoughts

Storybook for sandboxed development

As much as possible, we like to create features in small incremental Pull Requests. It helps us make PRs more easily reviewable, and allows us to get feedback and adjust course as early in an implementation as possible.

However, we don't want to ship incomplete features to DEV or any other Forem! Instead, we built out the markdown toolbar in our Storybook. This gave us a sandboxed environment where we had access to all of our design system classes, components, etc, without having to actually add the toolbar to the editor (so now you know where to look if you want to creep on new frontend features in development 🤓).

There were a couple of extra benefits to this approach, namely:

We use @storybook/addon-a11y which gave us continuous accessibility feedback as we built the component
We were able to easily share the "work in progress" across our team, since although the code wasn't "live" in the app, it was "live" in Storybook

If you're new to Storybook, I'd recommend checking out this talk from @nickytonline

Core functionality: insert and undo formatting

The core functionality of the toolbar is to insert and remove formatting, and you can find the code responsible for this in markdownSyntaxFormatters.js. The logic is all contained in this helper file, keeping it separate from the Preact component itself, to allow for better readability and testability (there are well over a hundred tests for this utility file!).

Grouping formatters

We grouped the formatters broadly into two categories - inline (e.g. **bold**, _italic_) and multi-line (e.g. code blocks, lists). In the end, most of the formatters rely on two core functions: undoOrAddFormattingForInlineSyntax, and undoOrAddFormattingForMultilineSyntax. This means that most formatters can call the same function, just passing along what prefix and suffix is expected, e.g. the bold formatter looks like:

undoOrAddFormattingForInlineSyntax({
  selectionStart, // where the user's selected text starts
  selectionEnd, // where the user's selected text ends 
  value, // the current text area value
  prefix: '**', // the formatting expected before selection
  suffix: '**', // the formatting expected after selection
});

Outliers to the groupings

There are a couple of formatters which don't fall neatly into the two groups mentioned above, namely Heading and Link.

The Heading formatter has special functionality, where the heading level is incremented on each click, up until a maximum of heading level 4, after which it removes the formatting completely.

Similarly the Link formatter adjusts its behaviour depending on whether your selected text is a URL or not. Since they don't readily fit into the undoOrAddFormattingForInlineSyntax or undoOrAddFormattingForMultilineSyntax functions, they have their own custom code instead.

Allowing for formatting to be removed

On face value, the core function of handling a button press is pretty straightforward - add the prefix before the selected text, and the suffix after it. However, we had a few additional cases to consider, for example:

If the user's selected text is "hello world", but the characters immediately before and after the selection match the prefix/suffix, we want to remove the formatting. In this example above, the highlighted "hello world" should remain, and the stars on either side should be removed (rather than formatting it as bold for a second time and producing ****hello world****).

If the user's selected text includes the prefix/suffix, we also want to remove the formatting. In the example here, **hello world** should become "hello world".

Both of the above considerations become more complex in certain cases like links, where the user's selected text could be the URL, or the link description, or the entire format from beginning to end. For example, given the link [my link text](http://myurl.com), we want to remove the whole link formatting whether the user has selected "my link text", or "http://myurl.com", or the full link including both parts.

The upshot is that we need to check both the selected text, but also the text before and after the current selection before we decide what to do with the button press. We've favoured being a bit more verbose in the code to be clear about what we're doing at each stage of these checks, for example:

const selectedTextAlreadyFormatted =
    selectedText.slice(0, prefixLength) === prefix &&
    selectedText.slice(-1 * suffixLength) === suffix;

if (selectedTextAlreadyFormatted) {
  // return the appropriate result
}

const surroundingTextHasFormatting =
    textBeforeSelection.substring(textBeforeSelection.length - prefixLength) ===
      prefix && textAfterSelection.substring(0, suffixLength) === suffix;

if (surroundingTextHasFormatting) {
  // return the appropriate result
}

It would definitely be possible to make our formatter code terser, but we've veered on the side of readability so that the code is more maintainable and easier to contribute to.

Maintaining correct cursor position/text selection

The final consideration on button press is making sure the user's text selection remains consistent after we use a formatter.

If the user has text selected, we want to make sure it stays selected after adding/removing the formatting. Given the length of the text area value changes after adding/removing the formatting (e.g. adding or removing "**"), this means we have to calculate the indexes of the selection's new start and end point.

If the user doesn't have text selected, we want to make sure their cursor is placed inside the new formatting, ready to keep typing.

In cases like links, we adjust where we place the cursor depending on whether a link description or URL already exists. For example, if you select the text http://myurl.com and press the link button, you'll see this update to [](http://myurl.com) and notice your cursor is placed inside the square brackets, ready to write the description. Conversely, if your selected text was "my awesome portfolio", you'll see [my awesome portfolio](url), with the placeholder "url" selected, ready for you to replace it with the link's actual URL.

In the end then, all of our formatters return an object detailing all the information the Preact component needs to update the text area, including the properties:


editSelectionStart // The start index of the text we will replace
editSelectionEnd // The end index of the text we will replace
replaceSelectionWith: // The new text to place between the editSelectionStart and editSelectionEnd
newCursorStart // Start index of new cursor selection
newCursorEnd // End index of new cursor selection

Thinking about keyboard interactions

I'll preface this section by mentioning that there is a known bug on our editor page, in that there is a focus trap if you press the Tab key and activate the tags input. Development to replace the tags autosuggest component with an accessible version is underway and we aim to have this resolved very soon.

Roving tabindex

The markdown toolbar follows the toolbar authoring practices, and a substantial part of this is making it appropriately navigable by keyboard.

Once your focus is inside the toolbar, it's navigable by Left/Right Arrow key, and you'll see that the focus cycles without interruption - e.g. if you press LeftArrow when focused on the 'Bold' button, focus will move to the overflow menu (the last item on the right).

We use the roving tabindex technique to achieve this, managing the buttons' tabindex attribute in Javascript. I won't go into too much detail on that implementation here (maybe a follow up post!), but the result is that the controls are effectively grouped together.

Accessible tooltips

Prior to this toolbar work, the only tooltips we had in the codebase were "hover only", meaning they can't be triggered by keyboard. For this reason, we haven't used tooltips much to convey essential information, since not all users would be able to benefit from it. However, the toolbar design called for some extra detail for all users, to make sure the buttons' functions could be understood.

We've updated our Button component to accept a tooltip now, and by default this tooltip forms part of the button's accessible name (by including the text inside the button, even if it is visually hidden). The tooltip is shown on hover and on focus, meaning that the keyboard can trigger its appearance. We've also made sure that a user can temporarily dismiss the tooltip by pressing Escape, since it could be appearing over some other content and getting in the way!

Keyboard shortcuts

Some of the formatters also have keyboard shortcuts, which we implemented using a KeyboardShortcuts component we already use throughout the app.

One thing that came to light quickly, however, was that our KeyboardShortcuts component treated the macOS cmd key and the ctrl key interchangeably. This meant that on macOS, pressing ctrl + b would activate the bold formatter the same as cmd + b, when the standard behaviour would be for the cursor to move back one space. We've now resolved this issue across the codebase.

Another issue quickly raised by DEV community members after launch was that we'd neglected to call event.preventDefault() on a shortcut key press, with the unfortunate side effect that some fairly disruptive browser shortcuts were also being triggered by our shortcuts (for example, cmd + u in Firefox was adding underline formatting but also opening 'view source' for the page 🙈). Thanks to the quick feedback from the community, we were able to resolve this within hours of launch.

Changes to image upload

The final aspect of the toolbar development was some changes to the image upload flow.

Styling the file input

Styling file input selector buttons is notoriously tricky, and to make sure we could maintain the look and feel of our other toolbar buttons, we instead have relied on a visually hidden file input, with a separate button in the toolbar, which activates that hidden file input when it's clicked.

Making uploads cancelable

Previously a user couldn't cancel an in-progress image upload, but we've changed that! We've achieved this by making use of the AbortSignal interface.

When an upload begins, we create an AbortRequestController, and pass its "signal" to our helper function which makes the network request via fetch:

const startNewRequest = (e) => {
  const controller = new AbortController();
  setAbortRequestController(controller);
  handleInsertionImageUpload(e, controller.signal);
};

// Triggered by handleInsertionImageUpload
export function generateMainImage({ payload, successCb, failureCb, signal }) {
  fetch('/image_uploads', {
    method: 'POST',
    headers: {
      'X-CSRF-Token': window.csrfToken,
    },
    body: generateUploadFormdata(payload),
    credentials: 'same-origin',
    signal,
  })
...
});

To cancel the in-progress request we can call abortRequestController.abort(), and - tada - it's cancelled!

Final thoughts

I mentioned it further up, but a big shout out to the DEV community for quickly highlighting some issues with the toolbar when it went live. Thanks to your help, we were able to push fixes the same day it went live, and make the feature work better for others.

We're continuing to keep track of potential future enhancements, and you can see the current status on the GitHub epic.

If you'd like to dig deeper into the code, check out the Toolbar issue on GitHub, and its related pull requests.

5 things I'm thinking about when I check a Pull Request for accessibility

Suzanne Aitchison — Tue, 30 Mar 2021 11:24:05 +0000

(Photo by Cookie the Pom on Unsplash)

Developing reliable, accessible, apps is really a whole-team effort, and something I've not written much about before is how I approach things when I'm not the one writing the code.

This is by no means a complete guide to implementing or testing for accessibility, but hopefully it gives a general idea of things to think about when reviewing a Pull Request 🙂 Feel free to leave any of your own tips, suggestions, or questions in the comments!

If you'd like to skip directly to a section:

What even is this feature?
Initial check with axe
Keyboard operability
Screen reader checks
Considerations on focus management and dynamically appearing content

1. What even is this feature? 🤔

I find it's quite useful to take a step back and consider what UI pattern we're trying to introduce/refactor, and check the WAI ARIA Authoring Practices for a reminder of how that kind of UI pattern should behave.

Those docs are great to bookmark for development too, as they lay out expected behaviours, aria attributes, and link to example implementations.

Stepping back and asking yourself "what is this thing?" also helps spot opportunities to replace divs with more semantic alternatives. I've lost count of the amount of times I've had a lightbulb moment of "oh wait, this is actually a [insert something that should be obvious here]!".

2. Initial check with axe 🪓

The axe browser extension helps us capture a lot of low hanging fruit, e.g. colour contrast, missing landmarks or labels.

If there's multiple states the feature can be in, I'd try re-running axe in each state (e.g. a dropdown that's collapsed, vs expanded), as axe can only inspect the current DOM.

3. Keyboard operability 👩🏻‍💻

NB: If you use a Mac and/or Safari, please make sure your settings allow for tabbing to interactive elements. See Browser Keyboard Navigation in macOS

All features should be operable by keyboard alone, and this includes:

Pressing Tab to move through each of the interactive elements in a logical order (e.g. often this would be top-to-bottom, left-to-right)
Pressing Shift + Tab to move backwards through those elements
The currently focused element should be clearly visible (e.g. with a focus outline).
You should be able to interact with focusable elements as per the conventions in the WAI ARIA Authoring Practices. For example, activating a link with Enter, moving through combobox suggestions with Up Arrow/Down Arrow.
Being able to disclose content that would otherwise be triggered on a mouse hover (e.g. a tooltip that makes helper text appear on hover)

Bonus tip: invisible focus problems

If you ever get stuck debugging invisible focus issues, you can add this in the console to log out the focused element as it changes:

document.addEventListener('focusin', () => console.log(document.activeElement))

4. Screen reader checks 🤖

I've been asked a few times "Do you always check with a screen reader?" and the honest answer is "No".

My personal view is that a screen reader check is a must when:

We are introducing a new interactive feature (as opposed to a content change): things dynamically update/appear/disappear
Any aria attribute has been changed or introduced: these are only surfaced through assistive technology, so if we're not checking with a screen reader, we're not really checking at all

A little bit of initial setup

I usually use VoiceOver and Safari to conduct screen reader checks. This is mostly because VoiceOver is the default Mac screen reader, and is designed to work best with Safari (if you try using it with another browser you'll notice some buggy/unusual things).

If you use a Mac, I have a post with some initial setup instructions:

3 Quick Tasks to Get Familiar with Screen Readers (VoiceOver on Mac)

Suzanne Aitchison ・ Dec 1 '19

#a11y #webdev #html #beginners

If you don't use a Mac, I would recommend using NVDA and Firefox/Chrome, purely because NVDA is a free download and is very widely used (check out the latest Screen reader user survey.

Toggling VoiceOver on/off

If you have a keyboard with the function keys in the top row, you can turn VoiceOver on and off with Cmd + F5.

If you don't have the function keys, you can press the TouchID button three times in quick succession to bring up the accessibility options, where you can check/uncheck 'Enable VoiceOver'.

The rotor

I usually start a screen reader check using the VoiceOver Rotor (opened with the key combination ctrl + option + u)- it's an interactive menu that lists different elements by type (e.g. landmarks, links, form controls):

Press the left/right arrow keys to move through the different menus and get a quick overview of the relevant landmarks and accessible names of elements on the page. In the example above, you can quickly spot the 'Home' link has accidentally been named twice!

To jump to a particular element/section, use the up/down arrows to highlight and Enter to select.

You don't have to use the rotor at all if you don't find it useful, I just prefer it compared to reading through lots of the page to get to the section I'm interested in.

Accessible names

Axe will usually help flag this kind of issue, but as I navigate a feature with a screen reader, I tend to be on the lookout for elements where:

There is no accessible name (e.g. we've used an icon button with no aria label)
The accessible name is vague (e.g. 'click here' - to do what?)
The accessible name is repeated (e.g. lots of "toggle dropdown" - which dropdown?)

Bonus tip: silencing VoiceOver

It can sometimes be a bit much hearing everything announced as you're navigating around, especially if you're debugging one particular section. You can silence any in-progress VoiceOver announcement by tapping the ctrl key 🙂

5. Considerations on focus management and dynamically appearing content ✨

I usually pay particular attention to any features which involve content dynamically appearing/disappearing - for example: a dropdown menu, a warning banner, a modal.

The main things I'd be thinking about for these is:

How does a low-vision user know that content has appeared/disappeared? Is anything announced via the screen reader?
If the new content contains any focusable element (e.g. a link) - how do I reach it? If I have to press Tab 20 times something's probably not right.
If my keyboard focus was inside some content that's now disappeared - where is the focus now?

Usually some aria attributes or manual focus management with Javascript is required to make these kinds of components accessible. Again, you can usually find what's needed in the WAI ARIA Authoring Practices.

I joined the Forem team!

Suzanne Aitchison — Thu, 14 Jan 2021 13:29:36 +0000

I'm delighted to say I'm starting 2021 with a new role in the Forem team as a Software Engineer where I'll be focusing all on things frontend 🎉

Why Forem?

As a career-changer into tech, the DEV community has been a huge source of support and inspiration for me on my developer journey. I really love what Forem is doing in helping create inclusive, empowered, communities, and I'm super excited to be part of that.

I'm also really looking forward to working on an open-source project and interacting with the wider community of contributors. My first forays into open-source were during Hacktoberfest 2019 (which I posted about here on DEV!), and it definitely helped broaden my experience and make some really rewarding connections.

And finally, I care deeply about accessibility and inclusion (you might already know this from my previous posts, and my side project Up Your A11y), and I'm delighted to work for an organisation that feels the same.

A little bit about me

I got into coding about 4 years ago, and in a previous life I was an English teacher overseas, and an international student support manager here in the UK. I've lived in Cambodia, Vietnam and Prague, and travelled extensively in Nigeria and Ghana. Needless to say I'm not travelling so much any more, and I'm happily settled in my home country of Scotland, living by the beach in Edinburgh.

My coding career began in Android development and then later React and the frontend, which I ended up falling in love with. I advocate for accessible web experiences, through meet-up talks and Up Your A11y. I'm also really into CSS art! Last year I completed a project creating a new piece of CSS art every day for 100 days.

Aside from coding, I love sewing and make a lot of my own clothes, I do yoga every day and like to lift weights and go on long beach walks with my dog. Roller derby is my sport of choice, and until recently I helped run and co-captain a roller derby team here in Edinburgh. I'm also a (part-time) foster carer, which has made me pretty well-versed in Marvel and Pixar movies 😂

3 experiments with CSS paper effects

Suzanne Aitchison — Fri, 08 Jan 2021 14:19:30 +0000

Over the last few days I've been playing around with a few paper-inspired CSS effects in CodePen, and thought I'd share!

Experiment 1: Folded paper with taped edges

Inspired by new year's resolutions (and my lack of them), for this experiment I had a play about with a folded paper effect, and transparent layers to look like sellotape (or whatever brand of tape is popular in your country 😂).

The folded paper effect is created with an ::after pseudo element (I used ::after instead of ::before to make sure the text looked like it had been folded in the paper too), with two layered linear-gradients - one running left to right, and another top to bottom.

The tape itself has opacity set to 0.5 to give the semi-transparent effect, and I added a small dotted border on the tape ends to make it look a little serrated like it'd been cut.

Experiment 2: Pinned card

I then wanted to play about with some less crumpled paper, and had a go at a pinned card. Sticking with the 'pop it on your noticeboard' theme, it just has a simple reminder about a zoom call on the card itself.

The fun part of this - of course - was the pin. I love a bit of CSS art 😄. The different components of the pin are commented in the code so you can see how I went about it (much like all these experiments, the CSS could very usefully be tidied up in future, but hopefully you'll get the idea!). Much like the folded paper, it relies primarily on linear, and this time radial, gradients to make it look a bit more 'life like'.

Experiment 3: "Contact me" tear-off paper

Remember in the old days when you'd see adverts on noticeboards/lamp-posts/wherever with little phone number slips you could rip off and take home? I thought it might be fun to try to make one in CSS as an alternative "contact" section.

I wanted to try and make this semantic and accessible, so the contact links are all marked up as list items (this makes sure they're announced as a list to screen reader users, and show as a nice vanilla list if the CSS fails to load). I've also made heavy use of rem units, as a slightly hacky way of making sure that if a user has a larger font-size set on their browser, the content scales up without affecting the "CSS art" of it 🙂

I've tried to make some of the paper slips stick out a bit more, as if they'd been folded out from the poster slightly. To do this I used skew and - yet again - some linear gradients. It would be cool to make this interactive at some point, to let a user "tear" an item off of the list. Maybe a future experiment!

100 Days of CSS Art - Complete! 🎉

Suzanne Aitchison — Sun, 23 Aug 2020 15:06:53 +0000

100 days ago I joined the 100 Days Project Scotland which "gives anyone, regardless of age or ability, the framework and permission to get creative".

People from all over Scotland have been creating art in various forms - pottery, graphic design, portraiture... and for me, CSS art!

In case you missed it, I wrote a little bit about my motivation to take on this challenge here:

Join Me for 100 Days of Pure CSS

Suzanne Aitchison ・ May 16 '20 ・ 2 min read

#css #html #webdev #codepen

I also shared some lessons and favourite pieces from the first 50 days:

5 lessons from 50 days of CSS art

Suzanne Aitchison ・ Jul 4 '20 ・ 4 min read

#css #codepen #showdev #webdev

Today I finally finished the project, and to celebrate, I thought I'd share a couple of my favourite pieces from the second half 😄

My favourite piece overall - a self portrait!

My favourite piece (which probably says a lot about my ego haha) is a portrait of myself! This was my only attempt in the project to make a human, which felt a bit daunting, but I think it looks like me and I'm really happy with the result!

My favourite CSS animal

I made a lot of animals over the 100 days. They make for really good projects, as they're instantly recognisable, can be simplified a lot into basic shapes, and also they're cute, so what's not to love?

I made so many animals, I started a collection in CodePen for them. If you like you can visit my CSS Zoo

But since my last update on Dev 50 days ago, my favourite animal piece has been a portrait of my friend's dog, Colby. Here he is peeping over a picket fence:

My favourite animation

This one is harder to choose! A lot of my animations have been very simple, largely just due to the time constraints of creating an image a day. Now the project is finished I'm looking forward to learning more about animation and creating some more complex stuff! But of the second half of the project, my favourite animation is probably this little hamster wheel:

My favourite "realistic" one

To be honest I didn't do a lot of realistic images, and one thing I discovered over the project is that I much prefer the fun of finding the most basic shapes within an idea and creating fairly flat illustrations. But of the ones where I did try to make it slightly more realistic, I think this lava lamp is my favourite - my only regret is that I didn't have time to animate it!

My favourite "weird one"

Part of the challenge with this project has been to come up with an idea to make each day. Something that's simple enough to be achievable in whatever time I have that evening, but also something that will hopefully be fun and interesting.

Some of the ideas that come into my head are... um.. strange, sometimes. My favourite from the "strange" pile is this block of cheese:

What now?

It'll be strange having more time on my hands in the next little while, it's become such a habit to make an image every day!

One thing I'd like to do more of is writing tutorials here on Dev to help others get started with CSS art. I created one a while ago to make a sheep, and would love to do more:

Get started with CSS art - make a sheep! Step by step

Suzanne Aitchison ・ Jul 19 '20 ・ 8 min read

#css #html #codenewbie #codepen

If you'd like a tutorial on any of the images I've created, please do let me know!

See the full collection

You can view all the 100 pieces of CSS art over on CodePen: Suzanne makes 100 things in CSS

Get started with CSS art - make a sheep! Step by step

Suzanne Aitchison — Sun, 19 Jul 2020 13:06:13 +0000

I recently hit the halfway point in my 100 days of CSS art journey - I've learned a lot since I started - you can read about it in my last post:

5 lessons from 50 days of CSS art

Suzanne Aitchison ・ Jul 4 '20 ・ 4 min read

#css #codepen #showdev #webdev

I know first-hand it can be intimidating getting started with CSS art, and hopefully in this post I'll show you it's totally achievable, as we make this cute wee sheep, step by step.

What you'll learn by making this sheep

Some key positioning techniques
Making use of ::before and ::after pseudo elements
Utilising CSS custom properties (variables)
One way clip-path can help you create shapes

Checkpoints after each step

At the end of each of the 5 steps there is a CodePen showing you both the code and result of what we've covered up til the end of that step, so you won't get left behind!

If there is anything unclear in the instructions, do skip to that CodePen and take a closer look; hopefully all will become clear.

Step 1: Set up your canvas

Start a new pen in CodePen (or wherever you like to create your code!). The first step is to get ready with your "canvas" - i.e. the area of the page you will create your image inside.

Choose a background color

First we'll set the body element's background color - I chose a nice grass green, but feel free to use whatever funky color you like!

body {
  background: #54a865;
}

Create a box and position center

I've created a div with the classname "sheep" to act as our canvas. Width and height has been set to 180px, and we'll give it some margin too so it looks nice on the page.

<body>
  <div class="sheep"></div>
</body>

.sheep {
  position: relative;
  margin: auto;
  display: block;
  margin-top: 8%;
  margin-bottom: 8%;
  width: 180px;
  height: 180px;
}

Note the property position: relative. This is important, as inside the canvas we will be using absolute positioning. By setting the position to 'relative' here, the content of our canvas will be positioned relative to this canvas.

Give yourself a guide by adding a temporary canvas background

I've set the background of the 'sheep' to pink for now, purely so I can see exactly where the canvas is, and check it's positioned correctly. Choose whatever color stands out to you!

Work in progress - end of step 1:

Check what you should have so far:

Step 2 - Make some fluff

The most important part of a sheep? The fluff!

The fluff on this sheep is going to be made in two halves - left side and right side. On each side we will have three overlapping circles, like so:

Add a CSS variable for the fluff size

As we can see above, we'll have six total fluff pieces, all of which will be the same size. When you have a property that is going to be shared across multiple CSS selectors, it's a good idea to create a CSS property/variable for them.

This allows you to easily access and change the property in one place, without having to go through multiple places in your code.

We can create this fluff size variable at the root of the document like so:

:root {
  --fluff-size: 70px;
}

Now whenever we want to access the fluff size (e.g. for the width and height of all the fluff pieces) we can use var(--fluff-size) to get it!

Create the middle fluff pieces

The middle fluff pieces will be created with div elements:
<div class="fluff left"></div>
<div class="fluff right"></div>

The shared fluff class will contain the majority of our styles:

.fluff {
  position: absolute;
  width: var(--fluff-size);
  height: var(--fluff-size);
  border-radius: 50%;
  background: white;
  top: 50px;
}

Then we can use the extra left/right class names to position each side correctly.

The left side is going to be positioned at left: 0. Since this is the default for an absolute-positioned element, we don't need to add anything - yay!

The right side is going to be positioned at the right, which we can do as so:

.fluff.right {
  right: 0;
}

Create the upper fluff sections

To do this, we're going to use the ::before pseudo element. I'm using this purely to cut down on the amount of HTML code. Using .fluff::before will place an element as the first child of any element with the .fluff class - e.g.

<div class="fluff left">
  <!--  ::before fluff appears as if entered here      -->
</div>

We want to position the upper fluff elements slightly higher than the parent .fluff divs, and also more towards the center.

We can use the shared fluff class to do most of the work:

.fluff::before {
  content: "";
  position: absolute;
  width: var(--fluff-size);
  height: var(--fluff-size);
  border-radius: 50%;
  background: white;
  top: -35px;
}

And then once again we can make use of the left/right classes to move each side closer to the center, as so:

.fluff.left::before {
  left: 35px;
}

.fluff.right::before {
  left: -35px;
}

Create the lower fluff sections

This is very similar to the previous step. This time we'll use the ::after pseudo element. Using .fluff::after will place an element as the last child of any element with the .fluff class - e.g.

<div class="fluff left">
  <!--  ::before fluff appears as if entered here      -->
  <!--  ::after fluff appears as if entered here      -->
</div>

Similar to the above step, we'll use main fluff class to specify the majority of styles, and the left/right classes to push each lower fluff piece into the center.

Work in progress - end of step 2:

With that - our fluff is created - see what we have so far:

Step 3 - Add a head with ears

Now we have some fluff, but we need a head! We'll use a div with class name head to create this, and style it as round and black.

.head {
  position: absolute;
  width: 70px;
  height: 70px;
  background: black;
  border-radius: 50%;
}

We'll also once again use ::before and ::after pseudo elements - this time to make the ears.

The ears are ovals with a black background color. To make sure we keep the width and height the exact same on both, let's make some more variables for them:

:root {
  --fluff-size: 70px;
  --ear-width: 15px;
  --ear-height: 20px;
}

Position the head

We want to make sure that the head is positioned in the center of the body. One way do that would be to crunch some numbers and work out exactly how many pixels to the left we want to place it.

An easier way (in my opinion) would be to use the following:

left: 50%;
transform: translateX(-50%);

What this does is:

Use the left property to set the start position of the head to 50% of the parent div (i.e. the canvas we created in step 1). Our canvas is 180px wide, so this would be the same as left: 90px
Use the translateX transform to move the head to the left. The amount it moves to the left is 50% of the head's width. Our head is 70px wide, so this is the same as translateX(-35px)
The combination of the two places the center of the head (i.e. 35px) in the center of the parent

Work in progress - end of step 3:

You can check the ear positioning and sizes in the CodePen below, or try choosing your own first! After this step you should have something like:

Step 4: Add some face features!

We want a happy smiley sheep, so lets add some eyes first. We'll use very similar style as before, creating two HTML elements inside the head:

<div class="head">
  <div class="eye left"></div>
  <div class="eye right"></div>
</div>

We'll use a border to help it look like a dark pupil inside of a white eye:

.eye {
  position: absolute;
  background: black;
  border: 5px solid white;
  height: 10px;
  width: 10px;
  border-radius: 50%;
  top: 15px;
}

You can then use the left and right classes to position each eye how you like (check the work in progress CodePen below if you're not sure though!)

Use clip-path to create the mouth

clip-path can be a very useful CSS property. It effectively creates a mask for your HTML element, allowing only a portion of it to be shown.

In this case, we're going to use it to turn a block into a semi-circle.

Let's start with an HTML element <div class="mouth"></div> inside the head. We'll style it as a white block, and position in the center of the head just like we did with the in Step 3.

.mouth {
  position: absolute;
  left: 50%;
  transform: translateX(-50%);
  background: white;
  width: 30px;
  height: 30px;
}

Use Clippy to create your mouth shape

Clippy is an awesome tool for creating clip-path code easily. Visit the site, select the circle option from the right, and drag the element around to create the semi circle shape you want.

The code it generates should look a bit like:

clip-path: circle(50% at 50% 0);

Feel free to choose another shape for the mouth and play around with Clippy to your heart's content!

Once you're ready, add the clip-path property to the CSS for .mouth, and adjust the vertical positioning to suit. Here's what I have now:

.mouth {
  position: absolute;
  bottom: -10px;
  left: 50%;
  transform: translateX(-50%);
  background: white;
  width: 30px;
  height: 30px;
  clip-path: circle(50% at 50% 0);
}

Work in progress - end of step 4

You're nearly at the finish line! So far, you should have something like this:

Step 5: Add the legs and finish up!

There's no new techniques here, and the code for the legs should look fairly familiar by now. You'll need to create two new HTML elements:

<div class="leg left"></div>
<div class="leg right"></div>

Make sure you place these before the fluff elements and the rest of the code you created. This makes sure they sit behind everything else.

Each leg is a black rectangle, with a slight border radius to remove any sharp corners:

.leg {
  position: absolute;
  top: 120px;
  height: 50px;
  width: 15px;
  background: black;
  border-radius: 30%;
}

We can then use the left/right classes to position each leg. I've used the same positioning trick we looked at in step 3 to make the legs sit at 30% in from each side, i.e.

.leg.left {
  left: 30%;
  transform: translateX(-30%);
}

.leg.right {
  right: 30%;
  transform: translateX(30%);
}

Tidy up

Now you have all your elements in place, it's time to clean up by removing that pink background we added to the canvas in step 1, and deleting any extra code comments you don't want any more!

Ta da!

You should now have a finished sheep, a little bit like this:

Congratulations! If this is your first piece of CSS art, seriously - WELL DONE!

Round up

Let's take a look at what techniques you can now re-use in your CSS art to come:

Positioning items vertically and horizontally, including with % values
Using clip-path to make shapes
Using ::before and ::after to save lots of extra HTML elements
Using CSS variables

Awesome!

Thanks for following along to the end - if you do create a wee sheep through this tutorial I would absolutely love to see it! Drop your codepen link in the comments so we can all revel in its glory 😃🐑

5 lessons from 50 days of CSS art

Suzanne Aitchison — Sat, 04 Jul 2020 09:37:54 +0000

50 days ago I started out on my project for 100 Days Project Scotland - to create a piece of CSS art every day for 100 days. I wrote about my motivations here:

Join Me for 100 Days of Pure CSS

Suzanne Aitchison ・ May 16 '20 ・ 2 min read

#css #html #webdev #codepen

I hadn't really tackled any CSS art before this project, and it's been a fun journey to date! Today marks the halfway point, and I thought I'd share an update on what I've learned so far.

My top 5 learnings so far

1. Simple is often most effective

Throughout the last 50 days I've spent a varying amount of time and effort on each creation, and some days I've gotten really carried away with complex shapes, animations, and so on.

But - some of my most popular creations to date have been the simplest. Like this sheep, which is pretty much made of two colours, and a lot of circles!

So my advice to anyone else getting started with CSS art would be to focus on pictures you can make with a few basic shapes, and keep your colour palette as minimal as possible, as it can help the image look more striking.

2. Clip-path is very, very useful

Before I started this project I'd never had a need to use the CSS property clip-path. I'm not even sure I'd heard of it!

Clip-path allows you to define a shape that will determine what parts of your HTML element are shown. You can use it to create all different kinds of shapes! Check out the MDN web docs for clip-path.

Even better, there's a great tool for creating these shapes in a handy UI - Clippy. I've used this tool a whole lot in the last 50 days 😄

For example, I used it to create some random leaf shapes for my leafcutter ants to carry:

3. Gradients can be a time-saver (and a div-saver)

Quite often I've found that I need either stripes, or several neighbouring blocks of different colour. Until I started this project I hadn't fully appreciated how far CSS gradients can get you in this respect, especially with the ability to add fixed stops in a gradient to create hard stripes, rather than colours gently fading from one to another.

For example, I used a linear-gradient with some very gentle grading to create both the tail and wing stripes for this parrot:

And a repeating-linear-gradient to repeat a bunch of stripes in opposite directions on this ice cream cone:

4. CSS variables are scope-able and very helpful

I'd used CSS variables before, and immediately employed them in this project as it makes life so much easier to be able to e.g. edit all your colours in one place, defining/using like so:

:root {
  --ice-cream-color: #FCB8C3;
  --ripple-color: #FC889B;
  --cone-color: #F7C077;
  --waffle-color: #F3A63A;
}

.scoop {
  background: var(--ice-cream-color);
}

I usually have the same colour used in a few places in the picture, and being able to change it in one place is such a huge benefit 🙏

Something I hadn't really done with CSS variables before though was using them in a scoped fashion. Instead of declaring a variable value in the :root like above, you can declare them within a CSS certain selector and they'll be applied within that scope.

For example, in this cogs animation, the three cogs share a class which defines the majority of their appearance and behaviour. To make them slightly different sizes and colours, I used scoped CSS variables e.g.

.cog-one {
  --cog-color: #898888;
  --cog-outer-size: 50px;
}

.cog-two {
  --cog-color: #A16036;
  --cog-outer-size: 40px;
}

.cog {
  border: var(--cog-outer-size) solid var(--cog-color);
}

5. Inspiration can come from the mundane

A big part of the challenge especially initially was trying to think what on earth to make. It had to be simple enough that I could actually do it within a reasonable time frame, but also interesting enough to be enjoyable and hopefully a bit eye-catching.

And it turns out that some of the most boring things have been the most enjoyable to code and share 😄 So far my creations have included pretty banal stuff like my washing machine, a mug of tea, a cup of coffee, and a toaster:

Fancy joining me?

I'm looking forward to the second half of the project, and if you feel inspired to try some CSS art I'd love to follow you too!

You can connect with me and follow my creations on my CodePen profile, or on my Twitter.

I've found CodePen, like DEV, to be a really supportive community and I've been given a lot of encouragement and motivation there. Hopefully if you decide to a give it a go too, you'll find the same!

Hope to see you there, and for now I'll leave you with my day 50 creation - some celebratory balloons 👋🎉🎈

Accessible images, icons and emojis

Suzanne Aitchison — Sat, 20 Jun 2020 09:21:30 +0000

This post was originally published at Up Your A11y: Accessible, images, icons and emojis

One of the first things we often learn about web accessibility is that we need to provide alternative text for images we use in our websites and apps. This is important because the alt text on an image provides contextual information to:

Visually impaired users (via screen readers), who can't otherwise see the image well
Users with slow network connections who may have trouble loading your images
Crawlers that dictate your SEO, which need a way to understand what content is presented on your page without seeing it

When it comes to actually implementing that alternative text however, it can be so hard to know what to write!

Common failings of alt text

There are many instances of alt text on the web that fall into one of the below failings:

Repeating what surrounding text already describes
Using redundant phrases like "Image of…"
Providing meaningless alternative text for a purely decorative component (e.g. "divider line")
Focusing on what the image looks like, rather than what it is being used to convey (either in content or function)

I'm going to step through a few key questions you can ask yourself when adding imagery to your content, to help you identify meaningful alternative text. I’ll also then take a look at some alternative imagery you might use (emojis & font awesome icons) and how to handle those in an accessible way.

A quick note upfront:

In this post I have used screenshots of groups of HTML elements for illustration. Please understand that the examples below are created by neighboring <img> and text elements and we are considering surrounding text as a separate HTML element to the image itself.

Question 1: Does Your Image Actually Need Alternative Text?

It’s worth saying loud and clear, although all <img /> elements must have an alt attribute, not all images need alternative text. Often we use images in a way that are purely decorative, e.g. to help space out a page, add a bit of color to a very text-heavy page, use as fancy bullet points, etc. In cases where the image used is purely decorative, it is acceptable to provide empty alternative text.

Ask yourself, if this image wasn’t present on the page, what would the user miss out on? If the answer is purely that it wouldn’t look as nice, then it sounds like you don’t need alternative text.

Some examples where alternative text wouldn’t be necessary:

Images used for layout purposes only

In the example above, the image is used to provide a decorative dividing line. It adds no contextual or functional value, and therefore the alt attribute can happily be left empty - i.e. alt=""

Images used as bullet points

In this example, we would create the <ul>, removing the standard list style, and using images in each li item instead.

If we did set alternative text on every bullet point, screen reader users would hear the same alt text announced at the start of every list item. This would be pretty noisy, and for no additional value, since the icons are purely decorative. It’s another great use case for empty alt text: alt="".

Images where the surrounding text is descriptive enough already

Sometimes when we use an image to convey context on a page, we also add text which captions the image, or otherwise describes it. Consider the following example:

Depending on what we want to achieve, there might not be a need to add alternative text to this image of a slice of pie, as long as there is nothing further we want to communicate beyond what is already written in the text beside it. In this case again, empty alt text would be acceptable.

However, if we do want to convey something additional with the image, then we would need to add the relevant alternative text. For example, imagine if the text "Slice of Cherry Pie" was missing from the example above. In that case, it would be relevant to add alt text, otherwise we haven't successfully conveyed the message that a slice of cherry pie is 500 calories.

Question 2: Does this image have a function?

Through asking question 1, you’ve established you need some alternative text for your image. The next question then addresses what kind of image you’re trying to describe. Many images in your app might have a function attached to them, rather than purely being part of your content.

For example, consider the header section of the DEV site, which includes an image of the DEV logo.

In this case, it would make sense for the alternative text to succinctly convey the function of the image, e.g. “Home”.

Don’t be tempted to add redundant additional text, for example: “Link to Home”, “Navigate Home”, “Back to Home Page”, “Home Icon”, etc. The semantics of the HTML take care of this information for you already.

The image will be part of a link, and so the screen reader will already announced that it is an image and a link. Avoiding redundant alt text like this will really help streamline the experience for your screen reader users.

Question 3: What additional content does this image provide?

Through steps 1 and 2, we’ve established that the image conveys some content, but it doesn’t have an associated function. The image is therefore part of the content you are providing, and alternative text is required to make sure that users don’t lose the context it provides.

When considering what alternative text to add to your image the key guidance is once again to put yourself in the shoes of the user - “if I couldn’t see this image, what would I need to know to appreciate this content?”. It is not an easy question to answer, but it is worth considering carefully. Remember that the alternative text you provide is not only used by screen readers, but also to display on the page if the image fails to load, and for search engines to understand your content.

The same image in different situations would require different alternative text. By way of an example, consider the following examples using the same image:

Example 1: the image is used liked a title

Here you can see that we are using the image like a title, with the description below going on to explain the ingredients or recipe steps required to make the item. In this case the alt text could usefully be the name of the object pictured, i.e. "Cherry Pie".

Example 2: the detail of the image is important

In this case, we can see that the detail of the image is central to conveying meaning. In this case, we would want to provide more detail in the alt text, e.g. "A slice of cherry pie served on a white plate with two fresh cherries beside it"

As you can see, there is no hard and fast rule other than to consider what content is missing when the image is missing!

Some special kinds of imagery

In some cases the visual imagery on the page is not actually an image. Common examples of this are font icons and emojis.

Font Icons

The examples in this post will focus particularly on Font Awesome icons, as it is one of the most popular and widely used font icon providers. Given they are so widely used, it’s no surprise that they have their own handy guide to how to use their icons accessibly; summarised below.

1. As before, ask: does this need alternative text?

If your icon is purely decorative, then alt text isn’t required. However, unlike with an image, a font icon does not have an “alt” attribute that you can set to empty. In this case, we can hide it from assistive technology users by using the ‘aria-hidden’ property. For example:

  <i aria-hidden="true" class="fas fa-car"></i>

Please note that aria-hidden must be explicitly set to true as in the example, and the shorthand aria-hidden will not be effective.

2. Does the icon have an action?

If the icon is associated with an interactive element, such as a link, then we can add an ‘aria-label’ to the interactive element, while hiding the icon itself as in Step 1. For example:

<a href="/" aria-label="Home">
  <i aria-hidden="true" class="fas fa-home"></i>
</a>

3. In other cases, display some alternative text off-screen

As we cannot add alternative text to the icon itself, what we can do is add some actual text, but display it in a way to make it only visible to assistive technology users. This can be done using CSS and displaying the text off screen. As before, we will add ‘aria-hidden’ to the icon itself (NB: the 'title' attribute in Font Awesome allows a tooltip to appear for sighted users):

<i aria-hidden="true" class="fas fa-plant" title="Vegetarian"></i>
<span class="screen-reader-only">Vegetarian</span>

and the CSS would look like:

.screen-reader-only {
  position: absolute;
  left: -10000px;
  top: auto;
  width: 1px;
  height: 1px;
  overflow: hidden;
}

Emojis

Emojis are another special case in terms of imagery that doesn’t present itself in an img tag. We can copy and paste the Unicode value of an emoji and have it show in your browser, but some extra steps are needed to make this accessible.

Hide if purely decorative

Similar to the font icon example above, we can hide the emoji if it is purely decorative. As the emoji does not have its own tag, however, we will need to wrap it in a ’span’ to do this:

<span aria-hidden="true">&#x1F4D6;</span>

Add an "img" role otherwise

In all other cases, we can ensure that the emoji is treated by the browser as an image. We can do this with the 'role' and 'aria-label' attributes. For example:

<span role="img" aria-label="open book">&#x1F4D6;</span>

Final thoughts

All of the preceding guidance boils down to those few key considerations:

Is this image purely decorative?
Does this image have a function, or is it purely content?
What content would the user miss out on if the image was missing?

The final question is the most difficult one to answer, but by taking a little time over this, you can improve the experience for all of your users, as well as your SEO!

And as a special reward for making it to the end of this long post - I have a little decision tree you can download/save that summarises the steps above in a visual flowchart:

DEV Community: Suzanne Aitchison

What Cypress E2E testing has taught us about our code

Some background

A greater awareness of accessibility

Uniqueness of elements

The power of landmarks

Headings, headings, headings

Javascript races 🏁

Want to know more about E2E testing at Forem?

Assistive technologies your users might be using

Screen reader

Refreshable braille display

Screen magnification software

Switch controls

Speech input software

Do you have any others to share?

5 years in tech, and she's still coding

The career switch

Better late than never

My five years in tech

The bad stuff: a - thankfully - brief list

The good stuff

Breaking the bias

Feature update: tag selector

How does it work?

Adding a tag

Editing or removing a tag

What problems does it solve?

Future plans

That's it!

How we made the markdown toolbar

Feature update: Markdown Toolbar

Amy Lin for The DEV Team ・ Nov 29 '21

Storybook for sandboxed development

Core functionality: insert and undo formatting

Grouping formatters

Outliers to the groupings

Allowing for formatting to be removed

Maintaining correct cursor position/text selection

Thinking about keyboard interactions

Roving tabindex

Accessible tooltips

Keyboard shortcuts

Changes to image upload

Styling the file input

Making uploads cancelable

More feedback for screen reader users

Final thoughts

5 things I'm thinking about when I check a Pull Request for accessibility

1. What even is this feature? 🤔

2. Initial check with axe 🪓

3. Keyboard operability 👩🏻‍💻

Bonus tip: invisible focus problems

4. Screen reader checks 🤖

A little bit of initial setup

3 Quick Tasks to Get Familiar with Screen Readers (VoiceOver on Mac)

Suzanne Aitchison ・ Dec 1 '19

Toggling VoiceOver on/off

The rotor

Accessible names

Bonus tip: silencing VoiceOver

5. Considerations on focus management and dynamically appearing content ✨

I joined the Forem team!

Why Forem?

A little bit about me

3 experiments with CSS paper effects

Experiment 1: Folded paper with taped edges

Experiment 2: Pinned card

Experiment 3: "Contact me" tear-off paper

100 Days of CSS Art - Complete! 🎉

Join Me for 100 Days of Pure CSS

Suzanne Aitchison ・ May 16 '20 ・ 2 min read

5 lessons from 50 days of CSS art

Suzanne Aitchison ・ Jul 4 '20 ・ 4 min read

My favourite piece overall - a self portrait!

My favourite CSS animal

My favourite animation

My favourite "realistic" one

My favourite "weird one"

What now?