Forem: William Lindvall

Simple and accessible dark theme using CSS variables and `prefers-color-scheme`

William Lindvall — Wed, 22 Jan 2020 00:00:00 +0000

More and more users are choosing to use 'dark mode' settings on both mobile and desktop devices to view content and interact with their favorite applications. Not only is this increasingly popular feature a nice way to add some user personalization, it is also an accessibility concern as enabling a dark theme can greatly improve readability in low light (if it is implemented correctly).

Let's set up a simple example site to walk through an implementation of a dark-mode that both respects the user's OS preference and falls back to this preference if JS is disabled or unavailable.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Theming example</title>

    <style>
      html {
        --color__bg: #fee;
        --color__text: #333;

        color: var(--color__text);
        background-color: var(--color__bg);
      }
    </style>
  </head>
  <body>
    <h1>Theming example</h1>
  </body>
</html>

In order to check if the user's device has dark-mode enabled and alter our CSS variables accordingly, we can use the CSS media feature prefers-color-scheme and check if its value is set to dark. This can match one of three values; no-preference, light or dark. Of the web features mentioned in this post, prefers-color-scheme has the worst browser support at the time of writing. While it is supported in the latest version of most browsers, Edge and IE do not support this CSS feature at all.

@media (prefers-color-scheme: dark) {
  html {
    --color__bg: #333;
    --color__text: #fee;
  }
}

Let's update our markup to add a checkbox input that will allow our users to change the theme if they wish.

<body>
  <h1>Theming example</h1>

  <label>
    Toggle dark theme:
    <input id="theme-toggle" type="checkbox" name="theme-toggle" />
  </label>
</body>

Let's now hook up our checkbox to set a data attribute on out HTML-element that corresponds to the active theme. If you are not familiar with data attributes in HTML and JavaScript a suggest having a look at MDN's documentation.

const htmlEl = document.firstElementChild
const themeToggleEl = document.getElementById('theme-toggle')
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches

if (previousTheme) {
  htmlEl.dataset.theme = previousTheme
} else if (prefersDark) {
  htmlEl.dataset.theme = 'dark'
  themeToggleEl.checked = true
}

themeToggleEl.addEventListener('change', e => {
  const selectedTheme = e.target.checked ? 'dark' : 'light'
  htmlEl.dataset.theme = selectedTheme
})

We can now add some styles that respect the data attribute that we are setting on our HTML-element.

html[data-theme='dark'] {
  --color__bg: #333;
  --color__text: #fee;
}

html[data-theme='light'] {
  --color__bg: #fee;
  --color__text: #333;
}

To persist the theme that the user select we can use the window.localStorage to read and write to the current domain's Storage object.

const htmlEl = document.firstElementChild
const themeToggleEl = document.getElementById('theme-toggle')
const previousTheme = localStorage.getItem('theme')
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches

if (previousTheme) {
  htmlEl.dataset.theme = previousTheme
} else if (prefersDark) {
  htmlEl.dataset.theme = 'dark'
  localStorage.setItem('theme', 'dark')
  themeToggleEl.checked = true
}

themeToggleEl.addEventListener('change', e => {
  const selectedTheme = e.target.checked ? 'dark' : 'light'
  htmlEl.dataset.theme = selectedTheme
  localStorage.setItem('theme', selectedTheme)
})

