@olives/devos 2.1.0

package/.agents/skills/modern-web-guidance/guides/user-experience/parallax-scroll-effects.md

@@ -0,0 +1,230 @@
+# Build a Parallax Effect on Scroll
+
+A parallax effect on scroll is a visual technique where different layers of content move at varying speeds as the user scrolls down a page. This creates an illusion of depth, with foreground elements appearing to move faster than the background elements, resulting in an engaging and immersive browsing experience. This effect is best achieved using CSS Scroll-Driven Animations, which allow you to link animations to the scroll position of a container.
+
+## How to implement
+
+Here’s how to create a basic parallax effect:
+
+1.  **Create a wrapper element:** This element simply groups all the layers of the parallax effect together. It is not the scrollable element, so its overflow should be clipped. Also give it a `height` that matches the height of one of the layers of the parallax effect.
+
+    ```html
+    <div class="wrapper">
+      …
+    </div>
+    ```
+
+    ```css
+    .wrapper {
+      overflow: clip;
+      height: 100vh; /* Height of one of the layers of the parallax */
+    }
+    ```
+
+2.  **Declare the layers:** Inside the wrapper, add the individual layers that will move at different speeds.
+
+    ```html
+    <div class="wrapper">
+      <div class="layer">LAYER 0</div>
+      <div class="layer">LAYER 1</div>
+      <div class="layer">LAYER 2</div>
+      …
+    </div>
+    ```
+
+3.  **Add a translate animation:** Define a CSS animation that changes the `transform` property of the layers. For a parallax effect, you'll typically use `translateY` to move the layers vertically.
+
+    ```css
+    @keyframes parallax {
+      from {
+        transform: translateY(700px);
+      }
+    }
+    ```
+
+4.  **Set up the `view-timeline`:** To link the animation to the scroll position, create a `view-timeline` on the wrapper element and then apply it to the layers.
+
+    ```css
+    .wrapper {
+      view-timeline: --wrapper;
+    }
+
+    .layer {
+      animation: parallax linear both;
+      animation-timeline: --wrapper;
+    }
+    ```
+
+5.  **Stagger the animations:** To make the layers move at different speeds, you can use one of two main approaches: **staggering in the keyframes**, or **staggering the `animation-range`**. 
+
+    Both of these approaches can use hardcoded values, or can use the `sibling-index()`/`sibling-count()` implementation. The hardcoded values are easiest and also useful when having only a limited amount of layers. The `sibling-index()`/`sibling-count()` implementation is handy when you have many layers.
+
+    *   **Staggering in the keyframes:**
+
+        Using **hardcoded values**, you can define a custom property for each layer to manually control its parallax offset.
+
+        ```css
+        .layer:nth-child(1) { --offset: 100px; }
+        .layer:nth-child(2) { --offset: 200px; }
+        .layer:nth-child(3) { --offset: 300px; }
+
+        @keyframes parallax {
+          from {
+            transform: translateY(var(--offset));
+          }
+        }
+        ```
+
+        Using **`sibling-index()`**, let the `sibling-index()` function return the index of a child element amongst its siblings to automatically calculate the staggered effect.
+
+        ```css
+        @keyframes parallax {
+          from {
+            transform: translateY(calc(100px * sibling-index()));
+          }
+        }
+        ```
+
+    *   **Staggering the `animation-range`:**
+
+        Using **hardcoded values**, you can explicitly define the boundaries of the `animation-range` on each layer individually.
+
+        ```css
+        .layer:nth-child(1) { animation-range: entry 25% exit 50%; }
+        .layer:nth-child(2) { animation-range: entry 25% exit 75%; }
+        .layer:nth-child(3) { animation-range: entry 25% exit 100%; }
+        ```
+
+        Using **`sibling-index()` and `sibling-count()`**, you can calculate the range mathematically based on the total number of layers (`sibling-count()`).
+
+        ```css
+        .layer {
+          animation-range: entry 25% exit calc(100% / sibling-count() * sibling-index());
+        }
+        ```
+
+## Example code
+
+```css
+@keyframes parallax {
+  from {
+    transform: translateY(calc(100px * sibling-index()));
+  }
+}
+
+.wrapper {
+  view-timeline: --wrapper;
+}
+
+.layer {
+  animation: parallax linear both;
+  animation-timeline: --wrapper;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .layer {
+    animation: none;
+  }
+}
+```
+
+Alternatively, you can use the `animation-range` property to achieve a similar effect:
+
+```css
+@keyframes parallax {
+  from {
+    transform: translateY(700px);
+  }
+}
+
+.wrapper {
+  view-timeline: --wrapper;
+}
+
+.layer {
+  animation: parallax linear both;
+  animation-timeline: --wrapper;
+  animation-range: entry 25% exit calc(100% / sibling-count() * sibling-index());
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .layer {
+    animation: none;
+  }
+}
+```
+
+## 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: view()) and (animation-range: entry))` to check for support and provide a fallback for browsers that don't support it.
+  - The `(animation-range: entry)` 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.
+
+As for setting the `animation-range`:
+
+- **DO** give all layers the same start offset, e.g. `entry 25%`
+- **DO** give all layers a different end offset that uses `sibling-count()` and `sibling-index()` to distribute the offsets, e.g. `exit calc(100% / sibling-count() * sibling-index())`.
+
+
+## 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 an `IntersectionObserver` to track the visibility of the `.wrapper` element and updates the `transform` property of the layers based on the scroll position.
+
+```js
+// Fallback for browsers that don't support scroll-driven animations
+if (!CSS.supports('(animation-timeline: view()) and (animation-range: entry)')) {
+  const wrapper = document.querySelector('.wrapper');
+  const layers = document.querySelectorAll('.layer');
+
+  const observer = new IntersectionObserver((entries) => {
+    entries.forEach(entry => {
+      if (entry.isIntersecting) {
+        window.addEventListener('scroll', onScroll);
+      } else {
+        window.removeEventListener('scroll', onScroll);
+      }
+    });
+  }, { threshold: 0 });
+
+  observer.observe(wrapper);
+
+  function onScroll() {
+    const scrollY = window.scrollY;
+    const wrapperRect = wrapper.getBoundingClientRect();
+    const wrapperTop = wrapperRect.top + scrollY;
+    const wrapperHeight = wrapperRect.height;
+    const windowHeight = window.innerHeight;
+
+    if (scrollY >= wrapperTop - windowHeight && scrollY <= wrapperTop + wrapperHeight) {
+      const scrollPercent = (scrollY - (wrapperTop - windowHeight)) / (wrapperHeight + windowHeight);
+      
+      layers.forEach((layer, index) => {
+        // This matches the effect as defined in the CSS example above.
+        // Customize this further if needed.
+        const initialTranslateY = 100 * index;
+        const translateY = initialTranslateY * (1 - scrollPercent);
+        layer.style.transform = `translateY(${translateY}px)`;
+      });
+    }
+  }
+
+  // Trigger onScroll once to set initial positions
+  onScroll();
+}
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/persistent-app-tours.md

@@ -0,0 +1,112 @@
+# Creating Persistent App Tours
+
+Onboarding tours require overlays that persist while users interact with the highlighted features. Unlike auto popovers, manual popovers do not close when the user clicks elsewhere on the page. Combining `popover="manual"` with CSS Anchor Positioning allows you to create non-modal, tethered tour steps.
+
+### Recommended Implementation
+
+#### HTML
+```html
+<div id="feature-target">Highlight this feature</div>
+
+<!-- MANDATORY: Enforce overlay dialog semantics and accessible name bindings -->
+<div id="tour-step" popover="manual" role="dialog" aria-labelledby="tour-title">
+  <!-- Assume an <h1> precedes this element in the full document outline -->
+  <h2 id="tour-title">Step 1</h2>
+  <p>Learn how to use this feature.</p>
+  <button popovertarget="tour-step" popovertargetaction="hide">Got it</button>
+</div>
+```
+
+#### CSS
+```css
+#feature-target {
+  anchor-name: --feature-target;
+}
+
+#tour-step {
+  popover: manual;
+  position-anchor: --feature-target;
+  position-area: right center;
+  inset: auto;
+  margin: 1rem;
+  padding: 1rem;
+  border: 1px solid blue;
+  border-radius: 0.5rem;
+  background: aliceblue;
+}
+```
+
+#### JavaScript
+```javascript
+const tourStep = document.getElementById('tour-step');
+tourStep.showPopover();
+// MANDATORY: Programmatically route focus into the non-modal popover so keyboard/assistive technology users immediately perceive the new context
+tourStep.querySelector('button').focus();
+```
+
+### Implementation Guidelines
+
+* **MANDATORY:** Use `popover="manual"` to prevent the tour step from closing accidentally during user interaction.
+* **MANDATORY:** Mark the container with `role="dialog"` and link its heading via `aria-labelledby`.
+* **MANDATORY:** Shift programmatic focus inside the popover immediately after opening to prevent focus abandonment.
+* **DO** use CSS Anchor Positioning to tether the tour step to the specific feature being explained.
+* **DO** provide an explicit "Close" or "Next" button within the popover that uses `popovertargetaction="hide"`.
+
+### Fallback strategies
+
+Baseline status for Popover: Newly available. It's been Baseline since 2025-01-27.
+Supported by: Chrome 116 (Aug 2023), Edge 116 (Aug 2023), Firefox 125 (Apr 2024), Safari 17 (Sep 2023), and Safari iOS 18.3 (Jan 2025).
+
+If the browser does not support Popover, use the `@oddbird/popover-polyfill`:
+
+```html
+<script type="module">
+  if (!HTMLElement.prototype.hasOwnProperty('popover')) {
+    await import('https://unpkg.com/@oddbird/popover-polyfill');
+  }
+</script>
+```
+
+Alternatively, for legacy support without a polyfill, use `position: fixed` and manually calculate coordinates via JavaScript `getBoundingClientRect()`.
+
+#### anchor-positioning
+
+Anchor positioning is not natively supported by any major browser yet.
+
+To support browsers without anchor positioning, you can choose between using a polyfill or a pure CSS fallback.
+
+##### Option 1: Polyfill Fallback
+The `@oddbird/css-anchor-positioning` polyfill can be used to emulate anchor positioning. It does not support implicit anchors, so you MUST add explicit anchor names to the trigger. Additionally, `position-area` is not supported on popovers by the polyfill, so you MUST use `anchor()` on the desired insets instead of `position-area`.
+
+```html
+<script type="module">
+  if (!CSS.supports('anchor-name: --foo')) {
+    await import("https://unpkg.com/@oddbird/css-anchor-positioning");
+  }
+</script>
+```
+
+```css
+#tour-step {
+  /* If using the anchor positioning polyfill with a popover, DO use `anchor()` functions instead of `position-area`. */
+  left: anchor(right);
+  top: anchor(top);
+}
+```
+
+##### Option 2: Non-Polyfill CSS Fallback
+If you prefer not to use a polyfill, you can default the tooltip to a fixed position at the bottom of the viewport using `@supports not`.
+
+```css
+@supports not (anchor-name: --foo) {
+  #tour-step {
+    position: fixed;
+    bottom: 0;
+    left: 0;
+    right: 0;
+    width: 100%;
+    margin: 0;
+    border-radius: 0;
+  }
+}
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/persistent-toast-notifications.md

