<![CDATA[Drbr's Dev Blog]]>https://drbr.devRSS for NodeThu, 09 Apr 2026 14:11:34 GMT60<![CDATA[Drbr’s A11Y Resources]]>https://drbr.dev/drbrs-a11y-resourceshttps://drbr.dev/drbrs-a11y-resourcesWed, 31 Aug 2022 23:09:04 GMTAccessibility == Usability. From MDN:

Accessibility is the practice of making your websites usable by as many people as possible. We traditionally think of this as being about people with disabilities, but the practice of making sites accessible also benefits other groups such as those using mobile devices, or those with slow network connections.

Making an accessible website is not just checking requirements to comply to a standard, it’s a natural extension of UX design: we must design our software in a way that works for everyone.

Although official standards are well-documented, best-practice design patterns are much less standardized, hence many useful resources have been authored by individuals.

Standards / specs

The W3C Web Accessibility Initiative (WAI) is the de facto standards body for web accessibility. Their website contains loads of resources: tutorials, guides, articles, specs, and more about the how/what/why of accessibility.

Web Accessibility best practices by Level Access
Checklist for an accessibility audit, which includes all WCAG 2.1 criteria.

General guides / resources

How to self-audit

Interacting with your application in different ways as you develop it will help uncover usability issues. Here are some easy checks that anyone can do without special training:

  • Try using the site with only the keyboard. You should be able to access all the same information and perform the same actions that a mouse user can.

  • Inspect the semantics of the Accessibility Tree (AT) in the Chrome devtools. Screen readers and other assistive technologies view the site via the information in the AT. The contents of this tree should make sense semantically.

  • Try navigating the site using a free screen reader (VoiceOver on Mac or NVDA on Windows). It should convey all the same information as what's on the screen.

  • Run an automated checker such as axe, which is available as a browser extension, via the Lighthouse audit in the Chrome devtools, or as an NPM package.

  • Increase the text size to 200% using the browser's built-in zoom function. The layout should still be usable.

The following articles explain these (and other easy checks) in more depth:

Courses / Trainings

  • Learn Accessibility by web.dev (Google)
    20-chapter series of articles (a.k.a. "self-paced course"), written by Carie Fisher.

  • Web Accessibility on Udacity (by Google)
    Free online course. Summarized in this article.

  • A11ycasts by Rob Dodson
    30-part YouTube playlist. Most of the videos are between 5 and 15 minutes long.

  • Testing Accessibility by Marcy Sutton
    Paid 6-part course on building accessible web apps through the entire lifecycle: design, build, test, ship.

  • Practical Accessibility by Sara Soueidan
    Paid video course. Looks to be more focused on the technical nuts-and-bolts than Marcy Sutton's course.

Conferences / Meetups

  • A11y Talks
    A “virtual meetup” consisting of over 60 recorded talks. Hard to browse via their site; easier via their YouTube channel.

  • axe-con
    A free conference run by Deque Systems (accessibility consultancy and makers of axe).

    • Despite being an advertisement for Deque’s products, the conference contains lots of useful talks.

    • Recordings of past years can be watched for free, if you register.

  • Global Accessibility Awareness Day
    3rd Thursday in May each year - Miscellaneous events are held around the world

Component libraries

These component libraries claim to conform to WCAG standards; they could act as good reference implementations.

https://www.digitala11y.com/accessible-ui-component-libraries-roundup/

Influencers

Lots of helpful information about accessibility is written by independent people who have figured stuff out and shared their knowledge on personal blogs. These people have good things to say.

  • Carie Fisher (website) (twitter)

    • A11y writer/speaker

    • Creator of A11y Style Guide and A11y Talks virtual meetup

  • Marcy Sutton (website) (twitter) (”Testing Accessibility” blog)

    • Freelance a11y specialist

    • Free email list with interesting weekly mini-articles (which are informative, but are also ads for her workshops)

    • Conducts regular online workshops (see “Services” tab or https://testingaccessibility.com/workshops)

  • Ben Myers (website) (twitter)

    • Accessibility advocate with a weekly livestream, and also a blog

  • Scott O’Hara (website) (twitter)

    • Accessibility developer at Microsoft

  • Adrian Roselli (website)

    • Consultant with lots of deep-dive blog articles about specific topics and pitfalls

  • Sara Soueidan (website) (twitter)

    • She’s developing a paid online course, set to debut in early 2023

  • Sarah Higley (website)

  • Ashlee M Boyer (website)

Miscellaneous Articles

Various one-off pieces I found especially useful.

Consultancies

These companies can be hired to do accessibility audits for your software. Their websites also contain lots of educational material about how to conform to the various standards.

Advice threads / aggregations of resources

Dropping these links here so I can find them in the future; likely some interesting resources in these threads that could be listed above.

]]><![CDATA[How to remove circular dependencies from a fast-moving codebase]]>https://drbr.dev/how-to-remove-circular-dependencies-from-a-fast-moving-codebasehttps://drbr.dev/how-to-remove-circular-dependencies-from-a-fast-moving-codebaseWed, 20 Jul 2022 20:26:36 GMTThis is not a tutorial. This is more like "here's a technique I used in the past and I'm writing it down so someone could do it again." Implementing this will require custom coding that I did not write for you. If you have ideas about how to do this concretely (or differently), please leave a comment!

The subject of this article is a TypeScript codebase, but the same ideas could apply to projects written in any language.

The Problem

Once upon a time, I worked on a large single-page React app written in TypeScript. When the app got big enough, we started getting frequent runtime crashes due to circular imports (for example, if A imports B and B imports A, A doesn't yet exist when B gets loaded). We'd fix one cycle but then it would soon happen somewhere else. We had to do something to keep this problem from impeding us.

There are a lot of reasons one might want to remove circular dependencies, but it's clear to me that keeping a codebase void of cycles is beneficial. Here are what I see as the two main advantages:

  • Prevent some runtime errors when the app is being loaded (the problem we had above);
  • Enable smaller compilation units, which sets the stage for all sorts of great stuff like incremental builds/tests, code splitting, and more.

A Solution

Our codebase was big, so one person couldn't just go in at once and remove cycles. Without a way to track them, it was far too easy for people to unknowingly introduce new cycles in the course of their normal work, and also easy for a person removing a cycle to accidentally add a different one. We needed to make sure that we could remove them one by one, over time, without slipping back.

My solution looked like this:

  1. Add a local shell command that generates a list of all the import cycles in the codebase.
  2. That list gets checked in to source control so we can easily compare the cycles in our locally-changed codebase to whatever was there before.
  3. As part of every build (local and on the CI), the same command gets run to generate a list of all the cycles in the codebase. If the newly-generated file and the checked-in file are not an exact match, print the differences and fail the build. If a developer was changing cycles intentionally, they could first manually generate the file (by running the command) and check it in along with their changes.

This model was successful in keeping the number of cycles on a mostly-downward trajectory over time. By forcing the developer to manually "lock in" their changes every time they added or removed cycles (and supplying helpful error messages at build time), developers were able to understand the consequences of their changes and refactor their code accordingly to make sure cycles were being removed, not added.

How to detect the cycles

There are many ways to do this, but ideally it needs to be fast.

I used the Webpack circular-dependency-plugin, which has a big disadvantage in that it only detects runtime imports. TypeScript type-only imports are stripped out by the time Webpack runs. This is not terribly slow, but it's not terribly fast either. I'm pretty sure we could do better.

There's also https://www.npmjs.com/package/eslint-plugin-import, but it will run very slowly on large codebases, because the linter (by design) analyzes each file in isolation, so it's duplicating a lot of work when traversing the dependency graph.

If I were to do this again, in lieu of finding an existing tool that's fast enough, I'd consider writing a custom standalone tool. We should be able to get the imports from each file using the TypeScript compiler API and analyze the cycles using an O(n) algorithm such as Tarjan's strongly connected components algorithm. The downside here is that we wouldn't get in-IDE feedback (like we would with ESLint) when a cycle exists.

File format

As for the file generated by the tool, I used a JSON format so it could be easily parsed by scripts but also read by humans. Importantly, this file must be normalized, so that the cycles will be reported the same even if some code has moved around in minor ways. I normalized the raw results by sorting them three times:

  1. Sort cycles by length, descending. That makes it easy to find the biggest ones to refactor first.
  2. Rotate each cycle so that its first-alphabetical filename is at the start. So, B->C->A and C->A->B would both be reported as A->B->C.
  3. Within each length and after rotating, remove duplicates and sort alphabetically.

Also in the output file, I included a JSON object that mapped each file name to the number of cycles in which it appeared (sorted in descending order by count). This also proved to be a helpful tool in deciding which file to break down next.

Build output and manual inspection

The command line tool would have two modes (specified via args): one to generate the file in memory (run by the build script), and another to actually write it to disk (run by developers). The role of doing this in the build script is to make sure that cycles aren't being added, but also to make sure that if cycles are removed, a new version of the tracking file gets checked in. In my solution, the build generated the cycle list in memory and compared it to the one on disk. Depending on the result, one of the following could happen:

  • If the files were an exact match, quietly succeed/continue the build.
  • If the files were not a match, compare the array of normalized cycles to figure out which were added and which were removed. Display this information to the user.
    • If only removals were found, invite the user to manually regenerate the file and build again. With the regenerated file, subsequent builds would pass.
    • If there were additions (or a mixture of removals and additions), invite the user to manually inspect the list and decide what to do (either check in the new file anyway, or change their code to avoid adding cycles).

Because the file is normalized and checked in to source control, easily-inspectable diffs would show up on pull requests so everyone is aware of the cycles being changed. And, of course, the CI build would fail unless the checked-in file matched the freshly-calculated result.

Conclusion and next steps

A technique like this can help a team remove cycles over time on a large codebase, if you're willing to write some custom build steps. This system would remain in place to track the cycles until it gets down to zero, at which point it could be replaced with a much simpler build step that simply fails if any cycles are detected (no need for the tracking file).

Please comment if you know of another good cycle-detection tool that could work with this system!

]]><![CDATA[Test post]]>https://drbr.dev/test-posthttps://drbr.dev/test-postTue, 15 Feb 2022 09:25:03 GMTThis is my first blog post, does it even work? Just checking out the platform.

It should be able to support Markdown, like lists:

  1. Come
  2. See
  3. Conquer

But the markdown looks weird because I'm not typing it in a monospaced font, even though it renders with all the same markup.

Can I do links? Go check out my recipe blog!

]]>