@gallopsystems/agent-skills 1.31.2 → 1.32.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +13 -0
- package/package.json +1 -1
- package/plugins/gallop-ui/skills/gallop-ui/SKILL.md +1 -1
- package/plugins/gallop-ui/skills/gallop-ui/api-principles.md +5 -2
- package/plugins/gallop-ui/skills/gallop-ui/finding-a-component.md +5 -0
- package/plugins/gallop-ui/skills/gallop-ui/pitfalls.md +5 -0
- package/plugins/gallop-ui/skills/gallop-ui/pulling-updates.md +14 -3
- package/plugins/gallop-ui/skills/gallop-ui/using-in-an-app.md +15 -0
- package/plugins/generate-documentation/.claude-plugin/plugin.json +8 -0
- package/plugins/generate-documentation/skills/generate-documentation/SKILL.md +186 -0
- package/plugins/generate-documentation/skills/generate-documentation/bin/capture-example.mjs +53 -0
- package/plugins/generate-documentation/skills/generate-documentation/bin/render.mjs +82 -0
- package/plugins/generate-documentation/skills/generate-documentation/bin/shots.mjs +139 -0
- package/plugins/generate-documentation/skills/generate-documentation/formats.md +71 -0
- package/plugins/generate-documentation/skills/generate-documentation/templates/guide.html +116 -0
package/README.md
CHANGED
|
@@ -21,6 +21,7 @@ Then install the skills you want:
|
|
|
21
21
|
/plugin install vue-nuxt@gallop-systems-agent-skills
|
|
22
22
|
/plugin install frontend-design@gallop-systems-agent-skills
|
|
23
23
|
/plugin install gallop-ui@gallop-systems-agent-skills
|
|
24
|
+
/plugin install generate-documentation@gallop-systems-agent-skills
|
|
24
25
|
```
|
|
25
26
|
|
|
26
27
|
## Updating
|
|
@@ -180,6 +181,18 @@ Covers:
|
|
|
180
181
|
- Pulling a release: `yarn ui:pull`, `ui:migrate`, `ui:tokens`, `ui:check`, merge-commit subtree PRs
|
|
181
182
|
- Changing the layer, checking every app with `ui:impact` and screenshot sweeps, and working rules learned the hard way
|
|
182
183
|
|
|
184
|
+
### generate-documentation
|
|
185
|
+
|
|
186
|
+
Write a client-facing guide with real screenshots of the app, as a PDF, HTML page, email draft or WhatsApp messages.
|
|
187
|
+
Run it as `/generate-documentation <format> <what to document>`.
|
|
188
|
+
|
|
189
|
+
Covers:
|
|
190
|
+
- Two modes: **answer** (turn a client's questions into "you can already do this", "we changed it", "here's the fix") and **announce** (turn merged work into an unsolicited "you can now…" note)
|
|
191
|
+
- Checking each answer in the code and the running app before writing it
|
|
192
|
+
- Screenshots from a scratch copy of the app's fictional demo data only, never real data
|
|
193
|
+
- `bin/shots.mjs` Playwright helpers (sign-in, still captures, highlight rings, region and element shots) and `bin/render.mjs` (HTML to PDF, plus a contact sheet for reviewing page breaks)
|
|
194
|
+
- A guide template, writing rules for non-technical readers, and per-format rules
|
|
195
|
+
|
|
183
196
|
## Contributing a Lesson Back
|
|
184
197
|
|
|
185
198
|
Every skill ends with a **Contributing Back** section: when Claude works through
|
package/package.json
CHANGED
|
@@ -68,7 +68,7 @@ Detail, and how to propose a component: [finding-a-component.md](finding-a-compo
|
|
|
68
68
|
## Pull an update (decision procedure)
|
|
69
69
|
|
|
70
70
|
New worktree from `origin/main` → `yarn ui:pull vX.Y.Z` (its own commit; needs a clean tree) → read `CHANGELOG.md`
|
|
71
|
-
and `migrations/` between the two versions →
|
|
71
|
+
and `migrations/` between the two versions → whenever there's a newer `migrations/` table (minor releases too), `yarn ui:migrate --dry`, then `yarn ui:migrate`
|
|
72
72
|
and work its checklist → `yarn ui:tokens`, `yarn ui:check` → remove workarounds the release makes unnecessary → full
|
|
73
73
|
tests and a before/after visual sweep → PR, merged with a **merge commit**.
|
|
74
74
|
Steps and commands: [pulling-updates.md](pulling-updates.md).
|
|
@@ -108,8 +108,8 @@ colours: an app's extra button colour maps onto an existing `color`.
|
|
|
108
108
|
## `pt` sections and slots
|
|
109
109
|
|
|
110
110
|
- `class` is always `pt.root`. An overlay's `root` is its panel; its backdrop is `overlay`.
|
|
111
|
-
- Inside a list, an item's parts are `item`, `itemLabel`, `itemDescription`, `itemIcon
|
|
112
|
-
`groupLabel`.
|
|
111
|
+
- Inside a list, an item's parts are `item`, `itemLabel`, `itemDescription`, `itemIcon`, and every other part of a
|
|
112
|
+
row is prefixed `item` too (`itemBadge`, `itemCount`, `itemKbd`, `itemMeta`); a group heading is `groupLabel`.
|
|
113
113
|
- `icon` is only the component's own leading icon; other icons are named for their job (`toggleIcon`, `zoneIcon`,
|
|
114
114
|
`checkIcon`).
|
|
115
115
|
- A field's popup is `panel`; Tabs' panels are `tabPanel`; a title-plus-description block is `text`; an inner
|
|
@@ -150,6 +150,9 @@ colours: an app's extra button colour maps onto an existing `color`.
|
|
|
150
150
|
without new evidence.
|
|
151
151
|
- **Backward compatible by default:** a new prop or option must leave every existing call site rendering exactly as
|
|
152
152
|
before. A look that changes without the caller touching `pt` is a breaking change.
|
|
153
|
+
- **A rename can ship in a minor release** when the old name keeps working until the next major: a `pt` section
|
|
154
|
+
through `usePt`'s `renamed` map (a deprecated alias with one dev warning per old name), a data attribute rendered
|
|
155
|
+
under both names. It still gets a codemod row, so apps stop using the old name before the major removes it.
|
|
153
156
|
- **Breaking changes after 1.0** need a major release, a `CHANGELOG.md` note, and a row per change in
|
|
154
157
|
`migrations/<version>/<area>.json` with a `codemod` the kit can apply (`rename`, `invert-to`, `wrap-array`…) or
|
|
155
158
|
`manual` with a `locate` and a note. `yarn ui:migrate` then rewrites apps and writes the checklist. Before 1.0,
|
|
@@ -50,6 +50,11 @@ instead of a choice), it is a different component.
|
|
|
50
50
|
While the layer change is pending, the app may carry a small, local workaround marked `TODO(gallop-ui): <what the
|
|
51
51
|
layer should do>`. The next `ui:pull` removes it.
|
|
52
52
|
|
|
53
|
+
**A list of rows you write yourself** (people with an avatar and actions, settings rows, a pick-one list, a list the
|
|
54
|
+
user reorders) is `List` with `ListItem` and `ListGroup`: slots for leading, content and actions; selection with
|
|
55
|
+
checkboxes or pick-one; reorder; ghost or outlined, ruled or gapped. Don't hand-roll a `<ul>` with borders and
|
|
56
|
+
checkboxes. A list of records with columns is still `DataTable`.
|
|
57
|
+
|
|
53
58
|
## 4. No match: compose, then propose
|
|
54
59
|
|
|
55
60
|
1. **Compose layer primitives in the app** (`Card` + `DescriptionList` + `Button`…), in an app component named for
|
|
@@ -66,6 +66,11 @@ Rules learned the hard way while building the layer and moving every app onto it
|
|
|
66
66
|
open must read it again.
|
|
67
67
|
- **DataTable cell state follows the position** on a page turn unless the stateful component has `:key="row.id"`.
|
|
68
68
|
- **Don't copy an old phone table** with `layout="table"`: phones get cards.
|
|
69
|
+
- **Default icons missing after a pull?** The app has no `gallopUi.icons` and no `@iconify-json/ph`, so the layer
|
|
70
|
+
draws Phosphor from a collection that isn't there. Run `yarn ui:migrate` (it writes `icons: "lucide"`), or install
|
|
71
|
+
Phosphor on purpose. The layer prints a `[gallop-ui]` warning at build time for this.
|
|
72
|
+
- **A dev warning `[gallop-ui] <Component> pt "<old>" is deprecated`** means the app uses a name a minor release
|
|
73
|
+
renamed. It still works; run `yarn ui:migrate` to rename it before the next major removes it.
|
|
69
74
|
- **`/_ui` shows the wrong font?** The app sets its font from a layout. Move it to `--font-sans` in `@theme`.
|
|
70
75
|
|
|
71
76
|
## Verifying and reporting
|
|
@@ -40,12 +40,23 @@ ls layers/gallop-ui/migrations/; cat layers/gallop-ui/docs/upgrading.md
|
|
|
40
40
|
```
|
|
41
41
|
|
|
42
42
|
For each entry, decide: does this app call it (`git grep -n "<Component\|propName" -- app tests`), and does the call
|
|
43
|
-
site need to change? Read the affected components' `.md` "Migrating" sections.
|
|
44
|
-
|
|
43
|
+
site need to change? Read the affected components' `.md` "Migrating" sections. Any release with renames has a
|
|
44
|
+
`migrations/<major.minor>/` folder, minor releases included (1.1 has one); `docs/upgrading.md` explains how to apply it. Jumping several releases is
|
|
45
45
|
fine as long as you read every entry in between. The kit only knows the versions it has tables for, so check the
|
|
46
46
|
migration doc for how far back it reaches.
|
|
47
47
|
|
|
48
|
-
## 3. Run the codemod
|
|
48
|
+
## 3. Run the codemod whenever there's a newer table
|
|
49
|
+
|
|
50
|
+
Run it whenever `layers/gallop-ui/migrations/` has a folder newer than the version you came from, minor or major.
|
|
51
|
+
|
|
52
|
+
- **Minor releases (1.1, 1.2…) rename without breaking.** A renamed `pt` section keeps its old name as a deprecated
|
|
53
|
+
alias until the next major, and a renamed data attribute is rendered under both names. So the app renders the same
|
|
54
|
+
before the codemod, but logs one dev warning per old name: `[gallop-ui] <Component> pt "<old>" is deprecated`. Run
|
|
55
|
+
the codemod anyway so the warnings stop and the next major is a non-event.
|
|
56
|
+
- **A minor release can also add settings for existing apps.** 1.1's `icons` row writes `icons: "lucide"` into
|
|
57
|
+
`app/app.config.ts` so an existing app keeps its icons. Commit that line with the codemod output, and keep it.
|
|
58
|
+
- **Major releases break.** The old names are gone; the codemod and its checklist are how the app keeps working.
|
|
59
|
+
- An app already on the newest table gets `nothing to migrate` (exit 0).
|
|
49
60
|
|
|
50
61
|
```sh
|
|
51
62
|
yarn ui:migrate --dry # the diff and counts; nothing written
|
|
@@ -69,6 +69,19 @@ a plain class chosen in script, so a caller's class always beats it. What that m
|
|
|
69
69
|
- Overlays (Modal, Drawer, Popover, Tooltip, DropdownMenu) portal their box away: that box is `root`, so `class`
|
|
70
70
|
still styles what you see. The backdrop is `overlay`.
|
|
71
71
|
|
|
72
|
+
## Icons
|
|
73
|
+
|
|
74
|
+
- **One icon set per app: `gallopUi.icons`** in `app/app.config.ts`, `"phosphor"` (the layer's default, and a new
|
|
75
|
+
app's) or `"lucide"` (apps from before 1.1; `ui:migrate` writes it so they keep their glyphs). The layer's own
|
|
76
|
+
icons (chevrons, close, check, search…) follow it. Write the app's own icons in the same set (`ph:*` or
|
|
77
|
+
`lucide:*`), never a mix.
|
|
78
|
+
- The set's collection must be installed (`@iconify-json/ph` or `@iconify-json/lucide`) and listed in
|
|
79
|
+
`icon.serverBundle.collections`. The layer warns at build time when it isn't; otherwise the default icons would
|
|
80
|
+
silently be missing. `layers/gallop-ui/docs/icons.md` has the setup and a name map between the sets.
|
|
81
|
+
- An `icon` prop takes any Iconify name and is never mapped: `icon="ph:users"` stays Phosphor whatever the setting.
|
|
82
|
+
- To change single layer icons, give `gallopUi.icons` a map of roles instead of a preset name: `icons: { close: "ph:x-circle" }`
|
|
83
|
+
overrides that role over Phosphor. The roles are in `layers/gallop-ui/docs/icons.md`.
|
|
84
|
+
|
|
72
85
|
## Tokens and dark mode
|
|
73
86
|
|
|
74
87
|
- **Dark mode is required in every app.** No light-only option, no pinned light colours.
|
|
@@ -76,6 +89,8 @@ a plain class chosen in script, so a caller's class always beats it. What that m
|
|
|
76
89
|
strategy: the OS (`:root { color-scheme: light dark }`, the template default), or an attribute on `<html>`
|
|
77
90
|
(`data-color-scheme="light|dark"`, set from a cookie by `useColorScheme()`; no flash on first paint).
|
|
78
91
|
`TOKENS.md` has the contract; `theme/neutral.css` has every value.
|
|
92
|
+
- **A bare `border` is the `line` colour** (the layer's base style), not `currentColor`. Add a colour class only to
|
|
93
|
+
change it; `border-current` brings back the text colour.
|
|
79
94
|
- In app code write token classes (`bg-surface`, `text-fg-muted`, `border-line`, `bg-danger-soft`), not
|
|
80
95
|
`bg-white dark:bg-zinc-900`. Status colours are the `danger | warning | success | info` families.
|
|
81
96
|
- `yarn ui:tokens` checks the app's theme CSS against the contract: what is missing, what still has an old name.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "generate-documentation",
|
|
3
|
+
"description": "Write a client-facing guide with screenshots of the app (PDF, HTML, email or WhatsApp): answer a client's questions, or announce what shipped. Screenshots come from fictional demo data only; includes Playwright capture helpers and a PDF renderer with a page-review contact sheet.",
|
|
4
|
+
"version": "1.0.0",
|
|
5
|
+
"author": {
|
|
6
|
+
"name": "Gallop Systems"
|
|
7
|
+
}
|
|
8
|
+
}
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: generate-documentation
|
|
3
|
+
description: Write a client-facing guide with screenshots of the app, as a PDF, HTML page, email or WhatsApp messages. Two modes. "answer" turns a client's questions into answers ("you can already do this, here's how", "we changed it, here's how it works", "here's why that happened and the fix"). "announce" turns merged work into an unsolicited "you can now…" note. Use when the user wants to send a client or their staff documentation, a how-to, release notes, a "what's new" or answers to their questions about a Gallop app, even if they don't say "documentation".
|
|
4
|
+
argument-hint: <pdf|html|email|whatsapp> <answer: pasted questions | announce: PR, branch, or "what merged since …">
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Generate client documentation
|
|
8
|
+
|
|
9
|
+
You are writing for the client's staff: people who use the app every day and do
|
|
10
|
+
not read code. The result is a document they can follow alone, with real
|
|
11
|
+
screenshots of the app, that never shows real client data.
|
|
12
|
+
|
|
13
|
+
Arguments: a **format** (`pdf`, `html`, `email`, `whatsapp`; default `pdf`) and
|
|
14
|
+
what to document. Work out the **mode** from what you are given:
|
|
15
|
+
|
|
16
|
+
- **answer**: their questions or messages (pasted, a screenshot, an email). Each
|
|
17
|
+
question gets a section.
|
|
18
|
+
- **announce**: work that shipped (a PR, a branch, "everything merged since
|
|
19
|
+
Monday", or "the feature we just built"). Each user-visible change gets a
|
|
20
|
+
section. Nobody asked; you are telling them what they can now do.
|
|
21
|
+
|
|
22
|
+
If the format or the mode is unclear, ask once. Everything else you decide.
|
|
23
|
+
|
|
24
|
+
Format-specific output rules are in [formats.md](formats.md). Read it before
|
|
25
|
+
writing.
|
|
26
|
+
|
|
27
|
+
## 1. Work out what is true
|
|
28
|
+
|
|
29
|
+
Do this before taking a single screenshot. A guide that confidently describes the
|
|
30
|
+
wrong thing is worse than no guide.
|
|
31
|
+
|
|
32
|
+
### answer mode
|
|
33
|
+
|
|
34
|
+
Split the messages into separate questions (people send several in a row). For
|
|
35
|
+
each one, find out from the code, the in-app docs and the data (read-only) which
|
|
36
|
+
of these it is:
|
|
37
|
+
|
|
38
|
+
| Kind | Tag in the guide | What the section does |
|
|
39
|
+
|---|---|---|
|
|
40
|
+
| They can already do it | **You can do this already** | Numbered steps with screenshots |
|
|
41
|
+
| It needed a change, and we made it | **New** | How it works now, with screenshots, and the rules |
|
|
42
|
+
| A setting, data or setup problem | **A setting to fix** | Why it happened, then the fix |
|
|
43
|
+
| Not possible yet | (leave out, or **Not yet**) | Say so plainly; ask the user whether to build it before you write anything |
|
|
44
|
+
| Something only they can tell you | **Needs your answer** | Ask the question; don't guess |
|
|
45
|
+
|
|
46
|
+
Look at how the status or behaviour they're asking about is *derived*, not just
|
|
47
|
+
what it is called. "Why does it say Ready to send?" is usually answered by the
|
|
48
|
+
rule behind the label (a list of required items, a permission, a filter on an import).
|
|
49
|
+
Fixing the input to that rule is usually something they can do themselves.
|
|
50
|
+
|
|
51
|
+
For a question about records that are missing or wrong, check the actual records
|
|
52
|
+
(read-only) and the job that is supposed to bring them in (when it last ran,
|
|
53
|
+
whether it failed, what it filters on). If you cannot read production, give the
|
|
54
|
+
user a read-only query to run and wait for the result. Don't write the section on
|
|
55
|
+
a guess.
|
|
56
|
+
|
|
57
|
+
### announce mode
|
|
58
|
+
|
|
59
|
+
Collect what shipped: `gh pr view <n> --json title,body,files`, `git log
|
|
60
|
+
<range>`, or the merged PRs since a date. Then keep only **user-visible
|
|
61
|
+
changes**. Drop refactors, tests, dependency bumps, internal tooling and
|
|
62
|
+
performance work nobody will notice.
|
|
63
|
+
|
|
64
|
+
For each change that is left:
|
|
65
|
+
|
|
66
|
+
- Read the diff for its real behaviour: what staff see, what they click, what
|
|
67
|
+
changes on its own, and what changes the day it goes live (existing records that
|
|
68
|
+
will suddenly look different). That last one is the thing clients most need to
|
|
69
|
+
hear in advance.
|
|
70
|
+
- Read the page's in-app doc if the repo has them (Gallop portals keep one beside
|
|
71
|
+
every page). If the PR changed behaviour and didn't update that doc, tell the
|
|
72
|
+
user. Don't paper over it in the guide.
|
|
73
|
+
- Check who can use it. Admin-only screens either go in an admin-only guide or
|
|
74
|
+
are marked "ask your admin".
|
|
75
|
+
- Check it has been merged, or deployed if the user says the client already has
|
|
76
|
+
it. Never announce work that is still in progress.
|
|
77
|
+
|
|
78
|
+
Several changes make one short "What's new" guide. One feature makes a one-pager.
|
|
79
|
+
|
|
80
|
+
## 2. Try every step in the app
|
|
81
|
+
|
|
82
|
+
Before writing a step, do it in the running app on demo data: click every button
|
|
83
|
+
you are about to tell them to click. This is where wrong answers show up. A
|
|
84
|
+
move the guide said would work gets refused because the target record lacks a permission.
|
|
85
|
+
A setting turns out to be admin-only. A label on screen differs from the code's
|
|
86
|
+
name for it. When doing it shows your earlier answer was wrong, fix the answer,
|
|
87
|
+
and tell the user what changed.
|
|
88
|
+
|
|
89
|
+
## 3. Screenshots, from demo data only
|
|
90
|
+
|
|
91
|
+
**Never capture from a database or environment holding real client data**, not
|
|
92
|
+
even "just to look". The pictures go to the client and may be forwarded on.
|
|
93
|
+
|
|
94
|
+
1. **Find the safe data.** Read the repo's CLAUDE.md. Gallop Nuxt apps usually
|
|
95
|
+
have a fictional demo database and a dev server for doc screenshots (for
|
|
96
|
+
example `yarn docs:demo-data` and `yarn docs:dev`), plus a dev-only preview
|
|
97
|
+
login (`/api/auth/preview-login`). Build a **scratch copy** of the demo
|
|
98
|
+
database under its own name, and serve it on its own port, so you don't clash
|
|
99
|
+
with other sessions. If the repo has no fictional data source, stop and tell
|
|
100
|
+
the user. Don't screenshot real data, and don't invent data in a real database.
|
|
101
|
+
2. **Stage the scenarios** in the scratch database with SQL: the record that
|
|
102
|
+
shows the problem, the setting before it is fixed, the record filed under the
|
|
103
|
+
wrong owner. Use the same kind of record the client described, with made-up names.
|
|
104
|
+
Remove anything that distracts from the point (an unrelated badge on the same
|
|
105
|
+
card).
|
|
106
|
+
3. **Script the captures.** Copy [bin/capture-example.mjs](bin/capture-example.mjs)
|
|
107
|
+
to a scratch directory and write one step per section; it imports
|
|
108
|
+
[bin/shots.mjs](bin/shots.mjs). Run it from the app repo
|
|
109
|
+
(`cd <repo> && node <scratch>/capture.mjs <out-dir> [step]`), so Playwright
|
|
110
|
+
resolves from there. For each step, capture before, the action and after.
|
|
111
|
+
Ring the thing to click with `mark()`.
|
|
112
|
+
4. **Look at every image** before using it. Common faults: the crop cuts off the
|
|
113
|
+
heading, the wrong column was clicked, a dialog is half-rendered, or the
|
|
114
|
+
picture shows a state from a previous run.
|
|
115
|
+
5. **Reset what a step changed**, at the start of that step, so any step can be
|
|
116
|
+
re-run alone.
|
|
117
|
+
|
|
118
|
+
Capture gotchas:
|
|
119
|
+
|
|
120
|
+
- Find table columns by their header text, never by position: an index that was
|
|
121
|
+
right for one table clicks the neighbouring column of the next. A cell that
|
|
122
|
+
cycles states (Required → Optional → none) will have been changed by the wrong
|
|
123
|
+
click, so check the data and put it back.
|
|
124
|
+
- Write capture scripts as `.mjs`. A `.ts` file run through `tsx` outside a
|
|
125
|
+
`"type": "module"` package fails on top-level `await`
|
|
126
|
+
(`ERR_REQUIRE_ASYNC_MODULE`).
|
|
127
|
+
- Use `element()` for dialogs and drawers. For a panel, frame it with `shot()`
|
|
128
|
+
on its heading and its last line, or find it with
|
|
129
|
+
`xpath=ancestor::*[.//button[normalize-space()='…']][1]`.
|
|
130
|
+
- A Nuxt dev server freshly started after a lockfile change can 500 every
|
|
131
|
+
request with "IPC connection closed" while Vite re-optimizes. Restart it once.
|
|
132
|
+
- Image viewers, the Read tool included, can cache an image by its path.
|
|
133
|
+
When you regenerate a review image, give it a new name.
|
|
134
|
+
|
|
135
|
+
## 4. Write it
|
|
136
|
+
|
|
137
|
+
The writing rules hold in every format:
|
|
138
|
+
|
|
139
|
+
- **Their words, the app's labels.** Head each section with their question or the
|
|
140
|
+
feature in plain words. Name every button, menu and field exactly as it appears
|
|
141
|
+
on screen, in bold. No file paths, routes, table names, code or developer terms.
|
|
142
|
+
- **Second person, short sentences, one action per step.**
|
|
143
|
+
- **Say why before how**, in a sentence: "An order says Ready to ship once every
|
|
144
|
+
required document is in, and this product line doesn't require the signed
|
|
145
|
+
form." Then the steps.
|
|
146
|
+
- **Say who can do it.** If a step needs an admin, or a particular sign-in, say so
|
|
147
|
+
at the top of the guide and at the step.
|
|
148
|
+
- **Say what else it changes.** A setting changed for one record usually applies
|
|
149
|
+
to all of them. Say so, and give the narrower alternative when there is one.
|
|
150
|
+
- **Warn about day one.** If going live will change how many existing records
|
|
151
|
+
look, say what they'll see and that it is expected.
|
|
152
|
+
- **Warn about doing both.** When there are two ways to fix something and doing
|
|
153
|
+
both creates a duplicate, say "pick one".
|
|
154
|
+
- **"Please confirm first"** when the right fix depends on a fact only they know
|
|
155
|
+
(is this supplier the contract holder, or working under someone else's?). Give both branches.
|
|
156
|
+
- **Note the demo data** once, near the top: the screenshots use made-up records,
|
|
157
|
+
so the names differ but the screens are the same.
|
|
158
|
+
- Don't apologise, don't mention AI, and don't describe how you investigated.
|
|
159
|
+
|
|
160
|
+
## 5. Render, review, deliver
|
|
161
|
+
|
|
162
|
+
- **pdf and html:** start from [templates/guide.html](templates/guide.html) (its
|
|
163
|
+
header comment lists the building blocks), then render with
|
|
164
|
+
`node <skill-dir>/bin/render.mjs <guide.html> <out.pdf> --footer "<App name>"`,
|
|
165
|
+
run from the app repo. **Look at the contact sheet it prints.** Fix a heading
|
|
166
|
+
stranded at the foot of a page, a page holding a single note, or a figure
|
|
167
|
+
separated from its step: use `.keep` wrappers, a smaller figure width, or move a
|
|
168
|
+
note above its figures. Re-render, and look again.
|
|
169
|
+
- **email and whatsapp:** see [formats.md](formats.md).
|
|
170
|
+
- Save the deliverable where the user can open it, and hand it over (attach it
|
|
171
|
+
where your environment can). **Never send it yourself.** Emails are drafts,
|
|
172
|
+
WhatsApp text is for the user to paste, and publishing anything waits for
|
|
173
|
+
their yes.
|
|
174
|
+
- Then clean up: stop the dev servers you started, drop the scratch databases,
|
|
175
|
+
and undo any launch-config entries you added. Keep the capture script in
|
|
176
|
+
scratch so the user can ask for a retake.
|
|
177
|
+
|
|
178
|
+
In your reply, give the user the file, a line per section, and anything you
|
|
179
|
+
found that changes an earlier answer. Also list any open question the guide asks
|
|
180
|
+
the client to confirm.
|
|
181
|
+
|
|
182
|
+
## Contributing Back
|
|
183
|
+
|
|
184
|
+
This skill grows by capturing what it missed. If you just worked through something in this domain that this skill did not cover — an error you had to figure out, a behavior that contradicts what is documented above, a workflow knot — ask the user: **"Want me to contribute this back to the generate-documentation skill?"**
|
|
185
|
+
|
|
186
|
+
If yes, run `/contribute-skill`. If that command is not available, do the equivalent inline: distill the generic lesson (placeholders only — no project names, IDs, domains, or secrets), then branch or fork [gallop-systems/agent-skills](https://github.com/gallop-systems/agent-skills) and open a PR editing this skill.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Example per-job capture script. Copy it to a scratch directory, edit the
|
|
3
|
+
* steps, and run it from the app repo:
|
|
4
|
+
*
|
|
5
|
+
* cd <app repo> && node <scratch>/capture.mjs <out-dir> [only-step]
|
|
6
|
+
*
|
|
7
|
+
* Paths, labels and SQL below are placeholders for a typical Gallop Nuxt app.
|
|
8
|
+
*/
|
|
9
|
+
import { open, run, sql } from "<skill-dir>/bin/shots.mjs";
|
|
10
|
+
|
|
11
|
+
const [outDir, only] = process.argv.slice(2);
|
|
12
|
+
const BASE = "http://localhost:3100"; // the demo-data dev server, never one on real data
|
|
13
|
+
const DB = "postgresql://localhost:5432/<app>-docs-scratch"; // a scratch copy of the demo DB
|
|
14
|
+
const db = (q) => sql(DB, q);
|
|
15
|
+
|
|
16
|
+
const { browser, page, kit } = await open({ base: BASE, login: "/api/auth/preview-login" });
|
|
17
|
+
kit.out(outDir);
|
|
18
|
+
|
|
19
|
+
await run(
|
|
20
|
+
{
|
|
21
|
+
// A thing the user can already do: show before, the click, and after.
|
|
22
|
+
async setting() {
|
|
23
|
+
db("update widgets set required = false where code = 'example'"); // reset, so the step re-runs
|
|
24
|
+
await kit.go("/admin/widgets");
|
|
25
|
+
const table = page.locator("table").first();
|
|
26
|
+
const heads = await table.locator("thead th").allInnerTexts();
|
|
27
|
+
const col = heads.findIndex((h) => h.trim() === "Example"); // find columns by header text, never by index
|
|
28
|
+
const cell = table.locator("tbody tr", { hasText: "Row label" }).first().locator("th, td").nth(col);
|
|
29
|
+
await kit.mark(cell);
|
|
30
|
+
await kit.shot("setting-1-before", [table.locator("thead"), cell]);
|
|
31
|
+
await kit.unmark();
|
|
32
|
+
await cell.locator("button").first().click();
|
|
33
|
+
await page.waitForTimeout(1000);
|
|
34
|
+
await kit.mark(cell);
|
|
35
|
+
await kit.shot("setting-2-after", [table.locator("thead"), cell]);
|
|
36
|
+
await kit.unmark();
|
|
37
|
+
},
|
|
38
|
+
|
|
39
|
+
// A dialog or drawer: shoot the element itself.
|
|
40
|
+
async dialog() {
|
|
41
|
+
await kit.go("/records/1");
|
|
42
|
+
await page.getByRole("button", { name: "Outcome" }).first().click();
|
|
43
|
+
await kit.settle(500);
|
|
44
|
+
const dialog = page.getByRole("dialog").last();
|
|
45
|
+
await kit.mark(dialog.getByRole("button", { name: "Transfer…" }));
|
|
46
|
+
await kit.element("dialog-1", dialog);
|
|
47
|
+
await kit.unmark();
|
|
48
|
+
},
|
|
49
|
+
},
|
|
50
|
+
{ only },
|
|
51
|
+
);
|
|
52
|
+
|
|
53
|
+
await browser.close();
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Render a guide's HTML to PDF, and make a contact sheet of its pages to review.
|
|
3
|
+
* Run it from the app repo, so Playwright resolves from there:
|
|
4
|
+
*
|
|
5
|
+
* cd <app repo> && node <skill-dir>/bin/render.mjs <guide.html> <out.pdf> [--footer "Product name"]
|
|
6
|
+
*
|
|
7
|
+
* Prints the page count and the path of `<out>.sheet.png` (every page side by
|
|
8
|
+
* side). Look at the sheet before sending: it is how you catch a heading left at
|
|
9
|
+
* the bottom of a page, a page holding one note, or a screenshot split from its
|
|
10
|
+
* step. The sheet needs `pdftoppm` (poppler) and ImageMagick; without them it is
|
|
11
|
+
* skipped and only the page count is printed.
|
|
12
|
+
*/
|
|
13
|
+
import { createRequire } from "node:module";
|
|
14
|
+
import { execFileSync } from "node:child_process";
|
|
15
|
+
import fs from "node:fs";
|
|
16
|
+
import os from "node:os";
|
|
17
|
+
import path from "node:path";
|
|
18
|
+
|
|
19
|
+
const require = createRequire(path.join(process.cwd(), "package.json"));
|
|
20
|
+
const { chromium } = require("playwright");
|
|
21
|
+
|
|
22
|
+
const args = process.argv.slice(2);
|
|
23
|
+
const footerAt = args.indexOf("--footer");
|
|
24
|
+
const footer = footerAt >= 0 ? args.splice(footerAt, 2)[1] : "";
|
|
25
|
+
const [html, out] = args.map((p) => path.resolve(p));
|
|
26
|
+
if (!html || !out) {
|
|
27
|
+
console.error("usage: render.mjs <guide.html> <out.pdf> [--footer text]");
|
|
28
|
+
process.exit(1);
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
const escape = (s) => s.replace(/[&<>"]/g, (c) => ({ "&": "&", "<": "<", ">": ">", '"': """ })[c]);
|
|
32
|
+
const browser = await chromium.launch();
|
|
33
|
+
const page = await browser.newPage();
|
|
34
|
+
await page.goto(`file://${html}`, { waitUntil: "networkidle" });
|
|
35
|
+
await page.evaluate(() => document.fonts.ready);
|
|
36
|
+
await page.pdf({
|
|
37
|
+
path: out,
|
|
38
|
+
format: "Letter",
|
|
39
|
+
printBackground: true,
|
|
40
|
+
preferCSSPageSize: true,
|
|
41
|
+
displayHeaderFooter: true,
|
|
42
|
+
headerTemplate: "<span></span>",
|
|
43
|
+
footerTemplate: `<div style="font-size:7pt;color:#8a847b;width:100%;text-align:center;font-family:sans-serif">${
|
|
44
|
+
footer ? `${escape(footer)} · ` : ""
|
|
45
|
+
}<span class="pageNumber"></span> of <span class="totalPages"></span></div>`,
|
|
46
|
+
});
|
|
47
|
+
await browser.close();
|
|
48
|
+
|
|
49
|
+
const has = (bin) => {
|
|
50
|
+
try {
|
|
51
|
+
execFileSync("which", [bin], { stdio: "ignore" });
|
|
52
|
+
return true;
|
|
53
|
+
} catch {
|
|
54
|
+
return false;
|
|
55
|
+
}
|
|
56
|
+
};
|
|
57
|
+
|
|
58
|
+
if (has("pdftoppm") && has("magick")) {
|
|
59
|
+
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "gd-pages-"));
|
|
60
|
+
execFileSync("pdftoppm", ["-r", "60", "-png", out, path.join(dir, "p")]);
|
|
61
|
+
const pages = fs.readdirSync(dir).filter((f) => f.endsWith(".png")).sort((a, b) =>
|
|
62
|
+
a.localeCompare(b, undefined, { numeric: true }),
|
|
63
|
+
);
|
|
64
|
+
// A new name every run: an image viewer that caches by path would show the old sheet.
|
|
65
|
+
const sheet = out.replace(/\.pdf$/i, `.sheet-${Date.now()}.png`);
|
|
66
|
+
const cols = Math.min(5, pages.length);
|
|
67
|
+
execFileSync("magick", [
|
|
68
|
+
"montage",
|
|
69
|
+
...pages.map((p) => path.join(dir, p)),
|
|
70
|
+
"-tile", `${cols}x`,
|
|
71
|
+
"-geometry", "+6+6",
|
|
72
|
+
"-background", "#999",
|
|
73
|
+
sheet,
|
|
74
|
+
]);
|
|
75
|
+
console.log(`${pages.length} pages`);
|
|
76
|
+
console.log(`sheet: ${sheet}`);
|
|
77
|
+
console.log(`pages: ${dir}`);
|
|
78
|
+
} else {
|
|
79
|
+
const count = (fs.readFileSync(out, "latin1").match(/\/Type\s*\/Page[^s]/g) ?? []).length;
|
|
80
|
+
console.log(`${count} pages (install poppler and imagemagick for a contact sheet)`);
|
|
81
|
+
}
|
|
82
|
+
console.log(`pdf: ${out}`);
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Screenshot helpers for /generate-documentation.
|
|
3
|
+
*
|
|
4
|
+
* Import this from a per-job capture script (see capture-example.mjs). Playwright
|
|
5
|
+
* is resolved from the APP repo (the current working directory), not from this
|
|
6
|
+
* skill, so nothing needs installing here:
|
|
7
|
+
*
|
|
8
|
+
* cd <app repo> && node <scratch>/capture.mjs <out-dir> [only-step]
|
|
9
|
+
*
|
|
10
|
+
* Every helper works on one page that is already signed in. Captures are 2x,
|
|
11
|
+
* light theme, reduced motion, with dev chrome (Nuxt devtools, loading bar,
|
|
12
|
+
* scrollbars) hidden, so re-running a step gives the same picture.
|
|
13
|
+
*/
|
|
14
|
+
import { createRequire } from "node:module";
|
|
15
|
+
import { execFileSync } from "node:child_process";
|
|
16
|
+
import path from "node:path";
|
|
17
|
+
import fs from "node:fs";
|
|
18
|
+
|
|
19
|
+
const require = createRequire(path.join(process.cwd(), "package.json"));
|
|
20
|
+
const { chromium } = require("playwright");
|
|
21
|
+
|
|
22
|
+
export const STILL_CSS = `
|
|
23
|
+
*, *::before, *::after { transition: none !important; animation: none !important; caret-color: transparent !important; }
|
|
24
|
+
nuxt-devtools-frame, nuxt-devtools-inspect-panel, #nuxt-devtools-container, #nuxt-devtools-anchor,
|
|
25
|
+
[id^="nuxt-devtools"], #vue-tracer-overlay, vite-error-overlay, .nuxt-loading-indicator { display: none !important; }
|
|
26
|
+
::-webkit-scrollbar { display: none; }
|
|
27
|
+
.gd-mark { outline: 3px solid #e4572e !important; outline-offset: 3px; border-radius: 6px; }
|
|
28
|
+
`;
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* Open a browser signed in to `base`.
|
|
32
|
+
* `login` is a path that signs in on GET (a dev/preview login route), or an
|
|
33
|
+
* async function `(page) => {}` that signs in some other way.
|
|
34
|
+
*/
|
|
35
|
+
export async function open({ base, login, width = 1440, height = 900, timeZone = "America/New_York" }) {
|
|
36
|
+
const browser = await chromium.launch();
|
|
37
|
+
const context = await browser.newContext({
|
|
38
|
+
viewport: { width, height },
|
|
39
|
+
deviceScaleFactor: 2,
|
|
40
|
+
colorScheme: "light",
|
|
41
|
+
reducedMotion: "reduce",
|
|
42
|
+
timezoneId: timeZone,
|
|
43
|
+
});
|
|
44
|
+
// esbuild's keepNames helper, which some dev bundles reference before defining.
|
|
45
|
+
await context.addInitScript("globalThis.__name = (fn) => fn;");
|
|
46
|
+
const page = await context.newPage();
|
|
47
|
+
if (typeof login === "string") await page.goto(new URL(login, base).href);
|
|
48
|
+
else if (login) await login(page);
|
|
49
|
+
return { browser, page, kit: kit(page, base) };
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
function kit(page, base) {
|
|
53
|
+
let outDir = ".";
|
|
54
|
+
const k = {
|
|
55
|
+
page,
|
|
56
|
+
/** Where `shot`/`full`/`element` write. */
|
|
57
|
+
out(dir) {
|
|
58
|
+
outDir = dir;
|
|
59
|
+
fs.mkdirSync(dir, { recursive: true });
|
|
60
|
+
},
|
|
61
|
+
/** Go to a path and wait for it to be still. */
|
|
62
|
+
async go(p) {
|
|
63
|
+
await page.goto(new URL(p, base).href);
|
|
64
|
+
await k.settle();
|
|
65
|
+
},
|
|
66
|
+
/** Wait for the network, fonts and a beat for skeletons; re-apply the still CSS. */
|
|
67
|
+
async settle(ms = 700) {
|
|
68
|
+
await page.waitForLoadState("networkidle").catch(() => {});
|
|
69
|
+
await page.addStyleTag({ content: STILL_CSS });
|
|
70
|
+
await page.evaluate(() => document.fonts.ready);
|
|
71
|
+
await page.waitForTimeout(ms);
|
|
72
|
+
},
|
|
73
|
+
/** Ring the given elements (call `unmark` after the shot). */
|
|
74
|
+
async mark(...locators) {
|
|
75
|
+
for (const l of locators) await l.evaluate((el) => el.classList.add("gd-mark"));
|
|
76
|
+
},
|
|
77
|
+
async unmark() {
|
|
78
|
+
await page.evaluate(() =>
|
|
79
|
+
document.querySelectorAll(".gd-mark").forEach((el) => el.classList.remove("gd-mark")),
|
|
80
|
+
);
|
|
81
|
+
},
|
|
82
|
+
/**
|
|
83
|
+
* Screenshot the box that covers every locator, padded. Use two locators to
|
|
84
|
+
* frame a region (a heading and the last thing under it).
|
|
85
|
+
*/
|
|
86
|
+
async shot(name, locators, pad = 14) {
|
|
87
|
+
for (const l of locators) await l.scrollIntoViewIfNeeded().catch(() => {});
|
|
88
|
+
const boxes = [];
|
|
89
|
+
for (const l of locators) {
|
|
90
|
+
const box = await l.boundingBox();
|
|
91
|
+
if (!box) throw new Error(`shot ${name}: a locator is not visible`);
|
|
92
|
+
boxes.push(box);
|
|
93
|
+
}
|
|
94
|
+
const vw = page.viewportSize().width;
|
|
95
|
+
const x = Math.max(0, Math.min(...boxes.map((b) => b.x)) - pad);
|
|
96
|
+
const y = Math.max(0, Math.min(...boxes.map((b) => b.y)) - pad);
|
|
97
|
+
const right = Math.min(vw, Math.max(...boxes.map((b) => b.x + b.width)) + pad);
|
|
98
|
+
const bottom = Math.max(...boxes.map((b) => b.y + b.height)) + pad;
|
|
99
|
+
await page.screenshot({
|
|
100
|
+
path: path.join(outDir, `${name}.png`),
|
|
101
|
+
clip: { x, y, width: right - x, height: bottom - y },
|
|
102
|
+
});
|
|
103
|
+
console.log("shot", name);
|
|
104
|
+
},
|
|
105
|
+
/** One element exactly (a dialog, a drawer). */
|
|
106
|
+
async element(name, locator) {
|
|
107
|
+
await locator.screenshot({ path: path.join(outDir, `${name}.png`) });
|
|
108
|
+
console.log("shot", name);
|
|
109
|
+
},
|
|
110
|
+
/** The whole viewport. */
|
|
111
|
+
async full(name) {
|
|
112
|
+
await page.screenshot({ path: path.join(outDir, `${name}.png`) });
|
|
113
|
+
console.log("shot", name);
|
|
114
|
+
},
|
|
115
|
+
};
|
|
116
|
+
return k;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* Run the named steps in order, or just `only`. Each step is an async function
|
|
121
|
+
* taking the kit. Steps should reset the demo data they change (with `sql`) so
|
|
122
|
+
* any one of them can be re-run alone.
|
|
123
|
+
*/
|
|
124
|
+
export async function run(steps, { only } = {}) {
|
|
125
|
+
for (const [name, step] of Object.entries(steps)) {
|
|
126
|
+
if (only && only !== name) continue;
|
|
127
|
+
await step();
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/** Run SQL against a SCRATCH database (never a real-data one). */
|
|
132
|
+
export function sql(databaseUrl, query) {
|
|
133
|
+
if (!/demo|docs|scratch|fixture|seed|test/i.test(databaseUrl)) {
|
|
134
|
+
throw new Error(
|
|
135
|
+
`refusing to write to ${databaseUrl}: name it as a demo/docs/scratch database, or edit this guard deliberately`,
|
|
136
|
+
);
|
|
137
|
+
}
|
|
138
|
+
return execFileSync("psql", [databaseUrl, "-qAtc", query], { encoding: "utf8" });
|
|
139
|
+
}
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# Output formats
|
|
2
|
+
|
|
3
|
+
The content is the same in every format: one section per answer or feature, each
|
|
4
|
+
with the kind of answer, the why, the steps and the screenshots. What changes is
|
|
5
|
+
how much fits and how it is delivered. Whatever the format, you prepare it and
|
|
6
|
+
the user sends it.
|
|
7
|
+
|
|
8
|
+
## pdf (default)
|
|
9
|
+
|
|
10
|
+
For anything with more than two or three steps, or when the client will print
|
|
11
|
+
it or forward it.
|
|
12
|
+
|
|
13
|
+
- Start from `templates/guide.html`. Page 1 has the title, the date, who it is
|
|
14
|
+
for, a numbered contents list (one line per section, with the outcome), the
|
|
15
|
+
demo-data note and any sign-in or admin note. The first section may start
|
|
16
|
+
under it.
|
|
17
|
+
- One `<section>` per answer or feature. Each section after the first starts a
|
|
18
|
+
new page.
|
|
19
|
+
- Screenshot widths: `w-s` for a chip, a header or a single control; `w-m` for a
|
|
20
|
+
dialog, a card or a panel; `w-l` for a wide table. Before/after goes in a
|
|
21
|
+
`.pair`.
|
|
22
|
+
- Render with `bin/render.mjs` and review the contact sheet. A clean guide has no
|
|
23
|
+
stranded headings, no page holding a single note, and no figure on a different
|
|
24
|
+
page from its step. Eight pages for four answers is normal.
|
|
25
|
+
- File name: `<App> - <what it is> - <reader or date>.pdf`, for example
|
|
26
|
+
`Portal - answers for Dana.pdf` or `Portal - what's new - March 2026.pdf`.
|
|
27
|
+
|
|
28
|
+
## html
|
|
29
|
+
|
|
30
|
+
The same file as the pdf, before rendering, for the web: a link the client can
|
|
31
|
+
open, or a page in the app's own docs.
|
|
32
|
+
|
|
33
|
+
- Keep `shots/` beside the HTML and use relative image paths.
|
|
34
|
+
- If it is going to be published somewhere (an artifact, a docs site), that is the
|
|
35
|
+
user's call. Prepare it, and ask before publishing.
|
|
36
|
+
|
|
37
|
+
## email
|
|
38
|
+
|
|
39
|
+
For one to three short answers, or an announcement of one or two features.
|
|
40
|
+
|
|
41
|
+
- Write a **draft** in the user's voice, never sent by you. Give the subject, the
|
|
42
|
+
body and the list of attachments. If the user has an email tool connected,
|
|
43
|
+
create a draft there only if they ask.
|
|
44
|
+
- Subject: what it's about, in their words ("Your questions about order
|
|
45
|
+
documents", "New: orders now wait for the signed form").
|
|
46
|
+
- Body: a one-line greeting, then one short paragraph per answer: the answer
|
|
47
|
+
first, then the steps as a numbered list with the exact labels in bold. Refer to
|
|
48
|
+
the screenshots by number ("see screenshot 2"). End with one line offering
|
|
49
|
+
help.
|
|
50
|
+
- Attach the screenshots as numbered PNGs (`1-documents-setting.png`, …), in the
|
|
51
|
+
order the body refers to them. For more than about five screenshots, attach
|
|
52
|
+
the pdf instead and keep the body to a summary of each answer.
|
|
53
|
+
|
|
54
|
+
## whatsapp
|
|
55
|
+
|
|
56
|
+
For quick answers to someone who asked in a chat.
|
|
57
|
+
|
|
58
|
+
- **One message per answer**, short enough to read on a phone (about 600
|
|
59
|
+
characters at most). Put a number on each when there are several ("1/3").
|
|
60
|
+
- WhatsApp formatting only: `*bold*` (single asterisks), `_italic_`, plain line
|
|
61
|
+
breaks, and numbered steps as `1.` lines. No headings, tables, links in
|
|
62
|
+
markdown syntax, or nested lists.
|
|
63
|
+
- Bold the exact button and menu names: `Go to *Admin → Documents*`.
|
|
64
|
+
- Screenshots go as separate images, each with a one-line caption, sent after
|
|
65
|
+
the message they belong to. List them in order: message 1, image 1a, image 1b,
|
|
66
|
+
message 2, and so on. Two images per answer at most; crop tight, because they
|
|
67
|
+
are seen on a phone.
|
|
68
|
+
- Give the user the messages as plain text blocks, ready to paste, plus the image
|
|
69
|
+
files in order. You never send them.
|
|
70
|
+
- If an answer needs more than four steps, say so in the message and send the
|
|
71
|
+
pdf for that part.
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<!--
|
|
3
|
+
The guide layout for pdf and html output. Copy it next to the shots/ folder,
|
|
4
|
+
replace the example content, and render with bin/render.mjs.
|
|
5
|
+
|
|
6
|
+
Building blocks (all in the <style> below):
|
|
7
|
+
.toc numbered list of every answer, on page 1
|
|
8
|
+
.tag.can/.new/.data/.ask
|
|
9
|
+
what kind of answer this is: "You can do this already",
|
|
10
|
+
"New", "A setting or data fix", "Needs your answer"
|
|
11
|
+
blockquote.ask the client's own words, quoted
|
|
12
|
+
ol.steps numbered steps; each <li> holds its text and its figure
|
|
13
|
+
figure.w-s/.w-m/.w-l
|
|
14
|
+
screenshot widths: small (a chip or a header), medium (a
|
|
15
|
+
dialog, a card), large (a full-width table)
|
|
16
|
+
.pair + .arrow before → after, side by side
|
|
17
|
+
.note / .note.warn
|
|
18
|
+
grey for "good to know", amber for "watch out"
|
|
19
|
+
.keep wrap a heading, its text and its figure so a page break
|
|
20
|
+
cannot separate them
|
|
21
|
+
|
|
22
|
+
Page breaks: each top-level <section> after the first starts a new page. Keep
|
|
23
|
+
sections to one per answer or feature; never split one answer into two
|
|
24
|
+
sections just to start a page.
|
|
25
|
+
-->
|
|
26
|
+
<html lang="en">
|
|
27
|
+
<head>
|
|
28
|
+
<meta charset="utf-8">
|
|
29
|
+
<title>TITLE</title>
|
|
30
|
+
<link href="https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@400;500;600;700&display=swap" rel="stylesheet">
|
|
31
|
+
<style>
|
|
32
|
+
@page { size: Letter; margin: 0.6in 0.65in 0.7in; }
|
|
33
|
+
:root { --ink: #23201c; --muted: #6b655d; --line: #e6e1d9; --accent: #1f4d3a; --soft: #f4f1ec; --amber: #9a5b00; --amber-soft: #fdf6e3; --blue: #24467a; --blue-soft: #e7eefb; --green-soft: #e5f2ea; }
|
|
34
|
+
* { box-sizing: border-box; }
|
|
35
|
+
body { font-family: "Plus Jakarta Sans", system-ui, sans-serif; color: var(--ink); font-size: 10.5pt; line-height: 1.5; margin: 0; }
|
|
36
|
+
h1 { font-size: 22pt; margin: 0 0 4pt; letter-spacing: -0.01em; }
|
|
37
|
+
.sub { color: var(--muted); margin: 0 0 18pt; }
|
|
38
|
+
h2 { font-size: 15pt; margin: 0 0 4pt; letter-spacing: -0.005em; break-after: avoid; }
|
|
39
|
+
h3 { font-size: 11pt; margin: 14pt 0 4pt; break-after: avoid; }
|
|
40
|
+
h3 + p { break-before: avoid; }
|
|
41
|
+
section + section { break-before: page; }
|
|
42
|
+
blockquote.ask { border-left: 3px solid var(--line); padding: 2pt 0 2pt 10pt; color: var(--muted); font-style: italic; margin: 6pt 0 10pt; }
|
|
43
|
+
.tag { display: inline-block; font-size: 8.5pt; font-weight: 600; padding: 2pt 7pt; border-radius: 99px; margin-bottom: 6pt; }
|
|
44
|
+
.tag.can { background: var(--green-soft); color: var(--accent); }
|
|
45
|
+
.tag.new { background: var(--blue-soft); color: var(--blue); }
|
|
46
|
+
.tag.data, .tag.ask { background: var(--amber-soft); color: var(--amber); }
|
|
47
|
+
ol.steps { padding-left: 0; list-style: none; counter-reset: s; margin: 8pt 0; }
|
|
48
|
+
ol.steps > li { counter-increment: s; position: relative; padding-left: 26pt; margin: 0 0 12pt; break-inside: avoid; }
|
|
49
|
+
ol.steps > li::before { content: counter(s); position: absolute; left: 0; top: 0; width: 18pt; height: 18pt; border-radius: 50%; background: var(--accent); color: #fff; font-size: 9pt; font-weight: 600; display: flex; align-items: center; justify-content: center; }
|
|
50
|
+
figure { margin: 6pt 0 0; break-inside: avoid; }
|
|
51
|
+
figure img { display: block; max-width: 100%; border: 1px solid var(--line); border-radius: 6px; }
|
|
52
|
+
figcaption { font-size: 8.5pt; color: var(--muted); margin-top: 3pt; }
|
|
53
|
+
.w-s img { max-width: 2.4in; } .w-m img { max-width: 4.2in; } .w-l img { max-width: 100%; }
|
|
54
|
+
.pair { display: flex; gap: 14pt; align-items: flex-end; break-inside: avoid; }
|
|
55
|
+
.pair figure { flex: 0 0 auto; }
|
|
56
|
+
.arrow { font-size: 16pt; color: var(--muted); padding-bottom: 18pt; }
|
|
57
|
+
.note { background: var(--soft); border-radius: 6px; padding: 8pt 11pt; margin: 10pt 0; break-inside: avoid; }
|
|
58
|
+
.note.warn { background: var(--amber-soft); }
|
|
59
|
+
.note > strong:first-child { display: block; margin-bottom: 2pt; }
|
|
60
|
+
.keep { break-inside: avoid; }
|
|
61
|
+
ul { margin: 4pt 0 8pt; padding-left: 15pt; } li { margin: 2pt 0; }
|
|
62
|
+
.toc { border: 1px solid var(--line); border-radius: 8px; padding: 10pt 14pt; }
|
|
63
|
+
.toc li { margin: 4pt 0; }
|
|
64
|
+
.small { font-size: 8.5pt; color: var(--muted); }
|
|
65
|
+
b, strong { font-weight: 600; }
|
|
66
|
+
</style>
|
|
67
|
+
</head>
|
|
68
|
+
<body>
|
|
69
|
+
|
|
70
|
+
<section>
|
|
71
|
+
<h1>TITLE</h1>
|
|
72
|
+
<p class="sub">DATE · for READER</p>
|
|
73
|
+
|
|
74
|
+
<div class="toc">
|
|
75
|
+
<ol>
|
|
76
|
+
<li><b>First answer or feature, in the reader's words.</b> One line on the outcome.</li>
|
|
77
|
+
<li><b>Second.</b> One line.</li>
|
|
78
|
+
</ol>
|
|
79
|
+
</div>
|
|
80
|
+
<p class="small" style="margin-top:14pt">The screenshots come from a demo copy of APP filled with made-up records, so you'll see different names, but the screens and buttons are the same.</p>
|
|
81
|
+
|
|
82
|
+
<!-- The first answer may start on page 1, under the contents. -->
|
|
83
|
+
<h2 style="margin-top:22pt">1. Heading in the reader's words</h2>
|
|
84
|
+
<span class="tag can">You can do this already</span>
|
|
85
|
+
<blockquote class="ask">"Their question, quoted."</blockquote>
|
|
86
|
+
<p>Why it behaves the way it does, in one short paragraph.</p>
|
|
87
|
+
<ol class="steps">
|
|
88
|
+
<li>Go to <b>Exact label</b>, then <b>Exact label</b>.
|
|
89
|
+
<figure class="w-l"><img src="shots/example-1.png"></figure></li>
|
|
90
|
+
<li>Click <b>Exact label</b>. It saves straight away.
|
|
91
|
+
<div class="pair">
|
|
92
|
+
<figure class="w-s"><img src="shots/example-2-before.png"><figcaption>Before</figcaption></figure>
|
|
93
|
+
<div class="arrow">→</div>
|
|
94
|
+
<figure class="w-s"><img src="shots/example-2-after.png"><figcaption>After</figcaption></figure>
|
|
95
|
+
</div></li>
|
|
96
|
+
</ol>
|
|
97
|
+
<div class="note"><strong>Good to know</strong>
|
|
98
|
+
<ul><li>What else this changes.</li><li>The alternative for a single record.</li></ul>
|
|
99
|
+
</div>
|
|
100
|
+
</section>
|
|
101
|
+
|
|
102
|
+
<section>
|
|
103
|
+
<h2>2. A new feature</h2>
|
|
104
|
+
<span class="tag new">New in APP</span>
|
|
105
|
+
<p>What you can now do, and why it helps you. You don't need to do anything; it works on its own.</p>
|
|
106
|
+
<div class="keep">
|
|
107
|
+
<h3>Where you'll see it</h3>
|
|
108
|
+
<p>One sentence pointing at the screenshot.</p>
|
|
109
|
+
<figure class="w-m"><img src="shots/feature-1.png"><figcaption>What's circled.</figcaption></figure>
|
|
110
|
+
</div>
|
|
111
|
+
<div class="note"><strong>The rules</strong><ul><li>Rule, in the on-screen words.</li></ul></div>
|
|
112
|
+
<div class="note warn"><strong>What to expect the first day</strong>What changes as soon as this is live.</div>
|
|
113
|
+
</section>
|
|
114
|
+
|
|
115
|
+
</body>
|
|
116
|
+
</html>
|