Skip to content

2001105254-netizen/RacePulsePH / .agents/skills/modern-web-guidance

modern-web-guidance

Flagged

Search tool for modern web development best practices. MANDATORY: Execute FIRST for all HTML/CSS and clientside JS tasks. Do NOT skip — web APIs evolve rapidly and training weights contain obsolete patterns. Trigger immediately for: modals/dialogs/popovers, tables, dark mode, anchor positioning, container queries, view transitions, scroll-driven animations, parallax/reveals, forms, validation, autofill, accessibility, custom selects, scrollbars, CWV (LCP, INP, CLS), content-visibility, fetch priority, image optimization, security, passkeys, HTML sanitization, web components, dates/timezones, built-in AI, WebAssembly, standard HTML/CSS/DOM in frameworks, etc. DO NOT trigger for: backend (SQL, ORMs, API routes), infra/scripts (CI/CD, Docker, Actions, Python/Go, Git), or tooling/trivial (Vite, tsconfig, ESLint, tests, copy/renames, 3P docs), etc.

FileKindSize
SKILL.mdskill md9.6 KB
guides/accessibility/accessibility.mdmarkdown50.5 KB
guides/accessibility/accessible-error-announcement.mdmarkdown13.3 KB
guides/accessibility/accessible-generated-content.mdmarkdown2.2 KB
guides/accessibility/respect-os-text-scale.mdmarkdown7.1 KB
guides/built-in-ai/language-detection.mdmarkdown3.6 KB
guides/built-in-ai/language-model.mdmarkdown19.0 KB
guides/built-in-ai/prompt-api.mdmarkdown19.0 KB
guides/built-in-ai/summarizer.mdmarkdown6.2 KB
guides/built-in-ai/translator.mdmarkdown7.2 KB
guides/css/animate-to-intrinsic-sizes.mdmarkdown5.7 KB
guides/css/atrule-support-conditionals.mdmarkdown5.6 KB
guides/css/calculate-with-intrinsic-sizes.mdmarkdown10.4 KB
guides/css/child-state-based-styling.mdmarkdown4.9 KB
guides/css/content-based-styling.mdmarkdown5.2 KB
guides/css/css-layout.mdmarkdown21.2 KB
guides/css/css.mdmarkdown12.3 KB
guides/css/design-token-reactivity.mdmarkdown5.8 KB
guides/css/dynamic-sibling-styling.mdmarkdown3.6 KB
guides/css/fluid-scaling.mdmarkdown3.2 KB
guides/css/individual-transform-properties.mdmarkdown3.6 KB
guides/css/overflow-clipping-control.mdmarkdown8.1 KB
guides/css/reduce-style-repetition.mdmarkdown3.9 KB
guides/css/responsive-design.mdmarkdown1.8 KB
guides/css/selector-atrule-combinations.mdmarkdown3.6 KB
guides/css/size-aware-styling.mdmarkdown2.9 KB
guides/css/style-parent-with-has.mdmarkdown13.6 KB
guides/css/usage-aware-component-variations.mdmarkdown5.1 KB
guides/forms/animated-select-picker.mdmarkdown8.5 KB
guides/forms/autofill-address-form.mdmarkdown4.9 KB
guides/forms/autofill-highlight-inputs.mdmarkdown3.5 KB
guides/forms/autofill-payment-form.mdmarkdown9.7 KB
guides/forms/autofill-sign-in-form.mdmarkdown10.5 KB
guides/forms/autofill-sign-up-form.mdmarkdown11.6 KB
guides/forms/brand-consistent-forms.mdmarkdown8.4 KB
guides/forms/branded-select-styling.mdmarkdown5.6 KB
guides/forms/custom-select-picker-layouts.mdmarkdown7.8 KB
guides/forms/form-fields-automatically-fit-contents.mdmarkdown5.9 KB
guides/forms/forms.mdmarkdown18.9 KB
guides/forms/ime-safe-enter-submit.mdmarkdown6.3 KB
guides/forms/required-field-feedback.mdmarkdown13.9 KB
guides/forms/rich-media-picker.mdmarkdown10.5 KB
guides/forms/select-menu-interaction.mdmarkdown12.9 KB
guides/forms/slider.mdmarkdown6.5 KB
guides/forms/sms-otp-form.mdmarkdown12.5 KB
guides/forms/switch.mdmarkdown2.5 KB
guides/forms/validate-input-after-interaction.mdmarkdown17.2 KB
guides/html/accessible-web-components.mdmarkdown5.1 KB
guides/html/custom-elements.mdmarkdown9.3 KB
guides/html/form-associated-custom-elements.mdmarkdown4.9 KB
guides/html/html.mdmarkdown20.8 KB
guides/html/prerendering-custom-elements.mdmarkdown3.6 KB
guides/html/shadow-dom.mdmarkdown3.8 KB
guides/html/styling-web-components.mdmarkdown8.7 KB
guides/html/web-components.mdmarkdown6.6 KB
guides/js/calculate-event-differentials.mdmarkdown8.3 KB
guides/js/capture-location-agnostic-data.mdmarkdown9.7 KB
guides/js/coordinate-global-events.mdmarkdown4.0 KB
guides/js/sort-high-precision-timestamps.mdmarkdown6.6 KB
guides/js/support-global-calendar-systems.mdmarkdown5.8 KB
guides/performance/batch-analytics-events.mdmarkdown6.4 KB
guides/performance/break-up-long-tasks.mdmarkdown2.2 KB
guides/performance/calculate-total-foreground-time.mdmarkdown2.9 KB
guides/performance/conditional-async-dependencies.mdmarkdown5.3 KB
guides/performance/defer-rendering-heavy-content.mdmarkdown6.3 KB
guides/performance/defer-work-until-scroll-ends.mdmarkdown3.3 KB
guides/performance/deliver-optimized-decorative-images.mdmarkdown2.8 KB
guides/performance/deprioritize-background-fetches.mdmarkdown1.8 KB
guides/performance/detect-initial-visibility-state.mdmarkdown4.6 KB
guides/performance/efficient-background-processing.mdmarkdown5.0 KB
guides/performance/faster-spa-view-transitions.mdmarkdown3.6 KB
guides/performance/flicker-free-client-side-ab-testing.mdmarkdown8.5 KB
guides/performance/full-session-analytics.mdmarkdown5.7 KB
guides/performance/identify-heavy-scripts.mdmarkdown4.2 KB
guides/performance/identify-inp-causes.mdmarkdown8.7 KB
guides/performance/improve-next-page-load-performance.mdmarkdown7.2 KB
guides/performance/interaction-paint-timing.mdmarkdown11.2 KB
guides/performance/interactions-in-complex-layouts.mdmarkdown3.4 KB
guides/performance/lazy-load-video-and-audio.mdmarkdown9.3 KB
guides/performance/optimize-image-priority.mdmarkdown4.5 KB
guides/performance/optimize-preload-priority.mdmarkdown3.3 KB
guides/performance/optimize-script-priority.mdmarkdown2.6 KB
guides/performance/out-of-order-html-streaming.mdmarkdown12.1 KB
guides/performance/performance.mdmarkdown20.6 KB
guides/performance/resolution-optimized-pseudo-elements.mdmarkdown2.3 KB
guides/performance/schedule-tasks-by-priority.mdmarkdown2.3 KB
guides/privacy/privacy.mdmarkdown11.0 KB
guides/pwa/install-web-app.mdmarkdown15.0 KB
guides/pwa/migrate-web-app-origin.mdmarkdown3.6 KB
guides/security/client-side-encryption.mdmarkdown14.8 KB
guides/security/digital-signatures.mdmarkdown9.9 KB
guides/security/local-network-access.mdmarkdown12.3 KB
guides/security/passkey-authentication.mdmarkdown11.5 KB
guides/security/passkey-conditional-create.mdmarkdown7.9 KB
guides/security/passkey-management.mdmarkdown17.3 KB
guides/security/passkey-reauthentication.mdmarkdown6.4 KB
guides/security/passkey-registration.mdmarkdown10.3 KB
guides/security/passkeys.mdmarkdown4.9 KB
guides/security/quick-sign-ins.mdmarkdown17.5 KB
guides/security/restrict-outbound-connections.mdmarkdown13.2 KB
guides/security/sanitize-untrusted-html.mdmarkdown5.6 KB
guides/security/secure-external-subresources.mdmarkdown14.5 KB
guides/security/security.mdmarkdown29.3 KB
guides/security/trusted-types.mdmarkdown7.3 KB
guides/security/validate-origins.mdmarkdown12.7 KB
guides/security/verify-email-ownership.mdmarkdown14.5 KB
guides/ui-atoms/carousel-slide-effects.mdmarkdown10.1 KB
guides/ui-atoms/component-specific-light-dark-theme.mdmarkdown9.5 KB
guides/ui-atoms/icons.mdmarkdown17.9 KB
guides/ui-atoms/position-aware-tooltips.mdmarkdown8.3 KB
guides/ui-atoms/pull-to-reveal.mdmarkdown5.0 KB
guides/ui-atoms/responsive-table.mdmarkdown4.4 KB
guides/ui-atoms/scroll-position-aware-elements.mdmarkdown3.6 KB
guides/ui-atoms/scroll-progress-indicator.mdmarkdown6.6 KB
guides/ui-atoms/scrollability-affordance-hints.mdmarkdown11.9 KB
guides/ui-atoms/shrinking-header-on-scroll.mdmarkdown7.0 KB
guides/ui-atoms/single-line-overflow.mdmarkdown16.1 KB
guides/ui-atoms/state-aware-sticky-headers.mdmarkdown6.7 KB
guides/ui-atoms/viewport-aware-dropdowns.mdmarkdown9.9 KB
guides/ui-behaviors/2d-panning.mdmarkdown9.2 KB
guides/ui-behaviors/anchor-positioning-tab-underline.mdmarkdown3.1 KB
guides/ui-behaviors/animate-element-entry-exit.mdmarkdown7.7 KB
guides/ui-behaviors/animate-to-from-top-layer.mdmarkdown10.7 KB
guides/ui-behaviors/carousel-snap-highlights.mdmarkdown7.5 KB
guides/ui-behaviors/consistent-cross-document-transitions.mdmarkdown13.9 KB
guides/ui-behaviors/cross-document-transitions.mdmarkdown4.4 KB
guides/ui-behaviors/custom-button-actions.mdmarkdown8.2 KB
guides/ui-behaviors/declarative-dialog-popover-control.mdmarkdown7.6 KB
guides/ui-behaviors/directional-navigation-transitions.mdmarkdown5.1 KB
guides/ui-behaviors/drag-and-drop.mdmarkdown16.4 KB
guides/ui-behaviors/drag.mdmarkdown6.8 KB
guides/ui-behaviors/dynamic-sibling-animations.mdmarkdown2.6 KB
guides/ui-behaviors/dynamic-sort.mdmarkdown6.9 KB
guides/ui-behaviors/group-element-transitions.mdmarkdown6.2 KB
guides/ui-behaviors/highlight-text-ranges.mdmarkdown6.4 KB
guides/ui-behaviors/interactive-content-reveal.mdmarkdown5.7 KB
guides/ui-behaviors/interest-triggered-action-previews.mdmarkdown4.9 KB
guides/ui-behaviors/interest-triggered-tooltips.mdmarkdown19.8 KB
guides/ui-behaviors/light-dismiss-a-dialog.mdmarkdown4.1 KB
guides/ui-behaviors/motion.mdmarkdown7.6 KB
guides/ui-behaviors/move-dom-element-without-losing-state.mdmarkdown3.8 KB
guides/ui-behaviors/parallax-scroll-effects.mdmarkdown9.5 KB
guides/ui-behaviors/persistent-top-layer-ui.mdmarkdown2.3 KB
guides/ui-behaviors/physics-based-easing.mdmarkdown5.8 KB
guides/ui-behaviors/platform-controls-dismiss-dialog.mdmarkdown2.6 KB
guides/ui-behaviors/prevent-page-scroll-under-modal-dialog.mdmarkdown5.0 KB
guides/ui-behaviors/same-document-transitions.mdmarkdown8.3 KB
guides/ui-behaviors/scoped-component-transitions.mdmarkdown11.7 KB
guides/ui-behaviors/scroll-completion-effects.mdmarkdown7.5 KB
guides/ui-behaviors/scroll-entry-exit-effects.mdmarkdown9.8 KB
guides/ui-behaviors/scroll-snap-realtime-feedback.mdmarkdown10.7 KB
guides/ui-behaviors/scroll-snap-state-sync.mdmarkdown4.8 KB
guides/ui-behaviors/scroll-target-on-load.mdmarkdown3.4 KB
guides/ui-behaviors/scrollytelling.mdmarkdown8.8 KB
guides/ui-behaviors/search-hidden-content.mdmarkdown6.8 KB
guides/ui-behaviors/sortable-table.mdmarkdown7.7 KB
guides/ui-behaviors/spatial-navigation.mdmarkdown6.8 KB
guides/ui-behaviors/swipe-to-remove.mdmarkdown33.9 KB
guides/ui-behaviors/swipe-to-reveal.mdmarkdown14.2 KB
guides/ui-components/accordion.mdmarkdown14.7 KB
guides/ui-components/app-menus.mdmarkdown15.7 KB
guides/ui-components/breadcrumbs.mdmarkdown12.3 KB
guides/ui-components/card.mdmarkdown8.2 KB
guides/ui-components/carousel.mdmarkdown15.1 KB
guides/ui-components/checkbox.mdmarkdown5.7 KB
guides/ui-components/copy-button.mdmarkdown14.5 KB
guides/ui-components/dark-mode-toggle.mdmarkdown9.2 KB
guides/ui-components/dialog.mdmarkdown12.1 KB
guides/ui-components/hovercard.mdmarkdown20.9 KB
guides/ui-components/menu.mdmarkdown31.1 KB
guides/ui-components/navbar.mdmarkdown17.8 KB
guides/ui-components/navigation-drawer.mdmarkdown20.3 KB
guides/ui-components/persistent-app-tours.mdmarkdown11.2 KB
guides/ui-components/persistent-toast-notifications.mdmarkdown13.8 KB
guides/ui-components/progress-ring.mdmarkdown6.9 KB
guides/ui-components/progress.mdmarkdown10.6 KB
guides/ui-components/scrollspy.mdmarkdown6.9 KB
guides/ui-components/spinner.mdmarkdown5.9 KB
guides/ui-components/stack-drill-down.mdmarkdown36.5 KB
guides/ui-components/tabs.mdmarkdown21.7 KB
guides/ui-components/toolbar.mdmarkdown21.5 KB
guides/user-experience/content-first-noise-reduction.mdmarkdown8.3 KB
guides/user-experience/form-factor-adaptation.mdmarkdown6.0 KB
guides/user-experience/natural-interactions.mdmarkdown9.7 KB
guides/visual-design/adapt-scrollbar-to-contrast-preferences.mdmarkdown3.6 KB
guides/visual-design/apply-webgl-shaders.mdmarkdown13.1 KB
guides/visual-design/browser-ui-theming.mdmarkdown4.1 KB
guides/visual-design/color.mdmarkdown4.4 KB
guides/visual-design/complex-shapes.mdmarkdown3.5 KB
guides/visual-design/contrast-color.mdmarkdown7.1 KB
guides/visual-design/custom-text-decorations.mdmarkdown16.4 KB
guides/visual-design/customize-scrollbar-color-and-thickness.mdmarkdown2.7 KB
guides/visual-design/dark-mode.mdmarkdown16.8 KB
guides/visual-design/equal-width-text-lines.mdmarkdown6.4 KB
guides/visual-design/export-html-media-from-canvas.mdmarkdown17.1 KB
guides/visual-design/expose-canvas-content-to-browser-features.mdmarkdown19.6 KB
guides/visual-design/improve-text-layout-and-legibility.mdmarkdown5.1 KB
guides/visual-design/interactive-content-in-3d-scenes.mdmarkdown19.2 KB
guides/visual-design/precise-text-alignment.mdmarkdown4.8 KB
guides/visual-design/shaped-cutouts.mdmarkdown7.1 KB

