Product Ideas Portal

Replace "Description" and "Note" fields with "Issue", "User Impact", "Code Reference", etc. fields


Currently, the structure of a standard violation instance has two main fields where we write up the issue: the Description field and the Note field.

Description field

The Description field has three default sections delineated by words in square brackets, like this:

Here we write a high-level description of the violation...

[User Impact]
Here we write about who it affects...

[Code Reference]
Here we optionally provide a code example (it's not always available, for example in mobile audits or with reflow issues)

Less common bracket indicators in the Description field include:

  • [Pattern: pattern name...]: Not a section starter, but it provides a way to make it more obvious that an issue is part of a pattern.

  • [WCAG 2.1], [WCAG 2.0 Level AA], etc.: Not a section starter, but it provides a way to make it more obvious which standard version the violation came from.

  • [ADVISORY]: Not a section starter, but marks the issue as advisory

  • [Occurrence]: A section starter that either lists the modules that a pattern came from in brackets, or lists them in bullets with a detailed description of how the issue affects the module

  • [Validation/Regression - DATE - DEFECT STATUS]: Can be a section starter with details about the failure or passing of the violation.

Note field

The Note field has two default sections.

General description on how to fix the issue across the site, with detailed guidance when possible

[Compliant Code Example]
Here we provide a generic code example or a more detailed one, when possible.


  • Some clients rely on this data to be highly structured for importing purposes, but it's easy to mistype one of the words in a square bracket, to forget a bracket somewhere, or to include excess newlines, which can break their importing code.

  • The non-descriptive titles of "Description" and "Note" can be confusing to clients and can make it difficult for them to find the information they're looking for.

  • The use of brackets to either start a section (e.g. [Issue]) or simply add a flag to a violation (e.g. [WCAG 2.1]) provides a mixed metaphor that can be confusing.

  • After several rounds of validation, the addition of [Validation] sections often causes the Description field to hit the character limit.

  • It might be difficult to implement enhancements like a spell-checker, Markdown editor, or code formatter in the present layout.

Possible solutions

  • Consider allowing separate fields for these sections:

    • Issue

    • User Impact

    • Code Reference

    • Recommendation

    • Compliant Code Example

    • Validation/Regression notes

  • For "flags" like [Pattern], [WCAG 2.1], [ADVISORY], etc., I'm not sure of the best solution, but I think it would be good to try to avoid having to write them out in the issue text.

  • Hadley Luker
  • Sep 4 2020
  • Attach files