Download the PHP package phildaiguille/twig-a11y-rules without Composer

twig-a11y-rules

Accessibility linting rules for Twig templates, built on top of vincentlanglet/twig-cs-fixer.

What is this?

twig-a11y-rules is a standalone package of accessibility rules for Twig templates. It integrates with twig-cs-fixer and statically checks your templates for known accessibility issues — missing alt attributes, empty buttons, invalid ARIA roles, and more.

Note: Static analysis cannot guarantee full accessibility. Manual testing remains essential.

Inspired by Deque's Axe Linter and built as a modern successor to the unmaintained nielsdeblaauw/twigcs-a11y.

Requirements

• PHP >= 8.4
• vincentlanglet/twig-cs-fixer ^4.0

Installation

This package provides rules only — it does not expose its own binary. Use the twig-cs-fixer binary to run linting.

Usage

Create a .twig-cs-fixer.php configuration file at the root of your project:

Use $config->getRuleset() rather than $config->setRuleset(new Ruleset()): Config already loads the TwigCsFixer standard into its ruleset, and replacing it with an empty Ruleset disables all Twig formatting lint. Only pass a fresh ruleset to setRuleset() if you explicitly want the a11y rules only.

Standards

To make it easier to enable a sensible set of accessibility rules, this package provides a reusable standard. Rather than adding many rules one-by-one, you can add the standard to your Ruleset:

There are four presets with increasing coverage:

• A11yBasicStandard: lowest-noise checks for core HTML issues.
• A11yRecommendedStandard: broader structural, media, and form coverage.
• A11yStandard: the default balanced preset for most projects.
• A11yStrict: every stable rule shipped by this package.

Then run:

Symfony

Put .twig-cs-fixer.php next to composer.json and lint the templates/ directory:

Layouts (base.html.twig), child templates, partials, form themes and Twig UX components are recognised: page-level rules only run on complete pages (see Template classification).

Silencing a violation

Each violation has an identifier <Rule>.<MessageId>. Use it in a twig-cs-fixer comment, or the rule name alone to silence the whole rule:

Rules

See src/Rules/ for the full list.

This ruleset includes automated accessibility checks for common issues in Twig templates. Rules are grouped by category for easier discovery. The Preset column indicates the earliest preset that activates the rule.

Media

Structure

Forms

ARIA

Anchor

UI

Note on static analysis limits: some accessibility checks cannot be evaluated statically from template source alone. Rules such as color-contrast-enhanced, focus-visible, identical-links-same-purpose, CSS-based target-size, aria-labelledby-valid, frame-tested, and avoid-inline-spacing require runtime context. Use a browser-based tool such as axe DevTools or Lighthouse alongside this linter for complete coverage.

ColorContrastRule and TargetSizeRule are best-effort, inline-only checks: they only inspect style="..." attributes present directly in the template source. Contrast ratios and target sizes driven by external CSS, CSS variables, or computed styles are not detected. These rules reduce the chance of obvious mistakes in quick-markup situations; they are not a substitute for a full browser-based audit.

Contributing

Contributions are welcome — whether it's a new rule, a bug fix, or an improvement to existing ones.

1. Fork the repository and create a branch
2. Follow the TDD workflow described in CONTRIBUTING.md
3. Open a pull request with a clear description

Running the test suite locally

Adding a new rule

Each rule lives in src/Rules/{Category}/ and must have:

• A test class in tests/Rules/{Category}/
• Valid and invalid .html.twig fixtures in tests/Rules/{Category}/Fixtures/

See CONTRIBUTING.md for the full conventions, and ROADMAP.md for what is planned next.

Template classification and rule scoping

Some rules are "page-level" and must only run on full HTML pages (to avoid flagging partials/components). To make this reliable we introduce a simple TemplateKind classifier used by the rules engine:

• TemplateKind::FullPage: contains both <html> and <body> and isn't an extending child.
• TemplateKind::ChildTemplate: contains {% extends %}.
• TemplateKind::ParentTemplate: contains {% block %} but no <html>.
• TemplateKind::Partial: no <html>/<body>, typical component fragment.
• TemplateKind::MixedTemplate: {% extends %} + own {% block %}.
• TemplateKind::TwigUxComponent: uses {% props %} (Twig UX style components).

Rules may declare which kinds they support. Page-level rules such as LangAttributeRule, LandmarkRule, SkipLinkRule and MetaViewportRule are scoped to FullPage only — this prevents false positives on components and partials.

If you add a new page-level rule, include a partial fixture in the valid fixtures to document this decision and prevent regressions.

Versioning & backward compatibility

This package follows Semantic Versioning.

Public API (breaking changes only in a major release):

• Rule class names and namespaces under TwigA11y\Rules\
• Violation identifiers (<Rule>.<MessageId>, e.g. InputLabel.MissingLabel) — used in {# twig-cs-fixer-disable-line ... #} comments and in your own baselines
• The four standards under TwigA11y\Standard\ and their constructors

Not covered (may change in any release):

• Rule internals, AbstractA11yRule protected members, TokenCollectorTrait
• The exact wording of error messages
• The TwigA11y\Template\ classifier internals

New rules in an existing preset are a minor release. They may surface new errors in templates that previously passed. Pin an exact version if your CI cannot tolerate that.

License

MIT — see LICENSE.