Finally, let's try to avoid an incorrect theme flash by checking for a theme in localStorage and appropriately updating the HTML-element's theme data-attribute.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Theming example</title>

    <style>
      html {
        --color__bg: #fee;
        --color__text: #333;

        color: var(--color__text);
        background-color: var(--color__bg);
      }

      @media (prefers-color-scheme: dark) {
        html {
          --color__bg: #333;
          --color__text: #fee;
        }
      }

      html[data-theme='dark'] {
        --color__bg: #333;
        --color__text: #fee;
      }

      html[data-theme='light'] {
        --color__bg: #fee;
        --color__text: #333;
      }
    </style>

    <script>
      ;(() => {
        const htmlEl = document.firstElementChild
        const previousTheme = localStorage.getItem('theme')
        const prefersDark = window.matchMedia('(prefers-color-scheme: dark)')
          .matches

        if (previousTheme) {
          htmlEl.dataset.theme = previousTheme
        } else if (prefersDark) {
          htmlEl.dataset.theme = 'dark'
          localStorage.setItem('theme', 'dark')
        }
      })()
    </script>
  </head>
  <body>
    <h1>Theming example</h1>

    <label>
      Toggle dark theme:
      <input
        id="theme-toggle"
        type="checkbox"
        name="theme-toggle"
        value="dark"
      />
    </label>

    <script>
      ;(() => {
        const htmlEl = document.firstElementChild
        const themeToggleEl = document.getElementById('theme-toggle')
        const prefersDark = htmlEl.dataset.theme === 'dark'

        if (prefersDark) {
          themeToggleEl.checked = true
        }

        themeToggleEl.addEventListener('change', e => {
          const selectedTheme = e.target.checked ? 'dark' : 'light'
          htmlEl.dataset.theme = selectedTheme
          localStorage.setItem('theme', selectedTheme)
        })
      })()
    </script>
  </body>
</html>

Thanks to some nice and new (but widely supported) web features, it doesn't take much to implement a dark-mode toggle. Now all that's left is to add a dark-theme to your next personal project!

If you came across any issue or have a question regarding this post, feel free to submit it here.

Easy CI with GitHub Actions

William Lindvall — Mon, 20 Jan 2020 00:00:00 +0000

GitHub Actions were recently publicly released on November 13, which enable easy automation and orchestration of software workflows. In this post we will explore the value they can add by setting up an action that handles deployment of my personal site, a static site built using Eleventy and hosted on GH Pages.

If you wish to follow along, you can clone one of the many Eleventy starter projects to quickly get set up with a static site. Also, be sure to replace details such as the build script and deployment branch to correspond to those of your project.

To get started, navigate to your repo on GitHub and open the 'Actions' tab. Here we can see an overview of popular actions used by the community. Selecting 'Set up a workflow yourself' opens up a sample YAML file in .github/workflow/. At the moment this won't do a whole lot but is helpful for getting a taste of the syntax we need to use.

name: CI

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v1
      - name: Run a one-line script
        run: echo Hello, world!
      - name: Run a multi-line script
        run: |
          echo Add other actions to build,
          echo test, and deploy your project.

As we can see, there isn't much too it; Basically a list of steps performed in sequence, run on a particular hook (in this case push). The first steps in our build job uses an action called checkout. This is very common to see as it simply helps us fetch and checkout our repo. For the most common workflows, like checkout there are many open source actions easily accessible in the GitHub marketplace that we can use to create our custom action.

My personal webpage is a straightforward static site built with eleventy that is currently hosted on GH Pages. Deployment is very straightforward and simply involves running a build script and then a script that pushes the build directory to the master branch.

The first thing we can do is determine when our action should run. In this case, I want my site to be built and deployed on every push to the dev branch.

name: Deploy Eleventy site to GH Pages

on:
  push:
    branches:
      - dev

    [...]

The site's build process requires several external dependencies (such as node-fetch and clean-css) which we need to install before build, which is handled by actions-eleventy.

[...]

jobs:
  build:

  runs-on: ubuntu-latest

  steps:
  - name: Checkout repo
  uses: actions/checkout@v1
  - name: Install deps
  uses: bahmutov/npm-install@v1
  - name: Build
  uses: TartanLlama/actions-eleventy@v1.1

On build our site also fetches GH contribution data which currently uses an environment variable to consume a GH access token.

To allow this to work in our action we must first set up a repository secret that we can then set as the value of the environment variable. To add the secret to our repo, navigate to 'Secrets' in the repository settings, and click 'Add a new secret'.

