@olives/devos 2.1.0

package/.agents/skills/modern-web-guidance/guides/user-experience/search-hidden-content.md

@@ -0,0 +1,136 @@
+# Search hidden content
+
+Web interfaces often hide content from view to improve the user experience, save screen space, or increase page performance. Traditional methods like `display: none` or `visibility: hidden` work to hide content visually, but they also make that content completely inaccessible to screen readers and browser features like "Find in page".
+
+To hide content visually but still allow it to be searchable by users and enable it to be deep linked to via URL fragments and "Scroll to Text Fragment" links, you can use either the HTML `<details>` element or the `hidden="until-found"` attribute. The `<details>` element is generally recommended as it's simpler to implement and maintain, but there are some more complex cases where `<details>` is not sufficient and `hidden="until-found"` is required.
+
+For example:
+
+- If you want full control over the styling of the show/hide mechanism.
+- If the UI controls to show/hide the content are in another part of the DOM.
+- If you don't want to support hiding the content after it's shown.
+
+## How to implement
+
+The `<details>` element has searchable and accessible text by default, and no special implementation is required. Prefer using `<details>` over `hidden="until-found"` if possible.
+
+If you need to use `hidden="until-found"` instead, follow these instructions:
+
+1. **Apply the attribute:** Add the `hidden="until-found"` HTML attribute directly to the elements containing the content that should be hidden from view.
+2. **Synchronize UI state:** If the interface has related states that depend on the content's visibility (e.g., updating ARIA attributes, toggling open/close CSS classes, or rotating accordion icons):
+   - You **MUST** add an event listener for the `beforematch` event.
+   - Register the `beforematch` event listener directly on the element carrying the `hidden="until-found"` attribute. Since the event bubbles, you may alternatively use event delegation by registering a single listener on a parent element (such as a tab container) to manage multiple hidden sections at once.
+   - Inside the event listener, execute the logic to synchronize related UI elements (such as closing other open tabs or changing the state of a toggle button).
+
+## Example code
+
+**Goal:** Render a hidden container where the content remains invisible to the user until they search for a word within that section.
+
+### Using `<details>` element
+
+```html
+<details>
+  <summary>Click to expand</summary>
+  <p>This content is visually hidden.</p>
+</details>
+```
+
+#### Mutually exclusive disclosures
+
+When handling mutually exclusive content regions, like an exclusive accordion, use the native HTML `<details>` element with a shared `name` attribute.
+
+```html
+<div class="accordion-group">
+  <!-- The name attribute creates an exclusive disclosure group -->
+  <details class="disclosure" name="my-accordion">
+    <summary>Section 1</summary>
+    <p>Section 1 content</p>
+  </details>
+
+  <details class="disclosure" name="my-accordion" open>
+    <summary>Section 2</summary>
+    <p>Section 2 content</p>
+  </details>
+
+  <details class="disclosure" name="my-accordion">
+    <summary>Section 3</summary>
+    <p>Section 3 content</p>
+  </details>
+</div>
+```
+
+### Using `hidden="until-found"` attribute
+
+```html
+<!-- The browser automatically removes hidden="until-found" upon a search match -->
+<div class="hidden-container" hidden="until-found">
+  <p>This content is visually hidden.</p>
+</div>
+```
+
+#### Custom mutually exclusive disclosures
+
+When handling custom mutually exclusive regions controlled by external buttons, ensure only the matched panel remains visible. In the `beforematch` event handler, you MUST synchronize related ARIA states such as setting `aria-expanded="true"` on the controlling button.
+
+```html
+<div class="custom-accordion">
+  <div class="controls">
+    <button aria-expanded="true" aria-controls="panel-1" id="btn-1">Section 1</button>
+    <button aria-expanded="false" aria-controls="panel-2" id="btn-2">Section 2</button>
+  </div>
+
+  <div id="panel-1" class="panel">
+    <p>Section 1 content (visible)</p>
+  </div>
+
+  <div id="panel-2" class="panel" hidden="until-found">
+    <p>Section 2 content (hidden)</p>
+  </div>
+</div>
+```
+
+```javascript
+const accordion = document.querySelector('.custom-accordion');
+
+accordion.addEventListener('beforematch', (e) => {
+  // Hide all panels and synchronize button states before the browser reveals the matched panel
+  accordion.querySelectorAll('.panel').forEach((panel) => {
+    if (panel !== e.target) {
+      panel.hidden = 'until-found';
+    }
+  });
+  accordion.querySelectorAll('button').forEach((btn) => {
+    const controls = btn.getAttribute('aria-controls');
+    btn.setAttribute('aria-expanded', controls === e.target.id ? 'true' : 'false');
+  });
+});
+```
+
+## Best practices for `hidden="until-found"`
+
+- **DO** apply borders, padding, and backgrounds to nested child wrappers rather than directly to the element with the `hidden="until-found"` attribute. This prevents unintended layout shifts or visual remnants while the element is hidden.
+- **DO NOT** apply `display: none`, `visibility: hidden`, or any associated `display` or `visibility` CSS properties directly to elements with the `hidden="until-found"` attribute. This breaks the native functionality and permanently hides the content from the search index.
+- **DO NOT** use `hidden="until-found"` for sensitive information, internal data tokens, or irrelevant data that should not be exposed via search.
+- **DO NOT** use `hidden="until-found"` as a replacement for "screen reader only" (.sr-only) text.
+
+## Browser support and fallback strategies
+
+The `<details>` element is Baseline Widely available, so a fallback strategy is not required.
+
+The `hidden="until-found"` attribute is not yet Baseline Widely available, but it can be safely used with a fallback in unsupporting browsers. **DO NOT** avoid `hidden="until-found"` because of missing browser support, as its accessiblity benefits far outweigh the cost of implementing a fallback.
+
+#### `hidden="until-found"` fallback
+
+For standard UI elements like accordions or "Read more" sections, use JavaScript to feature-detect and show all content if the feature is unsupported.
+
+```javascript
+if (!('onbeforematch' in HTMLElement.prototype)) {
+  // Expand all hidden content for unsupported browsers
+  document.querySelectorAll('[hidden="until-found"]').forEach((el) => {
+    el.removeAttribute('hidden');
+    // MANDATORY: also update any aria references to this element.
+  });
+}
+```
+
+For mutually exclusive UI paradigms (like custom exclusive panels where content shares the same visual region), the fallback should extract and display all content linearly below the main interactive area, using URL anchor fragments to allow users to navigate directly to the respective sections.

