Add guide and evals for state-aware sticky headers

CODEOWNERS

@@ -30,9 +30,9 @@ guides/security/passkey-reauthentication/ @agektmr
 guides/security/passkey-registration/ @agektmr
 guides/security/passkeys/ @agektmr
 # Owned via feature "container-scroll-state-queries"
-guides/ui-atoms/context-sensitive-sticky-headers/ @bramus
 guides/ui-atoms/scroll-position-aware-elements/ @bramus
 guides/ui-atoms/scrollability-affordance-hints/ @bramus
+guides/ui-atoms/state-aware-sticky-headers/ @bramus
 # Owned via group "scrolling"
 guides/ui-atoms/carousel-slide-effects/ @bramus
 guides/ui-atoms/pull-to-reveal/ @bramus

README.md

@@ -142,7 +142,7 @@ _View an example:_ [the `navigation-drawer` guide](https://github.com/GoogleChro
 </details>
 
 <details>
-<summary><strong>130 real-world developer use cases</strong></summary>
+<summary><strong>131 real-world developer use cases</strong></summary>
 
 <h3>accessibility</h3>
 
@@ -252,6 +252,7 @@ _View an example:_ [the `navigation-drawer` guide](https://github.com/GoogleChro
 - **[scroll-progress-indicator](https://github.com/GoogleChrome/modern-web-guidance/blob/main/skills/modern-web-guidance/guides/ui-atoms/scroll-progress-indicator.md)**: Create a scroll progress bar, stepped progress tracker, or any visual affordance that communicates how far through a page or section the user has scrolled.
 - **[scrollability-affordance-hints](https://github.com/GoogleChrome/modern-web-guidance/blob/main/skills/modern-web-guidance/guides/ui-atoms/scrollability-affordance-hints.md)**: Build scroll-shadow overlays, gradient fades, or directional arrow indicators that appear only when there's actually more content to scroll to in that direction.
 - **[shrinking-header-on-scroll](https://github.com/GoogleChrome/modern-web-guidance/blob/main/skills/modern-web-guidance/guides/ui-atoms/shrinking-header-on-scroll.md)**: Smoothly animate a fixed header or full-page cover on scroll to dynamically shrink, gain shadows, and transform its layout over a predefined scroll distance.
+- **[state-aware-sticky-headers](https://github.com/GoogleChrome/modern-web-guidance/blob/main/skills/modern-web-guidance/guides/ui-atoms/state-aware-sticky-headers.md)**: Build sticky section headers or navbars that visually transform when they're actually "stuck" at the top, changing their color scheme or gaining a shadow.
 
 <h3>ui-behaviors</h3>
 

guides/features-and-use-cases.md

@@ -45,7 +45,7 @@
 │   └── size-aware-styling
 ├── container-scroll-state-queries
 │   ├── carousel-snap-highlights
-│   ├── context-sensitive-sticky-headers
+│   ├── state-aware-sticky-headers
 │   ├── scroll-position-aware-elements
 │   └── scrollability-affordance-hints
 ├── container-style-queries

guides/ui-atoms/state-aware-sticky-headers/expectations.md

@@ -0,0 +1,7 @@
+- The header container uses `position: sticky` to remain at the top of the scroller.
+- If any of the stuck styles change layout, `overflow-anchor: none` is applied to the parent of the header container.
+- If none of the stuck styles change layout, `overflow-anchor: none` should NOT be applied to the parent of the header container.
+- The header container defines `container-type: scroll-state` to enable scroll state queries.
+- The header container defines `container-name: section-header` to avoid collisions.
+- The header visual style changes (e.g., background color or box-shadow) when it is stuck at the top.
+- The visual style changes are implemented using the `@container scroll-state(stuck: top)` query.