@olives/devos 2.1.0

package/.agents/skills/modern-web-guidance/guides/user-experience/adapt-scrollbar-to-contrast-preferences.md

@@ -0,0 +1,74 @@
+# Adapt scrollbar to high-contrast preferences
+
+Users who enable high-contrast modes in their operating system or browser expect UI elements (like scrollbars) to be extremely legible, often relying on stark foreground-background separation rather than subtle grays or theme colors.
+
+This guide provides optional instructions on how to use the `@media (prefers-contrast: more)` CSS media feature to enforce high-contrast scrollbar styling.
+
+## Enhance Legibility
+
+When customizing scrollbars with `scrollbar-color` or custom variables, you can provide an explicit override for high-contrast modes. This is especially helpful if your primary application theme uses low-contrast scrollbars for aesthetic reasons.
+
+OPTIONAL: Use a `@media (prefers-contrast: more)` block to define dark, distinct colors for the thumb and track.
+
+```css
+/* Define default standard colors as variables */
+.scroller {
+  --scrollbar-thumb: #bbb;
+  --scrollbar-track: #f1f1f1;
+
+  scrollbar-color: var(--scrollbar-thumb) var(--scrollbar-track);
+  scrollbar-width: thin;
+  scrollbar-gutter: stable;
+}
+
+/* OPTIONAL: Provide clear, high-contrast overrides */
+@media (prefers-contrast: more) {
+  .scroller {
+    /* Use extremely distinct colors like solid black against white */
+    --scrollbar-thumb: #000000;
+    --scrollbar-track: #ffffff;
+  }
+}
+```
+
+### Issues to be aware of when using scrollbar-color
+
+- Do NOT animate or transition `scrollbar-color`. A [WebKit bug](https://bugs.webkit.org/show_bug.cgi?id=311752) causes the scrollbar to flicker every time `scrollbar-color` changes.
+- On macOS, `scrollbar-color` (standard) and `::-webkit-scrollbar` (legacy) properties are ignored by default because macOS uses native "overlay" scrollbars. You MUST pair custom colors with `scrollbar-width` (e.g., `thin` or `auto`) to force macOS to render them.
+- Even with `scrollbar-width` applied, macOS overlay scrollbars render the track (gutter) as transparent by default. If the design requires a visible track background color on MacOS, you MUST apply `scrollbar-gutter: stable;` to the scrollable container, but note that it only appears after the user hovers over the scrollbar.
+- Even with `scrollbar-gutter: stable` the track may be transparent on MacOS. The thumb should not depend on the track color to be visible.
+
+## Fallbacks & Browser Support
+
+### Fallbacks & browser support for scrollbar-color
+
+Baseline status for scrollbar-color: Newly available. It's been Baseline since 2025-12-12.
+Supported by: Chrome 121 (Jan 2024), Edge 121 (Jan 2024), Firefox 64 (Dec 2018), and Safari 26.2 (Dec 2025).
+
+This feature is progressive enhancement and does not always require fallbacks.
+
+If the styling is important and the user's Baseline target is "Baseline Widely Available" or earlier, you SHOULD include the non-standard `::-webkit-scrollbar` pseudo-elements as fallbacks.
+
+Wrap legacy fallbacks in an `@supports not (scrollbar-color: auto)` block to prevent conflicts between standard properties and legacy WebKit selectors in browsers that support both natively.
+
+If you are using custom properties to define colors, these will cascade to the legacy WebKit selectors automatically. You do NOT need to duplicate them.
+
+```css
+/* Legacy fallback for WebKit/Blink browsers */
+@supports not (scrollbar-color: auto) {
+  .scroller::-webkit-scrollbar {
+    /* Must define base size in WebKit for custom colors to be visual */
+    width: 12px;
+    height: 12px;
+  }
+
+  .scroller::-webkit-scrollbar-thumb {
+    background: var(--scrollbar-thumb);
+  }
+
+  .scroller::-webkit-scrollbar-track {
+    background: var(--scrollbar-track);
+  }
+}
+```
+

package/.agents/skills/modern-web-guidance/guides/user-experience/anchor-positioning-tab-underline.md

@@ -0,0 +1,95 @@
+In a tab menu, you should provide visual hints to users about what page they are on. One option is by underlining the tab. With anchor positioning, you can create a smooth animation between the positions of the underline. This does not work when changing the active tab loads a new web page.
+
+You can also use this effect to add an animated dot to indicate the active tab in a vertical tab bar.
+
+Create the underline using a `::before` pseudo-element on the `<ul>` that contains the `<li>` elements. **Using a pseudo-element is the preferred approach as it keeps the DOM clean and avoids adding extra elements for purely decorative effects.**
+
+```css
+ul::before {
+  /* Use a pseudo-element on the container to represent the animated indicator */
+  content: '';
+}
+```
+
+Make the active list item an anchor by adding the `anchor-name` property, which has a value that starts with `--`.
+
+```css
+li.active {
+  /* Make a unique anchor-name for the active element. */
+  anchor-name: --active;
+}
+```
+
+Tether the underline to the active item anchor with a `position-anchor` that matches the `anchor-name` on the anchor, and making it `position: absolute`.
+
+```css
+ul::before {
+  /* Tether the underline to the active element. */
+  position: absolute;
+  position-anchor: --active;
+}
+```
+
+Position the underline relative to the anchor using the inset properties and `anchor()` functions.
+
+```css
+ul::before {
+  /* DO NOT use position-area, which can not be transitioned. */
+  /* Use calc() to offset the top slightly */
+  inset-block-start: calc(anchor(bottom) + .1lh);
+  inset-inline-start: anchor(left);
+  inset-inline-end: anchor(right);
+}
+```
+
+Add a height and other visual styles.
+
+```css
+ul::before {
+  /* Apply your project's styles for the indicator */
+  block-size: .25lh;
+  background: red;
+}
+```
+
+Finally, add a transition on the `inset` properties.
+
+```css
+ul::before {
+  @media (prefers-reduced-motion: no-preference) {
+    /* MANDATORY: The transition must be wrapped in a prefers-reduced-motion media query to respect user preferences. */
+    transition: inset .2s;
+  }
+}
+```
+
+This is only a visual indicator, and must not be a replacement for setting the appropriate `aria-current="page"` or `aria-selected` aria values.
+
+```html
+<!-- MANDATORY: Provide explicit assistive technology state alongside the visual tab underline -->
+<nav aria-label="Primary">
+  <ul>
+    <li class="active">
+      <a href="/home" aria-current="page">Home</a>
+    </li>
+    <li>
+      <a href="/about">About</a>
+    </li>
+  </ul>
+</nav>
+```
+
+## Fallback strategies
+
+Anchor positioning is not natively supported by any major browser yet.
+
+If anchor positioning is not supported in the browser, use a `border-bottom` to add an underline. It will not be animated.
+
+```css
+ul li.active {
+  @supports not (position-anchor: auto) {
+    /* Choose a color appropriate to the app theme. */
+    border-bottom: .25lh var(--primary) solid;
+  }
+}
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/animate-element-entry-exit.md

@@ -0,0 +1,131 @@
+In the past, CSS transitions could not animate elements when they were first added to the DOM or when their `display` property changed from `none`. The `@starting-style` at-rule and `transition-behavior: allow-discrete` provide a declarative way to create smooth entry and exit animations.
+
+## Implementation
+
+### 1. Animating `display: none` Toggles
+
+To animate an element when toggling its visibility via an attribute (e.g., `hidden` with `display: none`):
+
+1. **Define the visible state**: Set the final property values (e.g., `opacity: 1`) on the base class.
+2. **Define the entry starting state**: Use `@starting-style` to specify the values to transition *from* when the element becomes visible.
+3. **Enable discrete transitions**: Include `display` in the `transition` property and use `transition-behavior: allow-discrete`.
+4. **Define the exit state**: Set the target values in the `hidden` attribute.
+
+```css
+.card {
+  display: block;
+  opacity: 1;
+  translate: 0;
+  /* MANDATORY: Use transition-behavior: allow-discrete for display transition */
+  transition:
+    display 0.4s,
+    opacity 0.4s ease-out,
+    translate 0.4s ease-out;
+  transition-behavior: allow-discrete;
+}
+
+/* Entry animation: transition FROM these values when first rendered */
+@starting-style {
+  .card {
+    opacity: 0;
+    translate: 0 -20px;
+  }
+}
+
+/* Exit animation: transition TO these values when hidden */
+.card:where(.hidden, [hidden]) {
+  display: none;
+  opacity: 0;
+  translate: 0 -20px;
+}
+
+/* Respect user preference for reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  .card {
+    /* Disable movement and shorten duration for a simple fade */
+    translate: none;
+    transition-duration: 0.1s;
+  }
+
+  @starting-style {
+    .card {
+      translate: none;
+    }
+  }
+
+  .card:where(.hidden, [hidden]) {
+    translate: none;
+  }
+}
+```
+
+### 2. Animating DOM Insertion and Removal
+
+For elements added via `appendChild()` or removed via `remove()`:
+
+- **Entry**: Use `@starting-style` as shown above. The browser will automatically detect the style change from "nothing" to the element's initial styles and trigger the transition from the `@starting-style` values.
+- **Removal**: Since `element.remove()` is instantaneous and doesn't trigger a CSS transition on its own, you must trigger the exit transition first (e.g., by adding a class) and wait for it to finish before removing the node from the DOM.
+
+```javascript
+// Trigger exit transition
+element.setAttribute('hidden', true);
+
+// 2. Wait for all active transitions/animations to finish,
+//    with a failsafe timeout in case an animation never ends (e.g. for looping animations)
+const animations = element.getAnimations();
+if (animations.length > 0) {
+  await Promise.race([
+    // Promise.allSettled ensures we wait even if some animations fail
+    Promise.allSettled(animations.map(a => a.finished)),
+    new Promise(r => setTimeout(r, 2000))
+  ]);
+}
+
+// 3. Finally remove the node from the DOM
+element.remove();
+```
+
+## Constraints & Accessibility
+
+- **MANDATORY**: Use `transition-behavior: allow-discrete` when transitioning `display`. Without it, the element will instantly disappear during exit.
+- **DO NOT** use `allow-discrete` in the `transition` shorthand — it will make older browsers ignore the entire `transition` declaration. Except in use cases where that is desirable, use a separate `transition-behavior: allow-discrete` declaration.
+- **MANDATORY**: Use `@starting-style` for entry animations. Browsers skip transitions on an element's first style update (initial render or `display: none` change) unless this is provided.
+- **DO**: Include `overlay` in the `transition` list if animating top-layer elements like `<dialog>` or `popover` to ensure they stay in the top layer during the exit animation.
+- **DO**: Respect user preferences for reduced motion using the `prefers-reduced-motion` media query.
+- **DO NOT**: Rely on `@starting-style` for exit animations; it only defines the *starting* point for an entry transition. Exit animations are defined by the transition to the hidden state.
+
+## Fallback strategies
+
+Baseline status for @starting-style: Newly available. It's been Baseline since 2024-08-06.
+Supported by: Chrome 117 (Sep 2023), Edge 117 (Sep 2023), Firefox 129 (Aug 2024), and Safari 17.5 (May 2024).
+
+For browsers that do not support these features, elements will toggle `display: none` instantly. You can detect support in JavaScript using `CSS.supports()` to conditionally apply manual animation logic.
+
+```javascript
+// Detect support for discrete transitions and starting-style
+const supportsModernTransitions =
+  window.CSS &&
+  CSS.supports('transition-behavior', 'allow-discrete');
+
+if (!supportsModernTransitions) {
+  // Implement manual JS-based fallback for entry/exit
+}
+```
+
+### Manual Entry Animation (JS Fallback)
+
+```javascript
+// To show:
+el.style.display = '';
+requestAnimationFrame(() => {
+  requestAnimationFrame(() => {
+    el.classList.remove('hidden');
+  });
+});
+
+// To hide:
+el.setAttribute('hidden', true);
+el.addEventListener('transitionend', () => {
+  if (el.classList.contains('hidden')) el.style.display = 'none';
+}, { once: true });
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/animate-to-from-top-layer.md

