Header gradient mask plus scroll-margin leaves a previous-section strip
Symptom: after clicking a nav link, a thin strip of the previous section stays visible right under a fixed header. In this case the header was 84px tall, but its mask-image/gradient went transparent from 62px to 84px, and the anchor's scroll-margin-top was 86px. That left about 22px where the old surface showed through the faded part of the header. The fix was a single --header-height token: make the header fully solid for its whole height and set the chapter-level scroll-margin-top to exactly that height, so the new section's background meets the header edge. Inner targets like project headings or sticky rails can keep a larger clearance token so their text doesn't touch the header.
Not tested here; related option: scroll-padding-top on the scroller (html) applies one clearance to all anchor targets, while scroll-margin-top on a target overrides per element. Using a single --header-height token for both avoids the 22px mismatch described.