diff --git a/contributor_docs/contributing_to_the_p5js_reference.md b/contributor_docs/contributing_to_the_p5js_reference.md
index 770188b8b6..69a75536a3 100644
--- a/contributor_docs/contributing_to_the_p5js_reference.md
+++ b/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 `
*
```
-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.
diff --git a/contributor_docs/documentation_style_guide.md b/contributor_docs/documentation_style_guide.md
index be6a48ddda..43edb2a7ed 100644
--- a/contributor_docs/documentation_style_guide.md
+++ b/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)**
diff --git a/contributor_docs/web_accessibility.md b/contributor_docs/web_accessibility.md
index cafeb701ef..7fd38f5a32 100644
--- a/contributor_docs/web_accessibility.md
+++ b/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%
This generates the following HTML:
@@ -70,7 +70,8 @@ Each element can be selected to get more details. A table of elements is also pr
-
- orange circle, at top left, covering 1% of the canvas.
+ orange circle, at top
+ left, covering 1% of the canvas.
-
fuchsia square, 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 %_
@@ -123,8 +124,8 @@ The generated HTML is as follows:
Grid Output
- white canvas, 400 by 400 pixels, contains 2 shapes: 1 circle 1 square
-
+ white canvas, 400 by 400 pixels, contains 2 shapes: 1 circle 1 square
+
@@ -158,12 +159,10 @@ If a user passes `LABEL` as an argument to either of these functions, an additio

-
### 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 `` element is created next to the `