@olives/devos 2.1.0

package/.agents/skills/modern-web-guidance/guides/user-experience/expose-canvas-content-to-browser-features.md

@@ -0,0 +1,401 @@
+# Expose canvas content to browser features
+
+Regular `<canvas>` content is not exposed to browser features such as screen readers, indexing, translation tools, accessibility assistive tools, find-in-page, print, etc. With `HTML in canvas`, you can render real DOM directly in a canvas element. Adding the `layoutsubtree` attribute to a `<canvas>` HTML element allows rendering descendant HTML elements within the canvas's rendering context. You can use it to style and lay out text in a canvas, expose canvas content to browser features (like accessibility, translation, or find-in-page), and apply 2D and 3D effects to HTML.
+
+## How to implement
+
+1. Check if HTML-in-Canvas is supported in the browser:
+
+```
+if ('requestPaint' in HTMLCanvasElement.prototype) {
+  // Use HTML in Canvas API
+} else {
+  // Use fallback strategy
+}
+```
+
+2. Add the `layoutsubtree` attribute to the `<canvas>` HTML element.
+3. Place your HTML content inside the `<canvas>` element with the `layoutsubtree` attribute.
+
+```html
+<canvas id="canvas" layoutsubtree>
+  <div id="html-content"></div>
+</canvas>
+```
+
+4. Scale your canvas grid to match the device scale factor to prevent blurriness:
+
+```js
+const observer = new ResizeObserver(([entry]) => {
+  const dpc = entry.devicePixelContentBoxSize;
+  canvas.width = dpc
+    ? dpc[0].inlineSize
+    : Math.round(entry.contentRect.width * window.devicePixelRatio);
+  canvas.height = dpc
+    ? dpc[0].blockSize
+    : Math.round(entry.contentRect.height * window.devicePixelRatio);
+});
+
+const supportsDevicePixelContentBox =
+  typeof ResizeObserverEntry !== "undefined" &&
+  "devicePixelContentBoxSize" in ResizeObserverEntry.prototype;
+const options = supportsDevicePixelContentBox
+  ? { box: "device-pixel-content-box" }
+  : {};
+observer.observe(canvas, options);
+```
+
+5. Render the HTML content to the canvas inside a `canvas.onpaint` event handler:
+
+- In 2D context, use the `drawElementImage` method:
+
+```js
+canvas.onpaint = () => {
+  ctx.reset();
+  // Draw the form element at x:0, y:0
+  let transform = ctx.drawElementImage(form_element, 0, 0);
+};
+```
+
+- In WebGL context, use the `texElementImage2D` method:
+
+```js
+canvas.onpaint = () => {
+  if (gl.texElementImage2D) {
+    try {
+      gl.texElementImage2D(gl.TEXTURE_2D, gl.RGBA8, uiElement);
+    } catch (err) {
+      console.error('texElementImage2D copy failed:', err);
+    }
+  }
+};
+```
+
+- In WebGPU context, use the `copyElementImageToTexture` method:
+
+```js
+canvas.onpaint = () => {
+  if (root.device.queue.copyElementImageToTexture) {
+    try {
+      const sourceDict = { source: valueElement };
+      const destDict = {
+        destination: { texture: targetTexture },
+        width: 512,
+        height: 128,
+      };
+      root.device.queue.copyElementImageToTexture(sourceDict, destDict);
+    } catch (err) {
+      console.error('copyElementImageToTexture copy failed:', err);
+    }
+  }
+};
+```
+
+When using a `requestAnimationFrame` loop to render the scene, call `canvas.requestPaint()` within the loop to ensure that the HTML content is rendered to the canvas. Make sure you only re-render the canvas if there has been an update to the descendant HTML elements:
+
+```js
+function render() {
+  // Request to update the canvas
+  canvas.requestPaint();
+  requestAnimationFrame(render);
+}
+requestAnimationFrame(render);
+
+canvas.onpaint = (event) => {
+  if (event.changedElements && event.changedElements.length > 0) {
+    // Update the texture with drawElementImage, texElementImage2D, or copyElementImageToTexture, and update the CSS transform as shown in step 6
+  }
+};
+```
+
+6. Update the CSS transform.
+
+- For the 2D context case, apply the transform returned by the rendering call to the `style.transform` property:
+
+```js
+canvas.onpaint = () => {
+  ctx.reset();
+  // Draw the form element at x:0, y:0
+  let transform = ctx.drawElementImage(form_element, 0, 0);
+
+  // Sync the DOM location with the drawn location
+  form_element.style.transform = transform.toString();
+};
+```
+
+- For the 3D case with WebGL or WebGPU, the browser needs to map from the 3D coordinate space into the CSS coordinate space using a viewport transform. To facilitate this, do the following:
+  - Convert WebGL MVP Matrix to DOM Matrix.
+  - Normalize the HTML element. HTML elements are sized in pixels (for example, 200px wide). WebGL, however, usually treats objects as "unit squares", for example, ranging from 0 to 1. If you don't normalize, your 200px button will look 200 times larger.
+  - Map to the canvas viewport. This step is the "re-scaling" phase: it stretches that unit-space math back out to match the actual pixel dimensions of your `<canvas>` element on the screen. It also flips the Y-axis, because in WebGL, up is positive, but in CSS, down is positive.
+  - Calculate the final transform. Multiply the matrices in order: Viewport _ MVP _ Normalization. Combining them into one final transform produces a "map" that tells the browser exactly where that HTML element layer should sit to align with the 3D drawing.
+  - Apply the transform to the HTML element. This moves the HTML element layer to sit directly on top of its rendered pixels. This ensures that when a user clicks a button or selects text, they are actually hitting the real HTML element.
+
+  ```js
+  if (canvas.getElementTransform) {
+    // 1. Convert WebGL MVP Matrix to DOM Matrix
+    const mvpDOM = new DOMMatrix(Array.from(htmlElementMVP));
+
+    // 2. Normalize the HTML element (Canvas Grid pixels -> WebGL Model Space)
+    const dprX = canvas.width / canvas.clientWidth;
+    const dprY = canvas.height / canvas.clientHeight;
+    const gridWidth = targetHTMLElement.offsetWidth * dprX;
+    const gridHeight = targetHTMLElement.offsetHeight * dprY;
+
+    const toGLModel = new DOMMatrix()
+      // Scale pixels to 1 unit, flip Y (as in CSS it points down, and in WebGL it points up)
+      .scale(1 / gridWidth, -1 / gridHeight, 1 / gridHeight)
+      // Center the origin: (0,0) becomes (-width/2, -height/2) before scaling
+      .translate(-gridWidth / 2, -gridHeight / 2);
+
+    // 3. Map to the canvas viewport
+    const clipToCanvasViewport = new DOMMatrix()
+      // Move center (0,0) to center of canvas
+      .translate(canvas.width / 2, canvas.height / 2)
+      // Scale normalized clip (-1..1) to viewport size
+      .scale(canvas.width / 2, -canvas.height / 2, canvas.height / 2);
+
+    // 4. Multiply: (Clip -> Pixels) * (MVP) * (pixels -> unit square)
+    const screenSpaceTransform = clipToCanvasViewport
+      .multiply(mvpDOM)
+      .multiply(toGLModel);
+
+    // 5. Apply to the transform
+    const computedTransform = canvas.getElementTransform(
+      targetHTMLElement,
+      screenSpaceTransform,
+    );
+    targetHTMLElement.style.transform = computedTransform.toString();
+  }
+  ```
+
+7. [Troubleshooting] If the developer is experiencing a mismatch in the DOM logical layout in 3D even after applying the CSS transform from step 5, check if the developer is experiencing the issue in Chromium 148 or earlier. If that's the case, check if `transform.is2D` is correctly set to false for a 3D DOMMatrix. If not, re-initialize the DOMMatrix which corrects `is2D` to be false before applying the transform to the target HTML element. This issue is fixed in Chromium 149+, and if the developer is experiencing it in newer Chromium versions, the is2D value is not the cause:
+
+```js
+if (transform.is2D) {
+  // Workaround for Chromium bug https://crbug.com/512171941
+  // affecting Chrome versions under 149 where `transform.is2D`
+  // is incorrectly true for a 3D DOMMatrix. The assignment
+  // below re-initializes the DOMMatrix which corrects is2D to be false.
+  transform = DOMMatrix.fromFloat64Array(transform.toFloat64Array());
+}
+targetHTMLElement.style.transform = computedTransform.toString();
+```
+
+## Example code
+
+### 2D Canvas
+
+```html
+<canvas id="canvas" layoutsubtree style="width: 400px; height: 200px;">
+  <div id="ui-element">
+    <p>
+      This text is rendered inside the canvas but is present in the DOM tree.
+    </p>
+    <input type="email" name="email" placeholder="enter your email" />
+    <button type="button">Submit</button>
+  </div>
+</canvas>
+
+<script>
+  const canvas = document.getElementById("canvas");
+  const ctx = canvas.getContext("2d");
+  const uiElement = document.getElementById("ui-element");
+
+  canvas.onpaint = () => {
+    ctx.reset();
+    // Draw the HTML element at x:0, y:0
+    const transform = ctx.drawElementImage(uiElement, 0, 0);
+
+    // Sync the DOM location with the drawn location
+    uiElement.style.transform = transform.toString();
+  };
+
+  // Handle resizing to match device pixels
+  const observer = new ResizeObserver(([entry]) => {
+    const dpc = entry.devicePixelContentBoxSize;
+    canvas.width = dpc
+      ? dpc[0].inlineSize
+      : Math.round(entry.contentRect.width * window.devicePixelRatio);
+    canvas.height = dpc
+      ? dpc[0].blockSize
+      : Math.round(entry.contentRect.height * window.devicePixelRatio);
+    canvas.requestPaint();
+  });
+
+  const supportsDevicePixelContentBox =
+    typeof ResizeObserverEntry !== "undefined" &&
+    "devicePixelContentBoxSize" in ResizeObserverEntry.prototype;
+  const options = supportsDevicePixelContentBox
+    ? { box: "device-pixel-content-box" }
+    : {};
+  observer.observe(canvas, options);
+</script>
+```
+
+### WebGL Canvas
+
+```html
+<canvas id="canvas" layoutsubtree style="width: 400px; height: 400px;">
+  <div id="ui-element">
+    <p>WebGL UI Element</p>
+    <button>Action</button>
+  </div>
+</canvas>
+
+<script>
+  const canvas = document.getElementById("canvas");
+  const gl = canvas.getContext("webgl");
+  const uiElement = document.getElementById("ui-element");
+
+  // Setup WebGL texture...
+  const texture = gl.createTexture();
+  gl.bindTexture(gl.TEXTURE_2D, texture);
+
+  canvas.onpaint = () => {
+    // 1. Update texture with HTML content
+    if (gl.texElementImage2D) {
+      try {
+        gl.texElementImage2D(gl.TEXTURE_2D, gl.RGBA8, uiElement);
+      } catch (err) {
+        console.error('texElementImage2D copy failed:', err);
+      }
+    }
+
+    // ... Render your 3D scene here, calculating htmlElementMVP matrix ...
+
+    // 2. Sync DOM position with 3D scene
+    if (canvas.getElementTransform) {
+      const mvpDOM = new DOMMatrix(Array.from(htmlElementMVP));
+
+      // Recalculate the DPR compensation mapping
+      const dprX = canvas.width / canvas.clientWidth;
+      const dprY = canvas.height / canvas.clientHeight;
+      const gridWidth = uiElement.offsetWidth * dprX;
+      const gridHeight = uiElement.offsetHeight * dprY;
+
+      const cssToUnitSpace = new DOMMatrix()
+        .scale(1 / gridWidth, -1 / gridHeight, 1 / gridHeight)
+        .translate(-gridWidth / 2, -gridHeight / 2);
+
+      const clipToCanvasViewport = new DOMMatrix()
+        .translate(canvas.width / 2, canvas.height / 2)
+        .scale(canvas.width / 2, -canvas.height / 2, canvas.height / 2);
+
+      const screenSpaceTransform = clipToCanvasViewport
+        .multiply(mvpDOM)
+        .multiply(cssToUnitSpace);
+
+      const computedTransform = canvas.getElementTransform(
+        uiElement,
+        screenSpaceTransform,
+      );
+      uiElement.style.transform = computedTransform.toString();
+    }
+  };
+</script>
+```
+
+### WebGPU Canvas
+
+```html
+<canvas id="canvas" layoutsubtree style="width: 400px; height: 400px;">
+  <div id="ui-element">
+    <p>WebGPU UI Element</p>
+  </div>
+</canvas>
+
+<script>
+  const canvas = document.getElementById("canvas");
+  const context = canvas.getContext("webgpu");
+  const uiElement = document.getElementById("ui-element");
+
+  // Setup WebGPU...
+  // const device = ...
+  // const targetTexture = ...
+
+  canvas.onpaint = () => {
+    // 1. Copy HTML content to texture
+    if (device.queue.copyElementImageToTexture) {
+      try {
+        const sourceDict = { source: uiElement };
+        const destDict = {
+          destination: { texture: targetTexture },
+          width: width,
+          height: height,
+        };
+        device.queue.copyElementImageToTexture(sourceDict, destDict);
+      } catch (err) {
+        console.error('copyElementImageToTexture copy failed:', err);
+      }
+    }
+
+    // 2. Sync DOM position (same matrix math as WebGL)
+    if (canvas.getElementTransform) {
+      const mvpDOM = new DOMMatrix(Array.from(htmlElementMVP));
+
+      // Recalculate the DPR compensation mapping
+      const dprX = canvas.width / canvas.clientWidth;
+      const dprY = canvas.height / canvas.clientHeight;
+      const gridWidth = uiElement.offsetWidth * dprX;
+      const gridHeight = uiElement.offsetHeight * dprY;
+
+      const cssToUnitSpace = new DOMMatrix()
+        .scale(1 / gridWidth, -1 / gridHeight, 1 / gridHeight) // Retain Z scale
+        .translate(-gridWidth / 2, -gridHeight / 2);
+
+      const clipToCanvasViewport = new DOMMatrix()
+        .translate(canvas.width / 2, canvas.height / 2)
+        .scale(canvas.width / 2, -canvas.height / 2, canvas.height / 2); // Retain Z scale
+
+      const screenSpaceTransform = clipToCanvasViewport
+        .multiply(mvpDOM)
+        .multiply(cssToUnitSpace);
+
+      const computedTransform = canvas.getElementTransform(
+        uiElement,
+        screenSpaceTransform,
+      );
+      uiElement.style.transform = computedTransform.toString();
+    }
+  };
+</script>
+```
+
+## Best Practices
+
+- **MANDATORY**: Check browser support for the HTML-in-Canvas API before using it.
+- **MANDATORY**: Always add the `layoutsubtree` attribute to the `<canvas>` element.
+- **MANDATORY**: Use an `onpaint` event handler to render the HTML content to the canvas.
+- **MANDATORY**: Use the `drawElementImage`, `texElementImage2D`, or `copyElementImageToTexture` methods to render the HTML content to the canvas.
+- **MANDATORY**: Update the CSS transform of the HTML element to match the transform of the rendered content by setting the `style.transform` property of the HTML element.
+- **MANDATORY**: Use `ResizeObserver` to observe the screen size and update the canvas size to match device pixels.
+- **DO NOT** embed cross-origin content in a canvas, as it is not supported.
+- **DO NOT** initialize `ResizeObserver` within the `onpaint` event handler, as it may lead to memory leaks.
+
+## Fallback strategies
+
+HTML in canvas is not natively supported by any major browser yet.
+
+The HTML-in-Canvas API is not currently supported in all modern browsers, thus a fallback strategy is typically required.
+
+However, given the improved performance benefits of this API, HTML-in-Canvas should be used if the browser supports it.
+
+The fallback strategy depends on the use case. For example, for an interactive HTML content in canvas, if HTML-in-Canvas is not supported, place the HTML content on top of the canvas using CSS.
+
+### HTML-in-Canvas polyfills
+
+Use the following polyfill script to mimic the HTML-in-Canvas API in browsers that do not support it.
+
+1. Install or embed the library:
+
+```
+# Install
+npm install three-html-render
+```
+
+```
+# Embed
+<script src="https://cdn.jsdelivr.net/npm/three-html-render/dist/polyfill.js"></script>
+```
+
+2. Run the `installHtmlInCanvasPolyfill()` method to translate HTML-in-Canvas.

