Feedback Stickers

A self-contained JavaScript module that lets reviewers place color-coded sticky notes on any HTML page, export them as YAML, and share them with the page author. Stickers pin to the element they are placed on, so they stay in the right position when the page is viewed at a different window size.

How it works

The built script (dist/feedback-stickers.min.js) is added to any HTML file with a single <script> tag. It injects a floating 📌 panel into the page. No server, no account, no browser extension required — a reviewer only needs a browser.

The review round-trip:

Requester                Reviewer
─────────────────────────────────────────────────────
Share HTML file   →
                         Open in browser
                         Place stickies & add notes
                  ←      Send back  .review.yaml
Import YAML       →
View stickies

Building from source

Requirements: Node.js 18+

npm install
npm run build          # → dist/feedback-stickers.min.js  (~18 KB)
npm run dev            # watch mode, unminified + source map

Embedding the script in an HTML file

From a CDN (no build step required)

The package is published to npm as @gridd/feedback-stickers and is available on both major CDNs.

jsDelivr — recommended, global edge network, SRI hash support:

<!-- always latest 1.x -->
<script src="https://cdn.jsdelivr.net/npm/@gridd/feedback-stickers@1/dist/feedback-stickers.min.js"></script>

<!-- pinned to an exact version (recommended for production) -->
<script src="https://cdn.jsdelivr.net/npm/@gridd/[email protected]/dist/feedback-stickers.min.js"></script>

unpkg — alternative CDN, also served directly from the npm registry:

<!-- always latest 1.x -->
<script src="https://unpkg.com/@gridd/feedback-stickers@1/dist/feedback-stickers.min.js"></script>

<!-- pinned to an exact version -->
<script src="https://unpkg.com/@gridd/[email protected]/dist/feedback-stickers.min.js"></script>

SRI integrity hashes — for pinned production deployments, generate a hash with:

curl -s https://cdn.jsdelivr.net/npm/@gridd/[email protected]/dist/feedback-stickers.min.js \
  | openssl dgst -sha384 -binary | openssl base64 -A

Then add it to the tag:

<script
  src="https://cdn.jsdelivr.net/npm/@gridd/[email protected]/dist/feedback-stickers.min.js"
  integrity="sha384-<hash>"
  crossorigin="anonymous"
></script>

From a local file

Add one line before </body>:

<script src="path/to/feedback-stickers.min.js"></script>

Testbed — the file starting-point/maturity-assessment-deckai.html already has this set up. Open it directly in a browser after running npm run build.

Single-file distribution (recommended for sharing)

Inline the script so the HTML is self-contained and can be shared as a single attachment:

<script>
  /* paste contents of dist/feedback-stickers.min.js here */
</script>

Or automate with a build step:

cat page.html \
  | sed 's|<script src=".*feedback-stickers.min.js"></script>||' \
  > page-review.html
echo '<script>' >> page-review.html
cat dist/feedback-stickers.min.js >> page-review.html
echo '</script>' >> page-review.html

Panel controls

Click the 📌 button in the bottom-right corner of any page to open the panel.

| Control | Purpose | | ------------------- | -------------------------------------------------------------------------------------------- | | Reviewer field | Your name or initials — shown on every sticky you place | | Color grid | 12 color categories; click a swatch to select it as the active color | | Color labels | Click the small text under any swatch to rename that category; saved globally in the browser | | Start Reviewing | Activates placement mode (cursor turns to crosshair) | | Stop Reviewing | Deactivates placement mode; stickies remain visible | | Export YAML | Downloads all stickies as a .review.yaml file | | Import YAML | Loads a .review.yaml file and merges its stickies onto the page | | Clear | Removes all stickies for the current page (asks for confirmation) |

Color categories (defaults)

