Webscan Documentation

Lesson 16 · Custom rules

Phase 4 · Auditing at scale — Lesson 16 of 21 · All lessons

Objective: understand what a custom rule is, write one that catches a pattern specific to your site, and know when it's the right tool.

Before you start: an organisation (Lesson 2) and some familiarity with findings (Lesson 5) and CSS selectors.

Why custom rules exist

The built-in scanner catches the standard accessibility barriers. But every codebase has its own recurring mistakes — a particular component that's always built wrong, an in-house widget the generic rules don't understand. You shouldn't have to wait for webscan to add a check for your pattern.

Custom rule — a detection rule you author, matching elements by CSS selector, that runs on every scan for your organisation and produces findings when it matches. It lets you teach webscan to catch a bad pattern specific to your site, with no code change and no waiting.

Key terms:

• Selector — a CSS selector (like .legacy-btn or div.modal) that picks out the elements the rule looks at. Same idea as everywhere else in webscan.
• Condition — what makes a match a problem (see the table below).
• Impact — the severity findings from this rule get (Critical / High / Medium / Low), so they slot into prioritisation.

The three conditions

When you create a rule you choose a condition — the thing that turns a matched element into a finding:

For the missing attribute condition you also specify which attribute to require.

Create a rule

1. From your organisation, open Custom rules and add one with: - a name and optional description (say why this pattern is a problem); - the selector to match; - the condition (and the attribute name, if the condition needs one); - the impact (severity) and an optional WCAG tag to map it to the standard; - the active toggle.
2. Save. From now on, every scan for your organisation runs this rule too, and any matches appear as ordinary findings — with your chosen impact and WCAG tag — flowing into verdicts and issues like everything else.

You can toggle a rule on/off at any time (handy while you tune it) or delete it.

When to use a custom rule (and when not)

Good uses:

• Ban a component your team has agreed never to use again.
• Enforce an in-house convention ("every custom control must have data-testid" — or, more usefully, a required ARIA attribute).
• Catch a recurring mistake the generic rules miss because it's specific to your markup.

Not the right tool when:

• The check needs real judgement or interaction — that's a manual audit (Lesson 14) or a recorded session (Lesson 15).
• A standard rule already covers it — don't duplicate the built-ins.

Tips & pitfalls

• Start narrow. A broad selector can flood every scan with findings. Target the specific class or element you mean, then widen only if needed.
• Set the impact honestly. The rule's impact feeds prioritisation (Lesson 17) — a best-practice nag marked Critical will drown out real criticals.
• Explain the rule in its description. Teammates (and future you) need to know why the pattern is banned, especially for an "exists" rule.
• Toggle, don't delete, while tuning. Turn a noisy rule off, refine the selector, turn it back on.

Recap

• A custom rule is an org-authored, selector-based check that runs on every scan and produces findings.
• Its condition decides what's a problem: element exists, missing accessible name, or missing an attribute.
• You set the impact and WCAG tag, and can toggle or delete it any time.
• Use it for site-specific patterns automation misses — not for things needing human judgement, and not to duplicate built-ins.

Try it yourself

Write one custom rule for a pattern on your site — for example, an "exists" rule banning a deprecated element, or a "missing accessible name" rule on your icon-button class. Run a scan and confirm your rule's findings appear with the impact you set.

Previous: ← Lesson 15 · Recorded audit sessions Next: Lesson 17 · Prioritisation & the verdict model →