CogJS - Cognitive-Oriented Web Accessibility Toolkit

cog-orient

cog-orient is a declarative attribute that highlights the section currently visible in the viewport. It helps users stay oriented as they scroll through long-form content, making it easier to focus, reference, or return to a particular point.

What It Does

When applied to a <section> or scroll-tracked element, cog-orient="true" monitors the element's visibility in the viewport. The topmost visible section automatically receives a highlight class while all others are cleared.

<section cog-orient="true">
  <h2>Step 1: Personal Info</h2>
  <p>Start by entering your name and email.</p>
</section>

How It Works

• Uses IntersectionObserver to track scroll position in real-time
• Adds the cog-orient-active class to the topmost visible section
• Automatically removes the highlight as you scroll past
• Only one section is highlighted at a time

Styling and Placement

The active section can be styled using the default class .cog-orient-active. You can override this in your own styles or theme config to suit your UI.

.cog-orient-active {
  outline: 2px solid #007acc;
  background-color: rgba(0, 122, 204, 0.05);
  scroll-margin-top: 2rem;
}

Accessibility Considerations

• Visual Orientation: Helps users track their position in large content blocks
• Low Distraction: Uses subtle styling to aid orientation without disruption
• Screen Reader Neutral: Does not interfere with reading order or ARIA landmarks

Testing cog-orient

// Test Checklist
// - Add cog-orient to multiple sections in a long page
// - Scroll slowly and observe which section is highlighted
// - Confirm only one section is active at a time
// - Test with reduced motion settings (prefers-reduced-motion)
// - Ensure it doesn't interfere with navigation or tabbing

Best Practices for cog-orient

• Use on Major Headings: Apply to top-level <section> blocks, not minor elements
• Keep Visual Cues Subtle: Avoid large animations or overly bright highlights
• Combine With cog-toc: Pair with cog-toc to create a rich navigation experience
• Don't Use Everywhere: Avoid using on short or densely packed layouts