Adapt or create a lab

For developers and LLMs editing a downloaded lab or using one as an example for a new activity: what a lab must do for the learner, how it is built, and how to check it.

Plain-text reference · Lab catalogue · Design system. Updated 10 October 2026.

Start

The learning loopStart with the HTML file and one clear learning goal

Learner actionon the model’s real cause
Visible model changein the picture, as it happens
Consequential evidencethe result, kept where it is needed
Next decisionmade from that evidence

Inspect what the learner changes, what the model shows and how the result helps them reason. Direct manipulation alone is not enough: every fresh state is incomplete until the learner acts, and the lab responds with evidence they can use.

Contribute on GitHubtimcarpe / examplicity

Have a fix or improvement? Open a focused PR with the lab link, what changed and how you checked it. An LLM can prepare a patch and PR description. For larger changes, open an issue first. Setup and contribution instructions are in the repository README.

View repository

Choose reasoning depthBefore editing, match the model to the change

Example choices in ChatGPT Work, or similar tools
Requested change	Reasoning	Example model	Why
Rename labels, edit instructions or adjust spacing	Light / low	Terra Light, or similar	Confirm the edit stays presentational.
Change examples, add feedback or fix one interaction	Medium	Sol Medium, or similar	Trace the affected input, state and feedback.
Change equations, linked controls, difficulty or completion rules	High / extra high	Sol High or Astra Extra High, where available, or similar	Check coupled behaviour and learning invariants.
Create a new simulation or diagnose a bug spanning several modes	High / extra high; deeper review if needed	Astra Extra High, or a similarly capable reasoning model	Plan the model, test representative cases and verify the result.

Explain the recommendation in terms of the task: “Changing difficulty here affects question generation, hints and completion. I recommend a higher-reasoning model so those stay consistent; I’ll check each affected path.”
Do not infer your model identity, active reasoning setting or the user’s available models. If unknown, describe the capability needed and ask the user to select it. Do not claim that you switched models or settings. If the user stays with the current model, work in smaller steps and make verification limits clear.
Reassess if the work reveals coupled behaviour, conflicting assumptions or repeated failed fixes. Deeper reasoning cannot replace running the lab or checking subject accuracy.
These are our recommendations, not measured minimums. Names vary by product and account; see OpenAI’s model and reasoning guidance (checked 6 September 2026).

Learning

Act on the causeExplore first, predict where it matters

Changing the cause and seeing the effect is the experiment. Do not swap it for a guess about the result.

On every guided stage the learner changes the model’s real variable or builds with the subject’s own objects. No invented prediction gestures, such as a marker on an axis or “tap where it will land”, unless the thing tapped is the object.
The first stage on a relationship lets the learner vary the cause and watch the effect. Prediction belongs at the consequential branch, boundary or counterexample, once there is a basis for it. There is no prediction quota.
A control is the learning act it carries, not the widget. Before removing or replacing one, name what the learner decided or computed with it and what it changed in the picture; keep that act in a form at least as direct.

Let wrong attempts play outThe model answers, not a worked solution

A miss is evidence. Show the real result beside the learner’s mark so they can see the difference.

Every meaningful wrong or incomplete construction runs and shows its own consequence. Do not auto-complete the learner’s proposal or supply a worked answer after a miss; keep their attempt visible for repair, and require a rerun after an edit.
A test counts as a miss only when the tested state differs from the last one; an unchanged test reads “Checked”. The cue after a miss names what to compare, never a direction, landmark or answer.
Where the lab’s design allows a way on after two different misses, “Continue with this result” appears in the Continue position and the stage stays Not finished. This is lab-specific, not a universal rule.

Keep what the learner needsEvidence, calculations and the source’s scope

Nothing the learner earned should disappear just because the screen moved on.

Useful evidence persists: in the live picture, as the previous trial beside the current one, or as a deliberate comparison. Carry what the next step needs automatically; no generic Save button quota.
When the syllabus asks for a calculation, the learner computes from the model’s own readings and the result sets or checks the model. Never print the method with the learner’s numbers substituted, and remove any field that shows the value they are asked to produce.
Keep the source’s outcomes and variables. If the original Experiment let the learner change five things, the new one does too; narrowing it is a defect.

Let guidance fall awayQuestions, earned answers, then less support

Each stage asks less of the interface and more of the learner.

Titles are questions. The earned statement answers them in the same words, only after a held result, in the subject’s terms, with formal names after the idea.
One goal sentence per stage. Check the outcome, not the path. Transfer is a fresh case with less support, using the exam’s own case where one exists and never naming the method.
Experiment is the same model with guidance removed, available early, with exact return to unfinished guided work.
Label Supplement or Extended content and give Core learners a plain way past, away from the run control. Aim for five to eight guided stages.

Task clarity

Five questionsAnswerable on every fresh stage, before anything is touched

