@olives/devos 2.1.0

package/.agents/skills/modern-web-guidance/guides/user-experience/navigation-drawer.md

@@ -0,0 +1,357 @@
+## Overview
+
+A navigation drawer is a panel that slides in from the edge of the viewport over the page content, dimming everything behind it. It is opened from a trigger button and dismissed by swiping the panel off-screen, tapping the dimmed backdrop, or pressing Escape.
+
+This guide implements the drawer as:
+
+- A `popover="manual"` element promoted to the top layer so the panel and its `::backdrop` overlay every other element on the page, regardless of stacking context.
+- A horizontally scrolling container with two CSS scroll-snap stops — one for "open", one for "closed" — so the swipe gesture is handled natively by the browser. This delivers momentum, velocity, and interruption tracking for free, with no JavaScript pointer-event code.
+- A scroll-driven animation that ties the backdrop's opacity to the scroll position, so the dim fades in and out smoothly as the user drags the panel.
+- An `IntersectionObserver` on the panel that detects when it has fully entered or fully left the viewport, and uses those moments to update focus, `aria-expanded`, and `inert`.
+
+This approach is preferred over JavaScript-driven `transform` animations because the scroll mechanism gives the user direct control of the panel's position (their finger drives it, not a tween) and it much more closely matches the interaction patterns that users are accustomed to in native mobile apps.
+
+## Implementation
+
+### 1. Markup
+
+The drawer is a single popover containing a horizontal scroller, which contains the visible "sheet". The trigger button lives in the page content.
+
+```html
+<!-- popover="manual" is REQUIRED. Do not use popover="auto" or "hint". -->
+<div class="Drawer" id="drawer" popover="manual">
+  <div class="Drawer-scroller">
+    <nav class="Drawer-sheet" tabindex="-1">
+      <!-- tabindex="-1" makes the sheet programmatically focusable so we
+           can move focus into it when the drawer opens, without adding it
+           to the natural tab order. -->
+      <ul>
+        <li><a href="/page-1">Page 1</a></li>
+        <li><a href="/page-2">Page 2</a></li>
+        <!-- ... -->
+      </ul>
+    </nav>
+  </div>
+</div>
+
+<main>
+  <header>
+    <!-- aria-controls links the trigger to the drawer; aria-expanded
+         reflects the current state for assistive tech. -->
+    <button id="drawer-open"
+            aria-label="Menu"
+            aria-expanded="false"
+            aria-controls="drawer">
+      <!-- MANDATORY: Inline decorative SVGs MUST define aria-hidden="true" -->
+      <svg aria-hidden="true" viewBox="0 0 24 24">...</svg>
+    </button>
+  </header>
+  <!-- Page content. -->
+</main>
+```
+
+### 2. Styles
+
+#### Reset the popover and fill the viewport
+
+The popover must cover the whole viewport so its `::backdrop` dims the entire page and the swipe surface extends edge-to-edge. The default user-agent popover styles (centered, auto-sized, bordered) get in the way and must be reset.
+
+```css
+.Drawer {
+  /* min() caps the sheet width on large screens but on a phone leaves
+     a 20% peek of page content visible, which is the affordance that
+     tells the user they can tap outside to dismiss. */
+  --drawer-width: min(20em, 80dvw);
+
+  /* Custom property driven by the scroll-driven animation below.
+     0 = drawer fully closed (transparent backdrop).
+     1 = drawer fully open (visible backdrop). */
+  --drawer-backdrop: 0;
+
+  /* Reset UA popover style that would constrain the element. */
+  width: auto;
+  height: auto;
+  background: transparent;
+  border: 0;
+  overflow: visible;
+}
+
+/* Style the popover's ::backdrop to achive the overlay effect and
+   provide visual affordances indicating that the rest of the page is inert */
+.Drawer::backdrop {
+  background: #000;
+  /* Use calc() to limit the opacity range so the content beneath is visible */
+  opacity: calc(var(--drawer-backdrop) / 2);
+}
+```
+
+#### Build the swipe surface with scroll snap
+
+The scroller is a horizontal grid wider than the viewport: column 1 holds the sheet (width `--drawer-width`), column 2 is an empty pseudo-element spacer the width of the viewport. Snapping between the two columns is what opens and closes the drawer.
+
+```css
+.Drawer-scroller {
+  position: relative;
+  display: grid;
+  /* Sheet on the left, full-viewport spacer on the right. The user
+     scrolls between the two snap stops to open and close. */
+  grid-template-columns: var(--drawer-width) 100%;
+
+  overflow-x: scroll;
+  /* Stop the swipe from chaining into the page's vertical scroll
+     when the user reaches either snap edge. */
+  overscroll-behavior: none;
+  scrollbar-width: none;
+  /* `mandatory` guarantees the drawer always settles fully open or
+     fully closed — never half-open after a partial swipe. */
+  scroll-snap-type: x mandatory;
+}
+
+/* Enable smooth scrolling natively, but only if the user has not
+   requested reduced motion. */
+@media (prefers-reduced-motion: no-preference) {
+  .Drawer-scroller {
+    scroll-behavior: smooth;
+  }
+}
+
+/* The empty spacer that creates the "closed" snap stop. */
+.Drawer-scroller::after {
+  content: '';
+  scroll-snap-align: end;
+  /* Open the popover already scrolled to this stop (drawer off-screen),
+     so the JS only needs to scroll to the open position to
+     animate it in. */
+  scroll-initial-target: nearest;
+}
+
+.Drawer-sheet {
+  display: grid;
+  grid-template-rows: auto 1fr;
+  /* Use `svh` (small viewport height) — not `vh` or `dvh` — so the
+     sheet height does not jump when the iOS Safari address bar
+     resizes mid-swipe. */
+  height: 100svh;
+
+  background: #333;
+  color: #fff;
+  overflow-y: auto;
+  scroll-snap-align: start;
+  scrollbar-width: none;
+}
+```
+
+#### Tie the backdrop opacity to the scroll position
+
+A scroll-driven animation maps `--drawer-backdrop` from 1 (open) to 0 (closed) across the scroller's range, so the backdrop fades in and out perfectly synced with the drag.
+
+```css
+/* MANDATORY: Wrap this entire block in @supports. Browsers that don't
+   support animation-timeline still parse the @keyframes and would
+   apply the animation's `0%` value (--drawer-backdrop: 1) at all
+   times, leaving the backdrop permanently opaque. The @supports gate
+   ensures the animation is only registered where it actually works. */
+@supports (animation-timeline: scroll()) {
+  .Drawer {
+    /* timeline-scope lets .Drawer reference a scroll-timeline that
+       is defined on its descendant (the scroller). Without this, the
+       timeline name is not visible to the .Drawer element. */
+    timeline-scope: --drawer-fade;
+    animation: fade-drawer-backdrop linear both;
+    animation-timeline: --drawer-fade;
+  }
+
+  .Drawer-scroller {
+    /* The horizontal scroll position of this element drives the
+       timeline named `--drawer-fade`. */
+    scroll-timeline: --drawer-fade x;
+  }
+
+  /* @property is REQUIRED. Without registering --drawer-backdrop with
+     a `<number>` syntax, the browser treats it as a string and cannot
+     interpolate it — the backdrop would jump from 0 to 1 with no
+     fade. */
+  @property --drawer-backdrop {
+    syntax: '<number>';
+    inherits: true;
+    initial-value: 0;
+  }
+
+  @keyframes fade-drawer-backdrop {
+    /* Scroll position 0 = drawer fully open = backdrop visible. */
+    0% { --drawer-backdrop: 1 }
+    /* Scroll position 100% = drawer fully closed = backdrop hidden. */
+    100% { --drawer-backdrop: 0 }
+  }
+}
+```
+
+### 3. Open and close the drawer
+
+Opening is two steps: promote the popover to the top layer, then scroll the sheet into view. Closing is one step: scroll back to the spacer; an observer (step 4) hides the popover once the sheet is fully off-screen.
+
+```js
+const drawer = document.getElementById('drawer');
+const openBtn = document.getElementById('drawer-open');
+const scroller = drawer.querySelector('.Drawer-scroller');
+const sheet = drawer.querySelector('.Drawer-sheet');
+
+function openDrawer() {
+  // Show the popover first so the element is in the top layer before
+  // we trigger any scrolling. `scroll-initial-target` (set on the
+  // ::after spacer) places the initial scroll position at the closed
+  // stop, so the drawer enters the top layer already off-screen.
+  drawer.showPopover();
+
+  // Scroll the sheet into view. The `behavior: 'auto'` option defers
+  // to the CSS `scroll-behavior` property, which will be smooth unless
+  // the user prefers reduced motion. Snap takes over at the end and
+  // locks the drawer fully open.
+  scroller.scrollTo({left: 0, behavior: 'auto'});
+}
+
+function closeDrawer() {
+  // Scroll back to the spacer. Do NOT call hidePopover() here —
+  // doing so would remove the element from the top layer mid-animation
+  // and the close animation would not be visible. The
+  // IntersectionObserver in step 4 hides the popover once the sheet
+  // has actually left the viewport.
+  scroller.scrollTo({left: scroller.offsetWidth, behavior: 'auto'});
+}
+```
+
+### 4. Detect open and closed state
+
+Use an `IntersectionObserver` on the sheet — not the scroll position — as the source of truth for the drawer's state. The observer fires regardless of how the sheet moved (user swipe, programmatic scroll, snap settle), so all dismissal paths converge in the same callback.
+
+```js
+function onDrawerOpened() {
+  // Mark the rest of the page inert so keyboard and screen-reader
+  // users cannot tab into content hidden behind the drawer.
+  document.querySelector('main').inert = true;
+  openBtn.setAttribute('aria-expanded', 'true');
+  // Move focus into the drawer for keyboard users.
+  sheet.focus();
+}
+
+function onDrawerClosed() {
+  // Hide the popover only after the close animation completes,
+  // so the slide-out is visible to the user.
+  drawer.hidePopover();
+  document.querySelector('main').inert = false;
+  openBtn.setAttribute('aria-expanded', 'false');
+}
+
+// Treat "any pixel of the sheet visible inside the popover root" as
+// "open enough to count as not closed". This threshold is intentionally
+// tiny so the closed callback only fires once the sheet is truly gone.
+const visibleThreshold = 1 / window.innerWidth;
+
+const observer = new IntersectionObserver(
+  (entries) => {
+    // During programmatic scrolling the observer can deliver multiple
+    // entries in one batch. Only the most recent describes the
+    // current state; earlier entries are intermediate positions.
+    const entry = entries.at(-1);
+    if (entry.intersectionRatio < visibleThreshold) onDrawerClosed();
+    if (entry.intersectionRatio === 1) onDrawerOpened();
+  },
+  // root: drawer makes the popover element the intersection root,
+  // so the ratio reflects the sheet's visibility within the popover
+  // (i.e. how much of it has been swiped on-screen).
+  {root: drawer, threshold: [visibleThreshold, 1]},
+);
+observer.observe(sheet);
+```
+
+### 5. Wire up the trigger and dismissal handlers
+
+```js
+// Open trigger.
+openBtn.addEventListener('click', openDrawer);
+
+// Light-dismiss: a tap on the dimmed area (anywhere inside the
+// popover but outside the sheet) closes the drawer. We implement
+// this manually because popover="manual" disables the browser's
+// built-in light-dismiss (which would also fire mid-swipe — see step 1).
+drawer.addEventListener('click', (event) => {
+  if (!sheet.contains(event.target)) closeDrawer();
+});
+
+// Escape key. Listen on document because focus may be inside the
+// drawer when the user presses Escape.
+document.addEventListener('keydown', (event) => {
+  if (event.key === 'Escape') closeDrawer();
+});
+```
+
+### 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).
+
+The drawer's core mechanics — scroll snap, `IntersectionObserver`, and `inert` — are all Baseline Widely available and required for the component to function. The popover API, the scroll-driven animation that fades the backdrop, and `scroll-initial-target` are progressive enhancements with simple fallbacks that can be easily implemented if wide browser support is required.
+
+#### Backdrop fade fallback (no `animation-timeline` support):
+
+Scroll-driven animations has limited availability.
+Supported by: Chrome 115 (Jul 2023), Edge 115 (Jul 2023), and Safari 26 (Sep 2025).
+Unsupported in: Firefox.
+
+Detect with `CSS.supports('animation-timeline: scroll()')` and write `--drawer-backdrop` from a `scroll` event listener if not supported. The CSS `@supports` block in step 2 ensures the keyframes never apply in unsupported browsers, so the JavaScript value is the only writer.
+
+```js
+if (!CSS.supports('animation-timeline: scroll()')) {
+  scroller.addEventListener('scroll', () => {
+    // Same mapping as the @keyframes: 0 scroll = 1 (open),
+    // sheet-width scroll = 0 (closed).
+    const ratio = 1 - scroller.scrollLeft / sheet.offsetWidth;
+    drawer.style.setProperty('--drawer-backdrop', ratio);
+  });
+}
+```
+
+#### Initial scroll position fallback (no `scroll-initial-target` support):
+
+scroll-initial-target has limited availability.
+Supported by: Chrome 133 (Feb 2025) and Edge 133 (Feb 2025).
+Unsupported in: Firefox and Safari.
+
+Detect with `CSS.supports('scroll-initial-target', 'nearest')` and inside `openDrawer()`, jump-scroll the scroller to the closed position immediately after `showPopover()`. Without this, the drawer would appear instantly in the open position with no slide-in animation.
+
+```js
+async function openDrawer() {
+  drawer.showPopover();
+
+  if (!CSS.supports('scroll-initial-target', 'nearest')) {
+    // Jump-scroll to the closed stop so the scroll below
+    // animates the drawer in from off-screen.
+    scroller.scrollTo({left: scroller.offsetWidth, behavior: 'instant'});
+    // Wait two animation frames for the jump-scroll to commit.
+    // A single rAF is not enough — the second `scrollTo` would
+    // cancel the first before the browser has a chance to apply it.
+    await new Promise((r) =>
+      requestAnimationFrame(() => requestAnimationFrame(r))
+    );
+  }
+
+  scroller.scrollTo({left: 0, behavior: 'auto'});
+}
+```
+
+#### `@property` fallback (no registered custom properties):
+
+Baseline status for Registered custom properties: Newly available. It's been Baseline since 2024-07-09.
+Supported by: Chrome 85 (Aug 2020), Edge 85 (Aug 2020), Firefox 128 (Jul 2024), and Safari 16.4 (Mar 2023).
+
+`@property` is only needed because the scroll-driven animation interpolates `--drawer-backdrop` between keyframes — without registration, the property would be treated as a string and would jump between 0 and 1 with no fade. If the scroll-driven animation fallback above is in place, that JavaScript writes a fresh numeric string to `--drawer-backdrop` on every scroll frame and never interpolates, so no seprarate `@property` fallback is needed since all browsers that support scroll-driven animations also support `@property`.
+
+
+#### Popover API fallback (no `popover` attribute support):
+
+Baseline status for the api.HTMLElement.showPopover capability: Newly available. It's been Baseline since 2024-04-16.
+Supported by: Chrome 114 (May 2023), Edge 114 (Jun 2023), Firefox 125 (Apr 2024), and Safari 17 (Sep 2023).
+
+Because this component uses `popover="manual"` and implements dismissal entirely from JavaScript, it does not depend on the popover API's defining behaviors — light-dismiss, the `popovertarget` attribute, top-layer-managed Escape handling, or focus management. The only popover features it actually uses are top-layer promotion (via `showPopover()`) and the `::backdrop` pseudo-element, which have been Baseline since April 2024.
+
+If wider browser support is needed, do not branch on feature detection — simply do not use popover at all. Drop the `popover="manual"` attribute, replace top-layer promotion with `position: fixed` and a high `z-index`, replace `::backdrop` with a sibling element styled identically (using the same `--drawer-backdrop` custom property), and toggle visibility from a class instead of `showPopover()`/`hidePopover()`. The rest of the component (scroll snap, the scroll-driven backdrop animation, the `IntersectionObserver`, and the dismissal handlers) is unchanged.

