Forem: Nate Watson

CSS tweaks for more accessible text

Nate Watson — Sat, 08 May 2021 13:04:58 +0000

One of the magical things about the web is that there are numerous ways people will access the sites we build. Whether it's on a phone, in a "reader mode", with images disabled, using a screen-reader or without a mouse, we can (and should) write code that ensures our sites work beautifully for all these different configurations.

With text particularly, there are a number of browser options that people might use to make content more accessible to them. This ranges from increasing font sizes for more legible text, swapping to a different font completely, or even swapping the text content itself via a translation tool.

Code that worsens support for these features is unfortunately common across the web, but goes unnoticed when testing against common accessibility tools such as screen-readers or automated auditors. Fortunately some small changes to how we write CSS can easily bring support for various text-related settings, and once you set things up, it'll quickly become second-nature on all your projects. So let's dive in and have a look at some guidelines for writing accessible CSS!

Tip 1: Use relative font size for nice font scaling

Font size is one of the most prominent accessibility settings in most browsers, and a good number of users set it to something other than the default. Stats gathered by the Internet Archive in 2018 showed that just over 3% of their website visitors were using a non-default font size setting, which is a pretty decent number of people!

What might be more surprising is that setting your CSS font sizes using pixels (i.e. with the px unit) causes that setting to do absolutely nothing. The problem with pixel units is that they tell the browser exactly how big something should be without allowing for any other factors (like a user having "very large" fonts selected in their browser settings) to come into play.

This is where relative font size units really shine. Rather than telling the browser "make my text exactly this big", they instead describe how big the text should be relative to some other element on the page. In the case of the em unit, it's relative to the parent element's font size, and for the rem unit it's relative to the font size of page's top-most, or root, element (almost always the <html> element).

By default, that root element's font size comes directly from the browser's font size setting. A browser with its fonts set to "very large" might give pages a root font-size of 24px by default, while one with "very small" might result in a default of 10px.

A lot of pages will override that default by setting a pixel-based font size on the HTML element, for example:

/** Don't do this **/
html {
    font-size: 18px;
}

This is often framed as providing a "sensible default", but it prevents the rest of the page from knowing the user's preferred font size. If you're approaching your sites from an accessible perspective, the user preference is almost always the most sensible default.

In short, avoid setting a pixel-based font-size on the HTML (or :root) element.

Setting font sizes

Now that we've got our root element respecting the browser font size, we need to extend that to all the other other elements on our site. Fortunately with a little bit of math (or an SCSS mixin) we can do this fairly effortlessly in a way that will be invisible to most users.

The key thing to know is that the default root font size is 16px in most browsers. That means text with its font size set to 1rem will display as 16px (1 times the root font size), 2rem will be 32px, 0.5rem will be 8px, and so on, for users who haven't changed the font size setting. With a little bit of maths, you can convert all your existing pixel sizes to an rem-equivalent:

sizeInRems = sizeInPixels / 16

Which should let you update any existing font size declarations to be root-relative:

- font-size: 16px;
+ font-size: 1rem;

- font-size: 24px;
+ font-size: 1.5rem;

// and so on