package/.agents/skills/modern-web-guidance/guides/user-experience/shaped-cutouts.md

@@ -0,0 +1,146 @@
+## Overview
+CSS Masking allows you to clip an element to a custom shape, such as adding a notch to a card or creating a shaped border. When combining shapes for complex layouts, choose your masking strategy based on the type of content the element contains:
+
+| Masking strategy                | Best For                        | Text Impact                    |
+| ------------------------------- | ------------------------------- | ------------------------------ |
+| Direct Element SVG Masking      | Images, Icons, Decorative shapes, Complex shapes | Not recommended (can crop text) |
+| Adjacent Element SVG Masking    | Cards with Text, Crucial content | Text remains fully readable    |
+| Pure CSS Gradients              | Simple Geometric Shapes           | Not recommended (can crop text) |
+
+---
+
+## Implementation
+To implement shaped cutouts:
+
+### Using an SVG Mask
+SVG masks allow you to define shapes that subtract from or add to the visible area using white (reveal) and black (hide) fills.
+
+> **Luminance vs. Alpha Masking**: SVG masks default to **luminance** (brightness) mode, which is why we use `fill="white"` to reveal areas and `fill="black"` to cut them out. If you prefer to use the SVG's transparency (alpha channel) instead of colors, you can set `mask-type: alpha;` in CSS or `mask-type="alpha"` on the SVG `<mask>` element.
+
+#### Direct Element SVG Masking
+When there is no text inside the element to worry about (such as profile avatars, product images, or illustrations), you can apply the SVG mask directly to the element.
+
+Using `maskContentUnits="objectBoundingBox"` inside the SVG mask ensures that the mask scales automatically to the width and height of any element it is applied to.
+
+```html
+<!-- 1. Define the mask in SVG (hidden from view) -->
+<svg width="0" height="0" style="position: absolute;" aria-hidden="true">
+  <defs>
+    <!-- objectBoundingBox makes the mask scale from 0 to 1 along the element's borders -->
+    <mask id="splat-mask" maskContentUnits="objectBoundingBox">
+      <!-- Organic Bezier path defining an artistic paint splat shape -->
+      <path d="M 0.5 0.05 C 0.58 0.05, 0.58 0.21, 0.67 0.18 C 0.76 0.15, 0.79 0.08, 0.85 0.15 C 0.91 0.22, 0.83 0.32, 0.89 0.38 C 0.95 0.44, 1.03 0.45, 0.99 0.55 C 0.95 0.65, 0.82 0.62, 0.8 0.72 C 0.78 0.82, 0.89 0.92, 0.8 0.97 C 0.71 1.02, 0.64 0.88, 0.55 0.93 C 0.46 0.98, 0.44 1.06, 0.35 1.01 C 0.26 0.96, 0.31 0.81, 0.22 0.79 C 0.13 0.77, 0.01 0.88, 0.01 0.77 C 0.01 0.66, 0.16 0.62, 0.14 0.52 C 0.12 0.42, -0.02 0.39, 0.03 0.29 C 0.08 0.19, 0.23 0.27, 0.29 0.19 C 0.35 0.11, 0.3 0.01, 0.4 0.01 C 0.5 0.01, 0.42 0.05, 0.5 0.05 Z" fill="white" />
+    </mask>
+  </defs>
+</svg>
+
+<!-- 2. Apply the mask to the image element -->
+<img src="avatar.jpg" alt="User Profile" class="shaped-avatar">
+
+<style>
+.shaped-avatar {
+  width: 200px;
+  height: 200px;
+  object-fit: cover;
+  
+  /* Apply the SVG mask ID with standard and webkit-prefixed properties */
+  -webkit-mask-image: url(#splat-mask);
+  mask-image: url(#splat-mask);
+}
+</style>
+```
+
+#### Adjacent Element SVG Masking
+Apply the mask to an adjacent element rather than the parent element containing text. This ensures that text doesn't get clipped and remains readable.
+
+To solve this, structure your component into a two-part layout:
+1. A **safe, unmasked text container** (`.card-body`) for all readable content.
+2. An **empty decorative `div`** (`.card-accent`) placed next to it, which receives the custom SVG mask.
+
+By assigning both parts the same background color, they visually merge into a single, custom-shaped component.
+
+```html
+<!-- 1. Define the SVG mask (hidden from view) -->
+<svg width="0" height="0" style="position: absolute;" aria-hidden="true">
+  <defs>
+    <!-- Use objectBoundingBox to make the mask scale with the element -->
+    <mask id="accent-stencil" maskContentUnits="objectBoundingBox">
+      <!-- Fill the entire area with white (fully visible) -->
+      <rect width="1" height="1" fill="white" />
+      <!-- Draw a black shape to cut out a concave curve. Extending the path to x=1.1 guarantees it fully clears the right edge, preventing subpixel lines -->
+      <path d="M 1.1,0 C 0.4,0.1 0.4,0.9 1.1,1 L 1.1,0 Z" fill="black" />
+    </mask>
+  </defs>
+</svg>
+
+<!-- 2. Create the unified card layout -->
+<div class="unified-card">
+  <!-- The text-bearing element remains unmasked and perfectly rectangular -->
+  <div class="card-body">
+    <h3>Premium Membership</h3>
+    <p>Get exclusive weekly updates on modern web standards and premium UI designs.</p>
+  </div>
+  <!-- The empty accent element next to it is masked to form the custom shape -->
+  <div class="card-accent"></div>
+</div>
+
+<style>
+.unified-card {
+  display: flex;
+  width: 400px;
+}
+
+.card-body {
+  flex: 1;
+  background-color: #1e293b; /* Elegant slate color */
+  color: #f8fafc;
+  padding: 24px;
+  border-top-left-radius: 16px;
+  border-bottom-left-radius: 16px;
+}
+
+.card-accent {
+  width: 60px;
+  background-color: #1e293b; /* Same background color so they merge visually without seams */
+  border-top-right-radius: 16px;
+  border-bottom-right-radius: 16px;
+
+  /* Reference the SVG mask */
+  -webkit-mask-image: url(#card-accent-mask);
+  mask-image: url(#card-accent-mask);
+}
+</style>
+```
+
+### Using a Single CSS Gradient for Simple Cutouts
+When you only need simple geometric cutouts (such as a semi-circular top notch, side indentations, or straight diagonal cuts), you do not need to write or reference an external SVG. Instead, you can define a CSS radial or linear gradient directly inside the `mask-image` property.
+
+```html
+<div class="gradient-masked-card">
+  <h3>Notched Coupon Card</h3>
+  <p>This card uses a pure CSS radial gradient to cut out a semi-circular notch along its top edge.</p>
+</div>
+
+<style>
+.gradient-masked-card {
+  background: linear-gradient(135deg, #3b82f6, #1d4ed8);
+  color: white;
+  padding: 40px 24px 24px 24px; /* Extra top padding ensures content clears the notch */
+  border-radius: 16px;
+  text-align: center;
+
+  /* radial-gradient places a circle at 50% (horizontal center) and 0% (top edge), cutting out a 20px transparent notch */
+  -webkit-mask-image: radial-gradient(circle at 50% 0%, transparent 20px, black 21px);
+  mask-image: radial-gradient(circle at 50% 0%, transparent 20px, black 21px);
+}
+</style>
+```
+
+## Fallback strategies
+Baseline status for Masks: Newly available. It's been Baseline since 2023-12-07.
+Supported by: Chrome 120 (Dec 2023), Edge 120 (Dec 2023), Firefox 53 (Apr 2017), and Safari 15.4 (Mar 2022).
+
+If a browser does not support `mask-image` or the prefixed version:
+- **For Shaped Images**: The element will degrade gracefully, displaying as a normal rectangular element with its default fallback styles.
+- **For Shaped Cards**: The adjacent decorative `.card-accent` element will remain a solid, unmasked rectangle. Since it shares the same background color as the text container, the entire card will simply render as a standard, clean rectangular container.
+- **Progressive Enhancement**: By keeping text layers outside the mask entirely, your content is guaranteed to remain completely readable, structured, and accessible on older browsers.