To provide this in our build step as an environment variable we can use set-env action and run this prior to build.

jobs:
  build:

  [...]

  - name: Env variables
  uses: allenevans/set-env@v1.0.0
  with:
    GH_TOKEN: ${{secrets.GH_TOKEN}}
  - name: Build
  uses: TartanLlama/actions-eleventy@v1.1

Finally, we run the actions-gh-pages action pushing our build files to master, passing the GH access token we configured, resulting in a YAML file that looks like the following:

name: Deploy Eleventy site to GH Pages

on:
  push:
    branches:
      - dev

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repo
        uses: actions/checkout@v1
      - name: Install deps
        uses: bahmutov/npm-install@v1
      - name: Env variables
        uses: allenevans/set-env@v1.0.0
        with:
          GH_TOKEN: ${{secrets.GH_TOKEN}}
      - name: Build
        uses: TartanLlama/actions-eleventy@v1.1
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v1.1.0
        env:
          PUBLISH_DIR: dist
          PUBLISH_BRANCH: master
          GITHUB_TOKEN: ${{secrets.GH_TOKEN}}

To add this workflow to our project we can commit this file right in the GitHub website by clicking the 'Start commit' button.

As seen, setting up custom GH Actions is very straightforward and easy to use to offload some of the burdens of our workflow. The action we created in this post is only the beginning and can be extended or composed together with other actions to, for example, integrate testing CI or more complex git workflows.

If you came across any issue or have a question regarding this post, feel free to submit it here.

Getting started with finite-state machines in React

William Lindvall — Thu, 16 Jan 2020 00:00:00 +0000

In web development, blog posts and library documentation too often use oversimplified examples to explain/illustrate UI patterns. When building out even the most simple form with a success message, one quickly realizes a isLoading boolean is probably not enough to describe the state.

To avoid a tangle of booleans and write more declarative and readable code, we can lean on the finite-state machine pattern. What it boils down to is:

There is a finite set of states that we can exist in
For each of these states, there is a set of events that allow us to transition into a new state

Let's have a look at an example in React of a button that fetches some async data using a helper hook useMachine to set up our reducer. The internals of this function aren't particularly important to this post as you could also choose to use a more popular and tested solution (like X State), however I wanted to keep the examples as simple as possible. If you are interested in how it works or have ideas for improving the API, the project is open on GitHub.

import React from 'react'
import useMachine from 'react-use-machine'

const LoadingButton = () => { 
  const {state, event, dispatch} = useMachine(
    {
      IDLE: {
        DATA_REQUESTED: 'LOADING',
      },
      LOADING: {
        DATA_SUCCESS: 'SUCCESS',
        DATA_ERROR: 'ERROR',
      },
      SUCCESS: {
        DATA_REQUESTED: 'LOADING',
      },
      ERROR: {
        DATA_REQUESTED: 'LOADING',
      },
    },
    'IDLE',
  )

  useEffect(() => {
    switch (event) {
      case 'DATA_REQUESTED':
        fetch('https://swapi.co/api/people/1')
          .then(d => d.json())
          .then(d => {
            console.log('data: ', d)
            dispatch('DATA_SUCCESS')
          })
          .catch(e => {
            console.log('err: ', e)
            dispatch('DATA_ERROR')
          })
        break
      default:
        break
    }
  }, [event, dispatch])

  return (
    <button
      onClick={() => dispatch('DATA_REQUESTED')}
      disabled={state === 'LOADING'}
    >
      load data
    </button>
  )
}

When calling the useMachine hook to set up our state machine we are passing an object with the following shape:

{
  <STATE>: {
    <EVENT>: <NEXT STATE>,
    [...]
  },
  [...]
}

It is therefore clear that in the example above, our button can be in only one of four states, 'IDLE', 'LOADING', 'SUCCESS' or 'ERROR'. With these deterministic states we can clearly describe our UI logic in a very declarative manner. For example disabling our button while loading is as simple as checking if our state value is equal to the string 'LOADING'.

When we dispatch events the reducer first checks what state we are in, then performs any change to state if it is allowed. We can perform any logic or side effects based on events as they are dispatched in our useEffect switch statement, which in the example is fetching some data.

Hopefully this post illustrated how this pattern can be used to clean up some of your code and prevent what should be impossible states in your components by explicitly declaring the transitions that are allowed.

If you came across any issue or have a question regarding this post, feel free to submit it here.

More on finite-state machines

Formal Forms with State Machines (Talk)

Robust React User Interfaces with Finite State Machines

A gentle introduction to React component composition

William Lindvall — Tue, 29 Oct 2019 00:00:00 +0000

Building front-end components using React provides developers with a great deal of flexibility in designing APIs that are highly reusable by exposing just the right amount of control to the user.

Learning React, it's easy to get into the habit of building components as "black boxes" and utilizing props as the way to pass data through your app. In this post I will explain an easy way to utilize props.children to make your components more reusable and avoid smells like "prop-drilling" and code duplication.

Below is some code from a simple React app that uses a NameTag component to render some text with a colored background.

// components/NameTag.js

import React from 'react'

const NameTag = ({name, bg}) => (
  <div style={{backgroundColor: bg}}>
    <p>My name is: {name}</p>
  </div>
)

export default NameTag

Note: If this syntax looks confusing to you I recommend checking out this page of the MDN web docs that explains destructuring assignment introduced and this article about arrow functions, both introduced in ES6.

// App.js

import React from 'react'
import NameTag from './components/NameTag'

const App = () => (
  <div>
    <NameTag name="William" bg="yellow" />
    <NameTag name="Greg" bg="pink" />
  </div>
)

export default App

Nice! Our NameTag component is reusable and neatly hides its slightly messier details of its implementation. Our app component looks super clean and easy to read. However, let's say wanted to add a title to this app with a similar colored background as our NameTag. Let's create a new Title component and render it in our app.

// components/Title.js

import React from 'react'

const Title = ({title, bg}) => (
  <div style={{backgroundColor: bg}}>
    <h1>{title}</h1>
  </div>
)

export default Title

// App.js

import React from 'react'
import NameTag from './components/NameTag'
import Title from './components/Title'

const App = () => (
  <div>
    <Title title="My app" bg="lightblue" />
    <NameTag name="William" bg="yellow" /> 
    <NameTag name="Greg" bg="pink" />
  </div>
)

export default App

It doesn't take long for us to spot some smells with our code at this point. Some of our code is now duplicated. What if there happened to be a bug in the way the background color had been implemented? The issue would have to be hunted down and fixed in various parts of the code. Let's see if we can refactor this app to make some more reusable components.

`props.children`

When you use your React component in JSX, any elements inside the component's opening and closing tags is passed to that component as props.children. This allows a component to utilize and manipulate the content that is rendered based on what is passed.

In our case, we simply want a component that wrap whatever we pass inside its tags with a container that has a colored background.

// components/Background.js

import React from 'react'

const Background = ({color, children}) => (
  <div style={{backgroundColor: color}}>{children}</div>
)

export default Background

// App.js

import React from 'react'
import NameTag from './components/NameTag'
import Background from './components/Background'

const App = () => (
  <div>
    <Background color="blue">
      <h1>My App</h1>
    </Background>

    <Background color="yellow">
      <NameTag name="William" />
    </Background>

    <Background color="pink">
      <NameTag name="Greg" />
    </Background>
  </div>
)

export default App

// components/NameTag.js

import React from 'react'

const NameTag = ({name}) => <p>My name is: {name}</p>

export default NameTag

"Prop-drilling"

Using children we can also avoid "prop-drilling" which is another code-smell that tends to show up when getting started with React. "Prop-drilling" is the act of passing data through several components with props, when these components don't actually have anything to do with the piece of data their passing along.

