Long-Form Guide Example

Why This Pattern Exists

Long-form pages ask more from navigation than a short landing page. When a reader commits to a guide, they need to know where they are, what is left, and how to jump to a useful section without losing their place.

The shared Foundry table of contents widget is meant to solve exactly that problem. It keeps the implementation reusable, while still allowing each theme to style the experience differently.

What Readers Need Most

Readers usually want three things from a guide layout: orientation, speed, and confidence. They need to understand the page structure, move around quickly, and trust that the section they clicked will land in the right place.

Why The Starter Includes It

The starter is supposed to demonstrate real patterns, not just isolated blocks. A guide page with a sticky table of contents is a practical example that downstream sites can adopt with very little custom work.

Shared Behavior Contract

The widget tracks headings as the reader scrolls and marks the active section. Sections that have already been passed get a subtler completed state so the list shows motion through the page instead of acting like a static menu.

The same runtime also powers a compact mobile mode. On smaller screens, the control stays visible, shows the current section, and expands only when the user wants the full list.

Active Section Tracking

The active state updates as soon as the reader crosses into the next heading region. This makes the table of contents feel connected to the article instead of lagging behind the scroll position.

Completed Section State

Completed sections should be recognizable without stealing attention from the current one. In the baseline theme, that means a subtler tint rather than a second strong highlight.

Progress Rail

The progress rail gives the reader a quick sense of how far they are through the document. It is intentionally thin and quiet, because it should reinforce the current section state rather than compete with it.

Mobile Compact Mode

A full sidebar does not translate directly to a phone. The better pattern is a compact sticky control that stays available while taking up very little space.

The mobile toggle surfaces the current section label, so the reader gets feedback even when the panel is collapsed. Expanding the panel reveals the full table of contents only when needed.

Keep It Lightweight

The compact control should feel like a utility, not a modal workflow. Readers should be able to expand it, choose a section, and continue reading without extra friction.

Respect Reduced Motion

The widget still works when reduced motion is enabled. Scroll-linked behavior should stay functional, but animated transitions should avoid becoming distracting or essential.

Anchor Offset And Sticky Headers

Sticky headers commonly break in-page navigation by covering the heading that was just selected. A reusable table of contents pattern has to account for that globally instead of hardcoding offsets in every page template.

Foundry measures the real header height and exposes a shared scroll offset variable. That value is then applied to heading targets so the clicked section remains visible below the fixed header.

Why Dynamic Measurement Wins

Header heights often shift across breakpoints, themes, and scrolled states. Measuring the live header is more maintainable than copying pixel values into page templates or one-off scripts.

Theme Ownership

Core owns structure, state, and behavior. Themes own the visual language. That split keeps the widget portable while still allowing a brand like Beauty Medica to make it feel editorial instead of generic.

Theme-shield provides the neutral baseline in the starter. A downstream theme can then change the tokens, spacing, surfaces, and emphasis styles without forking the runtime.

Site Overrides Should Stay Small

If a site needs a specific layout wrapper or placement tweak, it can do that locally. The goal is to avoid repeating the active-state logic, progress behavior, and anchor handling in every project.

Where To Reuse It Next

This same pattern fits knowledge base articles, service explainers, onboarding guides, policy pages, and documentation pages. Any page with multiple headings and a long scroll can benefit from the same contract.

The more consistently it is reused, the more valuable the shared theme tokens and runtime become. That is the point of moving it into Foundry instead of leaving it in a single site.