AddThisFeature

Reading Progress Bar

A slim bar showing how far through an article the reader has scrolled.

simple Content & Publishing

What it adds

A thin progress indicator pinned to the top of article pages, tracking scroll through the body text.

What your agent is told to do

5
  1. 1

    Measure progress against the article body element only. Take the top and bottom of the prose, not the height of the document.

  2. 2

    Recalculate the body height when the page reflows: late-loading images, expanded sections, embeds, and font swaps all change the total after first paint.

  3. 3

    Reuse the app's existing Progress Indicator System tokens for the bar's colour and height rather than introducing a new accent, and keep it visually distinct from Route Change Progress so the two are not confused.

  4. 4

    Hide the bar entirely when the article fits within the viewport, and update it on a throttled scroll handler tied to the frame rather than on every scroll event.

  5. 5

    Do not animate the fill with a transition. The bar should track the scroll position exactly, and a smoothed fill lags behind the reader and reads as broken.

Edge cases it handles

8
  • A short article that fits on one screen has no meaningful progress. The bar would sit at zero or jump straight to full, so it should not render at all.
  • Progress must stop at the end of the article body. Counting the footer, the related posts block, and the comment thread means the bar reads half full when the reader has finished the piece.
  • Images and embeds that load after first paint change the total height mid-read, so a reader who was at sixty percent suddenly drops to forty. Recompute the bounds on resize and on load, and reserve image dimensions so the shift is small.
  • A moving bar is a motion effect. Under prefers-reduced-motion, either hide it or update it without any animated transition.
  • A sticky site header and the bar compete for the same strip of screen. Decide which owns the top edge and offset the other, or the bar will disappear under the header on scroll.
  • The bar is decoration for assistive technology and should be hidden from the accessibility tree rather than announced as a live percentage on every scroll.
  • Returning to an article with a restored scroll position must show the correct fill immediately, not animate up from zero.
  • In right-to-left layouts the bar must fill from the right edge.

Definition of done

8
  • The bar reflects scroll position through the article body and reaches full at the end of the prose.
  • Articles shorter than the viewport show no bar.
  • Late-loading images and embeds do not leave the bar reporting a stale total.
  • The bar respects prefers-reduced-motion and does not animate its fill.
  • It coexists with the sticky header without overlap on any breakpoint.
  • It is hidden from screen readers and does not emit scroll announcements.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.