/inki-interactive-demo: write an interactive demo from a plain-text description
Interactive demos are clickable tours captured from a real Strapi app. Each demo is a YAML scenario played by a capture script. This skill turns a description written by a person ("highlight the navigation, then click Article…") into that scenario, captures it, and checks the screens.
Everything about the system is in claude-plugins/inki/skills/inki-interactive-demo/README.md. Read it first, completely: it defines the step types, the actions, the selectors and how to run the scripts.
Run every command below from the root of the strapi/documentation repository.
Input
$ARGUMENTS: the demo id (kebab-case, e.g. content-manager), optionally followed by a path to the description or the description itself.
The description lives in docusaurus/interactive-demos/<id>/description.md. If the user gave the description inline, write it to that file first, as they wrote it. If neither exists, ask the user to describe the tour: which page it starts on, then each step in order, with the text to show when they have one.
Two cases:
- New demo (no
scenario.yaml): build the scenario from the description. - Update (
scenario.yamlexists): the description, the UI or both changed. Start from the existing YAML. Keep every step the description still asks for, and change only what the description or the UI requires.
Step 1: Check the demo app
The scripts need a running demo app and these environment variables (see the README, "Update a demo after a UI change"):
DEMO_STRAPI_URL(defaulthttp://localhost:1337),DEMO_STRAPI_DIR(the app folder),DEMO_STRAPI_EMAIL,DEMO_STRAPI_PASSWORD.PLAYWRIGHT_CORE_PATHifplaywright-coreis not installed.
Check that $DEMO_STRAPI_URL/admin answers. If it does not, give the user the setup and start commands from the README and stop: do not create or start an app yourself unless the user asks.
Rules that always apply:
- The admin email must be a made-up
example.comaddress. The home page, the user menu and the users list show it, and it ends up in the published screenshots. IfDEMO_STRAPI_EMAILis a real address, stop and tell the user. - Never print, copy or write the Enterprise license. Features such as Releases, Content History or Review Workflows need the app started with
STRAPI_LICENSE="$(cat <license file>)". Check them withcurl -s $DEMO_STRAPI_URL/admin/project-type(isEE: true). - Headless browsers only.
Step 2: Turn the description into a plan
How the capture works, which shapes the plan:
- Every step's screenshot is taken before the reader acts: a
clickorfillstep shows the screen with the element still to click, and its bubble sits on that screen. - The outro card is drawn over the last step's screenshot.
- Each capture opens a fresh browser: anything stored in the browser (filters in the URL, open panels) starts over, while anything stored on the server (entries, releases, content-type settings) carries over from the previous capture or from other demos.
Read description.md and map each sentence to one step of the scenario (step types in the README):
| The description says | Step |
|---|---|
| Show, highlight, point at, explain an area | explain (zoom: true when it asks to zoom on a small area) |
| Click, open, go to (the reader does it) | click |
| Pick an option in a dropdown | click: role=option[name="..."], with before clicking the dropdown to open it |
| Type, fill in, enter a value in a field | fill with value |
| A pause, a section title, a message with no target | chapter |
| Something that happens off-screen between two steps | a silent do step, or before / after actions |
| Text about the result of a click ("Click Save: 'Saved!'") | the click step gets an instruction text, and the result text goes on the next step. If the click is the last step, add an explain or chapter step after it to show the result |
Texts:
- When the description gives the text of a bubble (usually in quotes), use it word for word.
- When it does not, write one: one or two short sentences, the same tone as the other demos ("Let's…", "Click on…"), UI labels exactly as the interface displays them in
*italic*or**bold**. Never name a button or field that the interface does not display. No em dashes. \nonly for real paragraph breaks or list items, never to wrap a line.
The intro (text and button) and the outro (text only, with no links: the reader is already on the docs page, and the outro card offers a Restart button) come from the description, or follow the pattern of the existing demos.
For a new demo, write the skeleton of scenario.yaml first: title (from the description, or the feature name like the other demos), viewport (width: 1280, height: 800 unless the screens need more room), start, intro and outro, with steps: []. Then add the steps one by one in Step 3.
Step 3: Find the selectors, step by step
Use the exploration script to see the app exactly where a step is shown:
node claude-plugins/inki/skills/inki-interactive-demo/scripts/explore.js <id> --step <N> --out <scratch folder>
It runs the setup, replays the scenario up to step N (after that step's before actions), and writes a screenshot (step-N.png) and the accessibility tree (step-N.aria.yaml). It also says whether step N's target matches a visible element. With no steps yet, or to look beyond the last step, add --url /admin/....
Before exploring, search the existing scenarios for the same screens: grep -n "Filters" docusaurus/interactive-demos/*/scenario.yaml. A selector that already works in another demo is the best starting point.
For each step, in order:
- Run
explore.jsat that step and look at the screenshot and the tree. - Pick the selector, preferring accessible names from the tree:
role=button[name="Save"],role=option[name="category"],[aria-label="Locales"],input[name=title]. Names are case-sensitive: copy them from the tree. Use CSS only when no accessible name exists (an open menu hides the rest of the page from role selectors, for instance). - Add the step to
scenario.yamland runexplore.js --step <N>again until it reports the target as found. When it says a selector matches nothing or only hidden elements, look in the tree: the element is often inside a closed dropdown or menu (add abeforeclick) or has another name.
When the description asks for something the UI no longer has, use the closest equivalent and note it as a deviation (Step 6). When a step text would then become false, fix only the false part.
Use # comments in the YAML to explain any non-obvious choice: a CSS selector, a workaround, a deviation from the description.
Step 4: Write the setup when the tour changes data
If the tour creates, edits, publishes or deletes anything, the next capture would start from a different state. Write docusaurus/interactive-demos/<id>/setup.js (see the README and the existing setup files) that brings the app back to the state the tour starts from, through the admin API (api.get, api.post, api.put, api.del).
A tour that only looks at pages also needs a setup when its screens show data that other demos change: an entry count, the list view columns (stored on the server), a release list. Pin that state in the setup, or reuse what an existing setup file does (content-manager/setup.js sets the Article list columns, for instance).
Step 5: Capture, twice
node claude-plugins/inki/skills/inki-interactive-demo/scripts/capture.js <id>
It prints one line per step, step N <type> -> <image>: keep it, Step 6 uses it to pair steps with screenshots, since steps on the same screen share one image.
When a step fails (Target not visible, a timeout), run explore.js --step <N> on it, fix the step, and capture again. Once it passes, run the capture a second time in a row: both runs must succeed, which proves the setup resets the app.
Step 6: Check the result
- Look at the screenshots in
docusaurus/static/img/assets/interactive-demos/<id>/(light and_DARK). They are WebP files: convert the ones you open to PNG first (sips -s format png <file> --out <scratch folder>on macOS). They show the bare interface, without bubble or highlight. Using the capture log, check that the screen of each step shows what its text says. - Privacy: no real email address in any screenshot, and
grep "@" docusaurus/interactive-demos/<id>/generated-capture.jsonfinds onlyexample.comaddresses. - For a new demo, ask the user which docs page shows it, then add
<InteractiveDemo id="<id>" />there and check the page inyarn dev: go through the demo once. - If a docs page or the component changed, run
yarn build(check its exit code, never through a pipe).
Step 7: Report
Keep it short:
- Steps in the scenario, and how many the description asked for.
- Deviations: each place where the scenario differs from the description, with the reason.
- Image pairs, and two weights: what a reader downloads to go through the demo (
bytesin the JSON, light and dark) and what the images add to the repository (du -shof the image folder, all sizes included). - Files changed:
description.md,scenario.yaml,setup.js(if any), the JSON and the images, and the docs page.
Do not commit: leave that to the user, or to /inki-commit when asked.