@@ -0,0 +1,30 @@
+# Creating Toast Notifications
+
+Toast notifications are transient status messages. Unlike menus, they should not close when a user interacts with other parts of the page. The popover="manual" state is ideal because it lacks "light-dismiss" behavior and allows multiple notifications to coexist.
+
+### Implementation Guidelines
+
+* **MANDATORY:** Use popover="manual" so the notification stays visible until explicitly closed or timed out by a script.
+* **DO** use a container to manage the stacking of multiple toasts. Since popovers in the Top Layer ignore parent z-index, you must position them individually or within a common layout group.
+* **DO** use sibling-index() to add margin between toast notifications so that items lower in the stack are visible.
+* **DO** provide an explicit "Close" button within the toast using popovertargetaction="hide".
+* **DO** use JavaScript for auto-dismissal timers (e.g., calling hidePopover() after 3000ms).
+* **DO** utilize transition-behavior: allow-discrete to animate the entry and exit from the Top Layer.
+
+### Fallback Strategies
+
+#### popover
+
+* **Guidance:** Use the [Popover Polyfill](https://github.com/oddbird/popover-polyfill). For legacy browsers, fall back to a fixed-position div with a high z-index.
+
+#### sibling-index()
+
+* **Guidance:** If sibling-index() is not supported, use the `+` operator to add margin manually. I.e. `popover + popover { margin-top: 1rem }`
+
+#### anchor-positioning
+
+* **Guidance:** Use the [CSS Anchor Positioning Polyfill](https://github.com/oddbird/css-anchor-positioning). For a non-polyfill fallback, default the tooltip to a fixed position at the bottom of the viewport using `@supports not (anchor-name: --foo)`.
+
+#### transition-behavior
+
+* **Guidance:** If transition-behavior is not supported, use JavaScript to add animation via classes as the toast element transitions in and out.

package/.agents/skills/modern-web-guidance/guides/user-experience/persistent-top-layer-ui.md

@@ -0,0 +1,48 @@
+When moving an open `<dialog>`, `popover`, or fullscreen element in the DOM using traditional methods like `appendChild()` or `insertBefore()`, the browser implicitly removes the element from the DOM and re-inserts it. This removal resets the state, causing open modals, popovers, and fullscreen elements to close abruptly.
+
+To reparent top-layer elements without interrupting the user experience or closing them, use the atomic `moveBefore()` API instead.
+
+### Reparenting open top-layer elements
+
+`moveBefore()` takes two arguments: the node to move, and a reference node to insert before (or `null` to append to the end of the new parent).
+
+```javascript
+const newParent = document.getElementById('new-container');
+const dialogElement = document.getElementById('my-dialog');
+
+// MANDATORY: Use moveBefore to ensure the <dialog> or popover stays open.
+// Passing null appends it to the end of newParent.
+newParent.moveBefore(dialogElement, null);
+```
+
+### Fallback strategies
+
+moveBefore() has limited availability.
+Supported by: Chrome 133 (Feb 2025), Edge 133 (Feb 2025), and Firefox 144 (Oct 2025).
+Unsupported in: Safari.
+
+Since `moveBefore()` is a progressive enhancement, you MUST use feature detection before calling it. For older browsers, you will have to fallback to traditional reparenting.
+
+**MANDATORY**: For `<dialog>` elements in unsupported browsers, the traditional move will close the dialog. If you need it to remain open, you must manually re-open it after the move.
+
+```javascript
+const targetParent = document.getElementById('target-container');
+const popoverOrDialog = document.getElementById('my-top-layer-element');
+
+// Check if moveBefore is supported
+if ('moveBefore' in Element.prototype) {
+  targetParent.moveBefore(popoverOrDialog, null);
+} else {
+  // Fallback: traditional move.
+  // Note: This WILL close <dialog>, popover, and fullscreen elements.
+  const wasOpen = popoverOrDialog.hasAttribute('open') || popoverOrDialog.matches(':popover-open');
+  targetParent.insertBefore(popoverOrDialog, null);
+  
+  // Manually restore state if possible
+  if (wasOpen && typeof popoverOrDialog.showModal === 'function') {
+    popoverOrDialog.showModal();
+  } else if (wasOpen && typeof popoverOrDialog.showPopover === 'function') {
+    popoverOrDialog.showPopover();
+  }
+}
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/physics-based-easing.md

@@ -0,0 +1,118 @@
+Traditional CSS easing functions like `ease-in` or `cubic-bezier()` are limited to simple curves, making it impossible to create complex physics-based effects like bounces or springs. The `linear()` timing function solves this by allowing you to provide a series of stops that can approximate complex curves. Transitions and animations are interpolated based on straight lines between the stops, but within enough stops, it can appear smooth.
+
+### Implementation Steps
+
+1.  **Generate the curve stops:**
+    Manually plotting dozens of points for a spring or bounce is impractical. Use a timing function from an external library, or use a  tool to convert an existing JavaScript easing function or an SVG path into the `linear()` syntax. Optional: store these timing functions as CSS custom properties for reuse throughout your site.
+2.  **Define the timing function:**
+    Apply the generated stops to the `transition-timing-function` or `animation-timing-function` property, or through the `transition` or `animation` shorthands.
+3.  **Adjust the duration:**
+    Unlike JavaScript physics engines where duration is derived from physical properties (mass, stiffness), CSS still requires a fixed `duration`. You may need to adjust the duration to get the intended effect.
+
+### Example: Spring Easing
+
+This example shows how to use a custom `linear()` function to create a spring effect that overshoots the target value before settling.
+
+```css
+.spring {
+  /* Define the physics-based easing as a reusable variable */
+  --spring-easing: linear(0, 0.016 0.5%, 0.06 1%, 0.226 2%, 1.116 5.4%, 1.375 6.6%, 1.527 7.7%, 1.565 8.2%, 1.585 8.8%, 1.581 9.3%, 1.559 9.8%, 1.458 10.9%, 0.937 14.3%, 0.784 15.5%, 0.693 16.6%, 0.67 17.1%, 0.657 17.7%, 0.671 18.7%, 0.729 19.8%, 1.042 23.3%, 1.13 24.5%, 1.182 25.6%, 1.201 26.7%, 1.192 27.7%, 1.156 28.8%, 0.977 32.2%, 0.925 33.4%, 0.894 34.5%, 0.882 35.6%, 0.887 36.6%, 0.907 37.7%, 1.045 42.4%, 1.069 44.5%, 1.059 46.3%, 0.979 50.9%, 0.96 53.4%, 0.966 55.3%, 1.013 59.9%, 1.024 62.3%, 0.986 71.2%, 1.008 79.9%, 0.995 88.9%, 1);
+
+
+  /* Apply the easing with a duration that fits the spring's complexity */
+  /* MANDATORY: Always include a duration; linear() does not calculate it automatically */
+  transition: scale 0.8s var(--spring-easing);
+}
+
+.spring:hover {
+  scale: 1.2;
+}
+```
+### Example: Bounce Easing
+
+This example shows how to use a custom `linear()` function to create a bounce effect.
+
+```css
+.bounce {
+  /* Define the physics-based easing as a reusable variable */
+  --bounce-easing: linear(0, 0.214 14.7%, 0.386 23.7%, 0.598 31.9%, 0.999 44.7%, 0.807 52.6%, 0.762 56%, 0.747 59.4%, 0.758 62.4%, 0.793 65.6%, 0.999 77.4%, 0.961 81.2%, 0.949 84.8%, 0.956 88%, 0.993 95.5%, 1);
+
+
+  /* Apply the easing with a duration that fits the bounce's complexity */
+  /* MANDATORY: Always include a duration; linear() does not calculate it automatically */
+  transition: scale 0.4s var(--bounce-easing);
+}
+
+.bounce:hover {
+  scale: 1.2;
+}
+```
+
+### Key Considerations
+
+*   **Performance:** For the smoothest physics-based animations, apply `linear()` to properties that run on a separate thread, such as `transform` and `opacity`.
+*   **Precision vs. Payload:** While more stops result in a smoother curve, they also increase the size of your CSS. Most generators allow you to "simplify" the curve to find the optimal balance between smoothness and code size.
+*   **Avoid Opacity for Bounces:** Applying bounce easings to `opacity` can cause visually jarring flickering if the value overshoots below 0 or above 1.
+*   **Accessibility:** Complex physics-based animations can be distracting or cause motion sensitivity for some users. Always respect user preferences by reducing or disabling these animations.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .element {
+    transition: none;
+  }
+}
+```
+
+### Fallback strategies
+
+Baseline status for linear() easing: Newly available. It's been Baseline since 2023-12-11.
+Supported by: Chrome 113 (May 2023), Edge 113 (May 2023), Firefox 112 (Apr 2023), and Safari 17.2 (Dec 2023).
+
+#### CSS Fallback
+For browsers that do not support `linear()`, provide a standard easing function as a fallback. The browser will ignore the `linear()` value if it doesn't recognize it, falling back to the previous valid declaration.
+
+```css
+.element {
+  /* Fallback for older browsers (standard smooth exit) */
+  transition: transform 0.8s ease-out;
+  
+  /* Modern browsers will override with the physics-based easing */
+  transition-timing-function: linear(0, 1.1, 0.95, 1.02, 1);
+}
+```
+
+#### JavaScript Library Fallback (Motion/GSAP)
+
+Optional: If a high-fidelity physics animation is critical even in older browsers, use a JavaScript library like **Motion** (motion.dev) or **GSAP** (greensock.com) to handle the animation when `linear()` is unsupported.
+
+1.  **Detect support:** Use `CSS.supports()` to check if the browser handles the `linear()` function.
+2.  **Conditionally load/apply:** If unsupported, use the library's spring or bounce implementation.
+
+```javascript
+/* Detect if the browser supports the linear() function */
+const supportsLinearEasing = window.CSS && CSS.supports('animation-timing-function', 'linear(0, 1)');
+
+if (!supportsLinearEasing) {
+  /* 
+     Example using Motion (motion.dev) for a spring fallback.
+     This should only be initialized if native CSS support is missing.
+  */
+  import("https://cdn.jsdelivr.net/npm/motion@latest/dist/motion.js").then(({ animate, spring }) => {
+    animate(".element", { transform: "scale(1.2)" }, {
+      easing: spring({ stiffness: 100, damping: 10 })
+    });
+  });
+}
+```
+
+You can also use `@supports` in CSS for more explicit feature detection:
+
+```css
+@supports not (animation-timing-function: linear(0, 1)) {
+  .element {
+    /* Alternative experience for unsupported browsers */
+    transition-duration: 0.4s;
+    transition-timing-function: cubic-bezier(0.34, 1.56, 0.64, 1);
+  }
+}
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/platform-controls-dismiss-dialog.md

@@ -0,0 +1,38 @@
+When a modal dialog is open, users expect to use familiar controls to dismiss them: pressing the <kbd>Esc</kbd> key on a keyboard, using the back button or gesture on mobile platforms, or a dismiss gesture with assistive technologies.
+
+When the `<dialog>` element was first introduced, it could be dismissed with the <kbd>Esc</kbd> key, but not other platform controls such as a back button/gesture on mobile. With the addition of the `closedby` attribute for `<dialog>` elements, the extended behavior of responding to more platform-specific controls for close requests has been applied for `<dialog>` elements that are opened in a modal state (i.e. when opened imperatively with the `<dialog>` element’s `showModal()` method in JavaScript or declaratively with the `show-modal` invoker command). So, there is no specific change developers need to make if they are already using the `<dialog>` element.
+
+```html
+<!-- MANDATORY: must be opened with either `showModal()` with JavaScript or the `show-modal` command using declarative command invokers in order respond to close requests including platform-specific controls. -->
+<dialog aria-labelledby="example">
+  <h1 id="example">Example</h1>
+  <p>Modal that can be dismissed with close requests.</p>
+</dialog>
+```
+
+When opened in a modal state, a dialog without the `closedby` attribute responds to close requests the same as explicitly setting the `closedby` attribute to `closerequest`.
+
+```html
+<!-- This is unnecessary as it is the default behavior for modal dialogs -->
+<dialog closedby="closerequest" aria-labelledby="example">
+  <h1 id="example">Example</h1>
+  <p>Modal that can be dismissed with close requests.</p>
+</dialog>
+```
+
+If you also want “light dismiss” behavior, then you must set `closedby` to `any`:
+
+```html
+<dialog closedby="any" aria-labelledby="example">
+  <h1 id="example">Example</h1>
+  <p>Modal that can be dismissed with close requests and light dismiss.</p>
+</dialog>
+```
+
+## Fallback strategies
+
+<dialog closedby> has limited availability.
+Supported by: Chrome 134 (Mar 2025), Edge 134 (Mar 2025), and Firefox 141 (Jul 2025).
+Unsupported in: Safari.
+
+`<dialog>` elements opened in a modal state can already be dismissed with <kbd>Esc</kbd>, so there is no fallback necessary. There is no good way to implement close requests from mobile back button/gestures, so it is simpler to embrace this feature as a progressive enhancement, especially given that there are other inclusive means to dismiss the modal dialog. Similarly, light dismiss behavior for a `<dialog>` element using `closedby="any"` can be considered a progressive enhancement.