Improve Accessibility Guidance for describe() Usage (#8101)

contributor_docs/contributing_to_the_p5js_reference.md

@@ -308,7 +308,7 @@ Finally, for every example you add, you are required to use the p5.js function `
 * </div>
 ```
 
-For more on `describe()` visit the [web accessibility contributor documentation](./web_accessibility/#describe).
+For more on `describe()` visit the [web accessibility contributor documentation](./web_accessibility/#describe), and the [Writing Accessible Canvas Descriptions](https://p5js.org/tutorials/writing-accessible-canvas-descriptions/) tutorial.
 
 With all the above you should have most of the tools needed to write and edit p5.js reference comments. However, there are a few more specialized usage of JSDoc style reference comments that you may come across in p5.js. These are situationally useful and not something that you need often.
 

contributor_docs/documentation_style_guide.md

@@ -25,6 +25,7 @@ Our community is large and diverse. Many people learn to code using p5.js, and a
 ### Code
 - [Code Samples](#code-samples)
 - [Comments](#comments)
+- [Accessible Canvas Labels](#accessible-canvas-labels)
 - [Whitespace](#whitespace)
 - [Semicolons](#semicolons)
 - [Naming Conventions](#naming-conventions)
@@ -116,7 +117,7 @@ Always use `let` to declare variables.
 
 **Pronouns**
 
-| Recommended |	Not Recommended |
+| Recommended | Not Recommended |
 | -- | -- |
 | they | he or she |
 | them | him or her |
@@ -142,7 +143,7 @@ Always use `let` to declare variables.
 
 The following terminology is adapted from the WordPress documentation guidelines for [Writing inclusive documentation](https://make.wordpress.org/docs/style-guide/general-guidelines/inclusivity/#accessibility-terminology). For more background on people-first language, see the CDC's guide on [Communicating With and About People with Disabilities](https://www.cdc.gov/ncbddd/disabilityandhealth/materials/factsheets/fs-communicating-with-people.html).
 
-| Recommended |	Not Recommended |
+| Recommended | Not Recommended |
 | -- | -- |
 | person with disability | the disabled, handicapped, differently abled, challenged, abnormal |
 | person without disability | normal person, healthy person, able-bodied |
@@ -230,6 +231,50 @@ let magicWord = 'Please';
 
 ```
 
+
+**[⬆ back to top](#table-of-contents)**
+
+## Accessible Canvas Labels
+
+- Use `describe()` to in p5.js example code, to add labels to your canvas so that it’s readable for screen readers.
+
+> Why? It makes examples accessible to screen readers, and models how to write good canvas labels. 
+
+
+```javascript
+// Good.
+function setup() {
+  createCanvas(100, 100);
+  describe('A red heart in the bottom right corner of a pink background.');
+}
+
+// Bad.
+function setup() {
+  createCanvas(100, 100);
+  describe('heart shape');
+}
+
+// Good.
+function draw() {
+  background(220);
+  fill(0, 255, 0);
+  ellipse(mouseX, 50, 40, 40);
+  // Label updates with shape's translation.
+  describe(`A green circle at x pos ${round(mouseX)} moving with the mouse pointer.`, LABEL);
+}
+```
+
+- Don’t use screen reader labels as a way of commenting your code. Labels should only summarize the resulting visual elements within a canvas. 
+
+- Don’t overuse screen reader labels, as you may end up complicating the screen reader’s interpretation of the canvas rather than helping it.
+
+- Do make your label descriptions short and accurate. The recommended length for label descriptions is one to two sentences. Use full sentences for your labels, and write in the present tense when describing elements.
+
+The above examples and suggestions are based on the [Writing Accessible Canvas Descriptions tutorial](https://p5js.org/tutorials/writing-accessible-canvas-descriptions/). This tutorial gives more detailed guidance, and includes other ways to label your canvas, in addition to  `describe()`: `describeElement()`, `textOutput()`, and `gridOutput()`.
+
+To understand the structure of p5.js’ web accessibility features for contributors, see the [Web Accessibility Contributor Doc](./web_accessibility.md#user-generated-accessible-canvas-descriptions).
+
+
 **[⬆ back to top](#table-of-contents)**
 
 ## Whitespace

contributor_docs/web_accessibility.md

@@ -51,10 +51,10 @@ This description is followed by a list of shapes where the color, position, and
 > orange circle at top left covering 1% of the canvas.\
 > fuchsia square, at bottom right, covering 2% of the canvas.
 
-Each element can be selected to get more details. A table of elements is also provided. In this table, each element’s  shape, color, location, coordinates, and area are described:
+Each element can be selected to get more details. A table of elements is also provided. In this table, each element’s shape, color, location, coordinates, and area are described:
 
 > orange circle location=top left area=1%\
-> fuchsia square    location = bottom right    area = 2%
+> fuchsia square   location = bottom right area = 2%
 
 <details>
 <summary>This generates the following HTML:</summary>
@@ -100,7 +100,7 @@ Each element can be selected to get more details. A table of elements is also pr
 
 `gridOutput()` lays out the content of the canvas in the form of a grid using an HTML table element. Each shape’s location in the grid is based on its spatial location on the canvas. A brief description of the canvas is available before the table output. This description includes the color of the background, size of the canvas, number of objects, and object types:
 
-> lavender blue canvas, 400 by 400 pixels, contains 2 shapes:  1 circle 1 square
+> lavender blue canvas, 400 by 400 pixels, contains 2 shapes: 1 circle 1 square
 
 Each shape’s description is placed in a cell of the table depending on its location on the canvas. Each description includes the color and type of shape:
 
@@ -123,8 +123,8 @@ The generated HTML is as follows:
     <div id="defaultCanvas0gridOutput">
       Grid Output
       <p id="defaultCanvas0gridOutput_summary" aria-label="grid output summary">
-     white canvas, 400 by 400 pixels, contains 2 shapes:  1 circle 1 square
-   </p>
+        white canvas, 400 by 400 pixels, contains 2 shapes: 1 circle 1 square
+      </p>
       <table id="defaultCanvas0gridOutput_map" summary="grid output content">
         <tbody>
           <tr></tr>
@@ -272,7 +272,7 @@ The page will output:
 
 ### describeElement()
 
-The `describeElement()` function creates a screen reader-accessible description for groups of shapes that create meaning together. For example, a custom-drawn “heart” shape made out of multiple lines of code. The first parameter should be a string with the name of the element, for example, “Heart”. The second parameter should be a string with the description of the element, for example, “A red heart in the bottom-right corner.” The third parameter is optional. If a user passes `LABEL` as a third parameter, an additional `<div>` element is inserted next to the `<canvas>` element. The new \<div> will contain a visible version of the same  description embedded in the `<canvas>` element.
+The `describeElement()` function creates a screen reader-accessible description for groups of shapes that create meaning together. For example, a custom-drawn “heart” shape made out of multiple lines of code. The first parameter should be a string with the name of the element, for example, “Heart”. The second parameter should be a string with the description of the element, for example, “A red heart in the bottom-right corner.” The third parameter is optional. If a user passes `LABEL` as a third parameter, an additional `<div>` element is inserted next to the `<canvas>` element. The new \<div> will contain a visible version of the same description embedded in the `<canvas>` element.
 
 `describeElement()` is supported by several functions in [src/accessibility/describe.js](https://github.com/processing/p5.js/blob/main/src/accessibility/describe.js):
 
@@ -300,4 +300,3 @@ function setup() {
 The page will output:
 
 ![A p5.js canvas, followed by two lines of description: "A red heart and yellow circle over a pink background," and "Heart: A red heart in the bottom-right corner."](images/sketch-text-output3.png)
-