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):