# Adapt or create an Examplicity lab

> For developers and LLMs editing a downloaded HTML 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. Updated 10 October 2026.

## Start

Every lab runs one loop: learner action on the model's real cause -> visible model change -> consequential evidence -> next decision. Direct manipulation alone is not enough; every fresh state is incomplete until the learner acts.

Read the HTML, CSS and JavaScript. Identify what the learner changes, what the model shows, and how the result helps them reason. If present, inspect script[data-examplicity-lab-contract] JSON for the learning relationship and adaptation guidance. Check it against actual behaviour; implementation maps can become stale. Explain discrepancies before relying on them. Without a contract, describe observed behaviour and ask about unclear teaching intent.

### Choose reasoning depth

For an LLM: assess the change against inspected code. Prefer a capable reasoning model and higher effort for mathematics, coupled state or teaching intent. Model capability and effort are separate choices. These are starting recommendations, not measured minimum requirements:

- Rename labels, edit instructions or adjust spacing: Light / low. ChatGPT Work example: Terra Light, or similar. Confirm the edit stays presentational.
- Change examples, add feedback or fix one interaction: Medium. ChatGPT Work example: Sol Medium, or similar. Trace the affected input, state and feedback.
- Change equations, linked controls, difficulty or completion rules: High / extra high. ChatGPT Work example: 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. ChatGPT Work example: Astra Extra High, or a similarly capable reasoning model. Plan the model, test representative cases and verify the result.

Explain the task-specific reason briefly: "Changing difficulty affects question generation, hints and completion. I recommend a higher-reasoning model so those stay consistent; I will check each affected path."
Do not infer your identity, active effort or account options, or claim to switch them. If unknown, describe the capability needed and ask the user to select it if available. If they keep the current model, work in smaller steps and state verification limits.
Reassess when coupled behaviour, conflicting assumptions or repeated failed fixes emerge. More reasoning can take longer and use more allowance; it does not replace execution or subject validation.
These examples are our recommendations. Names/settings vary by product/account. [Official model guidance](https://learn.chatgpt.com/docs/models), checked 6 September 2026.

## Learning

- Act on the cause. On every guided stage the learner changes the model's real variable or builds with the subject's own objects. No invented prediction gestures (a marker on an axis, "tap where it will land") unless the thing tapped is the object.
- Explore before predict. 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. 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 and what it changed in the picture; keep that act in a form at least as direct.
- Wrong attempts play out. Every meaningful wrong or incomplete construction runs and shows its own consequence. Do not auto-complete it or supply a worked answer; keep the attempt visible for repair; require a rerun after an edit.
- A miss counts only when the tested state differs from the last; an unchanged test reads "Checked". The cue after a miss names what to compare, never a direction or answer. A two-miss way on ("Continue with this result", stage stays Not finished) is lab-specific.
- Useful evidence persists: in the live picture, the previous trial beside the current one, or a deliberate comparison. Carry what the next step needs; no Save quota.
- When the syllabus asks for a calculation, the learner computes from the model's readings and the result sets or checks the model. Never print the method with their numbers substituted; remove fields that show the value they must produce.
- Keep the source's outcomes and variables; narrowing Experiment is a defect.
- Titles are questions; the earned statement answers them in the same words after a held result. One goal sentence; check the outcome, not the path; transfer is a fresh case with less support. Experiment is the same model without guidance, with exact return to guided work. Label Supplement/Extended content and give Core learners a plain way past.

## Task clarity

On every fresh stage, before anything is touched, the learner can answer:

1. What am I looking at? Every object the prompt names is labelled on the picture in the prompt's word.
2. What do I do first? The prompt's first clause is a verb on a thing that visibly is a handle.
3. What am I trying to make happen? A goal stated as a state of the picture.
4. How will I know, and what do I press? The test action named by its button word; the result appears where the act happened.
5. What did I learn? An earned statement that answers the title.

Prompt form: one or two sentences, verb + object, then the goal as a picture state, then the test action by button name. Insert carried values; never state a value the learner must derive. One instruction per screen: the status line reports what the picture shows and never adds a second instruction. No captions or keyboard hints stacked on the prompt; keyboard operation belongs in the accessible name.

Learner words: keep authoring 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; Explore/Investigate/Transfer kickers). Authentic curriculum terms stay when attached to their subject (power supply, database record, vector route). Tier labels stay. Restart: "Restart this stage", "Restart whole lab". Finish: "Done" / "Not finished".

## Building

- Lesson shell, top to bottom: shared header (lab name, progress, route select where there is a route, Experiment chip, restart) · tier kicker · title (a question) · prompt · picture card · status line · nav. Exactly one h1; no syllabus codes in the lab body.
- Column: data-lab-col standard 900px or wide 1160px; no local width rules. Two columns only while the side holds a real block. The verdict strip (p.v5-verdict, role=status) sits inside the picture card under the drawing. Navigation is the shared sticky .v4-nav only; the restart menu is an overlay that never moves the page.
- Shared parts: v4-chip (Experiment, in-card actions), v4-btn (navigation), v4-quiet (utility), select.v4-select (selectors), v4-foot (limitations line). Subject controls (a bit switch, a socket) are drawn as that object.
- Act on the object: drag the chord, flip the switch, connect the socket, edit the bit where it is shown. Nothing covers the drawing. Every operable thing looks operable and carries a one-word label. Show givens, constraints, tolerance and the success condition. A control that cannot act says why in the status line. Opening an editor or menu never moves the picture or the scroll position.
- Input that forgives: 44 x 44 targets at 390px width (input geometry, not painted size); a drag starting 6-10px off-centre, curving and releasing near the target completes the act with mouse and touch; the page still pans from the background; compare displayed values, never raw floats; fresh states never show a stale verdict.
- Verdict, marks and motion: the verdict appears in the picture in the subject's notation, with the learner's mark beside it. Violet is only the learner's mark; solid green ring = held, grey dashed ring = missed; kept readings and ghosts are dashed and never show the answer. Motion travels a visible path, pauses about 700ms where result meets mark, and the path stays drawn; reduced motion shows start, decisive stop and end.
- Artwork: draw real apparatus with the subject's conventions; keep or improve source artwork; crop the viewBox to the drawing; below-fold content is fine, never squash the subject; phone is a redesign, not a shrink; text stays at 11px or larger; nothing touches, overlaps or clips.

