p5.js Example Revision Project 2023

Contributors: Amy Chen, Lance Cole, Caleb Foss (lead), Darren Kessner, Kathryn Lichlyter

This document describes the process for revising the p5.js examples for the 2023 Sovereign Tech Fund project and outlines the structure for the new examples included in this repo.

Contents

• Review & Analysis
• Editing Criteria
• Organizational Structure
• Suggestions for Content & Design
• Preview

Review & Analysis

We reviewed all 190 current examples for the base p5 library (excluding the sound library), as well as the 29 examples revised/written by Malay Vassa for GSoC: review data. We gathered data to inform both the curation and editing processes.

To maintain wide coverage of the API while curating a smaller list of examples, we analyzed the coverage of different parts of the API: API coverage data.

As we selected examples to edit and highlight on the new Examples page, we focused on these two priority areas:

Maximize variety of demonstrations in terms of skill level, area of API, and category (typography, 3D, physics, etc.) Minimize revision needed for example to be accessible, clear, documented, etc.

Editing Criteria

We edited the curated p5 examples and wrote additional new examples from scratch using the following criteria:

• Content created follows accessibility guidelines:
  • Content rendered on a canvas includes a screen reader accessible description (via describe(), describeElement(), gridOutput(), or textOutput())
  • Color contrast meets WCAG AA requirements
  • Animations meet WCAG 2.3.1 and 2.3.3 requirements
• Readability score of Grade 8 or lower following tools like Hemingway App
• Has an image thumbnail depicting what the example creates
• Named to clearly identify its primary focus
• Includes an introduction paragraph that meets p5’s technical writing guidelines with links to relevant resources (within p5 reference and external like MDN)
• Includes comments that meet p5’s technical writing guidelines and help the reader follow the code
• Includes minimal code beyond its primary focus
• Is up-to-date with contemporary JS conventions/syntax and follows p5's Code Style Guide. (let vs var, prototype vs class, etc.)
• Invites remixing by avoiding unnecessary code that causes more fragility with change

Organizational Structure

The revised examples page will contain 60 examples distributed into 15 categories.

The overall order of examples progresses from beginner to advanced. Someone new to p5 can start from the top and work their way down. The examples introduce a broad range of the API piece by piece. They also introduce programming concepts. Each example builds on what has been introduced so far. We conceptualized this structure as a p5 “story”.

The examples directory in this repo contains a subdirectory for each category with a numbered name to maintain their order.

Each category directory contains a 'More' subdirectory with additional examples related to that category. These are unedited and do not meet all out evaluation criteria. We recommend including them as an optionally revealed section for site visitors who want to explore further variety.

Suggestions for Content & Design

We tried to avoid sketches that start animating without user interaction, as this goes against WCAG 2.3.3, and found some creative ways to do so. Some sketches do still start animating on load. We would suggest a button to completely stop the preview of the sketch, similar to the "run", "reset", and "copy" buttons currently used.

The git history on the examples has been maintained, and many files include contributions going back several years. If the page for each example listed all contributors for that file, this could be a great way to highlight the community collaborative nature of p5's development.

We would like to see the examples page communicate the progression from beginner to advanced to the visitor. Some introduction text at the top of the page would help, and there may be design choices that would help emphasize the progression.

We discussed the possibility of a future p5 Editor widget as a replacement for the current Ace editor. Before that is developed, we recommend adding a link/button to open the current example in the p5 Editor in a new tab. This will help visitors to remix examples and save them to their p5 Editor account.

Preview

Shapes & Color

Shape Primitives	Color

Animation & Variables

Drawing Lines	Animation With Events	Mobile Device Movement
Conditions

Imported Media

Words	Copy Image Data	Alpha Mask
Image Transparency	Create Audio	Video
Video Canvas	Video Capture

Input Elements

Image Drop	Input Button	DOM Form Elements

Transformation

Translate	Rotate	Scale

Calculating Values

Interpolate	Map	Random
Constrain	Clock

Repetition

Color Interpolation	Color Wheel	Bezier
Kaleidoscope	Noise	Recursive Tree

Listing Data with Arrays

Random Poetry

Angles & Motion

Sine Cosine	Aim	Triangle Strip

Games

Circle Clicker	Ping Pong	Snake

3D

Geometries	Custom Geometry	Materials
Orbit Control	Filter Shader	Adjusting Positions With A Shader
Framebuffer Blur

Advanced Canvas Rendering

Create Graphics	Multiple Canvases	Shader As A Texture

Classes & Objects

Snowflakes	Shake Ball Bounce	Connected Particles
Flocking

Loading & Saving Data

Load Save Storage	Load Save JSON	Load Saved Table

Math & Physics

Non Orthogonal Reflection	Soft Body	Forces
Smoke Particle System	Game Of Life	Mandelbrot