Improve Accessibility Guidance for `describe()` Usage #8101

NalinDalal · 2025-09-22T17:11:29Z

Addresses #6387

Changes:

Adding a new section to the documentation style guide with best practices and Do/Don’t examples for using describe().
Adding and clarifying cross-links between the style guide, web accessibility doc, and reference contribution guide.
Ensuring contributors can easily find and follow concise, visual, and non-redundant description guidelines for all reference examples.

Details:

Added a new “Canvas Accessibility Descriptions: describe()” section to documentation_style_guide.md, including best practices, a Do/Don’t table, and links to additional resources.
Added and clarified cross-links in contributing_to_the_p5js_reference.md and web_accessibility.md to make accessibility guidance more discoverable.
Confirmed there are no contradictions between the tutorial and contributor documentation.
Noted that some JSDoc reference examples (such as for ellipse() and line()) are missing or have weak describe() calls; this PR provides the groundwork for improving those examples.

Closes: #6387

PR Checklist

npm run lint passes
Inline reference is included / updated
Unit tests are included / updated

….js; simple docs are updated, not code

… to whitespace

…pposed to do

ksen0 · 2025-09-23T11:41:16Z

Hi @NalinDalal , thanks for preparing this. I left some comments, but most notably, I see that this PR has combined your work on the text-related reference which is a separate issue. Please isolate your PR to only contain what's related to the linked issue before implementing the suggestions. One way to isolate the PR would be to:

checkout dev-2.0, update it
create a new branch with e.g., git checkout -b describe-docs - this should switch to the branch
cherry pick only the relevant commits from this PR into that branch eg: git cherry-pick 2759e379591443bd19b0e92185903d9c9673d4ff

Then you can push and open a PR from that new branch, and work on it from there. In general / in the future, I would recommend working on separate branches for each issue in your fork, to avoid these collisions. (If you know other ways to clean up this PR so it focuses only on the linked issue, please feel free to do that, the above is just the most straightforward steps I typically recommend in this kind of situation - so I hope it helps, please let me know if you have questions.)

Lastly, you wrote:

Noted that some JSDoc reference examples (such as for ellipse() and line()) are missing or have weak describe() calls; this PR provides the groundwork for improving those examples.

