Interactive Explainer
Build an inspectable model: every interaction should reveal behavior grounded in the live implementation.
Process
- Trace the implementation, tests, runtime evidence, and source-of-truth state behind the behavior being explained.
- Name the question the reader should answer through interaction.
- Choose the smallest interaction that exposes the answer: scenario stepper, state transition, execution path, comparison, or selectable diagram.
- Model entities, transitions, and scenarios as data consumed by a shared renderer.
- Show source state and derived state as distinct concepts. Mark boundary crossings with their contract, owner, state change, failure behavior, and proof point.
- Cite behavioral claims with file paths and line numbers.
- Use the requested visual direction when specified. Otherwise follow the project's visual system when one exists, or choose simple legible defaults.
- Keep the HTML self-contained and preserve semantic controls, keyboard access, readable contrast, and reduced-motion behavior.
- Save the artifact at the requested or clearly named workspace path, run the validator, open the page, and exercise its primary interaction.
Supporting Files
- Use
assets/starter.html as the base for scenario-driven explainers and as the visual-token reference for other forms.
- Run
python3 scripts/validate_explainer.py <path-to-html> before delivery.
- The validator catches common structural and dependency mistakes. It is not a complete network or accessibility check; exercise the rendered page too.
Completion
Complete the explainer when its primary interaction faithfully exposes the target behavior from source truth, every behavioral claim is traceable, the validator passes, the interaction works in the rendered page, and the saved path is reported.
1---2name: interactive-explainer3description: Build a source-grounded interactive HTML explanation of behavior or state.4---56# Interactive Explainer78Build an **inspectable model**: every interaction should reveal behavior grounded in the live implementation.910## Process11121. Trace the implementation, tests, runtime evidence, and source-of-truth state behind the behavior being explained.132. Name the question the reader should answer through interaction.143. Choose the smallest interaction that exposes the answer: scenario stepper, state transition, execution path, comparison, or selectable diagram.154. Model entities, transitions, and scenarios as data consumed by a shared renderer.165. Show source state and derived state as distinct concepts. Mark boundary crossings with their contract, owner, state change, failure behavior, and proof point.176. Cite behavioral claims with file paths and line numbers.187. Use the requested visual direction when specified. Otherwise follow the project's visual system when one exists, or choose simple legible defaults.198. Keep the HTML self-contained and preserve semantic controls, keyboard access, readable contrast, and reduced-motion behavior.209. Save the artifact at the requested or clearly named workspace path, run the validator, open the page, and exercise its primary interaction.2122## Supporting Files2324- Use [`assets/starter.html`](assets/starter.html) as the base for scenario-driven explainers and as the visual-token reference for other forms.25- Run `python3 scripts/validate_explainer.py <path-to-html>` before delivery.26- The validator catches common structural and dependency mistakes. It is not a complete network or accessibility check; exercise the rendered page too.2728## Completion2930Complete the explainer when its primary interaction faithfully exposes the target behavior from source truth, every behavioral claim is traceable, the validator passes, the interaction works in the rendered page, and the saved path is reported.
Yeshwanthyk