guides/ui-behaviors/scroll-completion-effects.md

View on GitHub
# Triggering Effects After Programmatic Scrolling Completes

When programmatically scrolling to a section or element (especially with `behavior: 'smooth'`), triggering a follow-up action immediately—such as flashing a highlight state, starting an entry animation, or moving focus—causes the effect to run while the target is still off-screen or mid-scroll.

Previously, developers had to guess the scroll duration with `setTimeout()` (which fires too early on long scrolls and too late on short ones) or manually wrap a `scrollend` event listener in a `Promise` with a fallback timer (because `scrollend` does not fire when the target is already in view and no scrolling occurs).

The programmatic scroll methods on `Element` (`scrollIntoView()`, `scroll()`, `scrollTo()`, `scrollBy()`) and `Window` (`scroll()`, `scrollTo()`, `scrollBy()`) return a `Promise` that resolves when the scroll operation completes. If the target is already at the requested scroll position and no scrolling is needed, the returned `Promise` resolves immediately without hanging.

## Implementation

1. **Mark the handler as `async`**: Use an `async` function for the event listener or navigation handler that triggers the scroll.
2. **Await the scroll method directly**: Call `await element.scrollIntoView({ behavior: 'smooth', ... })` (or `await element.scrollTo(...)`, `await window.scrollTo(...)`, etc.). Execution pauses until the browser finishes the scroll animation and the scroll position settles.
3. **Apply the post-scroll effect**: Toggle the highlight class, start the animation, or move focus after the `await` expression completes.

