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 section on describe()](./documentation_style_guide.md#canvas-accessibility-descriptions-describe) 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

@@ -1222,6 +1222,32 @@ class Mover {
 
 ## Assets
 
+# Canvas Accessibility Descriptions: `describe()`
+
+To make p5.js sketches accessible, every example that draws to the canvas should include a call to [`describe()`](https://p5js.org/reference/#/p5/describe). This provides a concise, visual description for screen readers.
+
+**Best Practices for `describe()`:**
+
+- **Concise:** 1–3 sentences. Briefly describe what is visually present on the canvas.
+- **Visual-Only:** Focus on what a sighted user would see. Do not describe code, instructions, or interactions unless they are visually represented.
+- **Non-Redundant:** Avoid repeating information already available in the title or code comments.
+- **Clarity:** Use simple, direct language. End with punctuation for screen reader clarity.
+
+**Do/Don’t Examples:**
+
+| Do | Don’t |
+| --- | --- |
+| `describe('A blue rectangle in the center of a white canvas.');` | `describe('This code draws a rectangle.');` |
+| `describe('A red heart and yellow circle over a pink background.');` | `describe('Click to draw a heart.');` |
+| `describe('A black dot moves from bottom to top on a gray square.');` | `describe('A shape.');` |
+
+**More Guidance:**
+
+- 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 more best practices and rationale.
+- Reference examples must include a `describe()` call. See [Contributing to the p5.js Reference](./contributing_to_the_p5js_reference.md#add-a-canvas-description-using-describe) for details.
+
+
 - 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:

contributor_docs/web_accessibility.md

@@ -242,6 +242,8 @@ When creating screen reader-accessible outputs, naming the colors used in the ca
 
 ### describe()
 
+**See also:** [Documentation Style Guide: Canvas Accessibility Descriptions](./documentation_style_guide.md#canvas-accessibility-descriptions-describe) for best practices, Do/Don’t examples, and summary guidance on writing effective `describe()` calls.
+
 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):

src/type/textCore.js

@@ -753,45 +753,42 @@ function textCore(p5, fn) {
    * line using the renderer’s measurement functions. The final width is determined as the maximum width
    * among all these lines.
    *
-   * For example, if the text contains multiple lines due to wrapping or explicit line breaks, textWidth()
-   * will return the width of the longest line.
-   * 
-   * **Note:** In p5.js 2.0+, leading and trailing spaces are ignored.
-   * `textWidth("  Hello  ")` returns the same width as `textWidth("Hello")`.
+  * For example, if the text contains multiple lines due to wrapping or explicit line breaks, textWidth()
+  * will return the width of the longest line.
+  *
+  * <b>Whitespace note:</b> In p5.js 2.0+, leading and trailing spaces are ignored when measuring the bounding box.
+  * <code>textWidth("  Hello  ")</code> returns the same width as <code>textWidth("Hello")</code>.
+  * <code>textWidth(" ")</code> (a single space) may return 0, while <code>fontWidth(" ")</code> returns a nonzero width.
+  *
+  * <b>Comparison:</b>
+  * <ul>
+  *   <li><code>fontWidth('   x y   ')</code> includes all spaces; <code>textWidth('   x y   ')</code> may ignore them.</li>
+  *   <li><code>fontWidth(' ')</code> returns a nonzero width; <code>textWidth(' ')</code> may return 0.</li>
+  * </ul>
    *
    * @method textWidth
    * @for p5
    * @param {String} text The text to measure
    * @returns {Number} The width of the text
    *
-   * @example
-   * <div>
-   * <code>
-   * function setup() {
-   *   createCanvas(200, 200);
-   *   background(220);
-   *
-   *   // Set text size and alignment
-   *   textSize(48);
-   *   textAlign(LEFT, TOP);
-   *
-   *   let myText = "Hello";
-   *
-   *   // Calculate the width of the text
-   *   let tw = textWidth(myText);
-   *
-   *   // Draw the text on the canvas
-   *   fill(0);
-   *   text(myText, 50, 50);
-   *
-   *   // Display the text width below
-   *   noStroke();
-   *   fill(0);
-   *   textSize(20);
-   *   text("Text width: " + tw, 10, 150);
-   * }
-   * </code>
-   * </div>
+  * @example
+  * <div>
+  * <code>
+  * function setup() {
+  *   createCanvas(200, 100);
+  *   textSize(32);
+  *   let s1 = 'x y';
+  *   let s2 = '   x y   ';
+  *   let w1 = textWidth(s1);
+  *   let w2 = textWidth(s2);
+  *   text(s1, 10, 40);
+  *   text(s2, 10, 80);
+  *   line(10, 45, 10 + w1, 45); // underline tight width
+  *   line(10, 85, 10 + w2, 85); // underline tight width (ignores whitespace)
+  *   describe('Shows that textWidth for text with and without leading/trailing spaces is identical, as whitespace is ignored.');
+  * }
+  * </code>
+  * </div>
    *
    * @example
    * <div>