package/.agents/skills/modern-web-guidance/guides/user-experience/flicker-free-client-side-ab-testing.md

@@ -0,0 +1,168 @@
+# Flicker-Free Client-Side A/B Testing
+
+## The Problem
+
+Client-side A/B testing tools work by loading a script that modifies the DOM after the browser has already begun constructing the page. Without intervention, the user briefly sees the original content before it flickers or flashes to the experiment variant. Testing platforms have historically worked around this with "anti-flicker snippets" that hide the entire page with `opacity: 0` until the experiment script finishes or an arbitrary timeout (typically 4 seconds) elapses. This approach sacrifices progressive rendering, allows accidental clicks on invisible content, and introduces unnecessary paint cycles.
+
+## The Solution
+
+The `blocking=render` attribute allows a `<script>` or `<link>` element placed in the `<head>` to block rendering—but not parsing—until the resource has been fetched and executed. This gives experimentation scripts the same render-blocking behavior that stylesheets have by default, ensuring the browser never paints the page until the experiment variant has been applied. No opacity hacks, no arbitrary timeouts, and no flicker.
+
+### Implementation Strategy
+
+1. **MANDATORY:** Place the experimentation script in the document `<head>` and add `blocking="render"`.
+2. **MANDATORY:** Ensure the script either has `type="module"` (preferred for inline scripts) or `async` (preferred for external scripts with a `src` value).
+3. **DO** keep the experimentation script small and fast. Because rendering is blocked until the script executes, a large or slow script directly delays first paint.
+4. **DO NOT** use `blocking="render"` on scripts that do not need to run before first paint. It is intended only for scripts whose output must be visible in the initial render.
+5. **DO NOT** apply `blocking="render"` to scripts outside the `<head>`. Only scripts in the `<head>` can block rendering.
+
+## Implementation Guide
+
+### Basic Setup
+
+MANDATORY: Load the experimentation script with both `async` and `blocking="render"`. The `async` attribute ensures the script does not block HTML parsing (the browser continues building the DOM while fetching the script). The `blocking="render"` attribute ensures the browser does not paint anything until the script has executed.
+
+```html
+<head>
+  <!--
+    MANDATORY: Both `async` and `blocking="render"` are required.
+    - `async`: Prevents parser-blocking, so the DOM is built in parallel.
+    - `blocking="render"`: Holds rendering until the script executes,
+      ensuring experiment changes are applied before the user sees anything.
+  -->
+  <script
+    src="https://cdn.example.com/experiment-sdk.js"
+    async
+    blocking="render"
+  ></script>
+</head>
+```
+
+### Loading Experiment-Specific Styles
+
+If the experiment requires a variant stylesheet, use `blocking="render"` on the `<link>` element. Stylesheets in the `<head>` already block rendering by default, but dynamically injected stylesheets or those added via script do not. Use `blocking="render"` explicitly when the stylesheet is added dynamically or when you want to be explicit about the intent.
+
+```html
+<head>
+  <!--
+    DO: Use blocking="render" on experiment stylesheets that are
+    dynamically inserted or conditionally loaded by the experiment SDK.
+    This ensures variant styles are applied before first paint.
+  -->
+  <link
+    rel="stylesheet"
+    href="https://cdn.example.com/experiment-variant-b.css"
+    blocking="render"
+  >
+</head>
+```
+
+### Inline Experiment Script
+
+If the experiment logic is lightweight enough to inline, use an inline module script with `blocking="render"`. This is useful when the experiment logic fetches a configuration and applies DOM changes directly.
+
+```html
+<head>
+  <!--
+    DO: Use an inline module script when the experiment logic is small.
+    Module scripts are deferred by default (non-parser-blocking),
+    and blocking="render" ensures rendering waits for execution.
+  -->
+  <script type="module" blocking="render">
+    // Fetch the experiment configuration from your testing platform.
+    const config = await fetch('/api/experiment?id=homepage-cta')
+      .then(res => res.json());
+
+    // Apply the variant by setting a data attribute on <html>.
+    // CSS rules keyed to this attribute will style the variant.
+    document.documentElement.dataset.variant = config.variant;
+  </script>
+
+  <style>
+    /* Default styles (control group) */
+    .cta-button {
+      background-color: blue;
+    }
+
+    /* Variant B styles, activated by the data attribute */
+    [data-variant="b"] .cta-button {
+      background-color: green;
+    }
+  </style>
+</head>
+```
+
+## Best Practices
+
+- **MANDATORY:** The experimentation script MUST execute quickly. A slow script delays all rendering. Set a performance budget (e.g., under 100ms execution time) for the render-blocking script.
+- **DO** split heavy experiment logic from the render-blocking script. Load a small, render-blocking stub that applies the variant, then load heavier tracking or analytics scripts separately with `async` or `defer` (without `blocking="render"`).
+- **DO** use a data attribute on `<html>` or `<body>` to signal the active variant, and use CSS selectors keyed to that attribute for variant styling. This avoids direct DOM manipulation in the render-blocking script.
+- **DO NOT** use `blocking="render"` on analytics, tracking, or other non-visual scripts. Only scripts that must change what the user sees on first paint should block rendering.
+- **DO NOT** combine `blocking="render"` with legacy anti-flicker snippets. They solve the same problem; using both creates unnecessary delays.
+
+## Fallback Strategies
+
+blocking="render" has limited availability.
+Supported by: Chrome 105 (Sep 2022), Edge 105 (Sep 2022), and Safari 18.2 (Dec 2024).
+Unsupported in: Firefox.
+
+The `blocking` attribute is not supported in all browsers. In browsers that do not support it, the attribute is ignored and the script loads with its default behavior (`async` in the examples above), which may result in flicker. A fallback is required to prevent flicker in unsupported browsers.
+
+### Fallback: Anti-Flicker Snippet
+
+DO: Use a lightweight anti-flicker snippet as a fallback only when `blocking="render"` is not supported. Feature-detect support and skip the fallback in browsers that handle it natively.
+
+```html
+<head>
+  <!--
+    DO: Load the experiment script with blocking="render" for
+    browsers that support it. This is the preferred approach.
+  -->
+  <script
+    src="https://cdn.example.com/experiment-sdk.js"
+    async
+    blocking="render"
+  ></script>
+
+  <script>
+    // DO: Only apply the anti-flicker fallback in browsers
+    // that do not support blocking="render".
+    if (!Object.hasOwn(HTMLScriptElement.prototype, 'blocking')) {
+      // Hide the page until the experiment script runs.
+      document.documentElement.classList.add('ab-loading');
+
+      // DO: Set a timeout to reveal the page if the experiment
+      // script takes too long. This prevents an indefinitely
+      // blank page on slow connections. Adjust the timeout
+      // to match your experiment SDK's expected load time.
+      setTimeout(() => {
+        document.documentElement.classList.remove('ab-loading');
+      }, 4000);
+    }
+  </script>
+
+  <style>
+    /*
+      DO: Use opacity to hide content during experiment loading.
+      This is only applied when blocking="render" is unsupported.
+    */
+    .ab-loading {
+      opacity: 0 !important;
+    }
+  </style>
+</head>
+```
+
+```javascript
+// DO: In your experiment SDK's initialization callback,
+// remove the fallback class to reveal the page.
+function onExperimentReady() {
+  document.documentElement.classList.remove('ab-loading');
+}
+```
+
+## Other Considerations
+
+1. **Performance Impact**: `blocking="render"` trades first-paint speed for visual correctness. Monitor Largest Contentful Paint (LCP) and First Contentful Paint (FCP) to ensure the experimentation script is not adding excessive delay.
+2. **Third-Party Script Reliability**: If the experiment SDK is hosted on a third-party CDN, a CDN outage could block rendering entirely. The browser applies its own timeout heuristics (which may be longer than 4 seconds), but there is no developer-controlled timeout for `blocking="render"`. Ensure the third-party provider has strong uptime guarantees.
+3. **Server-Side Alternatives**: For performance-critical pages, consider server-side A/B testing (where the server renders the correct variant directly) instead of client-side testing. Server-side approaches eliminate flicker entirely without any render-blocking cost. Use client-side `blocking="render"` only when server-side testing is not feasible.