| Color | Default label | Suggested use | | --------- | ------------- | --------------------------- | | 🟡 Yellow | Note | General observation | | 🟠 Amber | Flag | Needs attention | | 🟧 Orange | Caution | Risk or concern | | 🔴 Red | Blocker | Must fix before release | | 🌸 Rose | Critical | Severe issue | | 💗 Pink | Design | Visual / layout feedback | | 🟣 Purple | UX | Interaction / flow feedback | | 🔵 Indigo | Dev | Implementation comment | | 💙 Blue | Info | Background context | | 🩵 Teal | Content | Copy or text feedback | | 🟢 Green | OK | Explicitly approved | | 🟩 Lime | Approved | Sign-off |

Labels are customisable per session. Renamed labels are saved in the browser's local storage and persist across page loads.

Placing and managing stickies

1. Open the panel, enter your name, choose a color category.
2. Click Start Reviewing — the cursor changes to a crosshair.
3. Click anywhere on the page to drop a sticky at that location.
4. Type a note in the sticky's text area.
5. Minimize a sticky (−) to collapse it to a colored dot; click the dot to expand it again (only works while reviewing is active).
6. Delete a sticky (×) to remove it permanently.
7. Drag a sticky by its header bar to reposition it (only while reviewing is active).
8. Click Stop Reviewing when done — stickies stay visible but cannot be moved or expanded.

Stickies are saved to the browser's local storage automatically as you work. They reload the next time the same file is opened in the same browser.

Review workflow — step by step

Step 1 — Requester: prepare the file

Build the script and embed it in the HTML page you want reviewed:

<!-- at the end of <body> -->
<script src="feedback-stickers.min.js"></script>

Or inline the minified script for a single self-contained file (see Single-file distribution above).

Send the HTML file to the reviewer. If the script is not inlined, include feedback-stickers.min.js alongside it in the same folder (or zip archive).

Alternatively if you use Docusaurus rendering engine, you can use the @gridd/docusaurus-feedback-plugin's export button that generates the page with inlined scripts, images, for easy share with the less technical colleagues.

Step 2 — Reviewer: open the file

Open the HTML file in a desktop browser (Chrome, Firefox, or Safari). Local files work fine — no web server needed. If the browser blocks local scripts, see the note at the bottom of this section.

Chrome tip: If you see a blank panel or the 📌 button does nothing, open DevTools console (F12) to check for errors. For file:// pages Chrome sometimes requires you to allow local file access: go to chrome://settings/content/javascript and make sure JavaScript is enabled.

Step 3 — Reviewer: annotate the page

1. Click the 📌 button (bottom-right).
2. Enter your name or initials in the Reviewer field.
3. Pick a color matching the type of feedback (customize labels if your team has a shared convention).
4. Click Start Reviewing.
5. Click on the part of the page you want to annotate — a sticky appears.
6. Type your note.
7. Repeat for as many locations as needed. Switch colors between placements.
8. Click Stop Reviewing when finished.

Step 4 — Reviewer: export and send

1. In the panel, click Export YAML.
2. A file named <page-title>.review.yaml is downloaded.
3. Send this file back to the requester (email, Slack, PR comment attachment, etc.).

Step 5 — Requester: view the review

1. Open the same HTML file in a browser.
2. Click the 📌 button.
3. Click Import YAML and select the received .review.yaml file.
4. The reviewer's stickies appear on the page, anchored to the same elements they were placed on.

If multiple reviewers sent back files, import them one at a time — stickies are merged by ID, so no duplicates are created. Each reviewer's name is shown in the header of their stickies.

Handling multiple reviewers

Collect all .review.yaml files and import them in sequence. Because stickies are merged by id (UUID), importing the same file twice is safe — it updates in place rather than duplicating.

YAML export format

version: "1.0"
page:
  url: "file:///path/to/page.html"
  title: "Page Title"
  exportedAt: "2026-05-28T10:00:00.000Z"
colorLabels:
  yellow: "Note"
  amber: "Flag"
  # ... all 12 colors
