Help on the card: tooltips, tours and automatic screenshots¶

Exercise context-help-playwright-screenshots-annex.pdf · PDF

You are in the middle of a game and a card comes up that nobody remembers. Do you open the booklet? No. You read the card. The rule is printed on the thing itself, at the moment you need it. It is the kind of help people actually read.

Your app can do the same. The best documentation page is the one the user never has to open. On this page you put help on the screen, step by step, from a better label up to a guided tour. Then you hand your manual's pictures to a robot, because screenshots taken by hand go out of date the day you change a button.

Help that knows where you are¶

Context-sensitive help is help that appears on the screen, about the control you are using, at the moment you are using it.

The context is where you are (this screen, this field) and what you are doing. It is an old idea: F1 in classic Windows programs opened the help page of the dialog in front of you, not page 1 of the manual.

The help ladder¶

There are five rungs, and more really is not better: every bubble is an apology for a label that could be clearer. Always try the lowest rung first. Each rung up costs more to build and more to read.

Here is how to choose, on the booking screen of an imaginary cinema app:

That last row is forgiveness, from the 1987 Apple guidelines: give it an Undo, or at least a confirmation that names the consequence. A warning in a bubble does neither.

Three words for every tooltip¶

They come from WCAG 2.2, success criterion 1.4.13 Content on Hover or Focus (level AA), which you can place next to the rest of accessibility:

• Dismissible: you can close it without moving the pointer or the focus. In practice, Esc.
• Hoverable: you can move the pointer onto the bubble and it stays, to read it, select its text or use a screen magnifier.
• Persistent: it does not vanish on a timer while you are still there.

Add one more rule of ours: a tooltip opens on hover and on keyboard focus. Plenty of people move through a form by pressing Tab, and everything must work from the keyboard (WCAG 2.1.1).

HelpTip: from spec to Svelte¶

Build the tooltip once, as a component. It takes two props: the text, and a label for screen readers. Create src/lib/HelpTip.svelte:

<script>
  let { text, label = 'Help' } = $props();
  const id = $props.id();          // a unique id, to link button and bubble
  let open = $state(false);
</script>

<span class="helptip" role="group"
      onmouseenter={() => (open = true)} onmouseleave={() => (open = false)}>
  <button type="button" aria-label={label} aria-describedby={id}
          onfocus={() => (open = true)} onblur={() => (open = false)}
          onkeydown={(e) => { if (e.key === 'Escape') open = false; }}>?</button>
  <span class="bubble" role="tooltip" {id} hidden={!open}>{text}</span>
</span>

<style>
  .helptip { position: relative; display: inline-block; }
  button   { width: 24px; height: 24px; padding: 0; border: 2px solid black;
             border-radius: 50%; background: white; font-size: 14px; line-height: 1; }
  .bubble  { position: absolute; z-index: 10;
             left: calc(100% + 8px); bottom: -4px;   /* right of the button, growing upwards */
             width: 440px; padding: 8px 10px;
             border: 3px solid black; background: #ffe45c;
             font-size: 14px; font-weight: 400; }
  .bubble::before { content: ''; position: absolute;   /* an invisible bridge over the 8px gap */
                    top: 0; bottom: 0; left: -11px; width: 8px; }
</style>

Use it next to a label:

<script>
  import HelpTip from '#lib/HelpTip.svelte';
</script>

<label for="tags">Tags</label>
<HelpTip label="Help about tags"
  text="Separate tags with commas, for example: home, school. NoteBox keeps at most 5 and writes them in lower case." />
<input id="tags" />

Each line is there for a reason:

The bubble grows upwards, so a field below the label stays visible. A field beside the button gets covered, and at 440px wide the bubble can run off a narrow window. Change left, bottom or the width until the field stays readable.

Before you call it finished¶

Hands off the mouse. Then do the same checks with the mouse:

A guided tour¶

A guided tour is the beginners' set-up of the game: it walks you through your first turn. It is also the most expensive rung to keep alive, because every step points at a control that may move.

You do not write the dimmed overlay yourself. driver.js does the dimming, the positioning and the keyboard:

npm install driver.js

// src/lib/tour.js
import { driver } from 'driver.js';
import 'driver.js/dist/driver.css';

