Eval iteration 1: the callout 'edge' variant picked up the diagram connector styles, and all three skill runs hand-wrote a template filler. fill_template.py takes values.json with @fragment files, escapes </ in the quiz; suite 21 checks.
5.5 KiB
Components for an explain-diff page
Every snippet below is styled by assets/template.html. Copy, then replace
the sample content. Keep the class names: the stylesheet and the checker
know them. Sample text is in English; write yours in the page language.
Skippable deep background
The newcomer's tour of the system goes in a collapsible block, so a reader who knows it can jump straight to the narrow background.
<details class="deep">
<summary>How the hint service works <span class="hint">(skip if you
know it)</span></summary>
<p>…</p>
</details>
Callouts
Three kinds: concept (a definition or key idea), edge (an edge case
worth remembering), risk (what can still go wrong, or a follow-up).
<aside class="callout concept">
<p class="callout-title">Lazy guest</p>
<p>A visitor who has not played yet has no session row …</p>
</aside>
<aside class="callout edge">
<p class="callout-title">Edge case: session creation fails</p>
<p>…</p>
</aside>
<aside class="callout risk">
<p class="callout-title">Not covered by this change</p>
<p>…</p>
</aside>
Flow of components
Nodes left to right, an arrow between each pair. Its label carries the
example data that travels (a call, a payload, a return value). hl marks
the component the change touches. On a phone the flow turns vertical.
<figure class="diagram">
<div class="flow">
<div class="node"><span class="node-title">Browser</span>
<span class="node-sub">guest g-42, no session</span></div>
<div class="arrow">ensureGuest()</div>
<div class="node hl"><span class="node-title">fetchHint</span>
<span class="node-sub">new: session first</span></div>
<div class="arrow">rpc hint(day=12)</div>
<div class="node"><span class="node-title">Database</span>
<span class="node-sub">auth-gated RPC</span></div>
</div>
<figcaption>After the fix: the session exists before the hint call.
</figcaption>
</figure>
A return value travels back through the label of the same arrow
(hint(day=12) → "starts with B") or through a second flow below.
Row of states
Same markup with state nodes; hl marks the state the change adds.
<div class="flow">
<div class="node state"><span class="node-title">running</span></div>
<div class="arrow">crash ×3</div>
<div class="node state hl"><span class="node-title">stopped</span>
<span class="node-sub">new: final</span></div>
</div>
Before and after
<div class="compare">
<div class="pane before">
<p class="pane-label">Before</p>
<p>…</p>
</div>
<div class="pane after">
<p class="pane-label">After</p>
<p>…</p>
</div>
</div>
Simplified UI mock
For UI changes: draw only what the user sees that matters, as boxes.
mark outlines the element the change affects. Put two mocks inside the
panes of a compare block for a before and after view.
<div class="mock">
<div class="mock-bar">Daily puzzle · day 12</div>
<div class="mock-body">
<p>Find the word in 6 tries.</p>
<div class="mock-field">B _ _ _ _</div>
<div class="mock-button">Hint</div>
<div class="mock-alert mark">Hint unavailable</div>
</div>
</div>
mock-alert ok gives the success colour.
Toy data
<div class="table-wrap">
<table class="data">
<thead><tr><th>Visitor</th><th>Session</th><th>Hint</th></tr></thead>
<tbody>
<tr><td>g-42</td><td>none</td><td>refused</td></tr>
</tbody>
</table>
</div>
Code excerpt and diff
Show only the lines that matter, with the path:line above. Escape <,
> and & in every code block.
<figure>
<span class="path">apps/web/src/game/daily.ts:31</span>
<pre><code>export async function fetchDailyHint(day: number) {
const ok = await ensureGuestSession();
if (!ok) return null;
}</code></pre>
<figcaption>The session comes first; a failure ends in null.</figcaption>
</figure>
A diff block holds raw unified-diff lines; the template's script colours
the +, - and @@ lines. Keep the leading + / - / space.
<figure>
<span class="path">apps/web/src/game/daily.ts</span>
<pre class="diff">@@ -28,6 +28,9 @@ export async function fetchDailyHint
export async function fetchDailyHint(day: number) {
+ const ok = await ensureGuestSession();
+ if (!ok) return null;
return rpc("hint", { day });</pre>
</figure>
Quiz data
The template renders the quiz from the JSON block quiz-data. Five
questions, three or four options each, exactly one "correct": true, and a
why on every option. Backticks in any string render as inline code. Plain
text only, no HTML; write <\/ for any </ inside a string.
[
{
"q": "A guest with no session asks for a hint. What runs first?",
"options": [
{"text": "The hint RPC", "correct": false,
"why": "That was the bug: the RPC refused a caller with no session."},
{"text": "`ensureGuestSession()`", "correct": true,
"why": "The fetcher now creates the session, then calls the RPC."},
{"text": "A page reload", "correct": false,
"why": "Nothing reloads; the fix stays inside the fetcher."}
]
}
]
Labels on #quiz-root follow the page language. {n} and {total} in the
score label are filled by the script.
| Placeholder | English | French |
|---|---|---|
{{QUIZ_RIGHT}} |
Right. | Exact. |
{{QUIZ_WRONG}} |
Not quite. | Pas tout à fait. |
{{QUIZ_SCORE}} |
Score: {n} out of {total} | Score : {n} sur {total} |