## Interrupted Scrolls & Focus Management

- **Handling rapid / interrupted scrolls**: If a new scroll starts on the same scroll container before an ongoing smooth scroll finishes, the browser aborts the ongoing smooth scroll and **resolves** (does not reject) all pending scroll promises on that container. If you need to suppress the post-scroll effect for superseded scrolls when a user clicks rapidly, track an incrementing operation ID and return early after `await` if a newer scroll was started:

```javascript
let currentScrollId = 0;
const sections = document.querySelectorAll('section');

async function scrollToAndHighlight(targetElement) {
  const scrollId = ++currentScrollId;
  sections.forEach((sec) => sec.classList.remove('highlight'));

  await targetElement.scrollIntoView({ behavior: 'smooth', block: 'center' });

  // Abort follow-up effect if another scroll was triggered while awaiting
  if (scrollId !== currentScrollId) return;

  targetElement.classList.add('highlight');
}
```

- **Focusing the target after scrolling**: When moving keyboard focus to the target element (or a heading inside it with `tabindex="-1"`) after `await targetElement.scrollIntoView(...)`, pass `{ preventScroll: true }` to `focus()` so the focus call does not initiate a second, competing scroll:

```javascript
await targetElement.scrollIntoView({ behavior: 'smooth', block: 'center' });
targetHeading.focus({ preventScroll: true });
```

