Teaching Elements · the web vocabulary for teaching, by job
Teaching
01
Reveal complexity gradually
Fight the wall of text. Show a summary, let the reader choose to go deeper. On-brand twist: a closed accordion is a visible unopened door.
Why does the model do this? +
Because it optimizes for the shape of a correct answer, not the substance. Expand only when the reader wants the mechanism; the summary alone teaches the what.
The detail, opened +
Open state shown. The marker rotates 45° from + to ×. Keep bodies short; an accordion that hides three paragraphs is a page that should have cut two.
Accordion · closed door
Expandable detail
Native <details>. Summary teaches the what; the body holds skippable mechanism.
On-brand: a closed accordion is a visible unopened door. Only collapse what the reader can skip.
Files: the simplest memory. Good until you need to query across records.
Database: structure and query. The step up when lookups matter.
Graph: relationships between records become first-class.
Tabs
Facets in one space
Same slot, different views. Use only when the facets are genuinely parallel and comparable.
Not for sequential steps — that's a stepper. Tabs imply "pick one to look at," not "do these in order."
02
Compare — before/after, wrong/right
Show two states of the same thing so the difference teaches itself. The wrong/right pair is the most native element to your failure-modes body of work.
After
Before
⇄
Before / after slider
Drag to compare
One draggable divider reveals two states of the same frame. Strong for visual transformations.
Only when the two states share a frame. If they don't align pixel-for-pixel, use side-by-side instead.
Wrong way
Ask the agent to "handle the files"
Vague verb, no boundary. The agent invents scope.
agent.run("handle the files")
Right way
Name the operation and the target
One verb, one target, one done-condition.
agent.move(src, dst, dry_run=1)
Wrong / right pair
Same task, two approaches
Wrong on the left (recognition), right on the right (the fix). Red top-border vs green.
On-brand: the 22 failure modes are wrong-way entries; each earns a right-way counterpart. Never show wrong alone.
03
Anchor to a real thing
Pin labels onto an actual image, screenshot, or diagram so the explanation attaches to what the reader sees. The missing element for technical pages.
system diagram
1
2
3
1 The entry point where requests arrive.
2 The router that decides where each goes.
3 The store everything settles into.
Annotated diagram
Numbered pins + legend
Pins sit on the figure in reading order; the legend mirrors the numbers.
Max ~6 pins per figure. More than that, split the diagram — the reader can't hold more at once.
04
Make the reader do something
Doing beats reading for retention. A live playground, a knowledge check, a checklist they tick. The playground is where your AI-in-artifacts capability shines.
Which fails silently?
Playground & quiz
Interactive practice
Live input→output, and a knowledge check with plausible distractors.
On-brand: the playground dogfoods AI-in-artifacts — a real model call behind the input on a live page.
Checklist
Tickable actions
Ticking one strikes it through. Only for genuinely actionable items.
Not a summary in disguise. If the reader can't do each line, it's a list, not a checklist.
05
Orient in a long piece
On a long page, tell the reader where they are. A sticky table of contents that tracks position, a reading-progress bar. Earn their place only past ~1500 words.
TOC highlights the active section; the bar shows how far in. Both track scroll.
Past ~1500 words only. On a short page a progress bar is decoration that fails the test.
06
Call out and frame
Typed callouts, pull quotes, key-term definitions. Texture that guides the eye to what matters. Used sparingly — a page of callouts has no emphasis left.
Note
Neutral aside. The default, teal.
Tip
A shortcut or better way. Green.
Warning
A real risk or gotcha. Yellow.
Key insight
The one thing to remember. Violet.
Typed callouts
Note / tip / warn / key
Each type gets its accent + label. The base callout, specialized.
The type must match the content. A "warning" that isn't erodes every warning after it.
Complexity is earned, not adopted.
— the memory ladder
Pull quote
Lift the line
Pulls the single most quotable line out at scale. One per page at most.
For the line worth remembering, not decoration. If every section has one, none land.
07
Sequence a process
Show order and position in a fixed sequence. The compact stepper here; the playful winding trail has its own styleguide. Stepper for orientation, trail for a journey worth feeling.
✓
Connect
✓
Import
3
Review
4
Publish
Stepper
Fixed linear sequence
Done, current, upcoming. The compact cousin of the trail.
Stepper = orientation in a form/wizard. Trail = a journey worth making playful. Same job, different weight.
Created for you, with ❤️ by Robert Evans· The AI Design Architect