Please either include this in the PR (it's still directly related to the issue) or change the link from "Resolves #6387" to "Addresses #6387" to avoid autoclosing. Totally up to you, either is alright!

contributor_docs/documentation_style_guide.md

ksen0 · 2025-09-23T11:25:58Z

contributor_docs/documentation_style_guide.md


+# 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.


Minor: In the style of the rest of the doc, this can be 1 bullet point, followed by the bullet points of each of the best practices you have below

ksen0 · 2025-09-23T11:27:00Z

contributor_docs/documentation_style_guide.md

+
+**Do/Don’t Examples:**
+
+| Do | Don’t |


In the style of the rest of this document, each of the above "best practices" should be illustrated with a "Good" and "Bad" example. Instead of splitting these and using sa table here, integrate illustrative examples in the list above.

ksen0 · 2025-09-23T11:27:21Z

contributor_docs/documentation_style_guide.md

+
+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()`:**


This line is not needed - the whole style guide tries to be as compact as possible

ksen0 · 2025-09-23T11:28:47Z

contributor_docs/documentation_style_guide.md

+
+- 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.


This should also not be repeated (this is not a universal suggestion - but the style guide tries to be very compact)

ksen0 · 2025-09-23T11:30:03Z

contributor_docs/documentation_style_guide.md

+
+**More Guidance:**
+
+- See the [Web Accessibility Contributor Doc](./web_accessibility.md#user-generated-accessible-canvas-descriptions) for technical details and examples.


Minor: consider simpler and more direct language. "New to writing accessible canvas descriptions? Please check the Web Accessibility Contributor Doc and Writing Accessible Canvas Descriptions tutorial next."

ksen0 · 2025-09-23T11:33:48Z

contributor_docs/web_accessibility.md


 ### 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.


Technically, this documentation is a more detailed doc than the above. What about something like: "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: Canvas Accessibility Descriptions)" - more focusing on the motivation of the style guide and its audience, than on passive description of its contents

NalinDalal

updated it

NalinDalal · 2025-09-23T12:38:22Z

contributor_docs/web_accessibility.md


 ### 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.


perminder-17 · 2025-10-02T20:34:33Z

contributor_docs/documentation_style_guide.md


 ### Code
+
+<<<<<<< HEAD


I think this needs to be removed.

perminder-17 · 2025-10-02T20:35:05Z

contributor_docs/documentation_style_guide.md

+  - [Arrow Functions](#arrow-functions)
+  - [Chaining](#chaining)
+  - [Classes](#classes)
+  - # [Assets](#assets)


There's something wrong with this? do you mean just [Assets](#assets) without a #?

perminder-17 · 2025-10-02T20:42:12Z

contributor_docs/documentation_style_guide.md


+Always load assets from a folder called "assets".
+
+# <<<<<<< HEAD


Here as well? this should be remove I guess.

perminder-17 · 2025-10-02T20:44:39Z

contributor_docs/documentation_style_guide.md

+
+## 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.


Minor: the link is not correct.

Suggested change

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.

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.

perminder-17 · 2025-10-02T20:46:15Z

contributor_docs/documentation_style_guide.md

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


I think you added so many quotes? was ">" added for a reason?

perminder-17 · 2025-10-02T20:47:35Z

contributor_docs/web_accessibility.md


 ### 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: [Canvas Accessibility Descriptions](./documentation_style_guide.md#canvas-accessibility-descriptions-describe))


Suggested change

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: [Canvas Accessibility Descriptions](./documentation_style_guide.md#canvas-accessibility-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: [Canvas Accessibility Descriptions](./documentation_style_guide.md#canvas-accessibility-descriptions-describe))

perminder-17 · 2025-10-02T20:49:25Z

contributor_docs/web_accessibility.md


 ### 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: [Canvas Accessibility Descriptions](./documentation_style_guide.md#canvas-accessibility-descriptions-describe))


Also, how about adding removing "Canvas Accessibility Descriptions" and adding the link on "Documentation Style Guide"?

…v-2.0

perminder-17 · 2025-10-13T09:24:25Z

contributor_docs/documentation_style_guide.md

+  - [Wording](#wording)
+  - [Unbiased Documentation](#unbiased-documentation)
+  - [Accessibility and Disability](#accessibility-and-disability)
+  - [Code Samples](#code-samples)


These content needs to be present inside Documentation Style Guide?

I’m not quite sure why it’s being added again under the “Documentation Style Guide” section, and then repeated inside the code section below.
For example, [Code Samples](#code-samples) appears both under the “Code/Documentation Style Guide” and again under the “Code” heading. Could you please clarify the reason for this duplication?

perminder-17 · 2025-10-13T09:43:15Z

contributor_docs/documentation_style_guide.md

 ```javascript
 // Bad.
-let bad = '\'this\' \i\s \"quoted\"';
+let bad = "'this' is \"quoted\"";


In this one, nothing is “broken.” It's just showing what not to do.

Like,

let bad = '\'this\' \i\s \"quoted\"';

It's telling that let bad = '\'this\' \i\s \"quoted\"'; will still evaluate to 'this' is "quoted" but it will harm it's readability so you could revert this change.

perminder-17 · 2025-10-13T09:44:26Z

contributor_docs/documentation_style_guide.md

 // Bad.
-let huh = a && b < 0 || c > 0 || d + 1 === 0;
+let huh = (a && b < 0) || c > 0 || d + 1 === 0;

 // Good.
-let huh = (a && b < 0) || c > 0 || (d + 1 === 0);
+let huh = (a && b < 0) || c > 0 || d + 1 === 0;

 // Bad.
-if (a || b && c) {
+if (a || (b && c)) {
  return d;
 }


Here also, you should revert the changes since it's telling what not to do, and you have fixed them :")

perminder-17 · 2025-10-13T09:44:58Z

contributor_docs/documentation_style_guide.md


 // Bad.
-let what = a + b / c * d;
+let what = a + (b / c) * d;


This change must also be reverted.

perminder-17 · 2025-10-13T09:45:10Z

contributor_docs/documentation_style_guide.md

 // Bad.
-if (mouseIsPressed === true)
-  circle(mouseX, mouseY, 50);
+if (mouseIsPressed === true) circle(mouseX, mouseY, 50);


This change should also be reverted.

perminder-17 · 2025-10-13T09:46:07Z

contributor_docs/documentation_style_guide.md

  thing2();
-}
-else {
+} else {


I think here also. Please have a look wherever we write // Bad does not needs to be fixed. :"). It's actually fixed in the whole file, So not pointing all the changes.

perminder-17 · 2025-10-13T09:52:31Z

contributor_docs/documentation_style_guide.md

+Always load assets from a folder called "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.
+


I noticed that this seems to be repeated, since the “## Accessible Descriptions” section already covers the same content. Was there a specific reason for including it here again?

perminder-17

I think these should be the last bits, after that we are good to go. Thanks for your hardwork on this.

NalinDalal and others added 9 commits September 14, 2025 23:09

Add fontWidth() and clarify textWidth vs fontWidth docs in attributes.js

06019f3

Merge branch 'processing:dev-2.0' into dev-2.0

8f24e3e

updated as per maintainers comment, only documentation is updated

0aaf553

Add fontWidth() and clarify textWidth vs fontWidth docs in attributes…

486e2db

….js; simple docs are updated, not code

Merge branch 'processing:dev-2.0' into dev-2.0

944779c

aded docs for difference between textWidth and fontWidth with respect…

6633de2

… to whitespace

unnecesaary file introduced, removed it, cleanedup the thing i was su…

eb58aba

…pposed to do

Merge branch 'processing:dev-2.0' into dev-2.0

78ce6ac

docs updated as asked

2759e37

ksen0 reviewed Sep 23, 2025

View reviewed changes

NalinDalal added 2 commits September 23, 2025 12:10

removed things from previous pr

3da06c0

i think done, if not will ask maintainer

f911702

NalinDalal commented Sep 23, 2025

View reviewed changes

NalinDalal and others added 4 commits September 24, 2025 08:23

Merge branch 'dev-2.0' into dev-2.0

a0fae01

check, merge conflicts

b218819

Merge branch 'dev-2.0' into dev-2.0

cebc00c

Merge branch 'dev-2.0' into dev-2.0

e2bd6b1

perminder-17 requested changes Oct 2, 2025

View reviewed changes

NalinDalal and others added 3 commits October 3, 2025 12:16

updated the docs as per suggesstion from perminder

8549b93

Merge branch 'dev-2.0' of https://github.com/NalinDalal/p5.js into de…

cf75292

…v-2.0

Merge branch 'processing:dev-2.0' into dev-2.0

51534d6

NalinDalal requested a review from perminder-17 October 12, 2025 16:12

perminder-17 reviewed Oct 13, 2025

View reviewed changes

perminder-17 requested changes Oct 13, 2025

View reviewed changes

perminder-17 reviewed Oct 13, 2025

View reviewed changes

perminder-17 requested changes Oct 13, 2025

View reviewed changes

fixes as per review

74601d0


		# 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.


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


		More Guidance:

		- See the [Web Accessibility Contributor Doc](./web_accessibility.md#user-generated-accessible-canvas-descriptions) for technical details and examples.


		### 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.


		Always load assets from a folder called "assets".

		# <<<<<<< HEAD


		## 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.


		### 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: [Canvas Accessibility Descriptions](./documentation_style_guide.md#canvas-accessibility-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: [Canvas Accessibility Descriptions](./documentation_style_guide.md#canvas-accessibility-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: [Canvas Accessibility Descriptions](./documentation_style_guide.md#canvas-accessibility-descriptions-describe))

Uh oh!

Improve Accessibility Guidance for describe() Usage #8101

Are you sure you want to change the base?

Improve Accessibility Guidance for describe() Usage #8101

Conversation

NalinDalal commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Checklist

Uh oh!

ksen0 commented Sep 23, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

NalinDalal left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

perminder-17 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Improve Accessibility Guidance for `describe()` Usage #8101

Improve Accessibility Guidance for `describe()` Usage #8101

NalinDalal commented Sep 22, 2025 •

edited

Loading