package/.agents/skills/modern-web-guidance/guides/user-experience/overflow-clipping-control.md

@@ -0,0 +1,180 @@
+# Overflow Clipping Control
+
+While `overflow: hidden` is a "blunt instrument" that almost always clips content strictly at the padding-box, `overflow: clip` combined with `overflow-clip-margin` provides the "scalpel" for fine-grained layout control across block containers.
+
+Specify exactly where clipping occurs with `overflow: clip` and `overflow-clip-margin`. You can align the boundary precisely with inner box-model edges or extend the clipping boundary beyond the element's box by a specified offset (a safety margin). This modern approach is highly performant and eliminates the legacy requirement of adding extra wrapper containers with custom padding and negative margins just to let visual effects (like prominent child element shadows) render unclipped.
+
+Replaced elements (`<img>`, `<video>`, `<canvas>`, etc.) default to `overflow: clip` and `overflow-clip-margin: content-box`, giving you control to cleanly contain images that use `object-fit` or `border-radius`. 
+
+## How to Implement
+
+1. **Apply `overflow: clip`**: Ensure the target element has `overflow: clip` enabled. Setting `overflow: clip` is **mandatory** on block layout containers for `overflow-clip-margin` to take effect. If `overflow` is set to `hidden`, `auto`, or `scroll`, the `overflow-clip-margin` property is ignored by the browser. `overflow: clip` prevents all scrolling (both user-initiated and programmatic via JavaScript).
+2. **Align to a Box-Edge**: Use keywords to precisely align the clipping boundary to inner box-model edges:
+   - `content-box`: Clips content exactly where the content area begins, leaving the padding area completely clean. Content stops right at the padding's edge. Excellent for nested layout modules.
+   - `padding-box` (Default): Clips content at the inner edge of the border.
+   - `border-box`: Clips content at the outer edge of the border, allowing content to sit under or partially overlap a translucent border.
+3. **Define a Specified Offset (The Bleed)**: Provide a length value (e.g., `15px` or `5px`) to create a safety zone before cutting pixels. This allows prominent child element shadows to render unclipped past the boundary edge without expanding layout geometry.
+4. **Combine Box-Edge and Offset**: Specify both a box edge and a length offset simultaneously (e.g., `content-box 15px`) to offset from a specific box edge.
+
+## Example Code
+
+The following examples demonstrate dynamic container layout controls, showcasing automated inner content curve nested framing and child element shadow protection alongside progressive enhancement fallbacks.
+
+### Block Containers: Nested Rounded Curves
+
+* Apply `overflow-clip-margin: content-box` to a parent container with rounded corners and custom padding.
+* Apply similar rounded corners on inner child media and footer components along the concentric inner content box boundary, solving awkward nesting curves without custom `calc()` logic.
+
+```html
+<div class="nested-curve-parent">
+  <img src="avatar.jpg" alt="Nested Curve Demo">
+  <div class="nested-curve-footer">Card Footer</div>
+</div>
+```
+
+```css
+/**
+ * Standard block layout container with outer corner radii and padding.
+ * Keeps base level 1 fallback clipping roughly at the inner padding box.
+ */
+.nested-curve-parent {
+  /* Level 1 Fallback: clips child roughly at the padding box */
+  overflow: hidden;
+}
+
+/* Inner footer component with 12px rounded to visually demonstrate automatic concentric corner clipping */
+.nested-curve-footer {
+  background: #111;
+  color: #fff;
+}
+
+@supports (overflow-clip-margin: content-box) {
+  .nested-curve-parent {
+    /* MANDATORY: overflow: clip is required on non-replaced elements */
+    overflow: clip;
+    /* Automatically curves clipping edge to match inner content-box radius */
+    overflow-clip-margin: content-box;
+  }
+}
+```
+
+### Block Containers: Child Element Shadow Bleed
+
+* Apply `overflow: clip` and define an extended `overflow-clip-margin` length offset to create a visible safety zone permitting the child's shadow to render unclipped outside the parent container without altering layout geometry. Without this, the child's shadow is clipped at the parent's boundary.
+
+```html
+<div class="safety-zone-parent">
+  <h4>Clipped Container</h4>
+  <p>Inner content boundaries safely contained.</p>
+  <!-- Child button element positioned inside with a prominent shadow -->
+  <button class="demo-glowing-btn">Submit</button>
+</div>
+```
+
+```css
+/**
+ * Standard block layout container clipping inner content.
+ * Base fallback uses overflow: hidden, which abruptly slices child element shadows.
+ */
+.safety-zone-parent {
+  /* Level 1 Fallback: clips overflowing content but truncates child shadows */
+  overflow: hidden;
+}
+
+/* Child button element positioned inside with an expanded shadow */
+.demo-glowing-btn {
+  display: block;
+  box-shadow: 0 8px 13px rgba(229, 46, 113, 0.7);
+}
+
+@supports (overflow-clip-margin: 15px) {
+  .safety-zone-parent {
+    overflow: clip;
+    /* Establishes a visible safety zone allowing child element shadows to render safely outside */
+    overflow-clip-margin: 15px;
+  }
+}
+```
+
+## Strategic Implementation & Best Practices
+
+- **DO** apply `overflow: clip` on target elements when utilizing `overflow-clip-margin`, as setting `overflow` strictly to `clip` is **mandatory** on standard block layout containers to activate custom or inner curved clip margins.
+- **DO** set `overflow-clip-margin: content-box` on padded containers with rounded corners to automatically clip unrounded internal child elements into mathematically perfect nested border curves without manual padding subtraction logic.
+- **DO** configure `overflow-clip-margin` with a specified length offset when applying external visual effects (like `filter: drop-shadow()`) to prevent sharp bounding box truncation without altering or expanding layout geometry.
+- **DO NOT** apply `overflow: clip` if the container requires programmatic scroll manipulation via JavaScript or serves as the immediate layout context for `position: sticky` elements, as `clip` completely disables scrolling.
+
+## Fallback Strategies
+
+Baseline status for overflow: clip: Widely available. It's been Baseline since 2022-09-12.
+Supported by: Chrome 90 (Apr 2021), Edge 90 (Apr 2021), Firefox 81 (Sep 2020), and Safari 16 (Sep 2022).
+overflow-clip-margin has limited availability.
+Supported by: Firefox 148 (Feb 2026).
+Unsupported in: Chrome, Edge, and Safari.
+
+For target environments lacking native support for `overflow: clip` or `overflow-clip-margin`, progressive enhancement fallback strategies depend directly on the visual intent:
+- Fallback to `overflow: hidden` as the base experience to guarantee core boundaries are maintained.
+- Fallback to `overflow: visible` on elements where drop-shadows or external corner badges must not be truncated.
+
+### Complete Progressive Enhancement Fallback Implementation
+
+```html
+<!-- 1. Nested rounded edges fallback -->
+<div class="demo-container-fallback">
+  <img src="example.jpg" alt="Nested Curve Fallback">
+  <div class="demo-footer-fallback">Footer</div>
+</div>
+
+<!-- 2. Child element shadow bleed fallback -->
+<div class="demo-safety-parent">
+  <h4>Container</h4>
+  <p>Inner boundaries contained.</p>
+  <button class="demo-glowing-btn">Submit</button>
+</div>
+```
+
+```css
+/**
+ * 1. Block Container Nested Curves Fallback
+ * Keeps base level 1 fallback clipping roughly at the inner padding box.
+ */
+.demo-container-fallback {  
+  /* Level 1 Fallback: clip child roughly at padding box */
+  overflow: hidden;
+}
+
+.demo-container-fallback img {
+  object-fit: cover;
+  display: block;
+}
+
+@supports (overflow-clip-margin: content-box) {
+  .demo-container-fallback {
+    overflow: clip;
+    overflow-clip-margin: content-box;
+  }
+}
+
+/**
+ * 2. Child Element Shadow Bleed Fallback
+ * Base fallback clips content using overflow: hidden, abruptly truncating child element shadows.
+ */
+.demo-safety-parent {  
+  /* Level 1 Fallback */
+  overflow: hidden;
+}
+
+.demo-glowing-btn {
+  display: block;
+  width: 100%;
+  padding: 6px 12px;
+  background: #e52e71;
+  box-shadow: 0 8px 13px rgba(229, 46, 113, 0.65);
+}
+
+@supports (overflow-clip-margin: 15px) {
+  .demo-safety-parent {
+    overflow: clip;
+    overflow-clip-margin: 15px;
+  }
+}
+```