From b5787c94704fe6cc10ce0680dd0a85113a6bd141 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 e753bc591e3d59c38f2d4105ff799d24edb53889 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.