From 5cc3f9761e00734b9cdc5360ae14eae10208936f Mon Sep 17 00:00:00 2001 From: Nalin Dalal <116961144+NalinDalal@users.noreply.github.com> Date: Sun, 9 Nov 2025 23:40:30 +0530 Subject: [PATCH] Improve Accessibility Guidance for `describe()` Usage (#8101) * Add fontWidth() and clarify textWidth vs fontWidth docs in attributes.js * updated as per maintainers comment, only documentation is updated * Add fontWidth() and clarify textWidth vs fontWidth docs in attributes.js; simple docs are updated, not code * aded docs for difference between textWidth and fontWidth with respect to whitespace * unnecesaary file introduced, removed it, cleanedup the thing i was supposed to do * docs updated as asked * removed things from previous pr * i think done, if not will ask maintainer * check, merge conflicts * updated the docs as per suggesstion from perminder * fixes as per review * updated the bad code and good code examples, so actually now can diffrentiated b/w them * fix:inverted comma typos * invert typos * invert typos * invert typos * invert typos * invert typos * invert typos * invert typos * invert typos * invert typos * invert typos * invert typos * invert typos * invert typos * invert typos * invert typos * invert typos * invert typos * invert typos * invert typos to do fix * invert typos to do fix * invert typos to do fix * invert typos to do fix * invert typos to do fix * invert typos to do fix * invert typos to do fix * invert typos to do fix * invert typos to do fix * invert typos to do fix * invert typos to do fix * invert typos to do fix * invert typos to do fix * had docs style section repeated, removed to resolve redundancy * Tidy web accessibility updates * Tidy updates to documentation style guide * Tidy documentation style guide table of contents * Tidy web accessibility references in contributor docs * Tidy contributing documentation for describe() * Tidy unintended change in textCore.js * Update contributor_docs/documentation_style_guide.md --------- Co-authored-by: kit <1304340+ksen0@users.noreply.github.com> Co-authored-by: Perminder Singh <127239756+perminder-17@users.noreply.github.com> --- .../contributing_to_the_p5js_reference.md | 2 +- contributor_docs/documentation_style_guide.md | 49 ++++++++++++++++++- contributor_docs/web_accessibility.md | 13 +++-- 3 files changed, 54 insertions(+), 10 deletions(-) diff --git a/contributor_docs/contributing_to_the_p5js_reference.md b/contributor_docs/contributing_to_the_p5js_reference.md index 770188b8b6..8166404d47 100644 --- a/contributor_docs/contributing_to_the_p5js_reference.md +++ b/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 ` * ``` -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. diff --git a/contributor_docs/documentation_style_guide.md b/contributor_docs/documentation_style_guide.md index c238180172..836a7d7ed0 100644 --- a/contributor_docs/documentation_style_guide.md +++ b/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 diff --git a/contributor_docs/web_accessibility.md b/contributor_docs/web_accessibility.md index cafeb701ef..2d2f62e54d 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: @@ -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:
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 +

@@ -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 `
` element is inserted next to the `` element. The new \
will contain a visible version of the same description embedded in the `` 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 `
` element is inserted next to the `` element. The new \
will contain a visible version of the same description embedded in the `` 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) -