package/.agents/skills/modern-web-guidance/guides/user-experience/shrinking-header-on-scroll.md

@@ -0,0 +1,126 @@
+# Shrinking headder on scroll
+
+A shrinking header on scroll is a common UI pattern where a fixed header element at the top of the page smoothly transitions to a smaller size as the user scrolls down. This effect is often used to maximize screen real estate for the main content while keeping essential navigation or branding elements accessible. With CSS scroll-driven animations, this effect can be achieved in a declarative and performant way, by linking an animation to the scroll position of the document.
+
+## How to implement
+
+Here’s how to create a shrinking header on scroll:
+
+1.  **Create a fixed header:** Start with a header element that is fixed to the top of the page and has a predefined height.
+
+    ```html
+    <header>HEADER</header>
+    ```
+
+    ```css
+    header {
+      position: fixed;
+      height: 200px;
+      top: 0;
+      left: 0;
+      right: 0;
+    }
+    ```
+
+2.  **Define the shrink animation:** Create a CSS animation that changes the height of the header.
+
+    ```css
+    @keyframes shrink {
+      to {
+        height: 50px;
+      }
+    }
+    ```
+
+3.  **Apply the animation and scroll timeline:** Attach the animation to the header and use the `scroll()` function to link it to the document’s scroll position.
+
+    ```css
+    header {
+      animation: shrink auto linear both;
+      animation-timeline: scroll(block root);
+    }
+    ```
+
+4.  **Set the `animation-range`:** Use the `animation-range` property to specify the scroll distance over which the animation should occur. For example, to shrink the header over the first 150 pixels of scrolling, you would use `animation-range: 0px 150px;`.
+
+    ```css
+    header {
+      animation-range: 0px 150px;
+    }
+    ```
+
+**Tip:** To prevent the content following the header from being obscured by it, add a `padding-top` to the `body` (or the main content container) that is equal to the initial height of the header.
+
+**Tip:** To make sure the contents of the page scroll in sync with the shrinking header, set the `animation-range-end` to the difference between the start and end sizes. This ensures the animation completes precisely when the header reaches its final size. In this demo the header shrinks from `200px` to `50px`, so the `animation-range-end` is set to `150px`.
+
+## Example code
+
+```css
+@keyframes shrink {
+  to {
+    height: 50px;
+  }
+}
+
+header {
+  animation: shrink auto linear both;
+  animation-timeline: scroll(block root);
+  animation-range: 0px 150px;
+}
+```
+
+## Best Practices
+
+When using scroll-driven animations, it's important to follow a few best practices to ensure a smooth and accessible experience:
+
+- **DO** include feature detection: Not all browsers support scroll-driven animations. Use `@supports ((animation-timeline: scroll()) and (animation-range: 0% 100%))` to check for support and provide a fallback for browsers that don't support it.
+  - The `(animation-range: 0% 100%)` check **MUST** be included here, to filter out browsers with only partial support.
+  - **DO NOT** use the `scroll-timeline-polyfill` package for the fallback strategy as it is not feature complete and has a lot of known issues.
+  - If the animation is only considered to be decorative, opt for Progressive Enhancement and **DO NOT** provide a fallback.
+- **DO** respect user preferences: Some users prefer to have less motion on the web. Use the `prefers-reduced-motion` media query to disable or reduce your animations for these users.
+- **DO** try to animate only performant CSS properties: For the smoothest animations, stick to animating properties that can be handled by the browser's compositor thread, such as `transform` and `opacity`. Animating other properties like `width` or `height` can lead to performance issues.
+- **DO** use the correct declaration order: When using the `animation` shorthand property, declare `animation-timeline` and `animation-range` *after* it to prevent the shorthand from resetting the timeline.
+
+When using the `scroll()` function to create a scroll-driven animation:
+
+- **OPTIONAL** be explicit about the scroller: When not targeting the nearest ancestor scroller, be explicit about which scroller you want to use with `scroll(root)` or `scroll(self)`.
+  - When `root`, `nearest`, or `self` are not sufficient, use a named scroll-timeline.
+- **OPTIONAL** be explicit about the axis to track: When not targeting the default `block` axis (such as in a horizontal scroller), be explicit about which axis to track with `scroll(block)` or `scroll(inline)`.
+
+As for this use case specifically:
+
+- The element that you animate **MUST** not be `position: static` or `position: relative` when using percentages in the `animation-range`.
+  - This is because those elements are considered “in-flow”. Shrinking those elements as you scroll, would shrink the total scroll distance, thereby affecting the computed value of — for example — `10%` into the scroll.
+
+## Browser support and fallback strategies
+
+Scroll-driven animations has limited availability.
+Supported by: Chrome 115 (Jul 2023), Edge 115 (Jul 2023), and Safari 26 (Sep 2025).
+Unsupported in: Firefox.. Therefore, a fallback strategy is typically required.
+
+For browsers that do not support scroll-driven animations, you can use a fallback to recreate the visual effects. The fallbacks are typically built with either a scroll listener (for ScrollTimeline effects) or the IntersectionObserver API (for ViewTimeline effects).
+
+In browsers with built-in support for scroll-driven animations, ALWAYS use the native CSS implementation as those are more performant.
+
+Note that not every effect can be recreated using the fallbacks approach.
+
+For this use-case specifically, the following script applies the fallback for browsers that do not support scroll-driven animations. It uses a scroll listener to track the scroll position of the document over a distance of `150px` and updates the header's height accordingly.
+
+```js
+// Fallback for browsers that don't support scroll-driven animations
+if (!CSS.supports('(animation-timeline: scroll()) and (animation-range: 0% 100%)')) {
+  const header = document.querySelector('header');
+
+  const initialHeight = 200;
+  const finalHeight = 50;
+  const scrollDistance = 150;
+
+  window.addEventListener('scroll', () => {
+    const scrollY = window.scrollY;
+    const scrollPercent = Math.min(1, scrollY / scrollDistance);
+    const newHeight = initialHeight - (initialHeight - finalHeight) * scrollPercent;
+
+    header.style.height = `${newHeight}px`;
+  });
+}
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/size-aware-styling.md

@@ -0,0 +1,104 @@
+## Overview
+
+Size-aware styling allows components to change their layout or appearance based on the space available to them, rather than the size of the whole screen. This is useful for components like cards or navigation bars that might be placed in different parts of a layout (like a narrow sidebar or a wide main area).
+
+Using container queries is recommended because it makes components truly modular. You do not need to know where the component will live or write complex media queries to handle every possible layout.
+
+## Implementation
+
+### 1. Define the container
+
+MANDATORY: You must first tell the browser which element is the container to be measured.
+
+```css
+.card-container {
+  /* Define the container type. Use 'inline-size' for width-based queries. */
+  /* You can also use 'size' for both width and height, but it requires explicit sizing. */
+  container-type: inline-size;
+}
+```
+
+### 2. Apply styles based on container size
+
+Use the `@container` rule to apply styles when the container reaches a certain size.
+
+```css
+/* Default styles for small containers (stacked layout) */
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+/* Styles for larger containers (side-by-side layout) */
+/* This triggers when the container is wider than 400px */
+@container (min-width: 400px) {
+  .card {
+    flex-direction: row;
+    align-items: center;
+  }
+  
+  .card-image {
+    width: 150px;
+    height: 150px;
+  }
+}
+```
+
+### 3. Conditionally show content
+
+You can also use container queries to hide or show extra details when there is more room.
+
+```css
+.card-details {
+  /* Hide extra details by default in small spaces */
+  display: none;
+}
+
+@container (min-width: 600px) {
+  .card-details {
+    /* Show details when there is plenty of room */
+    display: block;
+  }
+}
+```
+
+### Fallback strategies
+
+Baseline status for Container queries: Widely available. It's been Baseline since 2023-02-14.
+Supported by: Chrome 105 (Sep 2022), Edge 105 (Sep 2022), Firefox 110 (Feb 2023), and Safari 16 (Sep 2022).
+
+For browsers that do not support container queries, the best approach is to use a safe default layout (like the stacked vertical layout) and progressively enhance it using media queries if the general screen size allows it.
+
+```css
+/* Default safe stacked layout */
+.card {
+  display: flex;
+  flex-direction: column;
+}
+
+/* Fallback using media queries for older browsers */
+@media (min-width: 600px) {
+  .card {
+    flex-direction: row;
+  }
+}
+
+/* Overwrite with container queries where supported */
+@supports (container-type: inline-size) {
+  @media (min-width: 600px) {
+    .card {
+      /* Reset media query fallback if needed, or let container query handle it */
+      flex-direction: column;
+    }
+  }
+  
+  @container (min-width: 400px) {
+    .card {
+      flex-direction: row;
+    }
+  }
+}
+```
+
+This ensures that users on older browsers still get a usable layout, even if it does not adapt perfectly to every specific container width.

package/.agents/skills/modern-web-guidance/guides/user-experience/soft-edge-content-fade.md

@@ -0,0 +1,62 @@
+## Overview
+To apply a transparency gradient to the edges of a container (e.g., to indicate more content is available to scroll or to fade out text), use CSS Masking with a linear gradient. This approach is superior to using a semi-transparent overlay because it actually fades the content itself, allowing the background to show through naturally without interfering with text selection or pointer events.
+
+## Implementation
+To implement a soft edge fade:
+
+### Fading the bottom edge of a container
+This is useful for indicating that there is more content below in a scrollable area.
+
+```css
+.container {
+  /* Enable scrolling */
+  overflow-y: auto;
+  
+  /* MANDATORY: Use vendor prefix for wider support in older browsers */
+  -webkit-mask-image: linear-gradient(to bottom, black 80%, transparent 100%);
+  
+  /* Standard property for modern browsers */
+  mask-image: linear-gradient(to bottom, black 80%, transparent 100%);
+}
+```
+
+### Fading both top and bottom edges
+You can use a single gradient with multiple color stops to fade both edges.
+
+```css
+.dual-fade-container {
+  /* Content is visible between 10% and 90% of the height */
+  -webkit-mask-image: linear-gradient(to bottom, transparent 0%, black 10%, black 90%, transparent 100%);
+  mask-image: linear-gradient(to bottom, transparent 0%, black 10%, black 90%, transparent 100%);
+}
+```
+
+## Fallback strategies
+Baseline status for Masks: Newly available. It's been Baseline since 2023-12-07.
+Supported by: Chrome 120 (Dec 2023), Edge 120 (Dec 2023), Firefox 53 (Apr 2017), and Safari 15.4 (Mar 2022).
+
+If a browser does not support `mask-image` or the prefixed version:
+- The content will not fade and will display with sharp edges.
+- Ensure the interface is still functional and content is readable without the fade (progressive enhancement).
+- You can use a semi-transparent overlay as a fallback, but be aware it requires knowing the background color and may interfere with text selection unless `pointer-events: none` is used.
+
+```css
+/* Fallback using an overlay for browsers that do not support masking */
+@supports (not (mask-image: linear-gradient(to bottom, black, transparent))) and (not (-webkit-mask-image: linear-gradient(to bottom, black, transparent))) {
+  .container {
+    position: relative;
+  }
+  
+  .container::after {
+    content: '';
+    position: absolute;
+    bottom: 0;
+    left: 0;
+    right: 0;
+    height: 20%;
+    /* Fallback assumes a solid background color (e.g., white) */
+    background: linear-gradient(to bottom, rgba(255,255,255,0), rgba(255,255,255,1));
+    pointer-events: none; /* Allow interaction with text underneath */
+  }
+}
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/stabilize-reactive-state.md

