Improve Accessibility Guidance for describe() Usage

contributor_docs/contributing_to_the_p5js_reference.md

@@ -308,7 +308,11 @@ 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 writing effective `describe()` calls:
+- See the [Web Accessibility Contributor Doc](./web_accessibility.md#user-generated-accessible-canvas-descriptions) for technical details and examples.
+- See the [Writing Accessible Canvas Descriptions tutorial](https://p5js.org/tutorials/writing-accessible-canvas-descriptions/) for best practices and rationale.
+- See the [Documentation Style Guide: Accessible Descriptions](./documentation_style_guide.md#accessible-descriptions) for Do/Don’t examples and summary guidance.
 
 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

@@ -21,8 +21,28 @@ Our community is large and diverse. Many people learn to code using p5.js, and a
 - [Wording](#wording)
 - [Unbiased Documentation](#unbiased-documentation)
 - [Accessibility and Disability](#accessibility-and-disability)
+- [Documentation Style Guide](#documentation-style-guide)
 
 ### Code
+  - [Code Samples](#code-samples)
+  - [Comments](#comments)
+  - [Accessible Descriptions](#accessible-descriptions)
+  - [Whitespace](#whitespace)
+  - [Semicolons](#semicolons)
+  - [Naming Conventions](#naming-conventions)
+  - [Variables](#variables)
+  - [Strings](#strings)
+  - [Boolean Operators](#boolean-operators)
+  - [Conditionals](#conditionals)
+  - [Iteration](#iteration)
+  - [Objects](#objects)
+  - [Arrays](#arrays)
+  - [Functions](#functions)
+  - [Arrow Functions](#arrow-functions)
+  - [Chaining](#chaining)
+  - [Classes](#classes)
+  - [Assets](#assets)
+
 - [Code Samples](#code-samples)
 - [Comments](#comments)
 - [Whitespace](#whitespace)
@@ -116,7 +136,7 @@ Always use `let` to declare variables.
 
 **Pronouns**
 
-| Recommended |	Not Recommended |
+| Recommended | Not Recommended |
 | -- | -- |
 | they | he or she |
 | them | him or her |
@@ -142,7 +162,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 +250,25 @@ let magicWord = 'Please';
 
 ```
 
+
+## Accessible Descriptions
+
+- Use `describe()` to make p5.js sketches accessible to screen readers. All reference contributions should include a concise, visual canvas description for accessibility. When writing a `describe()` call:
+  - Be **concise**: 1–3 sentences briefly describing what is visually present on the canvas.
+    - Good: `describe('A blue rectangle in the center of a white canvas.');`
+    - Bad: `describe('This code draws a rectangle.');`
+  - Focus on **visuals only**: Describe what a sighted user would see. Do not describe code, instructions, or interactions unless they are visually represented.
+    - Good: `describe('A red heart and yellow circle over a pink background.');`
+    - Bad: `describe('Click to draw a heart.');`
+  - Be **non-redundant**: Avoid repeating information already in the title or code comments.
+    - Good: `describe('A black dot moves from bottom to top on a gray square.');`
+    - Bad: `describe('A shape.');`
+  - Use **clear, direct language**: End with punctuation for screen reader clarity.
+    - Good: `describe('A green triangle on a white background.');`
+    - Bad: `describe('triangle');`
+
+For more guidance, see the [Web Accessibility Contributor Doc](./web_accessibility.md#user-generated-accessible-canvas-descriptions) and the [Writing Accessible Canvas Descriptions tutorial](https://p5js.org/tutorials/writing-accessible-canvas-descriptions/).
+
 **[⬆ back to top](#table-of-contents)**
 
 ## Whitespace
@@ -1224,23 +1263,3 @@ class Mover {
 
 - Always load assets from a folder called "assets".
 
-> Why? It models good project organization. It's also required for assets to load on the p5.js website. Place assets in the following folders to include them in our online documentation:
-- Examples: [src/data/examples/assets](https://github.com/processing/p5.js-website/tree/main/src/data/examples)
-- Reference Pages: [src/templates/pages/reference/assets](https://github.com/processing/p5.js-website/tree/main/src/templates/pages/reference/assets)
-- Learn Pages: [src/assets/learn](https://github.com/processing/p5.js-website/tree/main/src/assets/learn)
-
-```javascript
-let img;
-
-// Bad.
-function preload() {
-  img = loadImage('moonwalk.jpg');
-}
-
-// Good.
-function preload() {
-  img = loadImage('assets/moonwalk.jpg');
-}
-```
-
-**[⬆ back to top](#table-of-contents)**

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>
@@ -70,7 +70,8 @@ Each element can be selected to get more details. A table of elements is also pr
         </p>
         <ul id="defaultCanvas0textOutput_list">
           <li>
-            <a href="#defaultCanvas0textOutputshape0">orange circle</a>, at top left, covering 1% of the canvas.
+            <a href="#defaultCanvas0textOutputshape0">orange circle</a>, at top
+            left, covering 1% of the canvas.
           </li>
           <li>
             <a href="#defaultCanvas0textOutputshape1">fuchsia square</a>, at bottom right, covering 2% of the canvas.
@@ -100,7 +101,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:
 
@@ -109,8 +110,8 @@ Each shape’s description is placed in a cell of the table depending on its loc
 
 These descriptions can be selected individually to get more details. A list of elements where shape, color, location, and area are described is also available:
 
-- *orange circle, location = top left, area = 1 %*
-- *fuchsia square, location = bottom right, area = 2 %*
+- _orange circle, location = top left, area = 1 %_
+- _fuchsia square, location = bottom right, area = 2 %_
 
 <details>
 <summary>
@@ -123,8 +124,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>
@@ -158,12 +159,10 @@ If a user passes `LABEL` as an argument to either of these functions, an additio
 
 ![A p5.js canvas, with the text descriptions described earlier present below it](images/sketch-text-output.png)
 
-
 ### Outputs structure
 
 Although `textOutput()` and `gridOutput()` are located in [src/accessibility/outputs.js](https://github.com/processing/p5.js/blob/main/src/accessibility/outputs.js), the outputs are created and updated using functions distributed across the library. This section details the different functions that support the accessible outputs.
 
-
 #### outputs.js
 
 [src/accessibility/outputs.js](https://github.com/processing/p5.js/blob/main/src/accessibility/outputs.js) includes two public methods:
@@ -208,7 +207,6 @@ When `this._accessibleOutputs.text` or `this._accessibleOutputs.text` are `true`
 - `_accsBackground()` is called in:
   - `p5.Renderer2D.prototype.background()`
 
-
 #### textOutput.js
 
 [src/accessibility/textOutput.js](https://github.com/processing/p5.js/blob/main/src/accessibility/textOutput.js) contains all the methods that update the text output. The main method in this file is `_updateTextOutput()` which is called by `_updateAccsOutput()` in [src/accessibility/outputs.js](https://github.com/processing/p5.js/blob/main/src/accessibility/outputs.js) when `this._accessibleOutputs.text` or `this._accessibleOutputs.textLabel` are `true.`
@@ -219,7 +217,6 @@ When `this._accessibleOutputs.text` or `this._accessibleOutputs.text` are `true`
 - `_shapeDetails()`: Builds the text output table that contains shape details.
 - `_shapeList()`: Builds the list of shapes of the text output.
 
-
 #### gridOutput.js
 
 [src/accessibility/gridOutput.js](https://github.com/processing/p5.js/blob/main/src/accessibility/gridOutput.js) contains all methods that update the grid output. The main method in this file is `_updateGridOutput()`, which is called by `_updateAccsOutput()` in [src/accessibility/outputs.js](https://github.com/processing/p5.js/blob/main/src/accessibility/outputs.js) when `this._accessibleOutputs.grid` or `this._accessibleOutputs.gridLabel` are `true.`
@@ -230,18 +227,18 @@ When `this._accessibleOutputs.text` or `this._accessibleOutputs.text` are `true`
 - `_gridMap()`: Builds a grid that maps the location of shapes on the canvas.
 - `_gridShapeDetails()`: Builds the list of shapes of the grid output, each line of the list includes details about the shape.
 
-
 #### color\_namer.js
 
-When creating screen reader-accessible outputs, naming the colors used in the canvas is important. [src/accessibility/color\_namer.js](https://github.com/processing/p5.js/blob/main/src/accessibility/color_namer.js) contains `_rgbColorName()` a method that receives RGBA values and returns a color name. This function is called by `_accsBackground()` and `_accsCanvasColors` in [src/accessibility/outputs.js](https://github.com/processing/p5.js/blob/main/src/accessibility/outputs.js).
+When creating screen reader-accessible outputs, naming the colors used in the canvas is important. [src/accessibility/color_namer.js](https://github.com/processing/p5.js/blob/main/src/accessibility/color\_namer.js) contains `_rgbColorName()` a method that receives RGBA values and returns a color name. This function is called by `_accsBackground()` and `_accsCanvasColors` in [src/accessibility/outputs.js](https://github.com/processing/p5.js/blob/main/src/accessibility/outputs.js).
 
 `_rgbColorName()` uses `p5.color_conversion._rgbaToHSBA()` to get the HSV values of the color and then uses `_calculateColor()` to get the color name. The function `_calculateColor()` in this file comes from [colorNamer.js](https://github.com/MathuraMG/color-namer), which was developed as part of a [2018 Processing Foundation fellowship](https://medium.com/processing-foundation/making-p5-js-accessible-e2ce366e05a0) and in consultation with blind screen reader expert users. This function returns color names by comparing HSV values to those stored in the `colorLookUp` array, returning the closest color name as a string.
 
-
 ## User-generated accessible canvas descriptions
 
 ### describe()
 
+`describe()` is one of the ways that p5.js sketches can be made accessible to screen readers. All contributions to the reference should include accessible canvas descriptions (see: [Documentation Style Guide](./documentation_style_guide.md#canvas-accessibility-descriptions-describe))
+
 The `describe()` function creates a sketch author-defined screen reader accessible description for the canvas. The first parameter should be a string with a description of the canvas. The second parameter is optional. If specified, it determines how the description is displayed. If a user passes `LABEL` as a second parameter, an additional `<div>` element is created next to the `<canvas>` element. The new `<div>` element contains a visible version of the same screen reader-accessible description embedded in the `<canvas>` element.
 
 `describe()` is supported by several methods in [src/accessibility/describe.js](https://github.com/processing/p5.js/blob/main/src/accessibility/describe.js):
@@ -269,10 +266,9 @@ The page will output:
 
 ![A p5.js canvas, with a description below reading, "A pink square with a red heart in the bottom-right corner."](images/sketch-text-output2.png)
 
-
 ### 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 +296,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)
-

src/type/textCore.js

@@ -2737,4 +2737,4 @@ export default textCore;
 
 if (typeof p5 !== 'undefined') {
   textCore(p5, p5.prototype);
-}
+}