squarespace-wcag-utils

SqsA11y logo

SqsA11y

Latest release License: MIT Read the changelog

Accessibility enhancement utilities for Squarespace websites.

Current version: v0.4.12 Library: squarespace-wcag-utils

Copyright (c) 2026 Joe Lippeatt / 24Moves Consulting Licensed under the MIT License.

Introduction

SqsA11y started during an accessibility evaluation, documentation, and remediation project for three Squarespace websites. Early in that process, I found a Squarespace help forum discussion about WCAG compliance, which led me to the official Squarespace Accessibility Resources page.

Squarespace recommends following the Web Content Accessibility Guidelines (WCAG). However, I quickly found that some accessibility issues, especially on Squarespace 7.0 websites, are difficult to evaluate or remediate through the Squarespace editor alone.

For example, some templates and blocks provide limited control over accessible link text, image alt text, focus behavior, form labeling, and other details that are important during a WCAG review.

With those limitations in mind, I began building small JavaScript utilities to address specific issues one at a time. The first scripts focused on form field behavior and duplicate screen reader announcements. As the number of scripts grew, they became harder to manage individually, so I organized them into this library.

SqsA11y was designed so it could be modified on a per-site, per-template basis, as not all Squarespace sites are built the same. It is not a replacement for a manual accessibility audit, and it does not guarantee WCAG compliance. It is a collection of practical enhancements intended to help improve accessibility on Squarespace websites where the platform does not provide enough direct control.

Key Sections

Important sections of this document

Overview

SqsA11y is a JavaScript accessibility enhancement library for Squarespace websites. It is designed to help identify, document, and improve common accessibility issues found in Squarespace 7.0 and 7.1 templates that may not be otherwise available for remediation in the Squarespace builder.

When in Debug Mode, the library will post details in the console window for specific audits of potential issues that need to be tested manually.

The library includes modular enhancements for forms, labels, links, images, focus behavior, keyboard access, motion preferences, target size, and developer-facing accessibility audits. Each enhancement is intentionally scoped to a specific pattern so it can support accessibility review without trying to rewrite the entire website.

SqsA11y is not a replacement for a full WCAG evaluation. It should be used as part of a broader accessibility review that includes manual testing, keyboard testing, screen reader checks, visual inspection, and template-specific validation.

Important Before You Install

[!IMPORTANT] Use this library as part of an accessibility review and remediation process. Only certain sections of WCAG can be detected and mitigated with JavaScript and automation.

SqsA11y is intended to help improve common WCAG-related issues on Squarespace websites. It is an accessibility enhancement library, not a complete WCAG compliance solution.

Before installing this library, please understand the following:

[!TIP] Each individual enhancement section of SqsA11y can be enabled/disabled to make it easier to test a deployment

Why This Library Was Developed

What This Library Does

SqsA11y provides JavaScript-based accessibility enhancements for common Squarespace issues that may be difficult or impossible to edit directly in the Squarespace builder.

The library is designed to:

SqsA11y is intentionally modular. Each enhancement is scoped to a specific accessibility pattern so it can be reviewed, tested, enabled, disabled, or adjusted as needed for a specific Squarespace site.

What This Library Cannot Do

SqsA11y, like any JavaScript-based accessibility enhancement library, can help improve accessibility issues, but it cannot make a website fully WCAG compliant on its own.

This library cannot:

[!NOTE] SqsA11y should be used as an accessibility support tool within a broader WCAG review and remediation process.

Project Structure

This library is organized around a main loader, shared utilities, and individual enhancement modules.

squarespace-wcag-utils/
├── squarespaceA11y.js
│   Main loader. Reads config, loads utilities, and runs enabled enhancements.
│
├── utils/
│   Shared helper functions used by multiple enhancements.
│
└── enhancements/
    Individual accessibility enhancement and audit modules.

Most accessibility behavior lives in the enhancements/ directory. Each enhancement file is documented with related WCAG criteria, Squarespace context, dependencies, and implementation notes.

Runtime Behavior

Supported Squarespace Versions

SqsA11y is intended for use with Squarespace 7.0 and 7.1 websites.

The library has been developed around common Squarespace page structures, including forms, navigation, image blocks, summary blocks, video backgrounds, parallax images, and AJAX-loaded page content.

Because Squarespace markup varies by version, template, theme, block type, custom code, and third-party integrations, every installation should be tested on the specific website where it is deployed.

