diff --git a/contributor_docs/contributing_to_the_p5js_reference.md b/contributor_docs/contributing_to_the_p5js_reference.md index 770188b8b6..79068419c4 100644 --- a/contributor_docs/contributing_to_the_p5js_reference.md +++ b/contributor_docs/contributing_to_the_p5js_reference.md @@ -308,7 +308,11 @@ 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 writing effective `describe()` calls: +- 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 best practices and rationale. +- See the [Documentation Style Guide section on describe()](./documentation_style_guide.md#canvas-accessibility-descriptions-describe) for Do/Don’t examples and summary guidance. 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 be6a48ddda..06d24f4875 100644 --- a/contributor_docs/documentation_style_guide.md +++ b/contributor_docs/documentation_style_guide.md @@ -9,12 +9,14 @@ Hello! Welcome to the guidelines for writing p5.js documentation. This document - Airbnb [JavaScript Style Guide](https://airbnb.io/javascript/) (MIT) Our community is large and diverse. Many people learn to code using p5.js, and a large subset of those people are students in K–12 classes. After reading this guide, you will know: + - How to write effective, inclusive, and accessible prose for documentation purposes. - How to write simple code samples for documentation purposes. ## Table of Contents ### Writing + - [YUIDoc](#yuidoc) - [English](#english) - [Oxford Comma](#oxford-comma) @@ -23,6 +25,37 @@ Our community is large and diverse. Many people learn to code using p5.js, and a - [Accessibility and Disability](#accessibility-and-disability) ### Code + +- [Documentation Style Guide](#documentation-style-guide) + + - [Table of Contents](#table-of-contents) + - [Writing](#writing) + - [Code](#code) + - [YUIDoc](#yuidoc) + - [English](#english) + - [Oxford Comma](#oxford-comma) + - [Wording](#wording) + - [Unbiased Documentation](#unbiased-documentation) + - [Accessibility and Disability](#accessibility-and-disability) + - [Code Samples](#code-samples) + - [Comments](#comments) + - [Accessible Descriptions](#accessible-descriptions) + - [Whitespace](#whitespace) + - [Semicolons](#semicolons) + - [Naming Conventions](#naming-conventions) + - [Variables](#variables) + - [Strings](#strings) + - [Boolean Operators](#boolean-operators) + - [Conditionals](#conditionals) + - [Iteration](#iteration) + - [Objects](#objects) + - [Arrays](#arrays) + - [Functions](#functions) + - [Arrow Functions](#arrow-functions) + - [Chaining](#chaining) + - [Classes](#classes) + - [Assets](#assets) + - [Code Samples](#code-samples) - [Comments](#comments) - [Whitespace](#whitespace) @@ -116,13 +149,13 @@ Always use `let` to declare variables. **Pronouns** -| Recommended | Not Recommended | -| -- | -- | -| they | he or she | -| them | him or her | -| their | his or her | -| theirs | his or hers | -| themselves | himself or herself | +| Recommended | Not Recommended | +| ----------- | ------------------ | +| they | he or she | +| them | him or her | +| their | his or her | +| theirs | his or hers | +| themselves | himself or herself | **[⬆ back to top](#table-of-contents)** @@ -142,16 +175,16 @@ 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 | -| -- | -- | -| person with disability | the disabled, handicapped, differently abled, challenged, abnormal | -| person without disability | normal person, healthy person, able-bodied | -| has [disability] | victim of, suffering from, affected by, stricken with | -| unable to speak, uses synthetic speech | dumb, mute | -| deaf, low-hearing | hearing-impaired | -| blind, low-vision | vision-impaired, visually-challenged | -| cognitive or developmental disabilities | mentally-challenged, slow-learner | -| person with limited mobility, person with a physical disability | crippled, handicapped | +| Recommended | Not Recommended | +| --------------------------------------------------------------- | ------------------------------------------------------------------ | +| person with disability | the disabled, handicapped, differently abled, challenged, abnormal | +| person without disability | normal person, healthy person, able-bodied | +| has [disability] | victim of, suffering from, affected by, stricken with | +| unable to speak, uses synthetic speech | dumb, mute | +| deaf, low-hearing | hearing-impaired | +| blind, low-vision | vision-impaired, visually-challenged | +| cognitive or developmental disabilities | mentally-challenged, slow-learner | +| person with limited mobility, person with a physical disability | crippled, handicapped | ## Code Samples @@ -165,16 +198,16 @@ Choose meaningful code samples that cover the basics as well as gotchas. Only us ```javascript // Bad. -let magicWord = 'Please'; // Remember this. +let magicWord = "Please"; //Remember this. // Good. // Remember this. -let magicWord = 'Please'; +let magicWord = "Please"; // Bad. if (keyIsPressed === true) { thing1(); - // This is an important note. + //This is an important note. thing2(); } @@ -192,34 +225,24 @@ if (keyIsPressed === true) { ```javascript // Bad. //Remember this. -let magicWord = 'Please'; +let magicWord = "Please"; // Good. // Remember this. -let magicWord = 'Please'; +let magicWord = "Please"; ``` - Use `//` for multiline comments. ```javascript - // Bad. -/** - * I will use // for multiline comments. - * I will use // for multiline comments. - * I will use // for multiline comments. - * I will use // for multiline comments. - * I will use // for multiline comments. - */ - -//Bad. /* - I will use // for multiline comments. - I will use // for multiline comments. - I will use // for multiline comments. - I will use // for multiline comments. - I will use // for multiline comments. - */ +I will use // for multiline comments. +I will use // for multiline comments. +I will use // for multiline comments. +I will use // for multiline comments. +I will use // for multiline comments. +*/ // Good. // I will use // for multiline comments. @@ -227,9 +250,33 @@ let magicWord = 'Please'; // I will use // for multiline comments. // I will use // for multiline comments. // I will use // for multiline comments. - ``` +## Accessible Descriptions + +- Use `describe()` to make p5.js sketches accessible to screen readers. All reference contributions should include a concise, visual canvas description for accessibility. + +- **Concise:** 1–3 sentences. Briefly describe what is visually present on the canvas. + + - Good: `describe('A blue rectangle in the center of a white canvas.');` + - Bad: `describe('This code draws a rectangle.');` + +- **Visual-Only:** Focus on what a sighted user would see. Do not describe code, instructions, or interactions unless they are visually represented. + + - Good: `describe('A red heart and yellow circle over a pink background.');` + - Bad: `describe('Click to draw a heart.');` + +- **Non-Redundant:** Avoid repeating information already available in the title or code comments. + + - Good: `describe('A black dot moves from bottom to top on a gray square.');` + - Bad: `describe('A shape.');` + +- **Clarity:** Use simple, direct language. End with punctuation for screen reader clarity. + - Good: `describe('A green triangle on a white background.');` + - Bad: `describe('triangle');` + +New to writing accessible canvas descriptions? Please check the [Web Accessibility Contributor Doc](./web_accessibility.md#user-generated-accessible-canvas-descriptions) and [Writing Accessible Canvas Descriptions tutorial](https://p5js.org/tutorials/writing-accessible-canvas-descriptions/) next. + **[⬆ back to top](#table-of-contents)** ## Whitespace @@ -257,7 +304,7 @@ function setup() { ```javascript // Bad. -function setup(){ +function setup() { createCanvas(400, 400); } @@ -271,8 +318,8 @@ function setup() { ```javascript // Bad. -if(keyIsPressed === true) { - doStuff (); +if (keyIsPressed === true) { + doStuff(); } // Good. @@ -281,8 +328,8 @@ if (keyIsPressed === true) { } // Bad. -function setup () { - createCanvas (400, 400); +function setup() { + createCanvas(400, 400); } // Good. @@ -295,7 +342,7 @@ function setup() { ```javascript // Bad. -let y=x+5; +let y = x + 5; // Good. let y = x + 5; @@ -309,7 +356,7 @@ let y = x + 5; ```javascript // Bad. -let x = 0 +let x = 0; // Good. let x = 0; @@ -408,12 +455,12 @@ let y = 200; ```javascript // Bad. -flower = '🌸'; -var flower = '🌸'; -const flower = '🌸'; +flower = "🌸"; +var flower = "🌸"; +const flower = "🌸"; // Good. -let flower = '🌸'; +let flower = "🌸"; ``` - Use one `let` declaration per variable or assignment. @@ -424,12 +471,12 @@ let flower = '🌸'; // Bad. let positions = getPositions(), startSearch = true, - dragonball = 'z'; + dragonball = "z"; // Good. let positions = getPositions(); let startSearch = true; -let dragonball = 'z'; +let dragonball = "z"; ``` - Assign variables where needed and place them in a reasonable place. @@ -438,23 +485,23 @@ let dragonball = 'z'; ```javascript // Bad - unnecessary search. -function getCharacter(name = 'default') { +function getCharacter(name = "default") { let character = characters.find((c) => c.name === name); - if (name === 'default') { + if (name === "default") { return false; } if (character) { return character; } - + return false; } // Good. -function getCharacter(name = 'default') { - if (name === 'default') { +function getCharacter(name = "default") { + if (name === "default") { return false; } @@ -463,7 +510,7 @@ function getCharacter(name = 'default') { if (character) { return character; } - + return false; } ``` @@ -498,7 +545,7 @@ let name = "Hilma af Klint"; let name = `Hilma af Klint`; // Good. -let name = 'Hilma af Klint'; +let name = "Hilma af Klint"; ``` - Don't concatenate strings that cause the line to go over 80 characters. @@ -507,15 +554,18 @@ let name = 'Hilma af Klint'; ```javascript // Bad. -let essay = 'You see us as you want to see us: \ -in the simplest terms, in the most convenient definitions.'; +let essay = + "You see us as you want to see us: \ +in the simplest terms, in the most convenient definitions."; // Bad. -let essay = 'You see us as you want to see us: ' + - 'in the simplest terms, in the most convenient definitions.'; +let essay = + "You see us as you want to see us: " + + "in the simplest terms, in the most convenient definitions."; // Good. -let essay = 'You see us as you want to see us: in the simplest terms, in the most convenient definitions.'; +let essay = + "You see us as you want to see us: in the simplest terms, in the most convenient definitions."; ``` - Use template strings instead of concatenation when needed. @@ -523,10 +573,14 @@ let essay = 'You see us as you want to see us: in the simplest terms, in the mos > Why? Template strings have a concise syntax. They also provide proper newlines and string interpolation features. ```javascript -let name = 'Dave'; +let name = "Dave"; // Bad. -text(name + ', this conversation can serve no purpose anymore. Goodbye.' + name, 0, 0); +text( + name + ", this conversation can serve no purpose anymore. Goodbye." + name, + 0, + 0 +); // Good. text(`${name}, this conversation can serve no purpose anymore. Goodbye.`, 0, 0); @@ -538,7 +592,7 @@ text(`${name}, this conversation can serve no purpose anymore. Goodbye.`, 0, 0); ```javascript // Bad. -let bad = '\'this\' \i\s \"quoted\"'; +let bad = "'this' is \"quoted\""; // Good. let good = 'Air quotes make you look "cool".'; @@ -571,7 +625,7 @@ if (name) { } // Good. -if (name !== '') { +if (name !== "") { // ... } @@ -594,13 +648,13 @@ if (collection.length > 0) { ```javascript // 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; } @@ -610,7 +664,7 @@ if (a || (b && c)) { } // Bad. -let what = a + b / c * d; +let what = a + (b / c) * d; // Good. let what = a + (b / c) * d; @@ -622,8 +676,7 @@ let what = a + (b / c) * d; ```javascript // Bad. -if (mouseIsPressed === true) - circle(mouseX, mouseY, 50); +if (mouseIsPressed === true) circle(mouseX, mouseY, 50); // Better. if (mouseIsPressed === true) circle(mouseX, mouseY, 50); @@ -641,8 +694,7 @@ if (mouseIsPressed === true) { if (mouseIsPressed === true) { thing1(); thing2(); -} -else { +} else { thing3(); } @@ -683,15 +735,19 @@ function mouseIsOnLeft() { ```javascript // Bad. -if ((number === 123 || letters === 'abc') && mouseIsPressed === true && keyIsPressed === true) { +if ( + (number === 123 || letters === "abc") && + mouseIsPressed === true && + keyIsPressed === true +) { doStuff(); } // Good. if ( - (number === 123 || letters === 'abc') - && mouseIsPressed === true - && keyIsPressed === true + (number === 123 || letters === "abc") && + mouseIsPressed === true && + keyIsPressed === true ) { doStuff(); } @@ -777,16 +833,16 @@ let ball = {}; ```javascript // Bad. let secretObject = { - 'x': 100, - 'y': 200, - 'top-secret': 'classified', + x: 100, + y: 200, + "top-secret": "classified", }; // Good. let secretObject = { x: 3, y: 4, - 'top-secret': 'classified', + "top-secret": "classified", }; ``` @@ -794,14 +850,14 @@ let secretObject = { ```javascript let turtle = { - name: 'Leonardo', - color: 'dodgerblue', - weapon: '🗡️', - food: '🍕', + name: "Leonardo", + color: "dodgerblue", + weapon: "🗡️", + food: "🍕", }; // Bad. -let turtleName = turtle['name']; +let turtleName = turtle["name"]; // Good. let turtleName = turtle.name; @@ -811,17 +867,17 @@ let turtleName = turtle.name; ```javascript let turtle = { - name: 'Leonardo', - color: 'dodgerblue', - weapon: '🗡️', - food: '🍕', + name: "Leonardo", + color: "dodgerblue", + weapon: "🗡️", + food: "🍕", }; function getProp(prop) { return turtle[prop]; } -let turtleName = getProp('name'); +let turtleName = getProp("name"); ``` - Don't use leading commas. @@ -829,14 +885,14 @@ let turtleName = getProp('name'); ```javascript // Bad. let mathematician = { - firstName: 'Ada' - , lastName: 'Lovelace' + firstName: "Ada", + lastName: "Lovelace", }; // Good. let mathematician = { - firstName: 'Ada', - lastName: 'Lovelace', + firstName: "Ada", + lastName: "Lovelace", }; ``` @@ -845,14 +901,14 @@ let mathematician = { ```javascript // Bad. let artist = { - firstName: 'Lauren', - lastName: 'McCarthy' + firstName: "Lauren", + lastName: "McCarthy", }; // Good. let artist = { - firstName: 'Lauren', - lastName: 'McCarthy', + firstName: "Lauren", + lastName: "McCarthy", }; ``` @@ -876,10 +932,10 @@ let images = []; let lyrics = []; // Bad. -lyrics[lyrics.length] = 'Little rough around the edges, but I keep it smooth'; +lyrics[lyrics.length] = "Little rough around the edges, but I keep it smooth"; // Good. -lyrics.push('Little rough around the edges, but I keep it smooth'); +lyrics.push("Little rough around the edges, but I keep it smooth"); ``` - Use the `slice()` method to copy arrays. @@ -900,9 +956,11 @@ let numbersCopy = numbers.slice(); ```javascript // Bad. -let matrix = [[1, 0, 0], - [0, 1, 0], - [0, 0, 1]]; +let matrix = [ + [1, 0, 0], + [0, 1, 0], + [0, 0, 1], +]; // Good. let matrix = [ @@ -912,7 +970,11 @@ let matrix = [ ]; // Also good. -let matrix = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]; +let matrix = [ + [1, 0, 0], + [0, 1, 0], + [0, 0, 1], +]; ``` **[⬆ back to top](#table-of-contents)** @@ -982,29 +1044,28 @@ function drawSpiral(length, angle = 90) { ```javascript // Bad. function setup() { - loadImage('assets/moonwalk.jpg', function (img) { + loadImage("assets/moonwalk.jpg", function (img) { image(img, 0, 0); }); } - // Good. function setup() { - loadImage('assets/moonwalk.jpg', (img) => { + loadImage("assets/moonwalk.jpg", (img) => { image(img, 0, 0); }); } // Bad. function preload() { - loadImage('assets/moonwalk.jpg', (img) => { + loadImage("assets/moonwalk.jpg", (img) => { // Complex preprocessing... }); } // Good. function preload() { - loadImage('assets/moonwalk.jpg', processImage); + loadImage("assets/moonwalk.jpg", processImage); } function processImage(img) { @@ -1039,24 +1100,23 @@ function processImage(img) { ```javascript // Bad. -[1, 2, 3].map(number => number * number); +[1, 2, 3].map((number) => number * number); // Good. [1, 2, 3].map((number) => number * number); ``` + **[⬆ back to top](#table-of-contents)** ## Chaining -* Use individual function calls instead of function chaining. +- Use individual function calls instead of function chaining. > Why? To accommodate users who may not be familiar with the concept of function chaining. ```javascript // Bad. -fill(0) - .strokeWeight(6) - .textSize(20); +fill(0).strokeWeight(6).textSize(20); // Bad. fill(0).strokeWeight(6).textSize(20); @@ -1205,7 +1265,7 @@ class Mover { // Good. class Mover { // ... - + update() { this.x += this.xspeed; this.y += this.yspeed; @@ -1222,24 +1282,50 @@ class Mover { ## Assets +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. + +**Best Practices for `describe()`:** + +- **Concise:** 1–3 sentences. Briefly describe what is visually present on the canvas. +- **Visual-Only:** Focus on what a sighted user would see. Do not describe code, instructions, or interactions unless they are visually represented. +- **Non-Redundant:** Avoid repeating information already available in the title or code comments. +- **Clarity:** Use simple, direct language. End with punctuation for screen reader clarity. + +**Do/Don’t Examples:** + +| Do | Don’t | +| --------------------------------------------------------------------- | ------------------------------------------- | +| `describe('A blue rectangle in the center of a white canvas.');` | `describe('This code draws a rectangle.');` | +| `describe('A red heart and yellow circle over a pink background.');` | `describe('Click to draw a heart.');` | +| `describe('A black dot moves from bottom to top on a gray square.');` | `describe('A shape.');` | + +**More Guidance:** + +- 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. + - 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: + - Examples: [src/data/examples/assets](https://github.com/processing/p5.js-website/tree/main/src/data/examples) - Reference Pages: [src/templates/pages/reference/assets](https://github.com/processing/p5.js-website/tree/main/src/templates/pages/reference/assets) - Learn Pages: [src/assets/learn](https://github.com/processing/p5.js-website/tree/main/src/assets/learn) ```javascript -let img; - // Bad. function preload() { - img = loadImage('moonwalk.jpg'); + img = loadImage("moonwalk.jpg"); } // Good. function preload() { - img = loadImage('assets/moonwalk.jpg'); + img = loadImage("assets/moonwalk.jpg"); } ``` diff --git a/contributor_docs/web_accessibility.md b/contributor_docs/web_accessibility.md index cafeb701ef..af08c295d3 100644 --- a/contributor_docs/web_accessibility.md +++ b/contributor_docs/web_accessibility.md @@ -10,7 +10,6 @@ If you want to use p5.js with a screen reader, visit the [Using p5.js with a Scr The canvas HTML element is a grid of pixels. It doesn’t provide any screen reader-accessible information about the shapes drawn on it. p5.js has several functions that make the canvas more accessible to screen readers by providing [fallback text](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Basic_usage#accessible_content) descriptions. I’ll describe some of the details around the implementation of these functions. - ## Prerequisites - p5.js foundation @@ -18,7 +17,6 @@ The canvas HTML element is a grid of pixels. It doesn’t provide any screen rea - Looking inside p5.js - How to label your p5.js code - ## Library-generated accessible outputs for basic shapes p5.js supports library-generated screen reader-accessible outputs for basic shapes on the canvas with `textOutput()` and `gridOutput()`. It also supports user-generated screen reader-accessible descriptions of the canvas with `describe()` and `describeElement()`. All descriptions are inserted as child elements to the `` element. @@ -51,43 +49,62 @@ 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: ```html - -
+ +
Text Output -
+

- Your output is a, 400 by 400 pixels, white canvas containing the following 2 shapes: + Your output is a, 400 by 400 pixels, white canvas containing the + following 2 shapes:

- +
- + - +
orange circle location = top left area = 1%area = 1%
fuchsia square location = bottom right area = 2%area = 2%
@@ -100,7 +117,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: @@ -109,8 +126,8 @@ Each shape’s description is placed in a cell of the table depending on its loc These descriptions can be selected individually to get more details. A list of elements where shape, color, location, and area are described is also available: -- *orange circle, location = top left, area = 1 %* -- *fuchsia square, location = bottom right, area = 2 %* +- _orange circle, location = top left, area = 1 %_ +- _fuchsia square, location = bottom right, area = 2 %_
@@ -118,13 +135,23 @@ The generated HTML is as follows: ```html - -
+ +
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 +

@@ -138,14 +165,23 @@ The generated HTML is as follows: - +
fuchsia square + fuchsia square +
-
    -
  • orange circle, location = top left, area = 1 %
    • -
  • fuchsia square, location = bottom right, area = 2 %
    • +
      +
    • + orange circle, location = top left, area = 1 % +
      • +
    • + fuchsia square, location = bottom right, area = 2 % +
@@ -158,12 +194,10 @@ If a user passes `LABEL` as an argument to either of these functions, an additio ![A p5.js canvas, with the text descriptions described earlier present below it](images/sketch-text-output.png) - ### Outputs structure Although `textOutput()` and `gridOutput()` are located in [src/accessibility/outputs.js](https://github.com/processing/p5.js/blob/main/src/accessibility/outputs.js), the outputs are created and updated using functions distributed across the library. This section details the different functions that support the accessible outputs. - #### outputs.js [src/accessibility/outputs.js](https://github.com/processing/p5.js/blob/main/src/accessibility/outputs.js) includes two public methods: @@ -208,7 +242,6 @@ When `this._accessibleOutputs.text` or `this._accessibleOutputs.text` are `true` - `_accsBackground()` is called in: - `p5.Renderer2D.prototype.background()` - #### textOutput.js [src/accessibility/textOutput.js](https://github.com/processing/p5.js/blob/main/src/accessibility/textOutput.js) contains all the methods that update the text output. The main method in this file is `_updateTextOutput()` which is called by `_updateAccsOutput()` in [src/accessibility/outputs.js](https://github.com/processing/p5.js/blob/main/src/accessibility/outputs.js) when `this._accessibleOutputs.text` or `this._accessibleOutputs.textLabel` are `true.` @@ -219,7 +252,6 @@ When `this._accessibleOutputs.text` or `this._accessibleOutputs.text` are `true` - `_shapeDetails()`: Builds the text output table that contains shape details. - `_shapeList()`: Builds the list of shapes of the text output. - #### gridOutput.js [src/accessibility/gridOutput.js](https://github.com/processing/p5.js/blob/main/src/accessibility/gridOutput.js) contains all methods that update the grid output. The main method in this file is `_updateGridOutput()`, which is called by `_updateAccsOutput()` in [src/accessibility/outputs.js](https://github.com/processing/p5.js/blob/main/src/accessibility/outputs.js) when `this._accessibleOutputs.grid` or `this._accessibleOutputs.gridLabel` are `true.` @@ -230,18 +262,18 @@ When `this._accessibleOutputs.text` or `this._accessibleOutputs.text` are `true` - `_gridMap()`: Builds a grid that maps the location of shapes on the canvas. - `_gridShapeDetails()`: Builds the list of shapes of the grid output, each line of the list includes details about the shape. +#### color_namer.js -#### color\_namer.js - -When creating screen reader-accessible outputs, naming the colors used in the canvas is important. [src/accessibility/color\_namer.js](https://github.com/processing/p5.js/blob/main/src/accessibility/color_namer.js) contains `_rgbColorName()` a method that receives RGBA values and returns a color name. This function is called by `_accsBackground()` and `_accsCanvasColors` in [src/accessibility/outputs.js](https://github.com/processing/p5.js/blob/main/src/accessibility/outputs.js). +When creating screen reader-accessible outputs, naming the colors used in the canvas is important. [src/accessibility/color_namer.js](https://github.com/processing/p5.js/blob/main/src/accessibility/color_namer.js) contains `_rgbColorName()` a method that receives RGBA values and returns a color name. This function is called by `_accsBackground()` and `_accsCanvasColors` in [src/accessibility/outputs.js](https://github.com/processing/p5.js/blob/main/src/accessibility/outputs.js). `_rgbColorName()` uses `p5.color_conversion._rgbaToHSBA()` to get the HSV values of the color and then uses `_calculateColor()` to get the color name. The function `_calculateColor()` in this file comes from [colorNamer.js](https://github.com/MathuraMG/color-namer), which was developed as part of a [2018 Processing Foundation fellowship](https://medium.com/processing-foundation/making-p5-js-accessible-e2ce366e05a0) and in consultation with blind screen reader expert users. This function returns color names by comparing HSV values to those stored in the `colorLookUp` array, returning the closest color name as a string. - ## User-generated accessible canvas 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](./documentation_style_guide.md#canvas-accessibility-descriptions-describe)) + The `describe()` function creates a sketch author-defined screen reader accessible description for the canvas. The first parameter should be a string with a description of the canvas. The second parameter is optional. If specified, it determines how the description is displayed. If a user passes `LABEL` as a second parameter, an additional `
` element is created next to the `` element. The new `
` element contains a visible version of the same screen reader-accessible description embedded in the `` element. `describe()` is supported by several methods in [src/accessibility/describe.js](https://github.com/processing/p5.js/blob/main/src/accessibility/describe.js): @@ -253,15 +285,15 @@ With example code: ```js function setup() { - background('pink'); + background("pink"); - fill('red'); + fill("red"); noStroke(); circle(67, 67, 20); circle(83, 67, 20); triangle(91, 73, 75, 95, 59, 73); - describe('A pink square with a red heart in the bottom-right corner.', LABEL); + describe("A pink square with a red heart in the bottom-right corner.", LABEL); } ``` @@ -269,10 +301,9 @@ The page will output: ![A p5.js canvas, with a description below reading, "A pink square with a red heart in the bottom-right corner."](images/sketch-text-output2.png) - ### 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): @@ -284,20 +315,19 @@ With example code: ```js function setup() { - background('pink'); + background("pink"); noStroke(); - describeElement('Heart', 'A red heart in the bottom-right corner.', LABEL); - fill('red'); + describeElement("Heart", "A red heart in the bottom-right corner.", LABEL); + fill("red"); circle(66.6, 66.6, 20); circle(83.2, 66.6, 20); triangle(91.2, 72.6, 75, 95, 58.6, 72.6); - describe('A red heart and yellow circle over a pink background.', LABEL); + describe("A red heart and yellow circle over a pink background.", LABEL); } ``` 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) - diff --git a/src/type/textCore.js b/src/type/textCore.js index 2a45168780..0b175c9054 100644 --- a/src/type/textCore.js +++ b/src/type/textCore.js @@ -2737,4 +2737,4 @@ export default textCore; if (typeof p5 !== 'undefined') { textCore(p5, p5.prototype); -} +} \ No newline at end of file