## Constraints & Best Practices

- **MANDATORY**: Await the `Promise` returned directly by `scrollIntoView()`, `scroll()`, `scrollTo()`, or `scrollBy()` rather than guessing scroll durations with `setTimeout()`.
- **DO NOT** wrap `scrollend` in a manual `new Promise()` as your primary implementation—`scrollend` does not fire when the target is already in view and no scroll distance is traveled, whereas scroll method promises resolve automatically in that case.
- **DO**: Pass `{ preventScroll: true }` when calling `.focus()` after awaiting a scroll method so the browser does not jump or scroll a second time.
- **DO**: Guard post-scroll effects with a request token if rapid user interactions can trigger overlapping smooth scrolls on the same container, since interrupting a smooth scroll resolves (rather than rejects) the previous promise.
- **Known Chrome bug with the root scroller**: Chrome has a bug where the `Promise` returned by `scrollIntoView()` resolves too early when it is the document's root scroller that is scrolling. Awaiting a `scrollIntoView()` on a nested scroll container works as expected. Do not wrap your content in a scroll container, such as `div` with `overflow-y: auto`, as a workaround for this bug.

## Accessibility considerations

Ensure that the control used to trigger scrolling has an appropriate role. If the scrolling is intended to redirect the user elsewhere in the current context, then use a `<a>` element with a `href` attribute, so that it receives an implicit `link` role, along with the expected keyboard interactions. Redirect focus to this location scrolled to, so that people can continue navigating from the location that they are redirected to.

