Kyle Gach

Ensuring Web Accessibility of UI Components, from Quick to Thorough

2021-07-05T16:42:30+00:00

Let’s start with the thorough: the only way to completely ensure a UI component is accessible is to test it with a variety of users in a real context. That requires both a fully-coded component and, typically, a working app in which to test it. It also requires proper UX research and testing, finding a suitably comprehensive variety of participants, etc. That process can be very expensive, and the necessary changes found by such a process are costly, too.

By considering accessibility throughout the process of designing and building a component, you can avoid expensive changes later. Here are ways of thinking about accessibility as you make a component, ordered from quick (and cheap) to thorough (and expensive).

1. Style Native Elements

Web technology specifications and browsers have already done an enormous amount of work to make their native elements (button, select, table, etc) accessible. The quickest path to making accessible components is to leverage that work and build on top of what’s already available. For example, style a select element instead of building your own.

In addition to being quick and easy, it’s also the most appropriate path, as building on top of semantic HTML helps the variety of assistive technologies understand the structure and behavior of your component.

2. Use an Accessible Library

Another way to get started fast and build on the efforts of others is to base your component on a library that has already done the work to be accessible. For React, you could look at radix-ui or react-aria; for Vue, Chakra UI; for web components, generic or Lion; among many others for those technologies and more. Pick whichever library meets your needs, but be sure to check (using the steps below) that it’s actually accessible.

3. Make Your Own

If you cannot accomplish what you need with native elements and cannot find a library suitable for your needs, then you’ll need to make your own component. As you work, you can check each of the aspects below to help ensure what you’re building is accessible to all of your users.

A. Copy work from good resources

Instead of starting from scratch, look for proven patterns that you can copy and adapt for your needs. The WAI-ARIA Authoring Practices provides many patterns (which they call “widgets”) of common UI interactions, such as accordions, breadcrumbs, and tabs, written with simple HTML, CSS, and JavaScript. They’re an excellent reference if your component fits (or closely fits) one of the documented patterns.

You could also consider referencing the source code of an open source accessible library or finding other resources, such as this Complete Guide To Accessible Front-End Components or the A11y Project. The web accessibility community is open and generous with their expertise and learning, so before you start building anything, be sure to do some research to find prior solutions and discussions.

B. Start with native elements whenever possible

Even if you’re building your own component, doing so on top of native elements can save a lot of effort. For example, the WAI-ARIA Authoring Practices example for Tabs is built with button elements, which are automatically keyboard navigable, correctly accept “space” and “enter” key events, handle tap interactions, etc.

C. Adequate color contrast

While users of all abilities should be considered while designing and building for the web, probably the biggest portion of those with disabilities have impaired vision of some kind. Thus, you can have a big impact by making sure the colors you use have sufficient contrast between foreground and background. There are many tools you can use to ensure enough contrast, such as browser extensions (like Stark for Chrome) and native apps (like Contrast for Mac). Browser developer tools (Firefox, Chrome) are also getting better and better at exposing accessibility information like color contrast ratios.

One of the easiest ways to ensure good contrast ratios between colors is to use a color palette designed with accessibility in mind, such as Radix Colors.

D. Don’t rely on color alone

As you’re designing, make sure your component does not use color alone to signify a state change or communicate meaning, such as a status. For example, a table containing links to items with an associated status should not merely color the link text. One solution would be to add icons alongside the link text.

The table column on the left is inaccessible, because it uses color alone to communicate information about each item. The items on the right use color as well as an icon with a unique shape to communicate the same information.

E. Document flow is sensible

As you’re building, try to imagine how the document structure flows from one element to another. Do headings come before their associated content? If a control affects another part of the page, does that control come before whatever it affects? Does the visual order match the DOM order? As an extra step, turn off styles in your browser and check that your component still makes sense.

F. Interactive elements are keyboard navigable

If an element of your component is clickable, then users should be able to tab to it and activate it with the keyboard as well. The tab order is closely related to document flow and is very important. It can be checked with tools like Firefox’s Accessibility Inspector. Tab and focus management can be nuanced for complex components, and the WAI-ARIA Authoring Practices can be a particularly helpful reference for knowing how something should function to match most user’s expectations.

G. Most elements should have an accessible name

You can use browser dev tools (Firefox, Chrome) to check the accessible name of the elements in your component. Before pulling up a tool, though, look at your component and try to identify all of the information that is conveyed visually. Then make sure that that information is also conveyed non-visually (for example, that an image displaying an icon has an alt attribute describing that icon’s meaning).

Firefox’s Accessibility Inspector is showing that the second input has no accessible name, because it is not correctly associated with the label.

H. Zooming doesn’t break the design

Using in-browser commands, zoom your component in to 200% and out to 50%. Is it still usable? This will usually surface aspects of your component with fixed dimensions, which should generally be avoided.

If you’ve used non-relative units in your styles (like px), then you’ll need to also confirm that changing the browser’s zoom level in preferences doesn’t adversely affect your component.

4. Check with Tools

As you’re building, and especially once you have a usable version of your component, there are many tools available to audit your work for accessibility issues and suggest fixes. One of the most popular is axe, which is available as a browser extension and built into Chrome dev tools and Lighthouse.

If you’re building your component in Storybook, axe is built into the a11y addon, to provide automatic audits as you work. You can also often integrate these audits into your continuous integration (CI) pipeline (for example, lighthouse-ci), preventing components from releasing with known accessibility problems.

Other tools you can use are assistive technologies (AT) themselves, such as screen readers like VoiceOver for Mac or NVDA for Windows. While there’s certainly a learning curve to using these tools, they will surface issues that cannot be found with automated checks and will help you empathize with how users of AT will understand and interact with your component.

5. Check with Users

There is no substitute for testing the actual component, in an actual product, with real people, with a variety of capabilities and impairments. User testing will help you discover aspects of your component not covered by the above steps or not even considered in your design. As designers and developers, it can be difficult to think of our work in the way that our users experience it. User testing can help break down these barriers to understanding. By using the above steps to make your component as accessible as you can before testing, you enable those testers to provide valuable feedback that might otherwise be lost in the noise of other issues.

A Helpful Baseline (Measuring Site Quality with Lighthouse CI)

2020-08-28T15:05:30+00:00

There is much to improve about this site. (If you’re reading this close to the publish date, that will be obvious, as you view the nearly naked prose and utter lack of design.) But making improvements without measuring the impact of the changes can risk making it worse. So, before I do any more work, I need a baseline from which to measure my changes against.

Lighthouse is a helpful tool to audit a website in five main criteria: performance, accessibility, best practices, SEO, and progressive web app (PWA). Those align nicely with my goals for the site, making it an ideal fit for my needs. Lighthouse also does something quite neat and very much in line with the “learn, then teach” spirit of this site. Reporting the audit successes & failures would be useful on its own, but the Lighthouse team went much further and provide the why behind each check, many with a “learn more” link. This greatly shortens the path from “oh no, not good” to “I learned a thing!”.

There are many ways to run Lighthouse. The easiest is probably using the built-in Audits panel of Chrome’s DevTools. That’s fine for a manual workflow, but I want to automate the audits, to ensure they run against every change to the site and surface the results well. For that, I’ll use Lighthouse CI, which I can run within my GitHub Workflow. Doing so is fairly straightforward:

Add Lighthouse step to workflow (commit)

Though it’s all in one commit, this contains multiple tasks.
1. Change the Deploy step to always build a deploy preview, which can then be audited
2. Add the Lighthouse step (following Lighthouse CI’s instructions), using the preview link from the previous step
3. Add some basic Lighthouse configuration
  1. Add recommended assertions (using the “no-pwa” variety until I can begin address those criteria)
  2. Publish reports to a temporary, public location (for free!)
4. Add a second deploy step (really, move the previous one) that conditionally deploys a preview or the production site, upon success of the prior steps
5. Refactor the Create Deploy Message step, to build up slightly different messages for each deploy step
Turn off failing assertions (commit)

While I haven’t done anything to intentionally make the performance or accessibility of this site worse (to then improve in a helpful blog post), I haven’t done anything extra to improve those things either. Thus, the recommended assertions return [four failed checks]. For now, I’ll disable those checks to get a passing audit, and will address each of them as my very next tasks.