(If you're using SCSS, read on for a mixin that will do some of this for you).

By not overriding the root font size and switching to relative sizes your text will now scale to match each user's preference - if they've left the setting untouched, everything will look exactly as it did before. But if they've chosen to change the setting - to something larger or something smaller - your website's text will now scale to reflect that preference:

A note on line-height

It's important to also switch your line-height values to proportional units, otherwise the values won't scale to match any changes to the calculated font size. For people who increase the root font size, this can cause overlapping lines of text that are pretty difficult to decipher:

In fact, this is something you should do even if your font-size values are still using pixel units. In addition to settings that change the root font size, most browsers have an option to force a minimum font size (usually found under an "advanced font options" menu or similar). This will override any font-size values that are too small, but won't affect any fixed-unit line-heights, resulting in the same overlapping shown above.

The best way to fix this is to switch to unitless line-height values. Line-heights are one of the few CSS properties where it's valid to leave off the units completely (so no px, no em, no %), with unitless values being interpreted as "the unitless number multiplied by the element's own font size".

A mixin to help

If you're like me, pixel values are how you and the people you work with communicate - design tools usually give values in pixels, the browser inspector shows computed sizes in pixels and they're a unit anyone who stares at a screen for eight hours a day probably has baked into their mind. Thinking in terms of rems can feel less instinctive, and having to pull out a calculator to convert units is no fun.

Fortunately, you can write a nice little SCSS mixin (or equivalent in your favourite CSS pre-processor) to do all the hard work for you. The one I use looks something like:

@mixin font-size($font-size, $line-height: null) {
    font-size: 1rem * $font-size / 16px; // Assuming 16px as the "standard" root font size

    @if $line-height {
        line-height: $line-height / $font-size; // Gives a unitless value
    }
}

...and then you can write font sizes using pixels (specifically the pixel size you want to be used when the browser is set to its default font sizes), and the outputted CSS will use the appropriate relative units:

// Input:
.paragraph {
    @include font-size(24px, 30px);
}

// Output:
.paragraph {
    font-size: 1.5rem;
    line-height: 1.25;
}

Tip 2: Avoid hardcoded element dimensions - give text space to grow

If you browse the web with increased font sizes, it's common to encounter situations where text is too big for its container:

In fact this isn't just an issue when increasing the font size. Anything that changes the amount of text or dimensions of the letters can make this happen, which includes things like translating a page, using a different typeface (whether intentionally or due to a webfont not loading) or changing the letter spacing.

The source of issues like this is hardcoding the dimensions of elements that contain text:

.Button {
    font-size: 1rem;
    height: 50px;
    width: 250px;
}

// html: <button class="Button">Learn more about the rubber plant</button>

In this case our button is going to look bad if the text ever becomes taller than 50px or wider than 250.

We're essentially telling the element to not shrink or grow, so anything that doesn't fit will simply overflow out of the element - as shown in the earlier screenshot.

Often hardcoded dimensions like this can be removed completely or, if you need to prevent the element becoming too small, replaced with min-width/min-height alternatives. If the dimensions play a part in vertically centering the text content, padding is often a suitable alternative:

.Button {
    font-size: 1rem;
    min-width: 250px;
    padding: 10px 20px;
}

After applying this approach to the button and card in the earlier screenshot, we end up with something much nicer:

Tip 3: Specify web font weights and styles

Just as the font sizes you specify might be overridden, the font-families named in your CSS may not end up being displayed on the page. There are a number of situations where this will happen:

A webfont fails to load, causing a fallback to be used,
Webfonts get blocked completely (for speed, security, to save data, etc.),
A user finds a particular typeface easier to read, so uses an extension to force it to be used everywhere,
The page is automatically translated into a language that uses characters not available in the webfont.

The first step to handling these situations gracefully is something most people already do: specifying fallback fonts, or a "font stack":

font-family: Fira, Arial, sans-serif;

This tells the browser to use Fira if it's available, otherwise use Arial, and if that's not available, use the browser's default sans-serif font family. The fallback fonts should be similar to the preferred font, so the page will still look reasonable regardless of which one ends up being used.

If you're using webfonts there's one more thing you should do to really make your text great, regardless of the font family that ends up being used. Attributes such as font weight and italics often carry additionally (and intentional) meaning, or help differentiate between pieces of text on the page. That makes it important to preserve them no matter which font family gets used. To do this, we need to look at our @font-face declarations. These might look something like:

@font-face {
    font-family: 'Fira';
    src: url('fira.woff') format('woff'), 
        url('fira.ttf') format('truetype');
}

Different font weights (bold, light, etc.) and styles (e.g. italics) have to be loaded from separate font files, and therefore require separate @font-face declarations. It's common to see these each given unique names, like:

@font-face {
    font-family: 'Fira';
    src: url('fira.woff') format('woff'), 
        url('fira.ttf') format('truetype');
} 

@font-face {
    font-family: 'FiraBold';
    src: url('fira-bold.woff') format('woff'), 
        url('fira-bold.ttf') format('truetype');
}

Which might be used something like:

.bold {
    font-family: FiraBold, Arial, sans-serif;
}

The issue with this approach is that the browser doesn't really know that our 'FiraBold' font is bold - if it fails to load (or is swapped out for a different font), the fallback font will display in a regular weight, no different to the text around it.

To fix this, we need to be explicit about the weights and styles when declaring and when using our fonts. Rather than giving each variation a unique font-family value, we should use the same font-family value across all the variations, and explicitly specify the weight and style of each. For the above example this would look like:

@font-face {
    font-family: 'Fira';
    font-weight: 400;
    font-style: normal;
    src: url('fira.woff') format('woff'), 
        url('fira.ttf') format('truetype');
} 

@font-face {
    font-family: 'Fira';
    font-weight: 700;
    font-style: normal;
    src: url('fira-bold.woff') format('woff'), 
        url('fira-bold.ttf') format('truetype');
}

The final step is to update any CSS where you're using the font variations, so that font-weight and font-style CSS properties are used to select variations of the same font-family:

.bold {
-   font-family: FiraBold, Arial, sans-serif;
+   font-family: Fira, Arial, sans-serif;
+   font-weight: 700;
}

Now if the fonts on your page are overridden, fail to load, or are unable to display some text, the weight and style of the text will be preserved:

Bonus tip: Don't use icon fonts

Icons fonts are easy to set-up and use, but they have a number of issues, including breaking completely for users who override fonts (or any other situation where webfonts aren't loaded). That's not to say you shouldn't use icons though (far from it - well used icons are great for accessibility and usability), but approaches that don't involve fonts are the best way to go.

People much smarter than me have written various articles on the topic, so I'm going to delegate to them for this one:

Seriously, Don’t Use Icon Fonts by Tyler Sticka - an older article, but still entirely relevant.
Accessible SVG Icons with Inline Sprites by Marco Hengstenberg
Accessible SVG Icons by Chris Coyier

And we're done!

Supporting numerous different browser configurations can seem like a daunting task, but hopefully these tips have shown that some small changes to how you write CSS can have a big impact. If you're starting a fresh project, try to make these patterns the default! You'll quickly see that they're no extra effort, and visitors to your site will love you for it.

Adding dark mode to your React app with hooks, media queries and CSS variables

Nate Watson — Thu, 28 May 2020 12:18:39 +0000

Dark mode is quickly becoming an essential feature on the web — Twitter’s recent redesign has the much-requested feature baked in, as does Facebook’s (beta) redesign, not to mention numerous smaller sites adding support.

Wanting to keep up with the cool kids, I decided to have a go at adding dark mode to my own personal website. After a night of picking out some colours and procrastinating over the technical approach, piecing together a working implementation turned out to be much quicker and easier than I had expected. I’ve detailed the approach I took here, in the hope that someone else might find it useful!

Note: this approach is great for smaller sites, but for more complex cases you might need to combine it with other techniques — there are some resources that might be handy linked at the end.

So what are we actually trying to build here?

Great question. The key features I’ll outline are:

Detecting if a device is set to dark mode at the system level
Switching the theme whenever the system-level setting changes
A simple system (using CSS variables) to swap colours throughout the site
A toggle to let people manually switch between dark and light themes
A SCSS mixin to support more complex theming, for when you need to do more than just swap out a colour.

Here’s a quick example of what this can look like — if you’re in a hurry feel free to jump into the code to see how it all fits together:

Detecting dark mode with Media Queries

First up, let’s use some CSS to detect when someone has their device set to dark mode. To do this we’ll use a media query.

CSS media queries are most commonly used to alter styles based on the size of the browser. But recently they’ve been becoming much more powerful, with an impressive list of detectable features making it into recent specifications.

The media query feature we care about is prefers-color-scheme. As the name suggests, it lets us detect what kind of colour scheme the user prefers — one of dark, light or no-preference. Using it looks something like this:

    @media (prefers-color-scheme: dark) {
      /* dark theme styles go here */
    }

Any styles within that media query will only be applied if the user’s system is set to dark mode. That alone is enough to start adding a dark theme to your site! Here’s a quick example of what that might look like (in plain CSS) for a simple component:

    .TextCard {
      background: white;
      color: black;

      margin: 0;
      padding: 10px 20px;
      border-radius: 20px;
    }

    @media (prefers-color-scheme: dark) {
      .TextCard {
        background: black;
        color: white;
      }
    }

For simplicity I’m using named colours here like “black” and “white”. In the actual implementation I extract my common colours to SCSS variables to keep them consistent.

Awesome! This is good progress. But after doing this for a few components you might notice a lot of repetition: you’ll likely be swapping the same colours in and out over and over. For example, if most of your text is a particular dark grey, you’ll likely be adding an identical media query everywhere you use that colour, to swap it for a (different) particular shade in dark mode.

This is where the next bit of the puzzle comes in: CSS variables ✨

Swapping colours with CSS variables

With CSS variables we can define our default (light mode) colours in single place, then set them up to swap to different colours when dark mode is active. If you’re familiar with SCSS variables then these are similar, except that we can dynamically change their values at runtime — this is key for using them as part of our theming system.

As a simple example, we might define primaryTextColor and primaryBackgroundColor as variables. For our default light theme we would set them like this:

    html {
      --primaryBackgroundColor: white;
      --primaryTextColor: black;
    }

Setting the variables on the html element means they will be accessible to everything else on our page, since everything will be a descendant of the html element.

To use these variables we would then swap out the relevant hardcoded colours throughout our styles with a var() value:

    .TextCard {
-      background: white;
+      background: var(--primaryBackgroundColor);
-      color: black;
+      color: var(--primaryTextColor);

      margin: 0;
      padding: 10px 20px;
      border-radius: 20px;
    }

Now we need to make the value of the variables change when dark mode is active. To do that we can use our query selector from earlier, but instead of applying it to each individual component, we’ll just use it once, targetting the html element:

    html {
      --primaryBackgroundColor: white;
      --primaryTextColor: black;
    }
+
+    @media (prefers-color-scheme: dark) {
+      html {
+        --primaryBackgroundColor: black;
+        --primaryTextColor: white;
+      }
+    }

Note that within the query selector the values of the two variables have swapped. When dark mode is active this change will propagate to everywhere we use the variables, instantly switching the colours of those elements.

Extending this to other areas of your site is as easy as defining new variables, setting them to a different value within the dark mode media query, then swapping hardcoded colour values throughout your code for variables.

Here’s a quick demo of this approach:

Adding an override button to toggle the theme

At this point we’ve built out a pretty manageable, extremely lightweight way to respect a user’s system colour preferences. But what if want to give users more control and let them manually select the theme? Maybe they’re on a device that doesn’t support system-level dark mode, or maybe they want everything dark except our website.

To do that we’ll add a toggle button that not only allows the theme to be switched manually, but also automatically reflects the system-level preference.

I chose to use the react-toggle library for the actual toggle button, but this should work with any toggle component — whether it’s from a library, a custom component you’ve built, or even a trusty <checkbox> element.

Here’s the code I started with:

    import React from "react";
    import Toggle from "react-toggle";

    export const DarkToggle = () => {
      return (
        <Toggle
          className="DarkToggle"
          icons={{ checked: "🌙", unchecked: "🔆" }}
          aria-label="Dark mode"
        />
      );
    };

We’ll start by adding some state that controls whether the toggle is set to dark mode and connecting it up to the toggle:

+   import React, { useState } from "react";
+   import Toggle from "react-toggle";

    export const DarkToggle = () => {
+     const [isDark, setIsDark] = useState(true);

      return (
        <Toggle
          className="DarkToggle"
+         checked={isDark}
+         onChange={event => setIsDark(event.target.checked)}
          icons={{ checked: "🌙", unchecked: "🔆" }}
          aria-label="Dark mode"
        />
      );
    };

If you’re not familiar with React’s useState hook, it’s definitely worth having a look at the official hooks documentation.

If you jump into the React dev tools you should be able to see the isDark state updating when you click the toggle:

Now let’s add in some standards-based magic so that the toggle automatically matches the user’s system dark mode setting. To do that we’ll use a great little React library called react-responsive. This lets you get the result of a CSS media query and have the value automatically update whenever the query result changes. It’s super useful stuff, all built around the standard JavaScript matchMedia function.

As you might’ve guessed the media query we’ll use is prefers-color-scheme: dark. The code for that looks like this:

    import React, { useState } from "react";
    import Toggle from "react-toggle";
    import { useMediaQuery } from "react-responsive";

    export const DarkToggle = () => {
      const systemPrefersDark = useMediaQuery(
        {
          query: "(prefers-color-scheme: dark)"
        },
        undefined,
        prefersDark => {
          setIsDark(prefersDark);
        }
      );

      const [isDark, setIsDark] = useState(systemPrefersDark);
    };

The useMediaQuery hook takes two important arguments: the media query (the first argument), and a function (the third argument) to call whenever the result of the media query changes. We want to update our isDark state whenever the media query changes, so that’s exactly what the code does.

Now if you switch your system dark mode on and off, the toggle should automatically switch at the same time. Sweet!

…But it’s not connected up to our CSS yet, so the toggle is pretty useless. To remedy that we’ll need to run some code whenever our isDark state changes. React’s useEffect hook is perfect for this — we give it an function, tell it what properties it depends on (isDark in this case), and then React handles calling the function whenever the property changes:

    [...]

      const [isDark, setIsDark] = useState(systemPrefersDark);

      useEffect(() => {
        // whatever we put here will run whenever `isDark` changes
      }, [isDark]);

    [...]

The other half of the puzzle requires a slight tweak to our CSS. There's no way our code can change the value of prefers-color-scheme, which makes it hard to force dark mode with our current set-up. Instead, we're going to make our colour variables change whenever the HTML element has dark class (which we'll dynamically add to the element in just a second):

    html {
      --primaryBackgroundColor: white;
      --primaryTextColor: black;
    }

    html.dark {
      --primaryBackgroundColor: black;
      --primaryTextColor: white;
    }

Finally, let’s update the body of the useEffect function to add (and remove) the dark class based on whether isDark is true:

    import React, { useEffect, useState } from "react";
    import { useMediaQuery } from "react-responsive";
    import Toggle from "react-toggle";
+
+   const DARK_CLASS = "dark";

    export const DarkToggle = () => {
      const systemPrefersDark = useMediaQuery(
        {
          query: "(prefers-color-scheme: dark)"
        },
        undefined,
        prefersDark => {
          setIsDark(prefersDark);
        }
      );

      const [isDark, setIsDark] = useState(systemPrefersDark);
+
+     useEffect(() => {
+       if (isDark) {
+         document.documentElement.classList.add(DARK_CLASS)
+       } else {
+         document.documentElement.classList.remove(DARK_CLASS)
+       }
+     }, [isDark]);

      return (
        <Toggle
          className="DarkToggle"
          checked={isDark}
          onChange={event => setIsDark(event.target.checked)}
          icons={{ checked: "🌙", unchecked: "🔆" }}
          aria-label="Dark mode"
        />
      );
    };

🎉 And we’re done! The page’s theme should now automatically change whenever the toggle’s value is changed, either by clicking the toggle directly or by changing the system’s dark mode setting.

Optional finishing touches

Handling more complex styles

I found that CSS variables were powerful enough to handle nearly all the tweaks I needed to make on my website. However, there were still a few edge cases they couldn’t handle (or would be inconvenient for) — things like adding a subtle border or ever-so-slightly changing a shadow opacity so it would show up better in dark mode.

For these cases I created a SCSS mixin that only applies styles when dark mode is active (similar to what we were doing before we introduced variables, where we had a media query directly in the CSS for each component). Using it looks like this:

    .Card {
      background: var(--backgroundPrimary);
      box-shadow: 0 4px 20px rgba(darken($mint, 15%), 0.22);

      @include whenDark {
         // styles to apply to the element when dark mode is active
         box-shadow: 0 4px 20px rgba(#000, 0.5);
      }
    }

The code for the mixin itself uses the & SCSS feature to reference the selector the mixin is called from, plus @content to allow content to be passed into it:

    @mixin whenDark {
      html.dark & {
        @content;
      }
    }

(If you dive into the sandbox code you’ll see I’m also using the mixin to set the colour variables, so all the CSS is using the same code to determine whether dark mode is active).

Supporting users without JS

By switching our CSS away from using the prefers-color-scheme media query to instead relying on a class set from our JavaScript code, we inadvertently broke dark mode support for any users with JavaScript disabled. (if you’re not pre-rendering your site this won’t be an issue, since the site the site probably won't display for non-JS users anyway).

Fortunately bringing back support is fairly straight forward if you’re using the mixin above — simply update it to also apply any styles when the media query is active:

    @mixin whenDark {
      html.dark & {
        @content;
      }

      @media (prefers-color-scheme: dark) {
        & {
          @content;
        }
      }
    }

Additional tips + resources

Emulating dark mode

Chrome’s dev tools let you emulate prefers-color-scheme values via the Rendering tab.

If you’re on a Mac, Safari’s dev tools also lets you flip to dark mode with the click of a button:

Remembering the user’s preference

This isn’t something I’ve done, but it’s certainly something worth exploring. If your site doesn’t already have a data-persistence solution, the use-persisted-state hook would be a great fit for the dark mode toggle.

Querying dark-mode from outside the toggle

In the set-up I’ve described the only thing that really knows if dark mode is active is the toggle component. For simple cases that’s all good and fine, but what if other pieces of your JavaScript need to behave differently based on the theme? Again, this isn’t something that I’ve needed, but any common option for sharing state should do the trick — whether it’s the Context API, Redux or whatever your site is already using.

Browser support

Bad news: our old friend Internet Explorer doesn’t support CSS variables. That means this approach isn’t going to look great there — all your variable-ized properties will fall back to their default/inherited values (e.g. probably black for text colour). If you do need to support IE, there are a few options — the main ones being css-vars-ponyfill and SASS-based fallbacks.

Resources

Here are some other resources that you might find useful (I certainly did):

Let’s Say You Were Going to Write a Blog Post About Dark Mode — even if you’re not writing a blog post about dark mode, this is an excellent starting point for diving into the edge cases, accessibility concerns and other points I haven’t really covered (sorry Chris!)
Color.review —my absolute favourite site for choosing accessible colour combos.
A Strategy Guide To CSS Custom Properties — A great article on how to strategically use and think about CSS variables.
How to design delightful dark themes — handy things to keep in mind when designing a dark theme.
Supporting dark mode in web content —some useful tips in here for dealing with images in dark mode.

Wowee, what a journey! Thanks for making it this far, and if you found any of this useful I’d love to see what you’ve built!