1. Start from a useful relationship
Every record is three parts: what goes in, what connects them, and what comes out. Write the claim in one sentence first. If that sentence cannot be shown, it is not ready.
2. Build both views on the canvas
Place blocks on the input canvas and the output canvas. Choose the block that carries the meaning:
- Colour: pickers with a fill, for perception, mixing and contrast.
- Variable or value: numbers that can be checked or scaled.
- Code Functions: reversible encoding, HTML entities or encryption examples. Markup is stored as text, never executed.
- Image or GIF: a process that has to be seen.
- Text: labels and short captions, not the whole demonstration.
Give identical samples the same group so their pickers stay in sync. Use fill when the colour itself is the demonstration.
3. Set defaults that already prove the claim
A first-time viewer should understand the record before touching anything. Colour pickers, sliders and code examples are for exploration after the default state has made the point. For the simultaneous-contrast example, the default greys are identical and the default surrounds are light and dark.
4. Name the relationship
Title the useful result. Summarise it in one line. The relationship field explains the mechanism, not the user interface. Category, library and relationship type are how people find it.
5. Cite the trail
Add the public references that back the claim. Title, URL and publisher are enough. Records without sources can be drafted; they should not be the public face of the library.
Copy these
Interactive records show how blocks carry the result:
- Surrounding colour changes perceived colour
- Blend two colours
- Hydrogen and oxygen form water
- Encode and decode Base64
- Convert Celsius to Fahrenheit
Sourced text records show a clear claim, mechanism and citation when a canvas is not required:
- Salt lowers the freezing point of water
- The angles of a triangle sum to 180 degrees
- Binary search halves a sorted search space
The same set is available as JSON at /api/v1/examples.
6. Save, review, publish
- Save a draft from the studio.
- Check input, split and output on a phone and a wide screen.
- Submit for review when the defaults already teach the result.
- Publish under CC0 once the record is accurate, sourced and visually complete.