From 2970b02436f0d207dd09e2b43e79510bf14b5b9f Mon Sep 17 00:00:00 2001 From: Ayush Date: Mon, 24 Aug 2026 20:10:27 +0530 Subject: [PATCH 1/2] docs: added describe function limits & best practices --- contributor_docs/web_accessibility.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/contributor_docs/web_accessibility.md b/contributor_docs/web_accessibility.md index b49abf8726..d52d6ac2ec 100644 --- a/contributor_docs/web_accessibility.md +++ b/contributor_docs/web_accessibility.md @@ -329,3 +329,10 @@ 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) + +### Best Practices + +When writing text for `describe()` and `describeElement()`, keep the following screen reader limitations in mind: + +- **Avoid transliterations:** Text-to-Speech (TTS) engines cannot reliably pronounce transliterations of languages. This makes it hard for screen reader users to understand the text. We encourage sketch creators to use their native script language when writing the text for describe functions. +- **macOS VoiceOver limitations:** macOS VoiceOver ignores the HTML `lang` attribute completely. As a result, Latin-script languages (Spanish, German, French, etc.) will be read with the default English voice, making it likely that words won't be pronounced correctly. From 63f9921884822298257ec6eea384222420f5797f Mon Sep 17 00:00:00 2001 From: Ayush Date: Mon, 24 Aug 2026 20:16:57 +0530 Subject: [PATCH 2/2] docs: added describe function limits & best practices --- contributor_docs/web_accessibility.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contributor_docs/web_accessibility.md b/contributor_docs/web_accessibility.md index d52d6ac2ec..370f519630 100644 --- a/contributor_docs/web_accessibility.md +++ b/contributor_docs/web_accessibility.md @@ -334,5 +334,5 @@ The page will output: When writing text for `describe()` and `describeElement()`, keep the following screen reader limitations in mind: -- **Avoid transliterations:** Text-to-Speech (TTS) engines cannot reliably pronounce transliterations of languages. This makes it hard for screen reader users to understand the text. We encourage sketch creators to use their native script language when writing the text for describe functions. -- **macOS VoiceOver limitations:** macOS VoiceOver ignores the HTML `lang` attribute completely. As a result, Latin-script languages (Spanish, German, French, etc.) will be read with the default English voice, making it likely that words won't be pronounced correctly. +- **Avoid transliterations:** Text to Speech (TTS) engines cannot reliably pronounce transliterations of languages. This makes it hard for screen reader users to understand the text. We encourage sketch creators to use their native script language when writing the text for describe functions. +- **macOS VoiceOver limitations:** macOS VoiceOver ignores the HTML `lang` attribute completely. As a result, Latin script languages (Spanish, German, French, etc.) will be read with the default English voice, making it likely that words won't be pronounced correctly.