@@ -0,0 +1,72 @@
+# Stabilize Reactive State with Temporal
+
+While some reactive systems (like [React](https://react.dev/)) rely strictly on reference equality to detect state changes, others (like [Vue](https://vuejs.org/) and [Svelte](https://svelte.dev/)) can track mutations to plain objects. However, for built-in objects like the legacy `Date` object, internal mutations (like `setHours()`) do not change the object's reference and are generally not tracked by any framework's default reactivity system. This leads to missed UI updates and hard-to-debug side effects.
+
+The `Temporal` API solves this by providing immutable objects. Any operation that modifies a value (such as adding time or setting a field) returns a new instance with a new memory reference. This guarantees that state updates are always detected by reactive systems, ensuring UI stability.
+
+## How to Implement
+
+To stabilize reactive state using Temporal:
+
+1. **Use Temporal types for state:** Store `Temporal` objects (like `Temporal.PlainDateTime` or `Temporal.PlainDate`) in your reactive state instead of legacy `Date` objects.
+2. **Perform immutable updates:** When updating the state, use Temporal methods like `.add()`, `.subtract()`, or `.with()`. These methods return a new object.
+3. **Pass the new reference to the state setter:** Use the newly created Temporal object to update your component state, triggering a reliable re-render.
+
+## Example Code: Temporal vs Legacy Date in State
+
+```javascript
+// ❌ BAD: Mutating legacy Date breaks reactivity
+let dateState = { deadline: new Date() };
+
+function extendDeadlineBad() {
+  // Mutates the object in place. Reference remains the same!
+  dateState.deadline.setHours(dateState.deadline.getHours() + 1);
+
+  // Frameworks will skip re-rendering because
+  // prevState === nextState (same memory reference)
+  updateState(dateState);
+}
+
+// ✅ GOOD: Temporal ensures immutability and reliable reactivity
+let temporalState = { deadline: Temporal.Now.plainDateTimeISO() };
+
+function extendDeadlineGood() {
+  // Returns a new object with a new reference.
+  const newDeadline = temporalState.deadline.add({ hours: 1 });
+
+  // Create a new state object with the new Temporal reference
+  temporalState = { deadline: newDeadline };
+
+  // Frameworks will detect the reference change and re-render the UI
+  updateState(temporalState);
+}
+```
+
+## Strategic Implementation & Best Practices
+
+- **DO** use `Temporal` for any date/time values stored in reactive state to benefit from its immutability.
+- **DO** use the most specific Temporal type for your use case (e.g., `Temporal.PlainDate` if you only need the calendar date) to avoid unnecessary complexity.
+- **DO NOT** mutate `Date` objects in place when they are part of a component's state.
+- **DO** ensure you handle environments without native support by conditionally loading a polyfill.
+
+### Fallback strategies
+
+Temporal has limited availability.
+Supported by: Chrome 144 (Jan 2026), Edge 144 (Jan 2026), and Firefox 139 (May 2025).
+Unsupported in: Safari.
+
+Since the `Temporal` API is a newer feature and may not be supported in all browsers, you should feature-detect it and conditionally load a polyfill if needed.
+
+```html
+<!-- Conditionally load the Temporal polyfill only if not natively supported -->
+<script>
+  if (typeof Temporal === "undefined") {
+    try {
+      const module = await import("https://esm.sh/@js-temporal/polyfill");
+      globalThis.Temporal = module.Temporal;
+    } catch (e) {
+      console.error("Failed to load Temporal polyfill:", e);
+    }
+  }
+</script>
+```