Fixing WCAG Violations on Bitrix: Audit and Implementation

Standard Bitrix catalog fails an automated Axe check — 40 violations on the homepage. That's not a reason to panic, but a cause for systematic audit. WCAG 2.1 Level AA is not optional for government and financial sites in Russia. In recent years, regulators directly reference the standard during inspections. But even for commercial projects, accessibility affects SEO: search bots read the site like a screen reader — poor semantics means poor indexing. We configure accessibility turnkey: from audit to final testing with real users. Over 5 years we've completed more than 50 WCAG projects, including large online stores on Bitrix.

Which WCAG violations are most common in Bitrix

Bitrix templates "out of the box" violate WCAG for several systemic reasons. Let's look at the most frequent.

Images without alt. The catalog.element component outputs <img> via CFile::ShowImage() — this method does not add alt automatically. In the template, you need to pass the attribute explicitly:

echo CFile::ShowImage($fileId, 800, 800, 'border="0"', 'alt="' . htmlspecialcharsEx($arResult['NAME']) . '"'); 

Buttons without text content. Icon buttons like "Add to cart" with an SVG icon and no text violate criterion 1.1.1. The minimum fix is to add aria-label:

<button class="cart-btn" aria-label="Add to cart"> <svg>...</svg> </button> 

Navigation menus without semantics. The standard bitrix:menu component generates <ul>/<li> without <nav> and without aria-label — multiple navigation menus on a page are indistinguishable for screen readers. Solution: wrap each menu in <nav> with a unique aria-label.

How to fix missing alt in the catalog.element component

Let's show with an example: a client is an auto parts online store with a catalog of 10,000 items. Axe found 400 alt violations. We overrode the catalog.element template — in result_modifier.php we added an array with alt from the element's NAME. Then in the template the image is output via a regular <img> with alt. Additionally, we had to handle images in SKUs via the OnGetImageAlt event. As a result, alt violations dropped to 0, and load time did not increase — page size changed negligibly.

Audit via automated tools

Before code fixes, a baseline check is needed. According to WCAG documentation (see Understanding Documents), automated tools do not replace expert review but speed up finding typical errors. Axe DevTools (Chrome extension) finds violations with DOM node references in 30 seconds. Lighthouse (Accessibility tab) gives a score of 0–100. The target for WCAG AA is 90+, but 100 does not guarantee full conformance: automation does not check logic, only markup.

A typical report for a Bitrix store: 20–40 violations, of which 60% are missing alt, 20% contrast issues, 10% missing label on form fields.

Manual audit reveals 3 times more critical errors than automated checks — this is confirmed by our projects. Axe finds only 30% of violations, while manual testing finds 100%.

Why automated checking is not enough

Axe only finds what is coded into its rules: contrast, alt, aria. But it does not check focus logic, screen reader readability, or keyboard navigation. For example, if a button appears dynamically, Axe will see it but won't check whether it can be tabbed to. Manual testing with NVDA or JAWS is mandatory. Manual audit reveals 3 times more critical errors than automated checks — this is confirmed by our projects.

Forms: fields with label

Bitrix forms (cart, registration, callback) often use placeholder instead of <label>. This violates criterion 1.3.1 — placeholder disappears on input, and users with cognitive impairments lose field context.

The bitrix:main.register component generates fields via $arResult['PERSONAL_FIELDS'] — the template must be rewritten with explicit <label for="...">:

<label for="USER_LOGIN">Login</label> <input type="text" id="USER_LOGIN" name="USER_LOGIN" required aria-required="true" autocomplete="username"> 

Skip-link for keyboard navigation

The first element on the page should be a link "Skip to main content" — it allows keyboard users to bypass navigation. In Bitrix it is added at the beginning of header.php:

<a class="skip-link" href="#main-content">Skip to main content</a> 

CSS makes it visible only on focus:

.skip-link { position: absolute; left: -9999px; } .skip-link:focus { left: 0; top: 0; z-index: 9999; padding: 8px 16px; background: #000; color: #fff; } 

Contrast and font sizes

WCAG 2.1 AA requires text contrast to background at least 4.5:1 for normal text and 3:1 for large text (18pt+). Gray labels on white background (#999 on #fff) give contrast 2.85:1 — violation. Check with the WebAIM Contrast Checker tool, fix by changing color to at least #767676.

How to conduct a WCAG audit on Bitrix: step-by-step guide

1. Run Axe DevTools on each typical page (homepage, catalog, product card, cart, form).
2. Collect the report — export JSON with violations.
3. Classify them into groups: alt, contrast, label, ARIA.
4. Fix first those that block the user path (buttons without text, missing skip-link).
5. Repeat the automated check — ensure the violation count has dropped.
6. Perform manual testing with NVDA or JAWS on 3–5 key scenarios.

The cost of audit and modifications is calculated individually. Yearly savings on support can be substantial.

What is included in turnkey accessibility setup

We provide: an audit report with a full list of violations and recommendations, correction of all errors in template and component code, skip-link setup, semantic markup, contrasts, form improvements, re-audit after fixes, training for content managers, and developer documentation. We guarantee elimination of all critical violations. Contact us to assess your project. Order a free accessibility consultation for your Bitrix site.

Experience: over 50 accessibility projects on 1C-Bitrix, 5+ years in the market. We use WCAG 2.1 and Russian recommendations.