## Workflows

### Adapt an existing lab

1. Read before editing: operate every control, then inspect the code and any contract.
2. List each control: where it sits, what it changes, and the learning act it carries. An adaptation must not lose those acts.
3. Clarify audience, prior knowledge and requested changes where unknown. Briefly explain the current experience and agree a focused plan.
4. Preserve causal relationships, meaningful interactions, feedback and completion unless the requested change calls for revising them. Preserve contract invariants and selected curriculum unless explicitly changed. Do not invent exam alignment.
5. Edit the complete HTML and update affected embedded guidance. Keep unrelated behaviour intact.

### Create a new lab from an example

1. Agree one learning goal, audience and concept. Identify the action on the cause, the evidence it produces and what demonstrates understanding.
2. Choose an example for a relevant interaction: direct manipulation, tracing a process or supported working. Run and inspect it before reuse.
3. Borrow useful layout, controls or feedback; build the model around the new concept. Do not copy unrelated modes, stages or completion rules.
4. Replace the title, description, instructions and lab-specific metadata. Do not carry over the example's identifiers, canonical URL or curriculum claims as the new lab's identity. Retain applicable licence and attribution notices for reused code.
5. If including a Lab Contract, write guidance for the new learning relationship and keep it consistent with implementation. Use the schema for field definitions.

Examples:

- [Lab catalogue](https://www.examplicity.org/): Choose and download a relevant example.
- [Binary Numbers](https://www.examplicity.org/labs/computer-science/binary-numbers): Practice and feedback.
- [Coordinate Geometry](https://www.examplicity.org/labs/mathematics/coordinate-distance-midpoint-perpendicular): Direct manipulation.
- [Graph Search](https://www.examplicity.org/labs/computer-science/dijkstra-a-star-graph-search): Algorithm traces.

### Design references

- [Design system](https://www.examplicity.org/developer/design-language.html): The single design reference: brand, colour, type, spacing, every shared component with a component lookup, and intentional per-lab differences, with current v5 and existing v3 parts marked; takes precedence over conflicting kit styling.
- [Component CSS](https://www.examplicity.org/developer/lab-design.css) and [interaction helpers](https://www.examplicity.org/developer/lab-kit/0.3.0/src/lab-design.js): Reuse only what the activity needs.
- [Lab Kit usage](https://www.examplicity.org/developer/lab-kit/0.3.0/README.md): Optional helpers. Inspect the version already embedded before replacing it.
- [Lab Contract](https://www.examplicity.org/developer/lab-contract) and [implementation maps](https://www.examplicity.org/developer/lab-contract#implementation): Adaptation guidance and observed behaviour.
- [Contract schema](https://www.examplicity.org/developer/lab-contract.schema.json): Field reference.

Prefer shared components for recurring features; keep calculations, constraints, geometry and meaningful layout differences local; never copy generated styles into a second source. Preserve layouts that help explain the concept: learning decides the layout. Keep labels readable, keyboard focus visible and feedback understandable without colour alone. Do not introduce Working levels, stages or controls just because an example has them.

## Check and deliver

Check at 1366 x 644 and 390 x 672 on every stage and Experiment:

- The whole prompt is visible on arrival; the first action is in view and clear of the nav.
- Each required control is unobstructed where it is used; the verdict is in view above the nav after the act.
- Opening the restart menu, an editor or a disclosure moves neither the page nor the picture.
- 44 x 44 targets; imperfect mouse and touch drags complete.
- No horizontal scroll; no text below 11px at 390px; no console errors; no authoring jargon in learner text.
- Every source control and the act it carried is accounted for.
- Try the main action, a meaningful wrong attempt, the held result, completion and both restarts, plus affected existing modes for adaptations. Read every screenshot at full size; report what you did not verify.

Deliver:

- Return one complete downloadable HTML file with required CSS, JavaScript and assets embedded. Open it offline and check behaviour and appearance.
- Published labs carry only the shared CSS they use plus common remix primitives. Keep dynamic class names literal or safelist them; never prune from an opening DOM snapshot alone.
- Check keyboard operation, readable text and narrow-screen layout without page-level horizontal overflow.
- Keep embedded guidance and instructions consistent. State what changed, what was checked and any limitations. Do not claim checks your tools cannot perform.
- Keep documentation references in the head:
  <link rel="help" href="https://www.examplicity.org/developer">
  <link rel="help" type="text/plain" href="https://www.examplicity.org/developer/llms.txt">
- References are not runtime dependencies. If unavailable, say so and continue with the supplied HTML and embedded guidance.

## Contribute

[GitHub repository and README](https://github.com/timcarpe/examplicity#readme): Setup and contribution instructions. Submit focused fixes with the lab URL, change and checks; an LLM can prepare a patch and PR description. Open an issue to agree larger changes first.