DEV Community: Praise Agbabiaka

A broken heading hierarchy is an architecture problem, not a markup one

Praise Agbabiaka — Sun, 09 Aug 2026 21:59:34 +0000

On a recent BigCommerce remediation, an audit flagged the heading hierarchy. Levels skipped and jumped across the page, so the structure a screen-reader user navigates by didn't hold together.

The checklist fix is obvious. Open each template, retag the headings, close the finding.

But the levels weren't the bug. They were the symptom.

Each heading was hardcoded into its own template. A section rendered an <h2> because whoever wrote that template picked <h2>, with no view of where it would sit on the assembled page. Nothing owned the hierarchy. It emerged, wrongly, from dozens of local decisions.

That's the real problem, and it's architectural.

A reusable heading component has no inherent level. The same block might be an <h2> on one page and an <h3> nested inside a region on another. Its correct level depends on where it sits, not on what it is.

Any component that bakes in a fixed level is going to be wrong somewhere because it can't see its own context.

So the fix isn't to hardcode a different level. It's to stop hardcoding heading levels altogether and render each heading from one place that receives its level from whatever owns the page structure.

The principle is portable. The idiom changes per stack:

BigCommerce (Handlebars): a single partial that receives the level as a parameter, replacing heading markup repeated across a dozen templates.
Shopify (Liquid): a snippet that takes the level through render.
React: pass the level as a prop, or use context when the hierarchy needs to be derived from component composition.
Astro: let the parent own the structure and pass the level through props, rather than having the child commit to a level it can't know from its own context.

Different mechanisms, one move.

Headings render in a single place, and the level is an input from context, not a constant.

It's also the fix that lasts. A hardcoded level regresses the moment a section is reused or a template is copied. A contextual one stays correct because the decision lives with the page structure instead of being re-decided everywhere.

That's the difference between closing a finding and fixing the system that produced it.

The accessibility failure was in the markup. The fix was in the architecture.

You don't have to choose between Shopify updates and accessibility fixes

Praise Agbabiaka — Mon, 03 Aug 2026 01:23:41 +0000

A while back, a developer told me something that stuck with me. He said fixing Shopify Liquid files is a hassle, because customizations don't scale with theme updates. The moment you start editing a theme, you've effectively forked it, and every future update has to be diffed and re-applied by hand.

He's not wrong. That's effectively how maintaining a customized Shopify theme works.

It's also why many teams avoid deep changes to a live theme, accessibility remediation included.

Accessibility fixes often require changes that only exist in Liquid templates: adding semantic HTML, correcting heading hierarchy, exposing labels to assistive technology, or fixing landmark structure. Those aren't changes you can reliably layer on afterward with CSS or JavaScript.

But "that's just how Shopify works" is where the conversation usually stops. I don't think it should stop there. The fork isn't a Shopify problem. It's a process problem. And process problems have process answers.

Solving the update problem comes down to two ideas: isolate changes so most of them never collide with an update, and keep a clean, greppable record of the changes that can't be isolated so the manual diff stays small and predictable.

The core problem

Two facts about Shopify themes create the pain:

Custom edits don't carry through theme updates. When Shopify ships a new version of the base theme, it doesn't merge your changes in. You get the new version, and reconciling your customizations is on you.
A GitHub-connected theme stops receiving Shopify's theme updates. Once a theme is connected to GitHub, Shopify's built-in "Update available" workflow no longer applies to that theme. If you want upstream theme updates, you need to bring them into your Git workflow yourself.

So you want two things at once: version control and the ability to take upstream updates. Do you have to choose one? No. You keep them in separate places on purpose. That's the core idea, and everything below is just the mechanics of it.

Setup, before any remediation starts

This groundwork is what makes the update painless later. Do it first.

Isolate CSS and JavaScript into custom files

Any styling or scripting change goes into its own custom asset files instead of being edited into the theme's existing files. These almost never conflict with an update. Because these are new assets rather than modifications to the theme's files, upstream theme updates rarely touch them, so Git treats them as independent additions rather than conflicting edits. The one exception is the line that loads them: the stylesheet_tag or script_tag that enqueues these custom assets lives in Liquid, usually in theme.liquid, so that single hookup is a Liquid edit an update can collide with. Tag it with your A11Y-REMEDIATION marker like any other Liquid change. With that one line accounted for, most of your work is gone from the diff before the diff even starts.

Tag every Liquid change and keep a list

Liquid is the part you can't fully isolate. Sometimes you have to edit a section or snippet directly. For every one of those edits, leave a clear comment describing what changed, and maintain a running list of every Liquid file you touched.