package/.agents/skills/modern-web-guidance/guides/user-experience/fluid-scaling.md

@@ -0,0 +1,78 @@
+## Overview
+
+Fluid scaling allows components to adjust their internal proportions (like font sizes and spacing) based on their current dimensions. This creates a more cohesive design than jumping between fixed breakpoints.
+
+While fluid scaling was historically achieved using viewport units (scaling based on the screen size), modern container query units allow components to scale relative to their parent container instead. This ensures components look good regardless of where they are placed in a layout, promoting better component isolation and reusability.
+
+## Implementation
+
+### 1. Define a container
+
+To use container query units, you must first define a containment context on a parent element.
+
+```css
+.component-wrapper {
+  /* Define the container type. Use 'inline-size' for width-based scaling. */
+  /* You can also use 'size' for both width and height, but it requires explicit sizing. */
+  container-type: inline-size;
+  
+  /* Optional: Name the container for specific targeting */
+  container-name: fluid-card;
+}
+```
+
+### 2. Use container query units
+
+Use container query units (`cqi`, `cqb`, etc.) to set sizes relative to the container's dimensions.
+
+*   `cqi`: 1% of the container's inline size (width in horizontal writing modes).
+*   `cqb`: 1% of the container's block size (height in horizontal writing modes).
+
+**Note**: Container units can be used directly on any property without needing an `@container` query rule. They automatically resolve based on the nearest ancestor with a defined `container-type`.
+
+```css
+.component-title {
+  /* Scale font size based on container width */
+  /* 10cqi means 10% of the container's width */
+  font-size: 10cqi;
+}
+
+.component-body {
+  /* Scale padding based on container width */
+  padding: 5cqi;
+}
+```
+
+### 3. Constrain values with `clamp()`
+
+To prevent sizes from becoming too small or too large, use the CSS `clamp()` function. This impacts the user's ability to zoom or adjust their base font size. To ensure text meets accessibility guidelines, the maximum size must not be more than 2.5 times the minimum size.
+
+```css
+.component-title {
+  /* Clamp font size between 1rem and 2.5rem, scaling with 5% of container width */
+  font-size: clamp(1rem, 5cqi, 2.5rem);
+}
+```
+
+### Fallback strategies
+
+Baseline status for Container queries: Widely available. It's been Baseline since 2023-02-14.
+Supported by: Chrome 105 (Sep 2022), Edge 105 (Sep 2022), Firefox 110 (Feb 2023), and Safari 16 (Sep 2022).
+
+If container queries are not supported by the browser, you should provide a fallback using viewport units or standard media queries.
+
+```css
+.component-title {
+  /* Fallback for browsers that do not support container units */
+  font-size: clamp(1rem, 5vw, 2.5rem);
+}
+
+@supports (font-size: 1cqi) {
+  .component-title {
+    /* Use container units where supported */
+    font-size: clamp(1rem, 5cqi, 2.5rem);
+  }
+}
+```
+
+This fallback ensures that the text still scales, but it will be based on the screen width rather than the component's width. This should be tested to verify it works in your use case.