Skip to main content

Accessibility Management with Custom Components in Storefront Builder

1. Why Accessibility Matters​

AppDirect’s Storefront UI library (sfb-theme-components) is built and maintained to meet WCAG 2.1 AA. When you use the vanilla Plaza theme (without custom components), you automatically receive every accessibility fix and enhancement shipped by AppDirect.

Once you install custom components you will no longer receive automatic updates. It becomes your responsibility to keep both the UI library and your custom components code compliant each time the platform evolves.

2. Scenarios at a Glance​

ScenarioLibrary SourceAuto‑Updates?Your Action
1. No custom componentsCDN✅ YesNone – you are always on the latest, fully compliant build.
2. Custom components on v0.0.352+Copied locally via CLI❌ NoUse the CLI to upgrade the library, then audit & fix your custom code.
3. Custom components pre‑v0.0.352Hand‑rolled / legacy❌ NoUpgrade cautiously; expect deep testing and refactors.

3. Working With Custom Components v0.0.352+​

note

If you created a theme using custom components that used toolkit version 4.x.x or earlier upgrading the UI library to version 0.0.352+ still means the 3rd Scenario described previously applies to you! Only themes using custom components that were created with toolkit version 5.x.x or newer will fall under the 2nd Scenario.

3.1 Upgrade the UI library​

# inside your theme project
sfb-toolkit install @appdirect/sfb-theme-components@latest
  • The CLI downloads the newest version and updates your package.json.
  • Re‑build and run your theme locally; watch for breaking changes.
  • If something critical breaks, roll back:
sfb-toolkit install @appdirect/sfb-theme-components@<previous-version>

3.2 Audit your custom code​

After the upgrade your custom components will not inherit new fixes. Review:

  1. ARIA roles & labels – every interactive element must expose a name.
  2. Keyboard navigation – tab order, focus states, skip links.
  3. Color & contrast – text, icons, and states meet 4.5 : 1 (AA).
  4. Copied atoms – if you copied low‑level atoms, re‑diff with the new versions and merge improvements.

4. Legacy Custom Components (pre‑v0.0.352)​

Older theme custom components often import internal modules directly from sfb-theme-components. Because those internal APIs aren’t covered by the library’s public semver contract, updating to a newer version can break your code: component names, prop signatures, or default behaviours may have changed, causing runtime errors or visual regressions.

Best practices:

  • Backup & branch – never upgrade directly on your production branch.
  • Incremental steps – if possible, jump through intermediate versions.
  • Full regression testing – visual, functional, and accessibility.
  • Refactor where needed – sometimes a small rewrite beats endless patching.

Need help? Contact your Customer Success Manager to coordinate with our Digital team for a guided upgrade plan.

5. Continuous Accessibility Testing​

ToolWhen to UseQuick Start
LighthouseAutomated baseline auditsDevTools → Lighthouse → run Accessibility report.
axe DevToolsIn‑browser issue surfacingInstall extension → scan page.
Keyboard‑only walkthroughManual navigation, focus trapsUse Tab, Shift + Tab, Enter, Space.
Screen readerSemantic / ARIA verificationVoiceOver (macOS), NVDA (Windows), or TalkBack (Android).

Run these checks after every library upgrade and before each release.

6. Additional Resources​

Need Assistance?​

Reach out to your AppDirect Customer Success Manager. Our Digital team can:

  • Review upgrade strategies
  • Pair on accessibility fixes
  • Validate final compliance before go‑live

Was this page helpful?

Tell us more…

Help us improve our content. Responses are anonymous.

Thanks

We appreciate your feedback!