Scroll section
A section whose content -- most often a child <sg-scene>'s progress -- advances as it travels through the viewport, following the Ghat plate's scroll arithmetic.
quiet warm playful
Open the live demo
npx @susegad/cli add scroll-section
Stands on: Core, Core: components, Tokens
The prompt
the prompt
A section whose scene advances as it travels through the viewport.
<sg-scroll-section>
<sg-scene name="paus" register="warm"></sg-scene>
</sg-scroll-section>
The prompt
Build a section wrapper that reads how far it has travelled through the viewport as one number, 0 to 1, and forwards it as a real progress value to a child scene, after the Ghat plate's own scroll arithmetic (its top and height against the viewport's own height, softened at both ends rather than a hard 0/1 cut). Use an IntersectionObserver to know when the section is anywhere near the viewport at all, and only run a per-frame loop while it is (pause entirely off screen, the engine's own discipline); add a lightweight, throttled scroll listener too, as a safety net for a single very fast scroll (a big keyboard jump, scrollTo()) that could carry the section from well below the viewport to well above it between two rendered frames, skipping the observer's own near zone before it ever reports "yes, near", the safety net measures the section's rect directly and settles progress correctly even then, rather than leaving it stuck at whatever it last was. Separately, give any purely visual reveal that does not need a numeric attribute a native, JavaScript-free path: animation-timeline: view(), guarded by @supports, so a caption can fade and lift in as it scrolls into view with no observer and no loop at all. Never scrub in the quiet register or under reduced motion: hand the section's own scene back to its own finished still instead, and do not force the scene's progress attribute to a specific number on the way there, remove it, so the scene's own default takes over cleanly.
Words to code
| When you say | Technique | What happens |
|---|---|---|
| after the Ghat plate's own scroll arithmetic | reuse | scroll-section.core.js's progressFromRect(rect, viewportHeight) is Ghat's scrollProgress() formula, (vh - top) / (vh*ease + height*ease), lifted out as a pure function and tested against a wide sweep of positions and sizes rather than assumed. |
| pause entirely off screen | A4, engine discipline | IntersectionObserver's rootMargin: '50% 0px' decides "near"; the rAF loop only ever schedules its next frame while #near is true, and a check confirms zero sg-scroll-progress events fire during a quiet window once the section is genuinely off screen. |
| a safety net for a single very fast scroll | honest coverage | The bug this guards against is real, not hypothetical: an early draft only used the observer, and a single large mouse.wheel() scroll in a check carried the section clean through its near zone in one paint, so progress never moved from 0 even though the section had visibly passed. The fix adds a throttled scroll listener that measures the rect directly and settles progress to wherever the section actually is, whether or not that counts as "near" right now. |
| a native, JavaScript-free path … no observer and no loop at all | native first | scroll-section.css's @supports (animation-timeline: view()) { .sg-scroll-reveal { animation-timeline: view(); … } }. CSS cannot write an HTML attribute, so this path is only for effects that stay inside CSS (opacity, transform); a numeric progress on a child element inherently needs the JavaScript path instead. |
| do not force the scene's progress attribute … remove it | A7/A8, a real bug found by looking | The first draft called scene.setAttribute('progress', '1') on the way to still(). The scene then painted a blank box, not its finished frame, caught by looking at an actual screenshot, not by any assertion, exactly the kernel's "look means naming" discipline. The fix removes the attribute instead of pinning it, matching SKILL.md's own documented way to hand a scene back to its default ("remove the attribute … to hand the scene back to time"), and a regression check now asserts the still scene paints a real <canvas> or <svg>, not just that a number reads correctly. |
Accessibility
- No JavaScript: a plain block of content, fully readable, nothing hidden pending scroll.
- The scene inside (if any) carries its own accessible status text for its
progress, per the scene contract; this component adds nothing that isn't already in the DOM. - The
.sg-scroll-revealCSS path respectsprefers-reduced-motionon its own (the animation is simply removed, content shown at rest).
Credit
After: the Ghat plate, a topographic survey sheet of the Western Ghats above Goa, whose contours ink themselves in as the sheet scrolls into view. What we took: the scroll-progress arithmetic, one number from a box and the viewport's height. What we left: the drawing itself. Ghat's contours, rivers, road and monsoon clouds live entirely inside the Ghat scene; this component only supplies the scroll number to whatever a page puts inside it.
<sg-scroll-section> advances a child <sg-scene>'s progress as the section travels through the viewport, following the Ghat plate's own scroll arithmetic.
Markup
<sg-scroll-section>
<sg-scene name="paus" register="warm"></sg-scene>
<p class="sg-scroll-reveal">Come for the rain. Our lowest rate runs June to September.</p>
</sg-scroll-section>
- Without JavaScript this is a plain
<section>-like wrapper (the custom element never upgrades): its content shows at rest, nothing scroll-linked. - A direct child
<sg-scene>gets itsprogressattribute set every frame the section is near the viewport, in warm and playful. Quiet and reduced motion never touch it: they remove theprogressattribute and call the scene's own.still(), so the scene shows its own finished frame (the charter's register table already gives a scene a still in quiet; this component adds nothing on top of that, and importantly does not pinprogress="1"on the way there, which produced a blank canvas in an earlier draft, see "known limits" below). - A
.sg-scroll-revealchild needs no<sg-scene>and no JavaScript at all:scroll-section.cssgives it a nativeanimation-timeline: view()fade-and-lift, entirely in CSS, wherever the browser supports the at-rule (@supports (animation-timeline: view()) { … }); elsewhere it simply shows at rest.
Why two different mechanisms
Setting an element's attribute (to drive a child <sg-scene progress>) inherently needs JavaScript, CSS cannot write an attribute. Any purely visual scroll effect that needs no attribute (a fade, a lift) can be genuinely CSS-only, native animation-timeline: view(), no JavaScript, no IntersectionObserver, no rAF loop. scroll-section.js is the JavaScript path, for the case that actually requires it.
Reading progress yourself
const section = document.querySelector('sg-scroll-section');
section.addEventListener('sg-scroll-progress', e => console.log(e.detail.progress)); // 0..1
section.progress; // the last value, read only
--sg-scroll-progress (0..1) is also set as a CSS custom property on the host every frame, for your own calc()-based effects.
The registers
- Quiet: no parallax, no scrubbing. The scene (if any) shows its own still.
- Warm: a slow parallax lift on a child
<sg-scene>(data-scroll-parallax,--sg-scroll-parallax: 1), the charter's "one living thing per screen." - Playful: the same parallax, bolder (
--sg-scroll-parallax: 1.6).
Reduced motion takes the same still path as quiet, in every register.
Accessibility
How this component meets WCAG 2.2 level A and AA, criterion by criterion, how each was checked, and what your page still owns.
- Meets 8
- Not applicable 4
| Criterion | Status | How it was checked |
|---|---|---|
| 1.1.1 Non-text content | Not applicable | The section adds no image, icon or media of its own. The <sg-scene> a page puts inside it carries its own text alternative (see the scene's docs). |
| 1.3.1 Info and relationships | Meets | packages/components/scroll-section/scroll-section.js adds no role, no wrapper and no reordering: it sets one CSS custom property on the host and the progress attribute on a child scene, so the author's markup reads in the order it was written. Without JavaScript it is a plain block. |
| 1.4.1 Use of color | Not applicable | The section carries no meaning in colour; it moves content and shows no state of its own. |
| 1.4.3 Contrast (minimum) | Meets | Without the opt-in .sg-scroll-reveal class the component sets no opacity, and the page's own text uses packages/tokens/tokens.test.js ("AA: <palette> <theme>: every text role on every surface is 4.5:1 or more"). With the class, the fade ends when the element has fully entered the screen (animation-range: entry 0% entry 90% in packages/components/scroll-section/scroll-section.css), so text that is the last thing on a page still ends fully shown. packages/components/scroll-section/scroll-section.check.mjs: "a .sg-scroll-reveal paragraph, the last thing on the page, ends fully shown" read opacity 0.12 before the fix (the range was entry 0% cover 40%, which a last paragraph can never reach) and 1.00 after, with a control ("with 1400 px of page after it") at 1.00 both times. Chromium; browsers without scroll timelines show the text at once. |
| 1.4.4 Resize text | Meets | Manual test, 2026-10-07: demo with the root font size at 200 percent at 1280 px, three registers, nothing wider than the screen (throwaway Playwright script). The section has no text or fixed size of its own. |
| 1.4.10 Reflow | Meets | Manual test, 2026-10-07: demo at 320 CSS px, three registers, page width 320 (no sideways scroll; throwaway Playwright script). The section is display: block and sets no width. |
| 1.4.11 Non-text contrast | Not applicable | The section draws nothing and has no control. A scene inside it is a drawing with its own rules. |
| 1.4.12 Text spacing | Meets | Manual test, 2026-10-07: the WCAG text-spacing values (line height 1.5, letter 0.12em, word 0.16em, paragraph 2em) injected on the demo, three registers, no sideways scroll (throwaway Playwright script). The section sets no text sizes or fixed heights. No check in the repository asserts it yet. |
| 2.2.2 Pause, stop, hide | Meets | Nothing moves on its own: the scroll scrub and the warm and playful parallax follow the reader's scroll and stop when scrolling stops. Quiet and reduced motion never scrub (packages/components/scroll-section/scroll-section.check.mjs: "quiet never scrubs", "reduced motion, warm: the section never scrubs") and nothing runs while the section is off screen ("no sg-scroll-progress events fire while off screen"). |
| 2.3.1 Three flashes or below threshold | Meets | The only visual changes are a vertical shift of at most 24 px (38 px in playful) and an opacity fade, both tied to scroll position, never to time: packages/components/scroll-section/scroll-section.css. Nothing flashes. |
| 2.3.3 Animation from interactions | Meets | AAA, informative. Under reduced motion the .sg-scroll-reveal animation and the parallax transform are removed in CSS, and the script settles to the still: scroll-section.check.mjs, "reduced motion, warm: the section never scrubs, staying at its still value". |
| 4.1.2 Name, role, value | Not applicable | The section is not a control and adds no role or state. axe on the demo: tools/axe.mjs --url /packages/components/scroll-section/demo.html: 0 violations across 6 runs (three registers, light and dark, desktop), 2026-10-07, and again at 390 px with touch and with JavaScript off, 0 violations; color-contrast was left for review by hand. |
The page author owns:
- The label, or
alt, on the<sg-scene>inside, and the text of anything in the section.
How it behaves
The section adds no role, label or control of its own, so this section is the conformance table.
Performance
The IntersectionObserver-gated loop only runs while the section is near the viewport (A4: pause off screen); a fast scroll safety net (a passive, rAF-throttled scroll listener) catches the case where a single very fast jump could skip past the observer's own near zone entirely. Measured against the Paus baseline in the same run: at rest (the page as loaded, section below the fold) the page is well under the baseline's own cost, since the section is idle; while actively being scrubbed, mean frame time comes in at parity with the Paus baseline (about 1.0x), see the registry gate evidence for the exact numbers.
Known limits
- An earlier draft pinned the child scene's
progressattribute to"1"on the way to calling.still(). That left the scene painting a blank box instead of its finished frame, a real, screenshot-caught bug, not a hypothesis. The fix removes theprogressattribute entirely before calling.still(), handing the scene back to its own default the waySKILL.mddocuments ("remove the attribute to hand the scene back to time"). A regression check now asserts the still scene actually paints a<canvas>or<svg>, not just that progress reads1. - Register changes made to an ancestor element (a page-level register switcher) after this component has already connected are picked up on the next scroll or intersection event, not instantly, there is no dedicated "motion changed" hook to react to sooner.
Lineage
After: the Ghat plate, a topographic survey sheet whose land inks itself in as the sheet scrolls into view.
What we took: the scroll-progress arithmetic (scrollProgress() in the plate, ported as progressFromRect here), how far a section has travelled through the viewport, as one number from its own box and the viewport's height.
What we left: everything else. Ghat's own reveal (contours inking in from sea level, rivers, a road, monsoon clouds) stays inside the Ghat scene itself; this component only supplies the scroll number, generically, to whatever scene or content a page puts inside it.