Now whenever I push a change to the site, a Lighthouse run is kicked off as part of my CI/CD workflow, and the results are published as both a status check (if pushing to a branch with a pull request) and a detailed report (not that exact report, as the generated one is only hosted temporarily; that link is from a manual audit using https://web.dev/measure/, and if it continues to work, it will probably not reflect the state of the site when this post was published).

Most importantly, I can now continue to improve the site knowing that my changes are truly having a positive impact on the things I care about.

Follow-up

I’m happy with this initial implementation, but there are aspects to improve.

Only run the second deploy step if pushing to master (in other words, if deploying to production) to avoid creating a duplicate deploy preview. GitHub workflows cannot have conditional steps, only conditional jobs. So I’d first have to split the steps into various jobs, and that would require passing data between jobs unless I duplicate a lot of the steps and logic.
After splitting steps into different jobs, the Lighthouse job could be conditional, allowing it to be skipped — for example, by adding “[skipLighthouse]” to a commit message—which would be nice for writing only updates (like publishing this post).
Publish reports to a more permanent location, using Lighthouse CI Server.
Tweak assertions, perhaps making use of a performance budget.

Helpful Deploy Messages

2020-05-27T17:50:10+00:00

How to make deploy messages much more useful when building & deploying with GitHub Actions.

To recap the previous post, this site is now built with GitHub Actions and (still) deployed by Netlify. When I was building in Netlify, each deploy had a helpful label that included (1) the branch being built, (2) the sha (a unique id for a commit) of the latest commit, and (3) the message of that commit. If I were to ever somehow deploy a bad build of the site, having well-labeled deploys makes it super easy to roll back to a working build (yet another benefit of a static site). Unlabeled deploys? Not so much. And I lost those helpful labels with my move to building on GitHub. The Netlify CLI (which I am using indirectly, via the Netlify Actions action) accepts a message option, and it seemed like I had access to each of the three pieces of information I needed, so I should be able to recreate the experience I want. Let’s find out!

TL;DR

It works! Here’s the relevant workflow code (full source). Place these as steps in your job:

Note — The code below worked well for my needs at the time of publishing this post. If you keep reading, you’ll realize, as I did, that because GitHub Actions is still in beta, the tool and the various resources created by the community can become outdated quickly. Please cross-reference what you see here with GitHub’s documentation.

- name: Checkout
  uses: actions/checkout@v2
  with:
    # Necessary to grab the HEAD commit from the source branch when
    # acting on a PR. Otherwise, `git log` will only contain the merge commit
    ref: ${{ github.event.pull_request.head.sha }}

- name: Create Deploy Message
  run: |
    # Grab the branch path from the appropriate (PR vs. push) property on context
    FULL_PATH_REF="${{ github.event.pull_request.head.ref || github.ref }}"
    # Strip "refs/heads/" from the start
    REF=${FULL_PATH_REF#refs\/heads\/}
    # Get the short form of the SHA
    SHA=$(git rev-parse --short ${{ github.event.pull_request.head.sha || github.sha }})
    # Yank the commit message from the log, using the SHA
    COMMIT_MSG=$(git log -n 1 --format=%s $SHA)
    # Create the deploy message
    DEPLOY_MESSAGE="$REF@$SHA: $COMMIT_MSG (${{ github.workflow }} workflow)"
    # Set it in env
    echo "::set-env name=DEPLOY_MESSAGE::$DEPLOY_MESSAGE"

# Build the site (omitted for brevity)...

# Deploy either preview or production
- name: Deploy
  uses: nwtgck/actions-netlify@v1.1.0
  with:
    # Pass the message
    deploy-message: ${{ env.DEPLOY_MESSAGE }}
    # more options...

The Goal

I want to construct a message with a structure like this:

<branch-name>@<sha>: <commit-message> (<workflow-name> workflow)

Part 0: GitHub Workflow Overview

Workflows are divided into “jobs” (currently, my workflow only has one job, build-and-deploy), and those jobs are further divided into “steps”. Each step has a few properties, and the one most relevant for this post is run, which operates as a shell. I’m using the default workflow shell, bash.

Workflows also evaluate expressions, like referencing a variable, using this syntax: ${{ expression }}, which I’ll use a lot here.

Part 1: Branch Name

In git terms, a branch is nothing more than a pointer to a specific commit, and that commit is known as the ref. Thankfully, GitHub provides the github context for use within workflows, which includes the ref. This workflow runs when either of these “events” occur (1) pushing to the master branch or (2) submitting or updating a pull requst (PR) against the master branch. Operating on two different event types presents the first challenge. I want to avoid running different code for different events, but each event type stores information in the github context differently. By using short-circuit evaluation, I can reference the appropriate context property:

# Grab the branch path from the appropriate (PR vs. push) property on context
FULL_PATH_REF="${{ github.event.pull_request.head.ref || github.ref }}"

github.event.pull_request.head.ref stores the branch name like "branch-name", but github.ref stores it with the pull path: "refs/heads/branch-name". As there’s no harm in attempting to replace something that can’t be found, I can run this code, using parameter expansion, on both cases to produce the non-pathed branch name:

# Strip "refs/heads/" from the start
REF=${FULL_PATH_REF#refs\/heads\/}

Part 2: SHA

Looking over the shape of the github context, this one seemed easy: there’s a github.sha property directly available in both events. Two reasons this isn’t so simple.

First, I’m interested in the latest commit that was built. github.sha is associated with that commit only for the push event. For PR events, github.sha points to the merge commit in the temporary branch GitHub creates (see workflow docs). Instead, similar to Part 1, I need to look at the github.event.pull_request.head.sha property, which does point to the commit of interest.

Second, both of those properties store the full sha (for example, 3b34510197cde6e3a53525d64415832f7ba34ab8), but I want the shortened, 8 character form: 3b345101. After some searching, I found the rev-parse git command to do the trick.

Putting those concerns together, and executing with a bit of command substitution:

# Get the short form of the SHA
SHA=$(git rev-parse --short ${{ github.event.pull_request.head.sha || github.sha }})

Part 3: Commit Message

git log will output a reverse-chronological list of commits on the current branch. And, as I found after some searching, git log -n 1 will output the nth most-recent commit(s)—in this case, 1. Finally, the --format=%s argument will restrict output to only the subject (the first line of the message) for the commit. Putting it all together:

# Yank the commit message from the log, using the SHA
COMMIT_MSG=$(git log -n 1 --format=%s $SHA)

This works great for push events. But reminder how, in Part 2, I learned that PR events’ github.sha pointed to a merge commit in the temporary merge branch? That’s because the Checkout Action checks out that merge branch when acting on a PR event. I can pass a ref to the action to check out the code at that commit instead, and I already have the ref that points to the relevant branch from Part 2: github.event.pull_request.head.sha. So, modifying the workflow with this in mind, I can get the commit message of interest:

- name: Checkout
  uses: actions/checkout@v2
  with:
    # Necessary to grab the HEAD commit from the source branch when
    # acting on a PR. Otherwise, `git log` will only contain the merge commit
    ref: ${{ github.event.pull_request.head.sha }}

- name: Create Deploy Message
  run: |
    # Grab the branch path from the appropriate (PR vs. push) property on context
    FULL_PATH_REF="${{ github.event.pull_request.head.ref || github.ref }}"
    # Strip "refs/heads/" from the start
    REF=${FULL_PATH_REF#refs\/heads\/}
    # Get the short form of the SHA
    SHA=$(git rev-parse --short ${{ github.event.pull_request.head.sha || github.sha }})
    # Yank the commit message from the log, using the SHA
    COMMIT_MSG=$(git log -n 1 --format=%s $SHA)


# Build the site (omitted for brevity)...

# Deploy (omitted for brevity)...

Part 4: Deploy Message

All of the pieces of the message are now ready to construct the whole. I’ve been assigning each value to a variable, e.g. REF, which I can reference here like $REF.

# Create the deploy message
DEPLOY_MESSAGE="$REF@$SHA: $COMMIT_MSG (${{ github.workflow }} workflow)"

Now that I have the message, I need to make it available to the deploy step. For that, I can graduate the DEPLOY_MESSAGE variable to an environment variable, using set-env:

# Set it in env
echo "::set-env name=DEPLOY_MESSAGE::$DEPLOY_MESSAGE"

In the deploy step, I can reference that environment variable with ${{ env.DEPLOY_MESSAGE }}.

Part 5: All Together

Here’s the workflow with each part integrated:

- name: Checkout
  uses: actions/checkout@v2
  with:
    # Necessary to grab the HEAD commit from the source branch when
    # acting on a PR. Otherwise, `git log` will only contain the merge commit
    ref: ${{ github.event.pull_request.head.sha }}

- name: Create Deploy Message
  run: |
    # Grab the branch path from the appropriate (PR vs. push) property on context
    FULL_PATH_REF="${{ github.event.pull_request.head.ref || github.ref }}"
    # Strip "refs/heads/" from the start
    REF=${FULL_PATH_REF#refs\/heads\/}
    # Get the short form of the SHA
    SHA=$(git rev-parse --short ${{ github.event.pull_request.head.sha || github.sha }})
    # Yank the commit message from the log, using the SHA
    COMMIT_MSG=$(git log -n 1 --format=%s $SHA)
    # Create the deploy message
    DEPLOY_MESSAGE="$REF@$SHA: $COMMIT_MSG (${{ github.workflow }} workflow)"
    # Set it in env
    echo "::set-env name=DEPLOY_MESSAGE::$DEPLOY_MESSAGE"

# Build the site (omitted for brevity)...

# Deploy either preview or production
- name: Deploy
  uses: nwtgck/actions-netlify@v1.1.0
  with:
    # Pass the message
    deploy-message: ${{ env.DEPLOY_MESSAGE }}
    # more options...

The full source of the workflow file is also available, if you find that helpful.

Conclusion

To maximize clarity, I kept the narrative of this post straightforward, but the reality of developing the code shared here was not straightforward at all. The beta nature of GitHub Actions means that many aspects, like the github context and the Checkout Action, are still actively changing. That can make it difficult and confusing to try to learn from community resources like blog posts, which can often describe or prescribe outdated details. Even the official support forum suffers from this issue, and I went through many trial-and-error cycles discovering what still works and what does not. Ultimately, I was best served relying on the official documentation as much as possible, and always double-checking any community-provided content against it.

Building & Deploying with GitHub Actions

2020-05-19T16:27:10+00:00

In The Work Before the Work, I set up automatic deploys with Netlify. But I have plans to automate much more than deploys.

One of the useful benefits of a static site (a website that is only static files and doesn’t require a backing server or database) is that it can be built and deployed just about anywhere, and those locations can be different. Netlify provides an amazingly simple publishing experience, using continuous integration and continuous deployment (CI/CD): push or merge to master and my site is automatically built (CI) and deployed (CD). But I wanted to extend beyond that simplicity for a few reasons. First, I want my CI pipeline to include more than just building the site. Eventually, I want to continuously audit for accessibility, performance, and other factors in the usability and quality of what I’m publishing. Second, I’ve been itching to play with GitHub Actions. Third, Netlify’s generous free plan, available for open source projects, has a limit of 300 “build minutes”/month. That’s likely fine for right now (building and deploying only takes ~0.5 build minutes right now), but the additional CI work will start consuming a lot more.

I drew up a plan for where I want to go:

Flow diagram of the planned CI/CD flow for the site. Made with the rather excellent Excalidraw.

First, we’re just going to tackle the build and deploy steps:

Simplified flow diagram highlighting the steps of the planned CI/CD flow I'll be implementing in this post.

That diagram illustrates that upon pushing changes (to a branch with an associated pull request or to master), the site will be built and then either deployed to a preview (if a push to a pull request) or production (if a push to master). If a step fails at any point, the flow stops. Finally, either the successful deploy or failure is communicated via a comment on the pull request or commit.

Before doing anything else, I need to disable automatic deploys. Going forward, I only want to deploy the site (or a preview) when it’s gone through all of those green checkmarks in the flow diagram. In Netlify, this is as easy as toggling a “stop builds” switch in my site settings.

Next, I create a GitHub workflow, starting from the blank starter. First, I add a step to install dependencies and then build the site. Then I search the GitHub Actions Marketplace for “netlify” and find Netlify Actions, which will make it simple to deploy the site (or a preview). Following the guidance on the README, I configure the action with my options and secrets.

Finally, I create a pull request to test it. The workflow kicks off as soon as I submit, and 30 seconds later I have a deploy preview available from Netlify:

The bottom deploy was built by Netlify; the top was built by the GitHub workflow. Note how the bottom entry contains useful information like the relevant branch, the SHA of the commit deployed, and the commit message.

That’s good enough for a starting point, but the information in the prior deploy entries is really useful, and I’d like to include it in my deploy message, to make future troubleshooting easier. To be continued…

RSS

2020-05-12T21:11:10+00:00

Embarrassingly, despite being subscribed to hundreds of RSS feeds personally, this site has never published one. Until now!

There were three tasks:

Generate the feed (commit)

11ty provides an easy-to-use RSS plugin that does the bulk of the work for me. I only had to decide which content to include: all of /writing/. I made one additional update: I created a new collection from which to generate the feed that is limited to the most recent 20 items in /writing/. I’ve heard stories about people with large static sites having their build times slow to a crawl because their feed generation was crawling hundreds of posts and creating an enormous file. RSS readers generally limit a feed to the most recent 10 posts or those published in the last 30 days. A limit of 20 should be well within those boundaries for the way I plan to use this site.
Add a page layout (commit)

In a misguided attempt at content portability, I had included each post’s title in the post content itself, which resulted in the title being displayed twice in a feed reader. For now, the page layout merely extends the base layout and displays the page’s title, but I can imagine many more eventual features, mostly regarding the display of metadata.
Add link tags to the head, for auto-discovery (commit)

Following the guidance of the WHATWG, I added the appropriate links to the site’s head, in the base layout. This will help browsers, feed readers, and other services discover my feed.

After publishing those updates, I searched for the site’s name in Feedly (my current feed reader) and subscribed. Seeing something I made displayed in a tool I’ve used every day for over a decade brought a big smile to my face.

The Work Before the Work

2020-05-07T22:58:10+00:00

I plan to record just about every bit of work that goes into this site. But first, I had to do a bit of work to make that possible.

Create the repo on GitHub, cloned it to my machine, and initialized the project (yarn init) (commit)
Add 11ty with minimal content and configuration (commit)
- So simple to get started!
Migrate (some) old content (commit)
- The migration itself was as simple as copy/pasting and updating some frontmatter because all of my content, old and new, is written in Markdown.
  - I could use an intermediate template to translate from the old frontmatter properties to the new ones expected by 11ty, but with only three migrated posts, that seems like overkill.
- Now that I have more than just a home page, I need to create a basic template to display content.
- I also need to ensure that media like images display correctly. Keeping all images in a single directory will make any future migrations go more smoothly and enables a more straightforward path to setting up a CMS later.
- Finally, I need to add a collection to display a list of all posts on the Writing page.
Add content to the home page, re: redesign (commit)
Set up continuous deployment on Netlify
- Now I can push to my master branch and the site will automatically build and, if successful, deploy.
Archive full previous version of the site at v1.kylegach.com
- I want to keep the old version around for posterity.
- I chose to not migrate some content; this provides a location to which I can redirect those requests.
Add minimal styles (system font, max-width for content) (deploy, commit)
- There’s a lot I want to have in place before I touch styles, but a limitless line length is difficult to read and must be addressed.
Add task list support for Markdown, so that I could, well, use task lists in markdown (commit)
- Also enable some handy markdown options to improve typography a bit with automatic smart quotes
Publish V2 Rebuild & Redesign, the first post on the new site ✨ (deploy, commit)
List V2-related posts on the home page (deploy, commit)
- Until I have better content, it seems wise to simply list all posts tagged ‘v2’.
- Which means I have to add tags to posts and add another collection to collect the ‘v2’ ones.
Publish V2 Goals (and update V2 Rebuild & Redesign) (deploy, commit)
- Revise the first post only to record work and pull out then expand the rest of what was there into a new one.
Add redirects for old content that was not migrated (commit)
- Cool URIs don’t change.
- I tried to do this through Netlify’s redirects feature, because it’s better to redirect on the server than on the client, but ran into a snag due to how I archived the old site (also on Netlify). I’ll revisit this.
Add site header with banner and update home page (deploy, commit)
- If people land on the site from a page that isn’t home, I’d like them to understand the redesign going on.
- Also, previously, only the home page displayed the site name. Oops.

So, now I have a workflow that allows me to publish posts and deploy changes with ease, and a simple foundation on which to build. Going forward, I’ll try not to dump these big lists of work, but I needed to get these essential tasks done as quickly as possible to preserve content and enable future updates.

V2 Goals

2020-05-06T20:55:10+00:00

Why rebuild and redesign? On an entirely new stack? In the open?

I had a lot of fun building the first version of this site. In my first post, I wrote about some of the goals I set out to achieve. Those still stand true for this version—learn some tools, get better about accessibility (a11y), and share what I learn—but there was one goal I kept to myself: I built the site to get a job. More specifically, I built the site in React to get a job writing React. I’m thrilled to say that it worked, remarkably well. As a UX engineer focused on design systems, I now write React code nearly every day for my career, and it’s been a good career, indeed.

So why am I tearing it all down and starting over? There are several forces in play.

I gleefully followed along as many designers and developers redesigned their sites in the open. And a number of others released thoughtful, gorgeous redesigns of their own. It looked like fun. It made me remember my own neglected home on the web, which I hadn’t touched in nearly four years. It made me want to tinker. To write. So I fired up my text editor, made some tweaks, and… couldn’t publish. The combination of the relatively complex tech stack I had taken on and years of not touching that stack was too much. I couldn’t get my site to build, and I didn’t want to fix it only to find myself in the same situation down the road. I needed to simplify.

I’m sure you’ve noticed, the whole web needs to simplify. My site, little more than a blog and portfolio, didn’t need React; it didn’t even really need JavaScript. I want my home on the web to reflect my values^{(citation needed)}, and a 721kb bundle of JS to serve text and some animated SVGs was not abiding by those values. Specifically, I have a growing appreciation for the access part of accessibility. The web is for everyone, and we should be tearing down any and all barriers that unnecessarily prevent or impede anyone from accessing what we build. That belief has only been strengthened by stories of people not being able to access the resources they need the most right now.

Thankfully, a lot’s changed in the last four years. Service workers! Web Components! Jamstack! Indie Web! CSS Grid! There’s a bunch of stuff I plan to learn and integrate. And, most notably for this effort, there’s 11ty. I plan to write more about why I chose 11ty, but the primary motivation is simple: in the last month or so, they’ve started publishing a leaderboard focused on performance and a11y. And look at those scores! It was immediately apparent that something about the tool either made those things easy, encouraged caring about them, or both. It was also clear that people who care about those things liked the tool, a lot. It would be fun to appear on that leaderboard one day, but mostly I just want to align myself and my site with the values demonstrated there.

So, goals for my site this time around:

Focus on accessibility and performance

Every feature I add, every word I write will be done with an eye toward maintaining an open, fast, inclusive web.
Learn and tinker

I did great with the “learn” part last time; this time, I want to tinker, too. It’s a much better outlet than mindlessly scrolling through Twitter and Instagram for the swings of boredom and nervous energy I’ve been feeling lately.
Set a lasting foundation

My tinkering will be in the direction of continual evolution. I don’t want to have to start from scratch again.
Write more

I write every day for my job. Code, yes, but also the outline of thoughts, that leads to an email to my peers, that leads to a proposal, that leads to the code. And pull request reviews. So many reviews. A newsletter, more emails, various chat messages. Suffice it to say, it can only help my career to get better at writing. If I can muster the vulnerability to write about non-technical things, it might help in other ways. I also plan to continue sharing what I’m learning, to pay it forward for the innumerable articles, blog posts, podcasts, and conversations from which I’ve benefitted.

These words from when I kicked off this site still ring true today:

It’s empowering to have a place of your own, viewable to all, where every aspect is exactly as you want it. Or, at least, as close as you can get it within your knowledge and skill set… I’m eager to find more ways to express and practice building my ideal web with design, code, and prose, and I’m delighted to finally have a place to do so.

V2 Rebuild & Redesign

2020-05-05T21:54:10+00:00

In an effort to share openly, this post will track and record the work done for the site. Read more about why I’m rebuilding and the goals I have for this project.

Tasks

Continuously updated.

Content

11ty

Initialize (post)
Add task list support to markdown (post)
RSS
- https://www.11ty.dev/docs/plugins/rss/
Syntax highlighting
- https://www.11ty.dev/docs/plugins/syntaxhighlight/
- Matches color mode?

Tooling

Features

Design

Basic starting styles (post)
Tailwind?

Everything I Did to Make This Site Fast, Part 1

2016-04-30T22:08:10+00:00

The web is best when it’s fast. A fast web doesn’t just provide a good experience, though that’s certainly important, it also ensures as many people as possible can access it at all. Many people are on slow, unstable connections. By making a site fast, you make it more likely for them to be able to use it.

Some things I already did

I purposefully did not do many of the tasks below until I was able to write this post, because I wanted to measure the impact of each change and be able to explain each step. However, some things that help the performance of this site would’ve been too time-consuming to build “the slow way” first only to completely change them to make them faster later. For example:

This site is static, meaning that all of the pages are pre-rendered on the server and then served directly. Most websites have many back-and-forth requests with a server before presenting a page; this one does not, which speeds things up considerably. Serving static content typically saves ~500ms of loading time.
I’m using a webfont for the headings, but the body text uses a font stack that leverages the viewer’s system’s default font, which does not need to be loaded from the server.
The animations are built with SVG and driven by a ~40 Kb JS library. It would’ve been easier to just include them as gifs or videos, but that would’ve had much larger download costs.

Please see the Colophon for more details.

Snapshot before any improvements

Before I do anything, let‘s get a snapshot of the current state of the site, to serve as a baseline. I‘m going to use the excellent WebPageTest and PageSpeed Insights for this.

Note: For all of the WebPageTest snapshots, I‘m testing the homepage of the site, three times, on a Motorola G in Chrome with a ‘3G - slow’ connection. The PageSpeed Insight snapshots are ran once, on the homepage.

Summary of initial snapshot. Full results.
Metric	First View	Repeat View
PageSpeed (Mobile)	68/100
PageSpeed (Desktop)	71/100
Speed Index (Mobile)	2025	511
Load Time (Mobile)	8.666s	2.864s

While developing on my home’s broadband connection, I thought the site felt fairly zippy, but these baseline results make it clear that there’s plenty of room for improvement. Here’s a breakdown of the content being loaded:

Content Type	Requests
css	1
flash	0
font	1
html	1
image	3
js	2
other	0

First view content breakdown, by requests.

Content Type	Bytes
css	6454
flash	0
font	19974
html	7901
image	402108
js	196044
other	0

First view content breakdown, by bytes.

Typically, the first step in improving web performance is reducing the number of requests. For this relatively simple site, that number is already pretty low. There’s only one image on the page; the other two image requests are tiny and from Google Analytics. The JavaScript is all combined into one bundle except for the Google Analytics package, which is loaded asynchronously. I could embed the font file within the CSS, using base64 encoding, but, as we’ll see later, that would make things worse in other ways.

The next typical step is reducing the size of requests. That definitely applies here, so let’s dig in.

Reducing the size of images

Before this exercise, the avatar image on the home page was a 639px × 639px, 392 Kb PNG. It has a fixed-width of 150px in the design, so I resized to 300px × 300px^[The dimensions are doubled to account for retina screens.], and optimized it while converting to JPEG, which brought it down to 70 Kb.

But I can do more. Not every screen is retina, so I need to serve the smaller, non-retina version by default, then use srcset to serve the retina version to screens that need it:

<img src="/avatar.jpg" srcset="/avatar@2x.jpg 2x" alt="Profile picture of Kyle" />

And the result:

Summary of snapshot after optimizing images. Full results.
Metric	First View	Repeat View
PageSpeed (Mobile)	90/100 (+22)
PageSpeed (Desktop)	96/100 (+25)
Speed Index (Mobile)	2056 (+1.5%)	498 (-2.5%)
Load Time (Mobile)	8.666s (-16.2%)	2.864s (+1.01%)

I’m not sure why the speed index on the first view and load time on the repeat view both went up slightly, but it’s such a small change that I’m not too concerned. Those oddities aside, this simple optimization resulted in big, easy speed wins.

And here’s the new breakdown:

Content Type	Bytes
css	6583
flash	0
font	19974
html	7920
image	70060
js	195757
other	0

First view content breakdown after optimizing images, by bytes.

Performance commit #1

Note: Even though I’m only testing the homepage, I went ahead and did this exercise for all images on the site.

Reducing the size of JavaScript and other resources

190 Kb of JavaScript is quite a lot, especially since that size is after gzipping. For now, though, I’m going to leave it be, as I would like to see how fast I can make this site while it still runs React client-side. I suspect that I’ll need to remove React to meet my informal goal of a speed index under 1000, but I’ll save that for last.

My CSS is only 6.5 Kb (gzipped). At that size, that’s too small to justify the effort to make it any smaller^[You should always endeavor to keep your CSS as small and simple as you reasonably can. The effort I’m avoiding here is because my styles are already architected in a way to keep them very small. Any further optimization will require either a lot of manual fine-tuning that could break future updates or an automated process using something like PurifyCSS. I intend to implement the latter in a future post.]. There are other reasons being the filesize to make CSS as small as possible, which I’ll cover later in this post.

Absolute vs. perceived performance

So far, I’ve only made changes that affected the page load time/size, which correlates to the absolute page speed. But that’s not all that matters. Arguably, perceived performance matters even more, as that affects how fast your site feels.

For example, check out this filmstrip view of a portion of the experience waiting for the site to load on 3G:

There’s a full 1.5 seconds between the initial content displaying and the webfont displaying. Worse, because I reference the webfont directly in CSS, via @font-face, there’s a FOIT making the headings completely unreadable until the webfont has finished loading. This is unacceptable.

Preventing a Flash of Invisible Text (FOIT)

I’m going to use FontFaceObserver to instead only apply the webfont to headings after it is loaded. While it is loading, they’ll use the same font stack as the body text, changing the FOIT into a FOUT. In some scenarios, this can provide a poor experience just like a FOIT, but I have a couple things going for me:

The body text is set in a font that doesn’t have to load at all, meaning it will display correctly immediately. So when the headings also use that font while the web font loads, they’ll match the rest of the site.
The webfont I’ve chosen for the headings, League Spartan, has a very similar baseline & caps height, so shifts after the webfont loads are minimal.

After making the change, the filmstrip now looks like:

Much better! You can see how the headings now display for a brief moment using the same font as the rest of the text, and then switch to the webfont after it has finished loading.

Performance commit #2

Clearing the critical path

What you can’t see in the filmstrips above is all that time before anything is visible:

Part of that is because it must download the full CSS file before it displays anything. In other words, the CSS is blocking the critical path, which happens regardless of the file’s size. So even though the size is fairly small, it has an outsized effect on the perceived performance of the site.

I’ll cover my approach for solving that issue (and possibly removing React on the client-side) in a future post.

Everything I Did to Make This Site Accessible

2016-04-16T04:54:54+00:00

I believe the web is meant to be open and available to everyone, no matter who they are, what device/software they’re using, or the speed/quality of the network they’re on.

Accessibility (also known as a11y) is so much bigger than just making things work for people with no or low vision. But, even if you define it so narrowly, that’s still 285 million people or ~5% of the world’s population. What follows is a collection of everything I’ve done to make this site as accessible as I could.

Note: I‘m using The A11y Project‘s helpful checklist as a rough starting point for this post.

Not relying on JavaScript (Progressive Enhancement)

This site is built using React, a JS library. But, it renders everything from the server before all that JS does anything. The JS then progressively enhances the site to enable things like super-fast additional page loads and the SVG animations. This means that the site will be accessible even if the JS were to fail for any reason. You may think the numbers for that are small… like, 1%. Keep in mind that it’s not 1% of people who always encounter a broken site, and 99% of people who don’t. It’s 1% of visits. I stole that line from this wonderful illustration of the phenomenon.

Also, progressive enhancement makes supporting older browsers so much easier. Because the site will always work without JS, you can cut the mustard so that your JS only runs on your supported browsers. Meaning you don’t ever have to write JS to work in non-modern browsers.

Making it responsive

The only reasonable way I know of to ensure a website is usable on any device/software is Responsive Web Design.

Writing semantic HTML

The easiest way to make something accessible is when you get it for free. By using <header>, <footer>, <nav>, <button>, and other elements appropriately, you build accessibility into the very structure of your app. This includes using <h1>, <h2>, etc… in a sensible order. I reviewed this site’s code and found some areas I could improve.

A11y commit #1

Supplanting semantic HTML with `aria` landmark roles

While most browsers automatically associate, say, <main> with aria-role="main", not all do. So it’s best to go ahead and define those yourself.

A11y commit #2

Focus states

A lot of sites have some CSS like this to remove the default dotted outline when elements are focused in some browsers:

a:focus {
  outline: none;
}

Don‘t do that! If you absolutely must remove it, you also must define your own focus styles.

Use alt text (and the equivalent for SVG)

Any image in the content of a site must have an appropriate alt attribute defined. The only exception is images that are purely decorative.

For SVGs, you can use the <title> and <desc> elements to describe the graphic in combination with aria attributes. See the commit for examples.

A11y commit #3

Test for sufficient color contrast and color blindness

Researchers have determined a minimum threshold for foreground/background color contrast that is readable by most people, which is specified as part of WCAG. You can use a tool like aXe, which integrates into Chrome‘s Dev Tools, or tota11y, which can be integrated into your site or used as a bookmarklet, to check if the text of your site meets this threshold. There are some gotchas, though:

It will only test actual text and backgrounds, not text that is part of or on top of an image.
It cannot determine the contrast of pseudo-elements (::before & ::after)

After running checks, if I find any colors that need changed, I like to use Colorable to find values with sufficient contrast.

A11y commit #4 & A11y commit #5

Consider a “Skip to content” link

Sometimes a site can have a lot of stuff that a person using a screenreader or restricted to a keyboard would have to wade through before they get to the content. Including a link to skip down to the content in the very beginning of your page that is visually hidden until focused is a nice way to help them out.

This site has a very minimal header and the primary navigation is at the bottom of the page, so the link I‘m adding will be “Skip to navigation”.

A11y commit #6 & A11y commit #7

Make sure to use descriptive links

Consider the post teasers on my Writing page. They have a title, a brief excerpt of the post, and a Keep Reading… link. Sighted users can see that the “Keep Reading…” belongs to the post above it, but screen readers have no way of relaying that information to their users. That is, not without a little help.

We can use aria attributes again to add a more descriptive label to those links:

<article role="article">
  <h3 id="everything-i-did-to-make-this-site-accessible"><a href="/writing/everything-i-did-to-make-this-site-accessible/">Everything I Did to Make This Site Accessible</a></h3>
  <em><span title="April 12, 2016">3 days ago</span></em>
  <div>I believe the web is meant to be open and available to everyone, no matter who they are, what device/software...</div>
  <a href="/writing/everything-i-did-to-make-this-site-accessible/" aria-labelledby="everything-i-did-to-make-this-site-accessible">Keep reading…</a>
</article>

Thanks to this CodePen by Gray Ghost Visuals for the technique.

You should also generally avoid using generic phrases like “Click here” for your links, because they provide very little context.

A11y commit #8

Test, test, test

After you’ve done everything you can, you should test your site using assistive technology tools. Ideally, you‘d do so with someone who uses such tools on a regular basis, but you can simply use the tools yourself in a pinch. If you‘re on a Mac, you have VoiceOver built in.

Of the Web

2016-04-12T14:01:34+00:00

I’ve been on the web for most of my life, but, without a site to call home, I haven’t been of the web for far too long.

I’m proud to announce the launch of this site, by far my most personal website ever. Making this spot on the web mine has taken great effort and care, and I’ve deeply enjoyed all of it^[Well, almost all of it. Those SVG animations were fairly tedious to make.]. Like any successful project, I defined a vision/goals for this site before I started any work:

Learn and employ many new tools to accurately demonstrate my understanding of building for the web, in a manner I believe to be best. This site’s primary purpose is to serve as my portfolio, and I wanted to use this site as a way to show off a bit, when doing so isn’t always appropriate or possible for the projects I work on at CivicPlus.
Make this site as accessible and fast as I can. The web is best when it is open to all, and making things accessible and fast (which are often overlapping concerns) helps provide that. I’ll probably be writing much more about this.
Build for learnability. I learned everything I know about building for the web from the generosity and kindness of others who shared their knowledge, tools, struggles, and passions. I owe my entire career to the web community, and I want to give back. While viewing source in the age of module bundlers and style processors is of less utility than it used to be, I hope that sharing this site’s source code can help someone curious enough to dig in.

It’s empowering to have a place of your own, viewable to all, where every aspect is exactly as you want it. Or, at least, as close as you can get it within your knowledge and skill set. For example, I get frustrated when I have to look at a white screen at night, so I made a “night mode” that automatically flips on after sunset. I’m eager to find more ways to express and practice building my ideal web with design, code, and prose, and I’m delighted to finally have a place to do so.