stickers:
  - id: "550e8400-e29b-41d4-a716-446655440000"
    reviewer: "Sandor Nagy"
    comment: "This section needs a clearer heading"
    color: orange
    position:
      xPct: 0.4531 # fallback: fraction of page width
      yPct: 0.2341 # fallback: fraction of page height
      anchorSelector: "#intro > p:nth-of-type(2)" # element the sticky is pinned to
      anchorOffsetXPct: 0.05 # position within that element (fraction of its width)
      anchorOffsetYPct: 0.12 # position within that element (fraction of its height)
    minimized: false
    rotation: -1.2
    createdAt: "2026-05-28T10:00:00.000Z"
    updatedAt: "2026-05-28T10:05:00.000Z"

Position resolution order:

1. If anchorSelector is present and the element is found on the page → position relative to that element.
2. Otherwise fall back to xPct / yPct (percentage of page scroll dimensions).
3. Legacy files with top / left (absolute pixels from older versions) are still accepted on import.

Browser compatibility

Requires a modern browser with Shadow DOM v1 support: Chrome 53+, Firefox 63+, Safari 10.1+, Edge 79+. All features used (Shadow DOM, Pointer Events, crypto.randomUUID, CSS.escape, URL.createObjectURL) are available without polyfills in these versions.

NOTICE

https://github.com/GriddApp/gridd-docusaurus-feedback-plugin

Copyright (c) 2026 DeckAI Inc. All rights reserved.

1. LICENCE

This library is licensed under the GNU Lesser General Public License, version 3 ("LGPL v3"), the full text of which is available at: https://www.gnu.org/licenses/lgpl-3.0.html

You may use, copy, modify, and distribute this library under the terms of the LGPL v3. If you modify the library, you must release your modifications under the same licence.

2. ADDITIONAL ATTRIBUTION REQUIREMENT (permitted additional term under LGPL v3 § 7)

As a condition of using this library — whether via CDN, inline embed, or any other distribution method — you must comply with the following attribution requirement in addition to the LGPL v3 terms:

a) SCRIPT BANNER PRESERVATION

The copyright and attribution banner comment at the top of feedback-stickers.min.js must be preserved in its entirety in all copies and distributions, including inline embeds. The banner reads:

/*!
 * @gridd/feedback-stickers v1.0.0
 * Copyright (c) 2026 DeckAI Inc. (deckai.co)
 * Licensed under LGPL v3 + Attribution Notice
 * https://www.npmjs.com/package/@gridd/feedback-stickers
 *
 * You may use and redistribute this library freely under LGPL v2.1,
 * provided this banner is preserved in all copies (including inline embeds)
 * and attribution is given in your project documentation.
 * See NOTICE file for full attribution requirements.
 * Commercial / white-label licences: [email protected]
 */

You must not alter, obscure, or remove this banner.

b) DOCUMENTATION OR README ATTRIBUTION

Any project, product, tool, or document that ships with or depends on this library must include the following notice in its documentation, README, or equivalent end-user-facing material:

Feedback annotation powered by @gridd/feedback-stickers (deckai.co) — used under LGPL v3 + Attribution Notice.

A hyperlink to https://deckai.co or https://github.com/GriddApp/gridd-docusaurus-feedback-plugin is strongly preferred wherever the format supports links.

c) INLINE EMBED COMPLIANCE

When this library is embedded inline (i.e. the minified source is copied directly into a <script> tag rather than loaded from an external URL), the banner comment in clause (a) above must still be present immediately before the inlined code. The inline embed does not exempt you from either clause (a) or clause (b).

d) NO REBRANDING

You may not republish this library — whether modified or unmodified — under a name, npm package identifier, or CDN path that does not include the "@gridd/" namespace prefix or that removes or replaces the "DeckAI" attribution, without a separate written commercial licence from DeckAI Inc.

3. COMMERCIAL LICENSING

If you wish to:

— use this library without the attribution requirements above, or — white-label or rebrand the library under a different namespace, or — incorporate it into a commercial product sold to end-users where the LGPL v3 terms are incompatible with your distribution model,

please contact DeckAI Inc. to obtain a commercial licence:

[email protected]

https://deckai.co

4. NO WARRANTY

This library is provided "as is", without warranty of any kind, express or implied. See the LGPL v3 for the full disclaimer of warranties and limitation of liability.