The learner asks	The stage answers with
What am I looking at?	Every object the prompt names is labelled on the picture in the prompt’s word. Symbols are attached to their thing before an instruction uses them.
What do I do first?	The prompt’s first clause is a verb on a thing that visibly is a handle.
What am I trying to make happen?	A goal stated as a state of the picture, not a procedure in symbols and not only the title.
How will I know, and what do I press?	The test action named by the word on its button, with the result appearing where the act happened.
What did I learn?	An earned statement that answers the title.

Prompt formOne instruction per screen

Where must the screen go for a sharp image?

Drag the screen until the rays meet on it, then press Test.

The screen must go where the rays meet: 15.0 cm behind the lens.

One or two sentences: verb and object, then the goal as a picture state, then the test action by its button name. Insert carried values into the prompt; never state a value the learner is meant to derive (say where to read it instead).
The status line under the picture reports what the picture shows after an act; it never carries a second instruction. No captions, operation hints or keyboard hints stacked on the prompt. Keyboard operation belongs in the accessible name.

Learner wordsSay it in the subject’s language, not the author’s

Keep authoring and status jargon out of learner text, accessible names and Finish screens: trial, reference, construction, construct, evidence, record, tested, held, unresolved, arrangement, model answer, notice, expected, explanation, supply, route, invariant, slice, and Explore, Investigate or Transfer kickers.

Authentic curriculum terms stay when introduced and attached to their subject: a power supply, a database record, a vector route. Tier labels stay (Core, Supplement, Extended, A Level). Restart reads “Restart this stage” and “Restart whole lab”; Finish reads “Done” or “Not finished”.

Building

Lesson shellHeader, title, prompt, picture, status, nav

Shared header: lab name, progress, route, Experiment, ↺ restart
Tier kicker, may be empty
Title, a question
Prompt
Picture card · verdict strip under the drawing
Status line
Back · Continue

See Lab shell in the design system for the drawn specimen.

Use the shared column (data-lab-col standard 900px or wide 1160px) with no local width rules. Two columns only while the side holds a real block; otherwise the picture takes the full width.
The verdict strip sits inside the picture card directly under the drawing. Navigation is the shared sticky .v4-nav and nothing else; the restart menu is an overlay that never moves the page.
Shared parts: v4-chip for Experiment and in-card actions, v4-btn for navigation, v4-quiet for utility actions, select.v4-select for selectors, v4-foot for the limitations line.

Act on the objectDrawn handles, visible targets, no silent controls

Keep or improve every useful interaction from the source. A button carrying the object’s name is not direct manipulation.

Drag the chord, flip the switch, connect the socket, edit the bit where it is shown. Selectors and deliberate Run or Test controls may sit beside the picture; nothing covers the drawing.
Every operable thing looks operable and carries a one-word label in the prompt’s word. A number, badge or plain region is never the only handle.
Show the givens, constraints, tolerance and success condition. No hidden movement count or undisclosed precision decides success.
A control that cannot act says why in the status line, and a missed drop says so. Opening an editor or menu never moves the picture or the scroll position.

Input that forgivesReal fingers, real mice

A required interaction that passes only with exact coordinates or a keyboard rescue is a defect.

At least a 44 × 44 target for every handle and button at 390px width. This is input geometry: a small terminal can keep its drawn size with a larger invisible target, settled by the visible object.
A drag that starts 6–10px off-centre, curves and releases near the target completes the act, with mouse and native touch. Snaps settle geometry but keep wrong constructions reachable.
The dragged surface owns the gesture; the page still pans from the background and header; the first tap after a drag works.
Compare displayed values, never raw floats. Fresh states carry the learner’s values but never a stale verdict or a solved state the prompt asks them to reach.

Verdict, marks and motionFeedback in the picture, in the subject’s notation

Held: solid green ring on the learner’s mark

Missed: grey dashed ring, the real result beside it

Kept reading or ghost: dashed, never the answer

Colours and marks: Learner state in the design system.

The verdict appears in the picture (the angle sum on the shape, the stored bit in its box) with the learner’s mark beside it; the strip carries the sentence.
Violet is only the learner’s mark. A solid green ring means held; a grey dashed ring means missed; a kept reading is dashed. Ghosts show the outcome a commitment implies, never the answer.
Motion is the explanation: what changes travels a visible path in one scene, pauses about 700ms where result meets mark, and the path stays drawn. Reduced motion shows start, decisive stop and end.

Artwork and compositionDraw the thing; nothing empty, nothing touching

Functional success never excuses crude illustration.

Draw real apparatus, devices and anatomy with the subject’s conventions right. Keep or improve source artwork and port its drawing functions; precise symbolic subjects may stay schematic.
Subject big, nothing empty: crop the viewBox to the drawing; no empty bands or reserved blank boxes. Below-fold content is fine; never squash the subject to fit a viewport.
Phone is a redesign, not a shrink: stack, fold tables into rows, drop decoration before evidence. Rendered text stays at 11px or larger.
Nothing touches, overlaps or clips in fresh, miss, repaired, busiest and open-editor states.

