@olives/devos 2.1.0

package/.agents/skills/modern-web-guidance/guides/user-experience/carousel-slide-effects.md

@@ -0,0 +1,187 @@
+# Build Carousel Slide Effects
+
+Carousel slide effects are a great way to add visual interest to a carousel. As the user scrolls through the slides, each slide can animate as it enters, centers, and exits the scrollport. For example, the slides can fade in and out, rotate, or scale in size. This creates a dynamic and engaging user experience. Unlike simple entry/exit animations, this effect uses a single, continuous animation to control the slide's appearance across the entire scrollport.
+
+## How to implement
+
+Here’s how to create carousel slide effects:
+
+1.  **Create a scroller:** This element will act as the container for your carousel slides. In this example it uses `overflow-x: scroll` to allow horizontal scrolling.
+
+    ```html
+    <ul class="scroller">
+      <li class="entry">1</li>
+      <li class="entry">2</li>
+      <li class="entry">3</li>
+      …
+    </ul>
+    ```
+
+    ```css
+    .scroller {
+      overflow-x: scroll;
+    }
+    ```
+
+2.  **Define the animation:** Create a CSS animation that defines the different states of your slides as they traverse the scrollport. You can define keyframes for any part of the animation. For example, you can define a state for when the slides are in the center of the scrollport by including a `50%` keyframe. In this example, the `scale` property makes the slides grow as they approach the center and shrink as they move away.
+
+    ```css
+    @keyframes animate {
+      0% {
+        scale: 0.5;
+      }
+      50% {
+        scale: 1;
+      }
+      100% {
+        scale: 0.5;
+      }
+    }
+    ```
+
+3.  **Apply the animation and `view-timeline`:** Attach the animation to the carousel slides and link it to a `view-timeline` that tracks the element as it scrolls through the container.
+
+    ```css
+    .scroller > * {
+      animation: animate auto linear both;
+      animation-timeline: view(inline);
+    }
+    ```
+
+    By default, `view()` tracks the element on the `block` axis. If you need to track it on the `inline` axis, you can use `view(inline)`.
+
+## Example code
+
+This code animates the carousel items of a horizontal scroller on scroll using an **anonymous view-timeline**:
+
+```css
+@keyframes animate {
+  0% {
+    scale: 0.5;
+  }
+
+  50% {
+    scale: 1;
+  }
+
+  100% {
+    scale: 0.5;
+  }
+}
+
+.scroller > * {
+  /* Applies the animation using an `auto` duration */
+  animation: animate auto linear both;
+  /* Sets the animation timeline to use an anonymous view progress timeline, tracking the element's progress through the scroller on the inline axis */
+  animation-timeline: view(inline);
+}
+```
+
+This code animates the carousel items of a horizontal scroller on scroll using a **named view-timeline**:
+
+```css
+@keyframes animate {
+  0% {
+    scale: 0.5;
+  }
+
+  50% {
+    scale: 1;
+  }
+
+  100% {
+    scale: 0.5;
+  }
+}
+
+/* This creates a named view-timeline on each carousel item. The timeline is used to drive the animation that is applied on the same element. */
+.scroller > * {
+  /* Applies the animation using an `auto` duration */
+  animation: animate auto linear both;
+  /* Defines a named view progress timeline, tracking the element's progress through the scroller on the inline axis */
+  view-timeline: --item inline;
+  /* Sets the animation timeline to use the named view progress timeline defined above */
+  animation-timeline: --item;
+}
+```
+
+## 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.
+
+Prefer a named `view-timeline` when multiple DOM elements need to animate based on the same timeline, or when you need to animate children of the element that has the `view-timeline` defined on it. If the element that you animate is also the element that defines the `view-timeline`, you can use an anonymous view-timeline using `view()`.
+
+When using the `view()` function to create a scroll-driven animation:
+
+- **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 `view(block)` or `view(inline)`.
+
+When using the `view-timeline` property to create a scroll-driven animation:
+
+- **DO** use a CSS `<dashed-ident>` for the name (e.g. `view-timeline: --my-custom-name`)
+- **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 `view-timeline-axis`.
+- **DO** make sure the scope of the lookup works: When the element that is declaring the `view-timeline` is not a flat tree ancestor of the animated element, hoist up the visibility of the `view-timeline`’s name by using `timeline-scope` on a shared ancestor.
+
+## 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 the Web Animations API (`Element.animate()`) to create a paused animation for each item in the carousel. It then listens to the `scroll` event on the scroller and updates the `currentTime` of each animation based on the item's scroll progress within the scroller.
+
+```js
+// Fallback for browsers that don't support scroll-driven animations
+if (!CSS.supports('(animation-timeline: view()) and (animation-range: entry)')) {
+  const scroller = document.querySelector('.scroller');
+  const entries = document.querySelectorAll('.entry');
+
+  // Create a map to store animations
+  const animations = new Map();
+
+  entries.forEach(entry => {
+    const animation = entry.animate(
+      {
+        scale: ['0.5', '1', '0.5']
+      },
+      {
+        duration: 1, // We'll control the time ourselves
+        fill: 'both'
+      }
+    );
+    animation.pause();
+    animations.set(entry, animation);
+  });
+
+  // Update animations on scroll
+  const tick = () => {
+    const scrollerRect = scroller.getBoundingClientRect();
+
+    entries.forEach(entry => {
+      const animation = animations.get(entry);
+      if (!animation) return;
+
+      const entryRect = entry.getBoundingClientRect();
+      const progress = (entryRect.left + entryRect.width / 2 - scrollerRect.left) / scrollerRect.width;
+
+      animation.currentTime = progress;
+    });
+  };
+    
+  scroller.addEventListener('scroll', tick);
+  tick();
+}
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/carousel-snap-highlights.md

@@ -0,0 +1,136 @@
+Scroll-state container queries allow you to style elements based on their current scroll state, such as whether an element is "stuck" (via sticky positioning) or "snapped" (via scroll snapping). This enables carousel or gallery experiences where the active item can be visually distinguished without relying on JavaScript intersection observers or scroll event listeners.
+
+### Core implementation
+
+To highlight snapped items, you must establish a scroll-snap container, define the snap targets as scroll-state containers, and then query that state to style descendants.
+
+#### 1. Establish the scroll snap container
+The parent container must have `scroll-snap-type` enabled.
+
+```html
+<div class="carousel">
+  <div class="carousel-item">
+    <div class="card">Product 1 content</div>
+  </div>
+  <div class="carousel-item">
+    <div class="card">Product 2 content</div>
+  </div>
+</div>
+```
+
+```css
+.carousel {
+  display: flex;
+  overflow-x: auto;
+  /* MANDATORY: Enable scroll snapping on the container */
+  scroll-snap-type: x mandatory;
+}
+```
+
+#### 2. Define snap targets as scroll-state containers
+Each item in the carousel that should be tracked for snapping must be declared as a `scroll-state` container.
+
+```css
+.carousel-item {
+  /* Define where the item snaps within the container */
+  scroll-snap-align: center;
+  
+  /* MANDATORY: Establish this element as a scroll-state query container */
+  container-type: scroll-state;
+}
+```
+
+#### 3. Query the `snapped` state
+
+Because container queries style **descendants**, you must apply the highlight styles to an element *inside* the snap target.  Because the scroll container is set to overflow on the x axis, use the `scroll-state(snapped: x)` query.
+
+**MANDATORY**: Wrap the styles in ` @media (prefers-reduced-motion: no-preference)` to only show the effect to users who have not requested reduced motion. Depending on your use case, you may retain portions of the effect, but in this case, the cards flash from white to blue in a way that may cause problems for some users, so we disable it completely.
+
+```css
+/* Specify transition outside of queries so that it is applied regardless of state.  */
+.card {
+  transition:
+    scale 0.4s cubic-bezier(0.25, 0.8, 0.25, 1),
+    background-color 0.4s,
+    color 0.4s,
+    box-shadow 0.4s;
+}
+/* 
+Only show the effect for users not requesting reduced motion. Disable completely, including the color change, as it causes a flash that may be problematic.
+*/
+@media (prefers-reduced-motion: no-preference) {
+  /* Style the content when its parent .carousel-item is snapped on the x axis */
+  @container scroll-state(snapped: x) {
+    .card {
+      background: #007bff;
+      color: white;
+      scale: 1.15;
+      box-shadow: 0 10px 25px rgba(0, 123, 255, 0.3);
+    }
+  }
+}
+
+/* MANDATORY Copy-Paste Safety: Disable highlight scaling/flashing for motion sensitive users */
+@media (prefers-reduced-motion: reduce) {
+  .card {
+    transition: none !important;
+    scale: 1 !important;
+  }
+}
+```
+
+The `snapped` descriptor can query specific axes: `x`, `y`, `inline`, `block`, or `both`.
+
+
+### Accessibility
+
+**AVOID**: using `scroll-state` with interactive elements.
+
+Visual highlights for snapped items can improve the UX, but the snapped item is not exposed to the accessibility tree. The visual theme applied to a snapped item should not convey that the element is active or focused, and a keyboard focus ring should be highly visible and distinct from the `snapped` highlight. If the snapped item is interactive, you must use other standard accessibility practices to make it accessible.  
+
+Snapping occurs due to scrolling, which does not move keyboard focus. However, keyboard focus may cause the scroll container to move, causing a change in the snapped item, which may or may not be the focused item. This will likely be a source of confusion for users and is discouraged.
+
+> [!NOTE]
+> Detailed accessibility requirements for carousels (such as ARIA roles, slide attributes, and complex keyboard patterns) have been intentionally omitted from this guide. Carousel accessibility is highly nuanced and context-dependent; refer to established accessibility standards and perform thorough user testing for production environments.
+
+
+## Fallback strategies
+
+Container scroll-state queries has limited availability.
+Supported by: Chrome 133 (Feb 2025) and Edge 133 (Feb 2025).
+Unsupported in: Firefox and Safari.
+
+For browsers that do not support scroll-state queries, you should provide a functional base experience where all items are legible, even without the "active" highlight.
+
+#### Feature detection
+You can use `@supports` to provide enhancements only to supported browsers:
+
+```css
+@supports (container-type: scroll-state) {
+  /* Enhancement styles here */
+}
+```
+
+#### JavaScript fallback
+
+If the highlight is critical for the user experience, use `IntersectionObserver` to determine the snapped item. Adjust the observed area to a thin slice in the center of the carousel by providing a `rootMargin` with a negative inline value. For example, to consider an element to be intersecting if it is in the center 2% of the carousel, set the `rootMargin` to `"0px -49%"`.  
+
+```javascript
+// Optional: detect support and apply a JS-based fallback
+if (!CSS.supports('container-type', 'scroll-state')) {
+  const observer = new IntersectionObserver((entries) => {
+    entries.forEach(entry => {
+      // Toggle a class based on intersection
+      entry.target.classList.toggle('is-snapped', entry.isIntersecting);
+    });
+  }, {
+    root: document.querySelector(".carousel"),
+    // Carousel item intersects if any part of the carousel item is in the middle 2% of the carousel.
+    rootMargin: "0px -49%"
+  });
+
+  document.querySelectorAll('.carousel-item').forEach(item => {
+    observer.observe(item);
+  });
+}
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/child-state-based-styling.md