For example, in our earlier version of our app, NameTag was being passed bg as a prop while this not what the component was designed for; This prop was solely introduced to handle a particular use case. This often occurs when multiple components depend on the same piece of data, often leading to brittle code that is a pain to refactor.

Through utilizing what we've learned about children, we can now simplify our code by making our components more composable and provide a more flexible API to handle a larger variety of use-cases.

If you came across any issue or have a question regarding this post, feel free to submit it here.

Custom Events in JavaScript

William Lindvall — Mon, 28 Oct 2019 00:00:00 +0000

How did I miss this? No clue. Since I discovered this feature I have been playing around with its possibilities; most of all I love how easy it is to grasp and how effortlessly it allows us to clean up our often event-based code.

Not only are you limited to using events fired by the browser, such as 'click', 'submit', 'scroll', but you can use the native CustomEvent constructor to create your own events.

Example

Let's see this in action by refactoring a simple callback-based example to utilize custom events. This example has two main components, a chat and a notification area that displays some information about the latest chat message.

import Chat from './chat'
import ChatForm from './chat-form'
import Notifications from './notifications'

const chat = Chat('chat')

const notifications = Notifications('notifications')

const chatForm = ChatForm(
  'chat-form',
  message => {
    chat.append(message)
    notifications.notify(message)
  }
)

const ChatForm = (id, cb) => {
  const el = document.getElementById(id)
  const messageInput = el.querySelector('input')

  el.addEventListener('submit', e => {
    e.preventDefault()
    cb(messageInput.value)
    messageInput.value = ''
  })

  return el
}

Currently, we must pass a callback into the initialization of our chat in order that renders the new chat message and notification. This works great but let's see if we can create a more flexible API for our chat that allows us to listen to new messages.

First, let's create a new CustomEvent and emit new chat messages in the submit event handler of our chat form.

const ChatForm = id => {
  const el = document.getElementById(id)
  const messageInput = el.querySelector('input')

  const newMessageEvent = new CustomEvent('new-message', {
    detail: {text: () => messageInput.value},
  })

  el.addEventListener('submit', e => {
    e.preventDefault()
    el.dispatchEvent(newMessageEvent)
    messageInput.value = ''
  })

  return el
}

Now, we can add an event listener to our chat element that listens for 'new-message' events and reacts calls the appropriate methods on the chat and notifications instances.

import Chat from './chat'
import ChatForm from './chat-form'
import Notifications from './notifications'

const chat = Chat('chat')

const chatForm = ChatForm('chat-form')

const notifications = Notifications('notifications')

chatForm.addEventListener('new-message', e => {
  const message = e.detail.text()
  chat.append(message)
  notifications.notify(message)
})

Due to the event-driven nature of a majority of our frontend programming, this native feature is very easy to get used to and use to clean up certain parts of our codebase in particular situations.

Browser support

The CustomEvent constructor is available in all major browsers with the only exception being Internet Explorer. Nonetheless, this simple polyfill is available if you need it.

The code for a working example containing the final example above can be found here. If you came across any issue or have a question regarding this post, feel free to submit it here.

Obscuring the DOM: A11y of hiding things with CSS & HTML

William Lindvall — Sun, 25 Aug 2019 00:00:00 +0000

As a web developer, I can't think of a single project that I have worked on that didn't require some logic dealing with hiding or showing DOM elements. Be it as part of an accordion, some tabs, a simple toast notification or a modal, toggling DOM elements in and out of view is something I find myself implementing all the time.

While it may be tempting to reach for the approach that seems easiest, or perhaps most familiar (often display: none;), it is important to take into consideration the various ways that these decisions affect users of your website.

This article will provide a brief description of some of the most common approaches that I have come across, and explain the repercussions of using them.

Typically, there are 3 extents to which we could hide DOM elements:

Hidden for everyone
Hidden for screen users
Hidden for assistive technology (AT) users

Which of these options is most appropriate can only be evaluated on a case-by-case basis and will determine best implementation for you. By using an inappropriate technique, you may be excluding a significant portion of your user-base from accessing part(s) of your site.