Workflows

Adapt an existing labRead it as a learner before planning

Read before editing. Open the lab and operate every control. Then inspect the HTML, CSS and JavaScript, and the JSON in script[data-examplicity-lab-contract] if present. It describes the learning relationship and adaptation guidance; check the implementation against it because a map can become stale.
List what the controls do. For each control, note where it sits, what it changes and the learning act it carries. That list is what an adaptation must not lose.
Agree the change. Ask about the audience, prior knowledge and intended change where these are unclear. Briefly explain the current learner experience and propose a focused plan.
Preserve the learning relationship. Keep causal relationships, meaningful interactions, feedback and completion rules unless the change calls for revising them. Preserve contract invariants and selected curriculum; do not invent exam alignment.
Edit the complete HTML. Make the requested change, update affected embedded guidance and keep unrelated behaviour intact.

If the contract and code disagree, explain the discrepancy before relying on either. If no contract exists, describe what you can establish from the implementation and ask about unclear teaching intent.
Read the contract fields · Read an implementation map

Create a new lab from an exampleBorrow patterns, not identity

Define one learning goal. Agree the audience, concept and what the learner should discover or practise. Identify the action on the cause, the evidence it produces and what demonstrates understanding.
Choose a useful example. Select for the interaction you need, such as manipulating a model, tracing a process or completing supported working. Run and inspect it before reusing a pattern.
Reuse selectively. Borrow relevant layout, controls or feedback. Build the new model around its own concept; do not copy unrelated modes, stages or completion rules.
Make the new identity explicit. Replace the title, description, instructions and lab-specific metadata. Do not carry over the example’s identifiers, canonical URL or curriculum claims. Retain applicable licence and attribution notices.
Document the new learning relationship. If including a Lab Contract, write guidance that describes the new lab and keep it consistent with the implementation. Use the schema as a field reference.

Useful starting points: Binary Numbers for practice and feedback, Coordinate Geometry for direct manipulation, and Graph Search for algorithm traces.
Lab Contract JSON Schema

Use the design referencesA reference, not a page template

Design systemThe single design reference: brand, colour, type, spacing, every shared component and the intentional per-lab differences, with v5 and v3 parts marked.
Shared component CSS and interaction helpers
Reuse only what the activity needs.
Lab Kit usageOptional helpers; inspect the version already embedded before replacing anything.

Prefer shared components for recurring features; keep calculations, constraints, geometry and meaningful layout differences local. Never copy generated styles into a second source. The design system’s component lookup lists each shared part and what the lab supplies.
Keep labels readable, keyboard focus visible and feedback understandable without colour alone.
Do not introduce Working levels, stages or extra controls merely because an example has them. Preserve a lab-specific layout when it helps explain the concept: learning decides the layout.

Check and deliver

ChecksAt 1366 × 644 and 390 × 672, on every stage and Experiment

Check	Passes when
Prompt on arrival	The whole prompt is visible without scrolling.
First action	The control the prompt names first is in view and clear of the nav.
Required controls	Each is unobstructed where it is used, after ordinary scrolling if the subject is tall.
Verdict after the act	The strip, or a local verdict at the act, is in view above the nav.
Menus and editors	Opening the restart menu, an editor or a disclosure moves neither the page nor the picture.
Hit areas and drags	44 × 44 targets; imperfect mouse and touch drags complete at both sizes.
Layout and text	No horizontal scroll; no text below 11px at 390px width.
Console and words	No page or console errors; no authoring jargon in learner text.
Source controls	Every source control and the act it carried is accounted for.

Try the main learner action, a meaningful wrong attempt, the held result, completion and both restarts. For an adaptation, check the affected existing modes too.
Read every screenshot at full size. A passing script certifies nothing on its own. Report what you did not verify.

Deliver one HTML fileOffline, complete, honest about limits

Embed required CSS, JavaScript and assets. Open the saved file without a network connection and check that it works and keeps its appearance.
Published labs carry only the shared CSS they use, plus common remix primitives. Keep dynamic class names literal or safelist them, and never prune from an opening DOM snapshot alone; substantial new layouts can be repackaged from the full stylesheet.
Check keyboard operation, readable text and a narrow-screen layout without page-level horizontal overflow.
Keep contract guidance and visible instructions consistent with the result. Describe what changed, what you checked and any remaining limitation.

Return the complete downloadable HTML file. Keep links to this reference in its <head> for future adaptations:

<link rel="help" href="https://www.examplicity.org/developer">
<link rel="help" type="text/plain" href="https://www.examplicity.org/developer/llms.txt">

Documentation links are references, not runtime dependencies. If you cannot access them, say so and continue from the supplied HTML and embedded guidance. Do not claim to have run checks that your tools cannot perform.