Visual Feedback

Visual Feedback

Overview

Turn any deliverable (concept, report, design, plan) into ONE self-contained HTML review page where every meaningful element is an inline comment point. Each comment can carry a category (Question/Error/Change/Praise) and priority (Must/Optional). Comments persist in localStorage, and the user exports them as structured markdown WITH a JSON attachment (clipboard or .md file) to paste back into the chat. The chat paste-back closes the loop: the agent maps each comment to its target id and works the feedback in.

The UI defaults to English and carries a small EN/DE toggle in the toolbar; the toggle switches every visible string AND the exported markdown, and persists in localStorage under fb:lang. Category/priority are stored as stable, language- independent ids (frage/fehler/aenderung/lob, muss/optional); only their display labels translate, so the JSON block reads the same in either language.

Template: copy and adapt template.html in this skill directory. It contains the complete widget CSS/JS and one example of every target type. Do not rebuild the mechanics from scratch - that is how past pages drifted into incompatible variants. The script builds its own toolbar, toast and preview overlay, so retrofitting an existing HTML page = paste the template's widget CSS block and complete ` into it, then only add the markers from the recipe plus data-fbkey/data-fbver on `. Nothing else is required.

Recipe (the page IS this)

1. Comment points. ` carries data-fbkey=""` (never reuse

across pages) and data-fbver="" (bump on every content rewrite, or old comments stick to changed spots). Each ` carries data-fbsec=" · "`. Targets:

• data-fbauto on a section/container auto-pins every p, li,

blockquote, h3, h4 and every table row inside (data-fbskip excludes subtrees) - the default for prose/tables

• data-fb="id" + data-fblabel="Label" for manual targets (cards,

callouts, diagram units)

• data-fb on SVG elements gives overlay pins with a comment panel below

the diagram

• `` for always-visible fields: one general-feedback

field per section plus a "Gesamturteil" at the end

1. Widget. A ✎ pin per target opens a textarea in place, plus type/priority

chips. Input autosaves (debounced). The sticky toolbar (built by the script) shows a storage-status pill, an "X/Y commented" counter, an EN/DE language toggle, a filter (All/Open/Commented), jump arrows, Preview, Copy feedback, Save as .md and Reset. All labels shown here are the English default; the DE toggle swaps them (and the export) to German.

1. Versioning that doesn't lose feedback. Comments live under

fb::v. When data-fbver is bumped, comments with a still-existing target id are carried into the new version automatically (marked "übernommen aus vX"); comments whose target is gone surface under "Nicht mehr zuordenbar". So bumping the version is safe, not lossy. Stable ids matter: manual data-fb ids and general fields carry cleanly; auto-ids are text-slug based. Multi-tab: saves are read-modify-write merged and a storage listener syncs other tabs live (targets with a pending edit or open editor are left alone), so the common case (one reviewer, maybe a second tab) never loses data. localStorage has no real transactions, so genuinely concurrent saves from two tabs in the same instant can still drop one - the tool is built for single-reviewer use, not concurrent co-editing.

1. Export - both ways, structured, dual-format. "Copy feedback"

(navigator.clipboard with execCommand fallback), "Save as .md" (Blob download) and "Preview" all produce the same document: human-readable markdown grouped by section, PLUS a machine-readable JSON block for the agent. The markdown headings follow the UI language (English shown below; German when the DE toggle is on). The JSON block is language-independent.

``markdown # Feedback: Captured on Page: ` · Version v · comments Summary: 2× Error, 1× Question (of which 1× Must)

## **** Text · `` · Error · Must Ref: "" > comment line(s)

... ``json { "page": ..., "version": ..., "comments": [ {id,type,section,label,quote,category,priority,comment,ts}, ... ], "orphans": [...] } ` ``

When working the feedback in, prefer the JSON block: id is the stable anchor, quote the context, category/priority the intent (values stay frage/fehler/aenderung/lob and muss/optional regardless of UI language).

1. Reset without dialogs. Reset is a two-click confirm inside the button

itself ("Sure? Click again" / "Wirklich? Erneut klicken", auto-disarm after 3 s). The page contains zero alert() / confirm() / prompt() calls - they block the browser.

1. Self-contained file. No CDNs, webfonts, or external requests; system font

stacks (e.g. Charter/Avenir on macOS); light + dark via prefers-color-scheme; prefers-reduced-motion respected; works from file:// (in-memory fallback with a visible warning when localStorage is blocked). English UI by default with an EN/DE toggle; German strings use real Umlauten, and no text uses em-dashes.

1. Verify, then open. Parse the HTML (python html.parser: no unclosed tags,

count of data-fb targets matches plan), node --check the extracted `, then open with macOS open (never browser-automation tools for local files). The widget mechanics themselves are covered by the jsdom smoke test template-test.js next to the template (needs npm install jsdom`, run only after changing the template, not per page).

Common mistakes

| Mistake | Fix | |---|---| | Rebuilding widget JS/CSS instead of copying the template | Copy template.html; only content and markers change | | Hand-marking every paragraph with data-fb | data-fbauto on the section; hand-mark only boxes and SVG elements | | Working feedback in from the prose alone | Use the JSON block: id is the stable anchor, quote the context | | Changing manual data-fb ids between versions | Keep ids stable so v-bump carries comments; only auto-ids may shift | | SVG pins at 0/0 or drifting after resize | Positioning runs via getBoundingClientRect on load AND resize - keep the template's positionSvgPins wiring intact | | Table rows not commentable | Use the ✎-cell + colspan-row mechanism from the template | | confirm() for reset | Two-click confirm in the button (template has it) | | Export as free-form plaintext | Grouped markdown with data-fbsec/data-fblabel so the agent can map comments back | | Only clipboard export | Also offer the .md Blob download (clipboard can fail on file://) | | Same localStorage key on two pages | Unique key per file, or comments bleed between pages | | Feedback UI drowns the content | Widgets stay collapsed until toggled; content layout comes first |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: okuegow
• Source: okuegow/agent-skills
• License: MIT
• Homepage: https://github.com/okuegow/agent-skills

Install and usage instructions live in the source repository linked above.