One refinement pays off later. Use a consistent, greppable marker in those comments:

{% comment %} A11Y-REMEDIATION: added aria-label + visible focus state to search toggle {% endcomment %}

Now your "list of changed Liquid files" isn't something you maintain by hand and hope is complete. It's one command:

grep -rl "A11Y-REMEDIATION" .

Designate an unconnected copy of the live theme to receive updates

Before you start, duplicate the live theme and leave that copy disconnected from GitHub. Because it isn't connected, it stays eligible for Shopify's updates. This copy is your update pipeline. The connected repo is your source of truth. Keeping them apart is the point.

The update workflow

When Shopify releases a new version of the base theme, this is how you take it without losing remediation work.

Phase 1: bring the update into version control

Update the theme copy in the Shopify admin. Shopify generates a new Updated Copy of the theme with the new version applied.
Create a backup branch from the connected repo's main. If anything goes sideways, you have a clean restore point.
Create an update branch and pull the code from the Updated Copy into it, not from the live theme. This gets the upstream changes into Git where you can actually diff them.

Phase 2: reconcile, with a focus on every Liquid change

Merge update into dev using --no-commit (git merge --no-commit --no-ff update). This leaves the merge staged but uncommitted, giving you a chance to inspect both conflicting and automatically merged changes before creating the merge commit. The --no-ff flag forces an actual merge commit so you always land in that reviewable staged state, even when Git could have fast-forwarded.
Diff every Liquid file you modified during remediation, file by file. This is the one deliberately manual step, and it's where your tagged comments and file list earn their keep. You know exactly which files to check, so you're reviewing a short list, not the whole theme. Keep, adapt, or discard each incoming change so accessibility fixes are preserved without missing legitimate improvements in the updated theme.
Commit to dev once the diff is clean, then merge dev into main.

Phase 3: push back to Shopify, in the right order

Push main to the Updated Copy, not to Live yet. Order matters here, to avoid schema errors: push the configuration files first, config/settings_schema.json and config/settings_data.json, then push the remaining theme files. Pushing the config first means that if there's a schema problem, the sync fails here, before the rest of the theme is touched, so you fix the JSON discrepancy and retry instead of discovering the problem after everything else has synced.
Verify the Updated Copy on Shopify before publishing. Alongside the usual schema and functional checks, re-run your accessibility checks here: an upstream update can change base-theme files you never touched and quietly regress accessibility along the way, so confirm the copy still holds up before it goes live. Only then publish it as the Live theme.

Why this holds up

Notice what each piece is doing. The unconnected copy keeps you eligible for updates. Version control keeps your work reviewable and reversible. Isolated CSS and JavaScript mean most of your changes never enter the diff at all. Tagged Liquid comments turn the unavoidable manual step into a bounded, predictable one. The config-first push order fails loudly and early instead of quietly and late.

None of this makes Shopify merge your changes. That was never on the table. What it does is shrink the manual work to the smallest surface possible and make every risky step recoverable.

The theme stays maintainable. Updates stay boring. "We customized it" stops meaning "we're stuck on this version forever."

That developer's complaint was fair. It just wasn't the end of the story. Shopify sets the constraint. A disciplined workflow keeps it manageable.

Building a Component Library: From First Component to Fully Automated Pipeline

Praise Agbabiaka — Tue, 19 May 2026 21:20:19 +0000

I was asked to architect and build a React component library from the ground up.

The problem was clear. We kept rebuilding the same components across different applications. The same buttons, inputs, modals, and layouts, recreated from scratch every time. Someone needed to own a component library and that someone ended up being me.

I nodded like I had a plan. I didn't.

I'd never built a component library before. I didn't know how to structure one, how to distribute one, or honestly how to scope one. But I figured the best way to learn was to start.

So I started small. Buttons. Inputs. The boring stuff that touches everything.

I focused on getting the foundations right, and I made the decision very early on that accessibility would be baked in from day one. Every component designed to be usable by keyboard users, screen readers, and other assistive technologies from the start. Not as a future improvement. Not as a "nice to have." Just part of the standard.

Then, the library kept growing.

Today, it's documented and hosted in Storybook, published as an npm package, and fully automated with CI/CD pipelines that handle Storybook deployments and npm publishing on every release.

What started as a vague ask turned into real infrastructure the team relies on daily.

A few things I'd tell anyone starting from zero:

You don't need to know everything upfront. Start with the smallest components and let the architecture reveal itself.
Treat accessibility like functionality. If it doesn't work with a keyboard, it's not done.
Automate early. Setting up CI/CD for publishing and deployment saved me more time than I expected.
Document everything. Storybook isn't just a demo tool. It's how the team actually adopts the library.

The gap between "I have no idea what to do" and "this is running in production" is smaller than you think. It's just a lot of small steps.

Building My First Wagtail Site

Praise Agbabiaka — Mon, 30 Oct 2023 04:09:01 +0000

Software development is an ever-changing field. Often, one has to pick up new technologies rather quickly. This was the case for me with Wagtail. And thanks to its simplicity, I was able to do so in no time.

Why Wagtail?

An opportunity to improve the accessibility of websites built with Wagtail opened up recently. And I immediately jumped on it. I was so excited at the prospect of putting my accessibility skills to use that I didn’t give much thought to the fact that I had no experience with Wagtail. I figured I could pick up Wagtail quickly enough if I put my mind to it. And since I learn best by doing, I decided to build a blog site to gain hands-on experience with Wagtail.

What’s Wagtail?

Wagtail is an open-source Content Management System built on Django. So, much of the process for building websites with Django translates directly to Wagtail. But Wagtail abstracts the need to define urls, views and admin functionality. In Wagtail, emphasis is placed on page and page content. Every page is built from a Django model that inherits from Wagtail’s Page model. Wagtail also provides a number of custom template tags and filters that extend the capabilities of the Django templating engine.

Building the Blog Site

I decided that my blog site would have a home page, a blog index page, blog post pages, and an about page. Since a home app comes out of the box with Wagtail, I only had to create a base and blog app for my Wagtail project.

In the home app, I updated the HomePage model to include fields for a hero image, heading, introduction and link to the blog index page. I defined the image and link fields as a Foreignkey to Wagtail’s Image and Page models, respectively.

As the name suggests, the base app defined functionalities shared across apps within the project. It contained snippets for the site logo, main menu and breadcrumb navigation. Within this app, I constructed a ContentBlock that allowed me to dynamically add subheading, image, list and rich text content to a page. This ContentBlock inherited from StreamBlock. It was used to define a StreamField to populate the body field of the about and blog post pages. Because the about page didn’t belong in the home or blog app, I defined a StandardPage model to create it.

The blog app held models and templates for the blog index page and blog post pages. I defined the BlogPage model as child page of the BlogIndexPage. And I populated the blog index page with meta data for each blog post. Thus, a new blog site was built.

I’m glad that I can now add Wagtail to my toolkit as a web developer. If you’d like to see my code, check out the praiztech_blog repository on GitHub. I'm still working on the front-end, though.

Growing My Skill in Web Accessibility

Praise Agbabiaka — Fri, 27 Oct 2023 12:21:44 +0000

As a self-taught web developer, my first impulse whenever I encounter a new concept is to search the Web. There's almost always a blog post or video that explains it in enough detail to help me understand. For the most part, this has been no different for web accessibility.

Using Online Resources

Once I learnt about web accessibility on Mozilla, it was quite easy to find other related posts. I found several excellent posts to expand my knowledge of accessible web development. I learnt to write accessible code with semantic Hypertext Markup Language (HTML) elements. I also learnt to test my websites with automated testing tools such as WAVE, axe DevTools and ARC Toolkit. To understand how blind users experience my websites, I learnt to test with NVDA and TalkBack screen readers. I also learnt to enhance the output of screen readers with Accessible Rich Internet Applications (ARIA) when there are no HTML alternatives.

Learning from a Great Mentor

As my knowledge of web accessibility grew, I realized that I was lacking an important skill. I didn't know how to perform a manual accessibility audit. I searched the Web but I couldn't find a simple guide on the process of manual accessibility testing. Yet, I knew I had to gain this skill. Manual auditing is the only way to identify all accessibility issues on a website.

So, when Rachele DiTullio posted on LinkedIn that they had created manual accessibility audit videos, I was excited. First, I watched the videos to understand their testing process. Then, I sent them an email requesting their mentorship. They were very receptive and agreed to mentor me. They agreed to provide weekly testing exercises and give feedback on the results. Thus began my journey into manual web accessibility auditing.

My first manual accessibility testing workbook

The Journey So Far

As I've performed manual accessibility audits, my skill have evolved over time. I've learnt to break down each webpage into smaller sections to test. I'm learning to better interpret the Web Content Accessibility Guidelines (WCAG). I'm learning how WCAG failures impact the web experience of users with disabilities. It's a journey. I'm getting better at it.