SqsA11y may require customized adjustment for:

Installation

Quick Start

The fastest way to install SqsA11y is to load the main squarespaceA11y.js file from a public CDN and add it to the site-wide Footer Code Injection area in Squarespace. Other hosting options are described below.

<!-- SqsA11y accessibility enhancement scripts -->
<script>
  window.sqsA11yConfig = {
    logging: false,
    excludeEnhancements: []
  };

(function () {
  var s = document.createElement("script");
  s.src = "https://cdn.jsdelivr.net/gh/ext237/squarespace-wcag-utils@main/squarespaceA11y.js";
  document.head.appendChild(s);
})();
</script>
<!-- /SqsA11y accessibility enhancement scripts -->

[!TIP] During active development, you can use a cache-busting query string to prevent Squarespace’s browser caching while testing changes. For example, you can use Date.now():

s.src = "https://example.com/path/to/squarespaceA11y.js?v=" + Date.now();

Configuration options

The window.sqsA11yConfig object has two values, logging and excludeEnhancements.

Example configuration with logging enabled and one enhancement disabled:

  window.sqsA11yConfig = {
    logging: true,
    excludeEnhancements: [
      "textSpacingAudit"
    ]
  };

After installing, test the site carefully with keyboard navigation, forms, menus, links, mobile layouts, and any custom Squarespace blocks or third-party scripts.

Hosting Options

SqsA11y can be hosted in several ways:

Option A: Load from jsDelivr

SqsA11y can be loaded from GitHub through jsDelivr, as showin in the Quick Start example above.

https://cdn.jsdelivr.net/gh/ext237/squarespace-wcag-utils@main/squarespaceA11y.js

The @main CDN URL loads the current version from the main branch of the GitHub repository. You can change that to other branches, or forks.

For example:

https://cdn.jsdelivr.net/gh/ext237/squarespace-wcag-utils@v0.4.12/squarespaceA11y.js

Replace v0.4.12 with the version tag you want to use.

[!NOTE] If you need site-specific changes, do not load directly from the @main branch. Fork the repository or host your own tested copy so your changes can be versioned and maintained separately.

Pull requests are welcome for improvements that may benefit other Squarespace sites. Please test changes carefully and include notes about the Squarespace version, template, or site pattern the change is intended to support.

Option B: Host the Files Yourself

You may also upload the SqsA11y files to a web-accessible server that you control. This is useful for sites that need custom code edits to the library.

Because Squarespace versions, templates, custom code, and third-party integrations can vary from site to site, self-hosting can make it easier to maintain a site-specific copy of the library. For example, you may choose to host each customized copy in a separate folder named for the client or website it supports.

Example script s.src URL:

https://example.com/path/to/squarespaceA11y.js?v=0.4.12

Option C: Other Production CDN

You may also host the library from another production CDN.

Use the same complete install pattern shown in Quick Start, but replace the s.src URL with the production CDN URL.

Option D: Squarespace File Hosting

Squarespace file hosting is a research TODO and is not currently the recommended installation method for SqsA11y.

Test the Installation

After installing the library, review the site carefully.

At minimum, test:

SqsA11y should be tested on the specific Squarespace site where it is installed.

[!IMPORTANT] Due to differences in Squarespace builder versions, themes, custom code, and third-party plugins, do not assume that successful behavior on one Squarespace site guarantees successful behavior on another.

How It Works

Bootstrap File

SqsA11y is loaded through a main bootstrap file, squarespaceA11y.js.

The bootstrap file is responsible for loading the shared utilities and registered enhancement modules, then running those enhancements after Squarespace has finished rendering the page.

Squarespace Page Rendering

Because Squarespace often modifies page content with JavaScript after the initial HTML loads, SqsA11y is designed to run after the DOM is ready and again after supported Squarespace AJAX page updates.

Runtime Enhancements

Most enhancements work by making runtime adjustments to the rendered page in the browser.

Depending on the module, runtime changes may include:

These changes happen in the browser after the page loads. They do not permanently rewrite the Squarespace template, source content, or builder configuration.

Modular Structure

Each accessibility enhancement is contained in its own module. This modular structure makes it easier to review, test, disable, or customize individual enhancements for a specific Squarespace site.

Examples of enhancement areas include:

Logging

When logging is enabled, SqsA11y reports enhancement activity in the browser console. See the section ‘Recommended Use During a WCAG Review’ for details on enabling logging.

This can help during a WCAG review by showing:

Logging should usually be enabled during testing and disabled for normal production use.

During a WCAG review, enable logging so the library can report which enhancements are running, which elements were reviewed, and which changes were made.

Logging is intended for auditing, editing, and debugging. It should normally be disabled on production sites after review is complete.

Enable logging in the load script config

Site wide logging can be enabled as the library is loaded. Set the window.sqsA11yConfig “logging” value to true. See the Configuration Options section for an example.

Set logging back to false when active review or debugging is complete.

Force logging directly in squarespaceA11y.js

You may want to toggle logging without modifying the client’s Squarespace script injection settings. Logging can also be forced on inside squarespaceA11y.js by temporarily swapping these lines:

const DEBUG = CONFIG.logging === true;
//const DEBUG = true; // global override for testing, uncomment to force debug logging

Reduce noisy console output

If console output becomes too noisy, individual enhancement logging can be disabled in the ENHANCEMENT_LIST by setting that enhancement’s debug value to false.

const ENHANCEMENT_LIST = [
  { name: "focusOutline", wcag: "WCAG 2.4.7", debug: DEBUG },
  { name: "targetSizeMinimum", wcag: "WCAG 2.5.8", debug: false }, /* override DEBUG */
];

This allows the enhancement to continue running while suppressing its debug output.

Disable individual enhancements during review

Individual enhancements can be disabled in either of two ways.

OPTION 1: Add the enhancement name to the page-level excludeEnhancements list:

<script>
  window.sqsA11yConfig = {
    logging: true,
    excludeEnhancements: ["targetSizeMinimum"]
  };
</script>

OPTION 2: Comment out the enhancement in the ENHANCEMENT_LIST inside squarespaceA11y.js while testing locally.

const ENHANCEMENT_LIST = [
  { name: "focusOutline", wcag: "WCAG 2.4.7", debug: DEBUG },
  /*{ name: "targetSizeMinimum", wcag: "WCAG 2.5.8", debug: false },*/
];

Suggested audit workflow

  1. Enable logging before beginning the review.
  2. Reload the page and check the browser console for enhancement activity.
  3. Review each logged change manually before treating it as an accessibility improvement.
  4. Test with keyboard navigation, screen reader review, browser zoom, mobile viewport widths, and relevant WCAG-specific checks.
  5. Temporarily disable individual enhancements when isolating an issue or confirming whether a behavior comes from the library, Squarespace, or custom site code.
  6. Document any remaining issues that require manual remediation in Squarespace or third-party tools.
  7. Disable logging before final delivery.

This library is intended to support WCAG review work, not replace it. Console output should be treated as developer guidance, not as a pass/fail accessibility report.

WCAG Documentation Example

When submitting mitigation documentation for manual and automated accessibility updates for a Squarespace website, it may be useful to document that this library was used as part of the review and mitigation process.

Example WCAG documentation:

As part of the accessibility mitigation work, the site includes the squarespace-wcag-utils accessibility enhancement library. This library provides JavaScript-based enhancements for selected Squarespace-generated patterns that may affect keyboard navigation, focus visibility, form labeling, link purpose, form status messages, target size, and related accessibility concerns. The library is used as a supplemental mitigation tool alongside manual review, content updates, design review, code inspection, automated testing, and functional keyboard/screen reader testing. Its use does not guarantee WCAG compliance by itself and is not a substitute for ongoing accessibility review. The library is intended to help address selected known Squarespace limitations where direct template or platform-level changes may not be available.

Creating New Enhancements

There is plenty of other WCAG-related issues that can be audited or repaired in Squarespace 7.0 and 7.1, and various theme templates. Here are the steps for creating new files:

  1. Create a new file inside /enhancements/.

Example:

enhancements/focusOutline.js
  1. In your new file, register the enhancement on window.sqsA11y.enhancements.

Example:

(function (window, document) {
    "use strict";

    window.sqsA11y = window.sqsA11y || {};
    window.sqsA11y.enhancements = window.sqsA11y.enhancements || {};

    window.sqsA11y.enhancements.focusOutline = function (options = {}) {
        const style = document.createElement("style");

        style.textContent = `
            :focus-visible {
                outline: 3px solid #005fcc;
                outline-offset: 3px;
            }
        `;

        document.head.appendChild(style);
    };
})(window, document);
  1. Add the enhancement to ENHANCEMENT_LIST inside squarespaceA11y.js.

Example:

const ENHANCEMENT_LIST = [
    { name: "skipToMain", wcag: "WCAG 2.4.1", debug: false },
    { name: "focusOutline", wcag: "WCAG 2.4.7", debug: false }
];

The name value must match:

Example:

focusOutline.js
window.sqsA11y.enhancements.focusOutline
excludeEnhancements: ["focusOutline"]

  1. Review the comment layout used by other files in the enhancements/ directory. Make sure the new file is well documented, including the Squarespace issue being audited or resolved, supported Squarespace versions or builders when known, related WCAG criteria, dependencies, and any important limitations.

  2. Commit your changes to a feature branch and open a pull request for review. Include notes about the Squarespace version, template, or site pattern the enhancement is intended to support.

Known Limitations

This library is intended to support accessibility review and remediation work on Squarespace websites. It does not guarantee WCAG compliance and does not replace a manual WCAG audit.

Known limitations include:

A complete accessibility review should still include manual WCAG testing, keyboard testing, screen reader review, browser zoom, mobile viewport testing, and review of any third-party tools or embedded services.

License

This project is licensed under the MIT License.

You may use, copy, modify, merge, publish, distribute, copies of this software, subject to the terms of the MIT License. This software is provided as-is, without warranty of any kind. It is intended to support accessibility review and remediation work, but it does not guarantee WCAG compliance, legal compliance, or accessibility compliance for any website.

See the LICENSE file for full license details.

WCAG Enhancement Map

The following section maps WCAG success criteria to related JavaScript enhancements and audits provided by this library.

These mappings describe where the library attempts to support accessibility review, mitigation, or JavaScript-based enhancement. They do not indicate that a criterion is fully satisfied, that a site is compliant, or that manual review is no longer needed.

[!IMPORTANT] This library ONLY reports and/or repairs issues related specifically to Squarespace templates. Not all areas of each success criterion are covered by this library. Some enhancements cannot be addressed with JavaScript. Some only address part of a requirement that. A complete manual evaluation of each checkpoint is still required.

1.1.1 Non-text Content

1.3.1 Info and Relationships

1.3.5 Identify Input Purpose

1.4.11 Non-text Contrast

1.4.12 Text Spacing

2.1.1 Keyboard

2.1.2 No Keyboard Trap

2.2.2 Pause, Stop, Hide

2.3.3 Animation from Interactions

2.4.1 Bypass Blocks

2.4.3 Focus Order

2.4.6 Headings and Labels

2.4.7 Focus Visible

2.4.10 Section Headings

2.4.11 Focus Not Obscured Minimum

2.5.8 Target Size Minimum

3.2.5 Change on Request

3.3.1 Error Identification

3.3.2 Labels or Instructions

4.1.2 Name, Role, Value

4.1.3 Status Messages

Potential Future Enhancements

The following section identifies WCAG success criteria where future versions of this library may be able to provide additional audits, warnings, or partial remediation. Inclusion in this section does not indicate that an enhancement is planned, only that JavaScript-based evaluation or mitigation may be possible.

[!IMPORTANT] Any future enhancement would still have limitations and would not replace manual accessibility testing. A complete manual evaluation of each checkpoint is still required.

1.1.x Content

1.3.x Content Structure and Meaning

1.4.x Visual Presentation and Perception

2.x User Interaction and Navigation

3.x Understandability and Input Assistance

4.x Technical Compatibility

WCAG Criteria Not Suitable for JavaScript Remediation

The following section identifies WCAG success criteria that cannot be reliably evaluated or remediated using client-side JavaScript. These checkpoints typically depend on content meaning, business processes, site-wide consistency, media content, human judgment, or information that is not available to page scripts.

[!IMPORTANT] These criteria should be evaluated as part of a manual WCAG audit. No enhancement in this library should be interpreted as satisfying these requirements.

1.2.x Audio and Time-Based Media

These checkpoints relate to audio-only content, video-only content, captions, transcripts, media alternatives, and audio description. These requirements usually depend on the actual media content, not only the surrounding Squarespace markup. These WCAG checkpoints cannot be reliably evaluated or remediated using JavaScript.

These items should be reviewed manually during a WCAG audit.

1.3.x Content Structure and Meaning

1.4.x Visual Presentation and Perception

2.x User Interaction and Navigation

3.x Understandability and Input Assistance

Changelog

See CHANGELOG.md for release history and unreleased changes.

This site is open source. Improve this page.