**DON'T** provide important information solely through visual design updates upon completion of programmatic scrolling. If there is important information that needs to be conveyed as a result of this interaction, ensure that this is available in sufficiently contrasting text, and that this is conveyed to people using screen readers through use of an ARIA live region.

## Fallback strategies

Browser support for Scroll method promises: Limited availability.
Supported by: Chrome 150 (Jun 2026) and Edge 150 (Jul 2026).
Unsupported in: Firefox and Safari.

In browsers that do not support scroll method promises, `scrollIntoView()`, `scroll()`, `scrollTo()`, and `scrollBy()` return `undefined` instead of a `Promise`.

- **Progressive enhancement (default `await` behavior)**: Because `await undefined` is valid JavaScript that resolves immediately on the next microtask, writing `await element.scrollIntoView({ behavior: 'smooth' })` will not throw an error in unsupported browsers. Instead, it degrades gracefully by running the post-scroll code as soon as the scroll begins. For non-critical visual flourishes like a temporary highlight, this is often sufficient.
- **Faithful fallback (`scrollend` + timeout)**: If your Baseline target does not support `scroll-promises` and the post-scroll action must wait until scrolling finishes in older browsers, check whether the return value is a `Promise` (`result instanceof Promise`). When it is `undefined`, wait for the `scrollend` event on the scroll container with a short fallback timeout in case the element is already in view and no scrolling occurs:

```javascript
function scrollIntoViewAsync(element, options, scroller = window) {
  const result = element.scrollIntoView(options);

  // Feature detect: in supporting browsers, scrollIntoView() returns a Promise
  if (result instanceof Promise) {
    return result;
  }

  // Fallback for browsers where scrollIntoView() returns undefined
  return new Promise((resolve) => {
    let timeoutId;

    const finish = () => {
      clearTimeout(timeoutId);
      scroller.removeEventListener('scrollend', finish);
      scroller.removeEventListener('scroll', onScroll);
      resolve();
    };

    const onScroll = () => {
      // Restart the idle timer on every scroll event. If scrollend never fires
      // (browsers without scrollend support), this resolves once scrolling goes idle.
      clearTimeout(timeoutId);
      timeoutId = setTimeout(finish, 100);
    };

    scroller.addEventListener('scrollend', finish, { once: true });
    scroller.addEventListener('scroll', onScroll, { passive: true });

    // If no scroll event fires within the idle window (e.g., already in view), resolve.
    // 100ms is an example value; it only needs to exceed the gap between scroll events.
    timeoutId = setTimeout(finish, 100);
  });
}
```
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall