From fab64f264b3aac75c045c9f6442aea8b1adab357 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 f28bd15610628b6ed30010afe4ac9054924a34f1 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.