export function startTour() {
  driver({
    showProgress: true,
    steps: [
      { element: '[data-testid="new-title"]',
        popover: { title: 'Start here', description: 'Type a title and press Add. A note needs a title.' } },
      { element: '[data-testid="search"]',
        popover: { title: 'Find a note', description: 'Search looks in titles and in tags.' } },
      { element: '[data-testid="editor"]',
        popover: { title: 'Write', description: 'Everything is saved automatically. There is no Save button.' } },
    ],
  }).drive();
}

Then one visible button on the screen:

<script>
  import { startTour } from '#lib/tour.js';
</script>

<button onclick={startTour}>Take the tour</button>

Run it: you get Next, Previous, the progress "1 of 3", and Esc leaves at any step. The rules for a good tour:

• 3 or 4 steps. If you could tell a new user only three things, which? The rest is what the manual is for.
• A title of two or three words and one sentence. Say what to do and what happens: "Type here to filter by title or tag", not "This is the search box".
• Stable selectors. Point at controls with data-testid, the attributes your Playwright tests already use. A selector like .btn:nth-child(3) breaks with the next layout change.
• Started by the user. Always leave a way out.

A robot takes the photos¶

Your manual has thirty screenshots. Tomorrow you change the colour of one button. How many pictures are wrong now? All of them. Nobody retakes thirty pictures, so screenshots made by hand rot.

In Unit 4, Playwright took screenshots to compare them. Now the same tool takes them to publish them. The script is slower than doing it by hand once, and faster from the second change of the interface, for ever.

The first time on each PC, install it and its browser (a download of over 100 MB):

npm install -D @playwright/test
npx playwright install chromium

Then write scripts/screenshots.js. This one is for NoteBox, so change the names to match your app:

import { chromium } from '@playwright/test';
const OUT = 'docs/assets';

const browser = await chromium.launch();
const page = await browser.newPage({ viewport: { width: 1100, height: 640 }, deviceScaleFactor: 2 });

await page.goto('http://localhost:4173');
await page.evaluate(() => localStorage.clear());     // same data on every run
await page.reload();

await page.screenshot({ path: `${OUT}/notes-screen.png` });                    // the whole window
await page.getByRole('button', { name: /Shopping list/ }).click();
await page.getByTestId('editor').screenshot({ path: `${OUT}/editor.png` });    // one element only

await page.getByRole('button', { name: 'Help about tags' }).focus();           // open the HelpTip
await page.getByTestId('editor').screenshot({ path: `${OUT}/tags-help.png` });

await browser.close();

Run it with two terminals, one for the app and one for the robot:

npm run build && npm run preview

node scripts/screenshots.js

Three PNG files land in docs/assets/. Change the bubble's yellow in the CSS, rebuild, run the script again, and every picture updates itself. Add it to package.json as "docs:shots": "node scripts/screenshots.js" so nobody has to remember it.

deviceScaleFactor: 2 makes pictures twice as dense, so they stay sharp in the PDF. If the files get too heavy, use 1. Where Playwright's own browser cannot run, launch one you have installed: chromium.launch({ executablePath: '/path/to/chromium' }).

Conventions¶

A manual's pictures should look like one set:

• Always the same window size and the same data.
• Cropped to what you talk about. Use locator.screenshot for one element.
• A caption under every picture.
• File names that say what the picture shows.

Then replace each placeholder in docs/user-manual.md and rebuild the site and the PDF:

![The editor with the help of the Tags field open](assets/tags-help.png)

The text in the brackets is the alt text a screen reader says on the site, and it becomes the caption in the PDF. So never leave it empty.

What usually goes wrong¶

For a picture of a tour step, click the tour button, wait for .driver-popover, then take the screenshot.

Key takeaways¶

• Context-sensitive help appears on the screen, about the control you are using, at the moment you are using it.
• Climb the help ladder from the bottom: better label, inline help, tooltip, guided tour, link to the manual.
• Whatever the user cannot do without must be visible without hovering: rung 0 or 1.
• A tooltip is dismissible, hoverable and persistent, and opens on hover and on keyboard focus.
• A guided tour has 3 or 4 steps, is started by the user, and always has a way out.
• A Playwright script regenerates your screenshots with the same size and the same data, so the manual keeps up with the app.

Quick check¶

There are still things in the box you have not written: the page for whoever installs your app, the list of what it stores, and the first guided game. The next lesson, Admin manuals, data and tutorials, covers all three.