@@ -0,0 +1,101 @@
+Historically, CSS selectors could only traverse downwards—you could style a child based on its parent, but not a parent based on its child. The `:has()` pseudo-class changes this, allowing you to conditionally style a container element depending on the presence or state of its descendants.
+
+By combining `:has()` with state pseudo-classes (like `:checked`, `:focus`, `:valid`, `:invalid`, or `:not()`), you can build complex, interactive UI components entirely in CSS, without needing JavaScript to toggle "modifier" classes (like `.is-active` or `.has-error`) on parent elements.
+
+This is particularly useful for components that need to respond to internal interactions, such as a localized theme toggle reacting to a checkbox (`:checked`), a form group highlighting an error (`:invalid`), or a card elevating when a child link is focused (`:focus-within`).
+
+### Implementing state-based container styling
+
+**MANDATORY**: You must use the `:has()` selector on the container element to detect the specific state (e.g., `:checked`, `:focus`, `:invalid`) of its interactive child element.
+
+To build a component that changes its styling based on a child's state:
+
+1. **Define the default styling**: Set CSS variables on the container to define its base state.
+2. **Apply state-based overrides**: Target the container with `:has([child-selector]:[state])` and redefine the CSS variables for the active or alternate state.
+
+*Example: A component that changes theme based on a child toggle.*
+
+```css
+/* 1. Define the default state on the component container */
+.theme-card {
+  /* Using custom properties makes state-switching cleaner */
+  --card-bg: #ffffff;
+  --card-text: #333333;
+  --card-border: #cccccc;
+
+  background-color: var(--card-bg);
+  color: var(--card-text);
+  border: 1px solid var(--card-border);
+
+  /* Use a transition for smooth state changes */
+  transition: background-color 0.3s, color 0.3s;
+}
+
+/* 2. Apply styles when the child enters the specific state */
+/* MANDATORY: Target the container and use :has() to check the descendant's state */
+.theme-card:has(.theme-toggle:checked) {
+  /* Override the properties for the active or alternate state */
+  --card-bg: #222222;
+  --card-text: #f0f0f0;
+  --card-border: #555555;
+}
+/* You can also combine :has() and :not() to target specific negative states */
+/* This selects a card that DOES NOT have a toggle in the checked state */
+.theme-card:not(:has(.theme-toggle:checked)) {
+  /* Optional: Explicit styles for the unchecked state if needed */
+}
+```
+
+```html
+<!-- The container element that receives the styling -->
+<div class="theme-card">
+  <!-- The child element whose state controls the parent -->
+  <label>
+    <input type="checkbox" class="theme-toggle">
+    Enable Dark Mode
+  </label>
+
+  <h2>Card Title</h2>
+  <p>The style of this entire card is controlled by the checkbox above.</p>
+</div>
+```
+
+**Performance tip**: When using `:has()`, scope the selector to the most specific container possible (like `.theme-card`). Avoid anchoring it to very high-level elements like `body:has(...)` if the styling changes are localized, as broad `:has()` queries can trigger more layout recalculations.
+
+### Fallback strategies
+
+Baseline status for :has(): Newly available. It's been Baseline since 2023-12-19.
+Supported by: Chrome 105 (Sep 2022), Edge 105 (Sep 2022), Firefox 121 (Dec 2023), and Safari 15.4 (Mar 2022).
+
+If the state-based styling is critical to the user experience or page layout, you must provide a fallback for browsers that do not support the `:has()` selector. For purely decorative effects, `:has()` can be used as a progressive enhancement without a fallback.
+
+**MANDATORY**: When implementing a fallback for critical features, you must use `@supports not selector(:has(*))` in your CSS to define a traditional class-based fallback. If the critical state change relies on user interaction, you must also use a small inline script with `CSS.supports()` to toggle that class based on the equivalent JavaScript event (e.g., `change`, `focus`, `blur`) representing the state change.
+
+```css
+/* Fallback CSS for older browsers */
+/* We check if the browser DOES NOT support the :has() selector */
+@supports not selector(:has(*)) {
+  /* Define a traditional modifier class that applies the exact same overrides */
+  .theme-card.is-active {
+    --card-bg: #222222;
+    --card-text: #f0f0f0;
+    --card-border: #555555;
+  }
+}
+```
+
+```javascript
+/* Fallback JavaScript for older browsers */
+/* Check for support before running the script to avoid unnecessary work in modern browsers */
+if (!CSS.supports('selector(:has(*))')) {
+  const toggle = document.querySelector('.theme-toggle');
+  const card = document.querySelector('.theme-card');
+
+  if (toggle && card) {
+    // Manually toggle the fallback class when the input state changes
+    toggle.addEventListener('change', (e) => {
+      card.classList.toggle('is-active', e.target.checked);
+    });
+  }
+}
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/complex-shapes.md

@@ -0,0 +1,73 @@
+## Overview
+To clip elements to complex, free-form shapes like brush strokes or organic textures, use CSS Masking (`mask-image`). While `clip-path` is excellent for geometric shapes or vector paths, `mask-image` allows you to use images (like PNGs with transparency) or SVGs to define the visible area of an element. This approach is more expressive because it supports semi-transparency, allowing for soft edges and complex textures that are difficult or impossible to achieve with `clip-path`.
+
+## Implementation
+To implement complex shapes using CSS masks:
+
+### Using transparency from an image
+You can use the transparency of an image as a mask, with opaque parts visible and transparent parts hidden. This can be a PNG, SVG, or other image with transparency, or a generated image, like a CSS gradient.
+
+```css
+.shaped-element {
+  /* MANDATORY: Use vendor prefix for wider support in older browsers */
+  -webkit-mask-image: url('mask.svg');
+  -webkit-mask-size: cover; /* Scale mask to cover element */
+  -webkit-mask-repeat: no-repeat; /* Do not tile the mask */
+
+  /* Standard property for modern browsers */
+  mask-image: url('mask.svg');
+  mask-size: cover;
+  mask-repeat: no-repeat;
+}
+```
+
+### Using an SVG element in HTML
+You can also reference a `<mask>` element defined in an inline SVG in your page's HTML. Use `maskContentUnits="objectBoundingBox"` to make the mask scale automatically with the size of the element. This tells the browser to interpret all coordinates inside the mask as fractions from `0` to `1` (like `0.5` for 50%) instead of absolute pixels.
+
+> **Luminance vs. Alpha Masking**: By default, SVG masks use **luminance** (brightness) to determine opacity, where white reveals, black hides, and gray creates semi-transparency. If you want the mask to use the **alpha channel** (transparency) of your SVG shapes instead, you can specify `mask-type: alpha;` in your CSS or `mask-type="alpha"` directly on the SVG `<mask>` element.
+
+```html
+<!-- White areas reveal content, gray creates semi-transparency, black or transparent hides it -->
+<svg width="0" height="0">
+  <defs>
+    <!-- objectBoundingBox scales mask coordinates (0 to 1) with the element's size -->
+    <mask id="custom-shape" maskContentUnits="objectBoundingBox">
+      <!-- Use white shapes to define fully opaque areas -->
+      <circle cx="0.5" cy="0.5" r="0.5" fill="white" />
+      <!-- Use gray shapes to define semi-transparent/faded areas -->
+      <circle cx="0.5" cy="0.5" r="0.25" fill="gray" />
+    </mask>
+  </defs>
+</svg>
+
+<div class="masked-content">
+  <!-- Content to be masked -->
+</div>
+
+<style>
+.masked-content {
+  /* Reference the SVG mask ID */
+  -webkit-mask-image: url(#custom-shape);
+  mask-image: url(#custom-shape);
+}
+</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:
+- The element will not be clipped and will display as a normal rectangle.
+- Ensure the content is still readable and the layout does not break without the mask (progressive enhancement).
+- Optionally, use feature detection to provide a simpler fallback shape with `clip-path`.
+
+```css
+/* Fallback for browsers that do not support masking */
+@supports (not (mask-image: url(x))) and (not (-webkit-mask-image: url(x))) {
+  .shaped-element {
+    /* Use a simple rounded rectangle as fallback */
+    clip-path: inset(5% round 15px);
+  }
+}
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/component-specific-light-dark-theme.md

@@ -0,0 +1,179 @@
+# Component-specific light/dark themes
+
+While more commonly set on the root, the `color-scheme` property can be set on individual elements to force them into a different color scheme from the rest of the page.
+This can be useful for components that must always be viewed in a specific color scheme (e.g. always in dark or light mode).
+
+Example use cases include:
+- Elements that are often in dark mode even on light mode pages for aesthetic reasons, e.g. code blocks, media players, photo galleries
+- Areas that contain media designed for a light background (e.g. images, videos, illustrations, print previews) can be set to light mode even if the rest of the page is in dark mode.
+- Elements whose color-scheme is controlled by a user-level setting, such as component previews
+- Embeds that don't support both light and dark modes
+- Design tools, maps, visualizations, games etc.
+
+## When to change colors vs. when to force `color-scheme`?
+
+Not every element that uses lighter text on darker background in light mode or darker text on lighter background in dark mode needs a different `color-scheme`.
+For example, a primary button may be rendered as blue with white text in light mode, but that does not warrant a `color-scheme: dark`.
+
+As a rule of thumb, typically elements using a different `color-scheme` are complex surfaces establishing their own visual context, rather than simple shallow containers.
+
+When considering using a different `color-scheme` on an element, ask yourself:
+
+- Should built-in browser UI that is not otherwise customized (e.g. form controls, scrollbars, etc) use that color-scheme or adapt to the page's color-scheme? -> if the former, don't use `color-scheme`.
+- Should any `light-dark()` colors resolve like they do for the rest of the page or based on the override? -> if the former, don't use `color-scheme`.
+- Should descendants be in that `color-scheme`? If not, don't use `color-scheme`.
+
+## Basic implementation
+
+Component-specific overrides are typically (though not strictly necessarily) used on pages that also support multiple color schemes via a global `color-scheme`.
+For implementing page-wide dark mode well, see `dark-mode` (via `npx -y modern-web-guidance@latest retrieve "dark-mode"`).
+
+Once a page-wide `color-scheme` is in place, and you are using color tokens sensitive to it (e.g. via `light-dark()`), you can simply set `color-scheme` on specific components to override the color mode for that subtree:
+
+```css
+pre, code, .dark {
+  color-scheme: dark;
+}
+```
+
+Note that some browsers automatically adapt components to a different color scheme anyway.
+To force the specified color scheme in all cases, use `only`, i.e. `color-scheme: only dark;` instead of `color-scheme: dark;`.
+
+### Adapting non-color values
+
+`light-dark()` currently only works for colors.
+
+## Best practices
+
+- **MANDATORY**: Do not set `color-scheme` on elements without a background, as that risks mixing background and text color pairs from different color-schemes, resulting in unreadable text.
+- **OPTIONAL**: While it is easier to reuse the same color pairs as the page-wide dark mode, we _can_ define different color pairs for these components. For example, we may want a dark mode component used in a light mode page to be a little less dark than when the same dark mode component is used in a page that is overall in dark mode.
+
+## Known issues to be aware of
+
+### Important gotcha: Inheritance of `light-dark()` colors
+
+**`light-dark()` resolves at computed value time.**
+This means that any inherited `<color>` properties set to a `light-dark()` color will only pass down one of the two colors to their descendants, not the `light-dark()` expression itself.
+
+This includes:
+- Built-in color properties that inherit, such as `color`, `accent-color`, `fill`, `stroke`, `text-shadow`, `caret-color`
+- Any registered inheritable custom properties with `syntax: <color>` and `inherits: true`
+- Any other `<color>` property set to `inherit`
+
+This means you should:
+- **NOT** register custom properties meant to hold *design tokens* (e.g. `--surface-color`) as `<color>`. Tokens need to keep their `light-dark()` expression live so descendants can re-resolve them under a different `color-scheme`.
+- When setting `color-scheme` on an element, re-specify any inherited `<color>` properties that may have been set to `light-dark()` values (directly or via design tokens), even if that's to the same design token.
+- **NOT** use `inherit` on `<color>` properties on elements with a `color-scheme` override (fine to use on their descendants).
+- **DO** use registered `<color>` properties for the *opposite* use case: when you deliberately want to snapshot the ancestor's resolved color and prevent it from re-resolving under the descendant's `color-scheme`. For example, capturing the page background to use elsewhere.
+- If you need to animate a color, use a separate `@property`-registered `<color>` property on the element being animated (registration is required for color interpolation) — this is not a design token, but a per-element animation target, so it does not conflict with the rule above.
+
+Example:
+
+```css
+:root {
+	--accent-color: light-dark(blue, skyblue);
+	--surface-color: light-dark(white, #222);
+	--text-color: light-dark(#111, white);
+
+	color-scheme: light dark;
+	accent-color: var(--accent-color);
+	color: var(--text-color);
+}
+
+body {
+	/* --surface-color dynamically switches despite being inherited because --surface-color is not registered */
+	background: var(--surface-color);
+}
+
+pre, code {
+	color-scheme: dark;
+	background: var(--surface-color);
+
+	/* Without this, accent-color would be blue, not skyblue! */
+	accent-color: var(--accent-color);
+
+	/* Without this, text-color would be #111, not white! */
+	color: var(--text-color);
+}
+```
+
+### Issues to be aware of when using color-scheme
+
+- Chrome and Firefox respect `color-scheme` for iframes: they render embedded pages in the correct color scheme and adjust the embedded page's `prefers-color-scheme` media query to reflect the embedding context's `color-scheme`. Safari does not, and resolves `prefers-color-scheme` to the system setting even inside iframes.
+  - **If you control both parent and iframe:** pass the parent's color scheme to the iframe explicitly — via a URL parameter (`?theme=dark`) at iframe construction time, or via `postMessage()` (which also lets you react to runtime changes). In the iframe, set a class on `<html>` (and/or `color-scheme` on `:root`) from that signal instead of relying on `prefers-color-scheme`.
+  - **If you only control the embedded page:** there is no reliable way to detect the embedding context's `color-scheme` from inside the iframe in Safari. Expose an explicit theme parameter on your embed API (e.g. a query string or `postMessage` protocol) and document it for embedders.
+
+## Fallback strategies
+
+### Fallbacks & browser support for color-scheme
+
+Baseline status for color-scheme: Widely available. It's been Baseline since 2022-02-03.
+Supported by: Chrome 98 (Feb 2022), Edge 98 (Feb 2022), Firefox 96 (Jan 2022), and Safari 13 (Sep 2019).
+
+The `color-scheme` property is **progressive enhancement**.
+Browsers that do not support it will ignore this property and use their default light-mode UI.
+
+To adapt to the user's preferences in older browsers, use `prefers-color-scheme` media queries to provide different colors when dark mode is preferred.
+
+- DO use the media query to switch custom properties on `:root` or `html`
+- Avoid using the media query on individual components unless the component requires a very specific type of dark mode customization beyond colors.
+
+```css
+:root {
+  /* Define brand colors for each mode */
+  --color-brand-light: #0056b3;
+  --color-brand-dark: #00e5ff;
+  --color-brand: var(--color-brand-light);
+
+  /* MANDATORY: Fallback for browsers without light-dark support */
+  @media (prefers-color-scheme: dark) {
+    --color-brand: var(--color-brand-dark);
+  }
+
+  /* Ignored in older browsers */
+  color-scheme: light dark;
+}
+
+button.primary {
+	background-color: var(--color-brand);
+}
+```
+
+### Fallbacks & browser support for light-dark()
+
+Baseline status for light-dark(): Newly available. It's been Baseline since 2024-05-13.
+Supported by: Chrome 123 (Mar 2024), Edge 123 (Mar 2024), Firefox 120 (Nov 2023), and Safari 17.5 (May 2024).
+
+For browsers that support `color-scheme` but not yet `light-dark()`, light and dark versions of colors should first be defined as custom properties, and the `prefers-color-scheme` media query should be used to set colors for the respective mode like in the example below:
+
+```css
+:root {
+  /* Define browser UI accent color for each mode */
+  --brand-accent-light: #0056b3;
+  --brand-accent-dark: #00e5ff;
+  --accent-color: var(--brand-accent-light);
+
+  /* MANDATORY: Fallback for browsers without light-dark support */
+  @media (prefers-color-scheme: dark) {
+    --accent-color: var(--brand-accent-dark);
+  }
+
+  /* OPTIONAL: use light-dark() for more control of built-in UI colors */
+  @supports (color: light-dark(white, black)) {
+    --accent-color: light-dark(var(--brand-accent-light), var(--brand-accent-dark));
+  }
+
+  /* MANDATORY: Automatically adapt native UI to user system preferences */
+  color-scheme: light dark;
+
+  /* Example inherited color property */
+  accent-color: var(--accent-color);
+}
+
+pre, code {
+  color-scheme: dark;
+
+  /* **Mandatory**: any inherited color properties must be set again, even if to the same design tokens */
+  accent-color: var(--accent-color);
+}
+```