@@ -0,0 +1,140 @@
+Elements that render in the "top layer" (like `<dialog>`, elements with the `popover` attribute, or tooltips) have historically been difficult to animate because they toggle between `display: none` and a visible state. Modern CSS provides `@starting-style`, `transition-behavior: allow-discrete`, and the `overlay` property to enable smooth entry and exit transitions for these elements. Note that native CSS nesting is used in the examples below.
+
+## Implementation
+
+### 1. Enable Discrete Transitions
+
+To animate the `display` property, you must set `transition-behavior: allow-discrete`. This allows the element to remain visible during its exit transition. If using transition shorthands, be sure to place the `transition-behavior: allow-discrete` afterwards to prevent the shorthand from negating it.
+
+### 2. The `overlay` Property
+
+When an element moves in or out of the top layer, it must transition the `overlay` property. This ensures the element stays in the top layer for the duration of the animation, preventing it from being clipped by other elements or the viewport prematurely.
+
+### 3. Entry Animations with `@starting-style`
+
+Use the `@starting-style` at-rule to define the styles an element should transition *from* when it is first rendered or its `display` changes from `none`.
+
+### 4. Animating the Backdrop
+
+The `::backdrop` pseudo-element can be animated similarly by applying transitions to its own properties.
+
+## Example
+
+```css
+/* 1. Define the visible (open) state */
+dialog[open],
+[popover]:popover-open {
+  opacity: 1;
+  transform: scale(1);
+
+  /* 2. Define the starting state for entry (must come after open state) */
+  @starting-style {
+    opacity: 0;
+    transform: scale(0.9);
+  }
+}
+
+/* 3. Define the base (closed/exit) state and transitions */
+dialog,
+[popover] {
+  opacity: 0;
+  transform: scale(0.9);
+
+  /* MANDATORY: transition display and overlay for top-layer elements */
+  transition-property: opacity, transform, display, overlay;
+  transition-duration: 0.3s;
+  transition-timing-function: ease-out;
+  /* Applies to discrete properties like display and overlay */
+  transition-behavior: allow-discrete; /* Note: be sure to write this after the shorthand */
+}
+
+/* 4. Animate the backdrop */
+dialog::backdrop,
+[popover]::backdrop {
+  background-color: rgba(0, 0, 0, 0);
+  /* The transition shorthand can also be used with allow-discrete */
+  transition:
+    display 0.3s allow-discrete,
+    overlay 0.3s allow-discrete,
+    background-color 0.3s ease-out;
+}
+
+dialog[open]::backdrop,
+[popover]:popover-open::backdrop {
+  background-color: rgba(0, 0, 0, 0.5);
+
+  @starting-style {
+    background-color: rgba(0, 0, 0, 0);
+  }
+}
+
+/* 5. Respect user preference for reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  dialog,
+  [popover] {
+    /* Disable movement and shorten duration for a simple fade */
+    transform: none;
+    transition-duration: 0.1s;
+  }
+
+  @starting-style {
+    dialog[open],
+    [popover]:popover-open {
+      transform: none;
+    }
+  }
+}
+```
+
+## Constraints & Accessibility
+
+- **MANDATORY**: Include `overlay` in your `transition` list for any element moving into or out of the top layer.
+- **MANDATORY**: Use `allow-discrete` for the `display` property transition.
+- **MANDATORY**: Respect user preferences for reduced motion using `prefers-reduced-motion` by simplifying transitions (e.g., removing transforms and shortening duration).
+- **DO**: Place the `@starting-style` block inside or after the "open" state selector to ensure proper cascading.
+- **DO NOT**: Use `@starting-style` for exit animations; exit animations are defined by the transition to the base (closed) state.
+
+## Fallback strategies
+
+#### Top-layer animation features
+
+Baseline status for @starting-style: Newly available. It's been Baseline since 2024-08-06.
+Supported by: Chrome 117 (Sep 2023), Edge 117 (Sep 2023), Firefox 129 (Aug 2024), and Safari 17.5 (May 2024).
+Baseline status for transition-behavior: Newly available. It's been Baseline since 2024-08-06.
+Supported by: Chrome 117 (Sep 2023), Edge 117 (Sep 2023), Firefox 129 (Aug 2024), and Safari 17.4 (Mar 2024).
+overlay has limited availability.
+Supported by: Chrome 117 (Sep 2023) and Edge 117 (Sep 2023).
+Unsupported in: Firefox and Safari.
+
+For browsers that do not support these features, top-layer elements will appear and disappear instantly. To provide animations in older browsers, you must use JavaScript to coordinate classes and wait for `transitionend` events or use the Web Animations API.
+
+```javascript
+// Feature detection for top-layer animations
+const supportsTopLayerAnimation =
+  window.CSS &&
+  CSS.supports('transition-behavior', 'allow-discrete') &&
+  CSS.supports('overlay', 'auto');
+
+if (!supportsTopLayerAnimation) {
+  // Manual JS fallback for entry/exit animations:
+  // 1. Add an `.is-opening` class for entry.
+  // 2. On close, add an `.is-closing` class, wait for the `transitionend` event, then call .close() or hide the popover.
+}
+```
+
+#### popover
+
+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()`.

package/.agents/skills/modern-web-guidance/guides/user-experience/animate-to-intrinsic-sizes.md

@@ -0,0 +1,127 @@
+# Animate to Intrinsic Sizes
+
+Animating elements to dynamic sizes like `block-size: auto` or `inline-size: max-content` has historically required JavaScript or fragile "max-height" hacks. The `interpolate-size` property and `calc-size()` function allow the browser to natively interpolate between fixed lengths and intrinsic sizing keywords.
+
+## Implementation steps
+
+1.  **Opt-in to keyword interpolation**: Apply `interpolate-size: allow-keywords` to a parent element (typically `:root`) to enable transitions for properties using intrinsic keywords.
+2.  **Define the transition**: Set a `transition` for the sizing property (e.g., `block-size`, `inline-size`) on the target element.
+3.  **Use intrinsic keywords**: Change the sizing property to a supported intrinsic keyword—`auto`, `min-content`, `max-content`, `fit-content`, or (for flex-basis) `content`—during an interaction (e.g., `:hover` or a state class).
+4.  **Perform calculations (Optional)**: Use `calc-size()` if you need to perform math on an intrinsic size (e.g., `auto + 2rem`). `calc-size()` also supports the `any` keyword for basis-agnostic calculations.
+
+## Example: Generic Expansion Pattern
+
+You can apply this pattern to any container (like a "Show More" section or a navigation menu) to transition between a restricted height and the element's natural size.
+
+```css
+/* Opt-in globally for all children */
+:root {
+  /* MANDATORY: Transitions to intrinsic keywords are disabled by default for compatibility */
+  interpolate-size: allow-keywords;
+}
+
+.expandable-container {
+  /* 1. Define a fixed initial size (or 0) and hide overflow */
+  block-size: 100px;
+  overflow: hidden;
+  
+  /* 2. Transition the sizing property */
+  transition: block-size 0.4s ease-out;
+}
+
+.expandable-container.is-expanded {
+  /* 3. Smoothly animate to the intrinsic natural height */
+  block-size: auto;
+}
+```
+
+## Example: Calculated Intrinsic Inline-Size
+
+```css
+.badge {
+  inline-size: 40px;
+  overflow: hidden;
+  white-space: nowrap;
+  transition: inline-size 0.3s ease;
+}
+
+.badge:hover {
+  /* calc-size(basis, calculation) */
+  /* 'size' refers to the evaluated basis (max-content in this case) */
+  inline-size: calc-size(max-content, size + 20px);
+}
+```
+
+## Example: Transition from Intrinsic to Fixed
+
+You can also animate in the opposite direction—starting from a natural size and collapsing to a specific length. This is useful for "dismissible" components.
+
+```css
+.collapsible-alert {
+  /* 1. Start with the natural content height */
+  block-size: auto;
+  overflow: hidden;
+  transition: block-size 0.5s ease-in-out, opacity 0.5s ease;
+}
+
+.collapsible-alert.is-dismissed {
+  /* 2. Smoothly collapse to zero */
+  block-size: 0;
+  opacity: 0;
+  pointer-events: none;
+}
+
+/* MANDATORY Copy-Paste Safety: Disable sizing animations for sensitive users */
+@media (prefers-reduced-motion: reduce) {
+  .expandable-container,
+  .badge,
+  .collapsible-alert {
+    transition: none !important;
+  }
+}
+```
+
+```javascript
+// MANDATORY Accessibility Synchronization: Ensure elements collapsed to zero dimensions are removed from the assistive technology tree, and sync aria-expanded states on triggers.
+const alertElement = document.querySelector('.collapsible-alert');
+alertElement.addEventListener('transitionend', (e) => {
+  if (e.propertyName === 'block-size' && alertElement.classList.contains('is-dismissed')) {
+    alertElement.hidden = true;
+  }
+});
+
+// Example trigger syncer
+const triggerBtn = document.querySelector('.accordion-trigger');
+triggerBtn?.addEventListener('click', () => {
+  const isExpanded = triggerBtn.getAttribute('aria-expanded') === 'true';
+  triggerBtn.setAttribute('aria-expanded', !isExpanded);
+});
+```
+
+## Key constraints
+
+*   **Keyword-to-Keyword Restriction**: You cannot animate between two different keywords directly (e.g., from `min-content` to `max-content`). One end of the transition must be a fixed length or percentage (e.g., `0` to `auto`).
+*   **Calc-size Syntax**: Inside `calc-size()`, you cannot mix different intrinsic keywords in the same expression. The first argument (the basis) defines what `size` represents.
+*   **Opt-in Requirement**: Transitions to intrinsic keywords are disabled by default (`numeric-only`) to maintain backward compatibility. You must apply `interpolate-size: allow-keywords` to the element or an ancestor. `calc-size()` acts as a per-property override, automatically enabling interpolation whenever it is used.
+
+## Fallback strategies
+
+interpolate-size has limited availability.
+Supported by: Chrome 129 (Sep 2024) and Edge 129 (Sep 2024).
+Unsupported in: Firefox and Safari.
+calc-size() has limited availability.
+Supported by: Chrome 129 (Sep 2024) and Edge 129 (Sep 2024).
+Unsupported in: Firefox and Safari.
+
+`interpolate-size` and `calc-size()` are progressive enhancements. Browsers that do not support them will perform an instant jump to the target size.
+
+*   **Graceful Degradation**: For simple `block-size: auto` transitions, standard browsers will simply toggle the size instantly, which is functional but less polished.
+*   **Manual keyword fallbacks**: When using `calc-size()`, always provide a standard keyword fallback for older browsers, as they will discard the entire `calc-size()` declaration.
+
+```css
+.card {
+  block-size: auto; /* Fallback for older browsers */
+  block-size: calc-size(auto, size); /* Modern browsers use this */
+  transition: block-size 0.3s ease;
+}
+```