1. Hidden for everyone

`display: none;`

By far the most common way of hiding an element for everyone is to set its CSS display property to none. This will hide the element visually and make it ignored by ATs. This technique will also remove the targeted element from the document's normal flow, meaning that it will not take up any space on the webpage.

.hidden {
  display: none;
}

`hidden`

The same effect can be achieved through the application of the HTML attribute hidden, which I also like to explicitly style to support legacy browsers.

[hidden] {
  display: none;
}

Both of these approaches are great, they are easy to read, short and behave as expected across browsers; however, if you wish to transition an element's styles while toggling in and out of view, display: none; will not work. A common approach to avoid this limitation is explicitly setting an element's max-width or max-height to be 0 along with overflow: hidden;. By providing an element no space to occupy, its contents will entirely collapse and be ignored by most screen-readers. To ensure the content is completely ignored by ATs, I like to combine this approach with visibility: hidden;.

.el {
  max-height: 999px;
  overflow: hidden;
  visibility: hidden;
  transition: 1s max-height ease;
}

.el--hidden {
  max-height: 0;
}

`visibility: hidden;`

If you are hiding something with the intent of showing it eventually, you may wish for the element to respect the space it takes up when visible. This can simply be achieved defining the CSS property visibility: hidden;. Note that this, again, hides the content both visually and to ATs.

.hidden {
  visibility: hidden;
}

2. Hidden for screen users

To clean up the visual UI but ensure elements are picked up by ATs , the most common technique is to move an element offscreen, or hide without width or height 0. There are a plethora of CSS snippets that will achieve this, most of which are variations of the example shown below.

.sr-only {
  clip: rect(1px 1px 1px 1px); /* IE 6/7 */
  clip: rect(1px, 1px, 1px, 1px);
  height: 1px;
  width: 1px;
  overflow: hidden;
  position: absolute;
  white-space: nowrap;
}

In the case that the target element is interactive, you will most likely want to be visible when focused. This can simply be achieved by modifying the selector to only target elements that are not active or focused (eg. .sr-only:not(:focus):not(:active)).

Alternatively, you can use the HTML ARIA attributes, such as aria-describedby or aria-labelledby, to force screen-readers to announce information related to a hidden element.

3. Hidden for assistive technology (AT) users

`aria-hidden`

In certain situations, you will find yourself using HTML elements for solely decorative purposes, for example icon fonts. In that case, you will want to ensure that these are not picked up by ATs. This can be done by simply setting the element's aria-hidden attribute to true.

Summary

To recap, we've gone over:

Hidden for everyone
- display: none or HTML hidden
- visibility: hidden; for transitioning elements
Hidden for screen users
- Move offscreen (and clip)
Hidden for assistive technology users
- aria-hidden

It is important to note that, as we are dealing with code that runs on many different browser engines, in different environments, based on a living specification, and will be interpreted by various assistive technologies, it is crucial that you test these approaches yourself. I like to keep this page, created by Terrill Thompson, bookmarked for this purpose. It implements these techniques (and several more), which you can use to easily try them out.

I hope that this post will encourage you to think twice before slapping a display: none; style on an element and be a bit more cautious of the accessibility implications of styling your site.

If you came across any issue or have a question regarding this post, feel free to submit it here.

Forem: William Lindvall

Simple and accessible dark theme using CSS variables and `prefers-color-scheme`

Easy CI with GitHub Actions

Getting started with finite-state machines in React

More on finite-state machines

A gentle introduction to React component composition

`props.children`

"Prop-drilling"

Further reading

Custom Events in JavaScript

Example

Browser support

Obscuring the DOM: A11y of hiding things with CSS & HTML

1. Hidden for everyone

`display: none;`

`hidden`

`visibility: hidden;`

2. Hidden for screen users

3. Hidden for assistive technology (AT) users

`aria-hidden`

Summary

Further reading: