@olives/devos 2.1.0

package/.agents/skills/modern-web-guidance/guides/user-experience/format-human-readable-durations.md

@@ -0,0 +1,87 @@
+# Formatting Human-Readable Durations with Temporal
+
+Presenting elapsed time or durations to users in a readable format (e.g., "1 hour and 30 minutes") has historically required manual math or external libraries. The `Temporal` API's `Temporal.Duration` class simplifies this by providing structured duration objects and powerful "balancing" capabilities via the `round()` method.
+
+## How to Implement
+
+To format a duration:
+
+1.  (**MANDATORY**) **Create a Duration**: Use `Temporal.Duration.from()` to create a duration object from a set of units.
+2.  (**OPTIONAL**) **Apply Balancing**: Use the `round()` method with the `largestUnit` option to control how units are balanced. For example, to convert 90 minutes into hours and minutes, or to keep it as total minutes.
+3.  (**MANDATORY**) **Build the Display String**: Access the specific unit properties (like `.hours`, `.minutes`) to construct the human-readable string manually, or **(Recommended)** use `Intl.DurationFormat` for a localized, automatic approach.
+
+### Example: Balancing and Localized Formatting
+
+```javascript
+// 1. Create a duration (e.g., from user input)
+const duration = Temporal.Duration.from({ minutes: 90 });
+
+// 2. Balance to hours (converts 90 minutes to 1 hour and 30 minutes)
+const balanced = duration.round({ largestUnit: 'hours' });
+
+// 3. Format using Intl.DurationFormat (Handles pluralization automatically)
+const formatter = new Intl.DurationFormat('en', { style: 'long' });
+console.log(formatter.format(balanced));
+// Note: Output may vary by browser (e.g., "1 hour and 30 minutes" or "1 hour, 30 minutes")
+```
+
+### Best Practices
+
+*   **DO** use `Temporal.Duration.round()` with `largestUnit` to control the display strategy (detailed breakdown vs total count).
+*   **DO** use `Intl.DurationFormat` for localized string formatting and automatic pluralization, or fall back to manual construction if not supported. 
+*   **DO NOT** rely on `Temporal.Duration.prototype.toString()` for user-facing text; it returns ISO 8601 strings (e.g., `PT1H30M`).
+*   **DO** use feature detection and a polyfill for environments lacking native support.
+
+## Fallback strategies
+
+### Fallbacks & browser support for Temporal
+
+Temporal has limited availability.
+Supported by: Chrome 144 (Jan 2026), Edge 144 (Jan 2026), and Firefox 139 (May 2025).
+Unsupported in: Safari.
+
+For browsers that do not yet support the native `Temporal` API, use feature detection and a polyfill. The standard reference polyfill is `@js-temporal/polyfill`.
+
+Note that the polyfill does not automatically assign the `Temporal` object to the global scope to avoid conflicts. You must manually assign it if your code relies on the global `Temporal` object.
+
+```javascript
+// Check if Temporal is supported natively
+(async () => {
+  if (typeof Temporal === 'undefined') {
+    // Load the polyfill conditionally
+    const module = await import("https://esm.sh/@js-temporal/polyfill");
+    globalThis.Temporal = module.Temporal;
+    // Extend Date.prototype if needed
+    Date.prototype.toTemporalInstant = module.toTemporalInstant;
+    initializeApp();
+  }
+})();
+```
+
+### Intl.DurationFormat
+
+Baseline status for Intl.DurationFormat: Newly available. It's been Baseline since 2025-03-04.
+Supported by: Chrome 129 (Sep 2024), Edge 129 (Sep 2024), Firefox 136 (Mar 2025), and Safari 16.4 (Mar 2023).
+
+If `Intl.DurationFormat` is not supported, you should feature-detect it and fall back to manual string construction by extracting the balanced duration properties.
+
+* **Guidance:** Use `typeof Intl.DurationFormat !== 'undefined'` to check for support. If unsupported, extract properties like `.hours` and `.minutes` from the balanced `Temporal.Duration` object and combine them, handling pluralization properly.
+
+```javascript
+// 3. Format the display string
+
+if (typeof Intl.DurationFormat !== 'undefined') {
+  // Use recommended Intl API if available
+  const formatter = new Intl.DurationFormat('en', { style: 'long' });
+  console.log(formatter.format(balanced));
+} else {
+  // Fallback manual formatting (assuming duration is already balanced)
+  const h = balanced.hours;
+  const m = balanced.minutes;
+
+  const hoursStr = `${h} hour${h === 1 ? '' : 's'}`;
+  const minutesStr = `${m} minute${m === 1 ? '' : 's'}`;
+
+  console.log(`${hoursStr} and ${minutesStr}`);
+}
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/group-element-transitions.md

@@ -0,0 +1,124 @@
+As items are added or removed from a list, or rearranged, transitions can help users maintain context. View transitions provide a way to transition between two states of an element by giving the element a unique `view-transition-name`. When multiple elements on a page share the same transition behavior, `view-transition-class` allows you to define that logic once in CSS rather than repeating it for every unique `view-transition-name`. This keeps your stylesheets maintainable while ensuring consistent animations across a group of elements.
+
+### Implementation steps
+
+1. **Assign unique names and a shared class**
+
+Each element that needs to be tracked individually during a transition must have a unique `view-transition-name`.
+
+```html
+<!-- Mandatory: Each element must have a unique view-transition-name -->
+<li style="view-transition-name: item-1" class="item">Item 1</li>
+<li style="view-transition-name: item-2" class="item">Item 2</li>
+```
+
+To apply shared styles, also assign a `view-transition-class`.
+
+```css
+.item {
+  view-transition-class: list-item;
+}
+```
+
+2. **Define the shared transition logic**
+   
+Use the `::view-transition-group()` pseudo-element with the class selector to apply styles to all members of that group.
+
+```css
+/* Targets any view transition group that has the 'list-item' class */
+::view-transition-group(.list-item) {
+  animation-duration: 0.5s;
+  animation-timing-function: ease-in-out;
+}
+
+/* Handle accessibility by respecting motion preferences */
+@media (prefers-reduced-motion: reduce) {
+  /* Disable all group transitions, including the default `root` group. */
+  ::view-transition-group(*),
+  ::view-transition-old(*),
+  ::view-transition-new(*) {
+    animation: none !important;
+  }
+}
+```
+
+3. **Optional: Define entry and exit animations**
+
+Use the `:only-child` selector to add specific transitions to the elements that are added or removed. `::view-transition-new()` and `::view-transition-old()` pseudo-elements are children of a `::view-transition-image-pair()` pseudo-element, so we can determine it is an added or removed element if it is the only child.
+
+```css
+/* A `::view-transition-new()` element is the only child if it wasn't present before the view transition, so it is an added element. */
+::view-transition-new(.list-item):only-child {
+  animation-name: slide-in;
+  /* Specify an animation duration if you want something different than the UA default of 0.5s */
+  animation-duration: 1s;
+}
+/* A `::view-transition-old()` element is the only child if it isn't present after the view transition, so it is a removed element. */
+::view-transition-old(.list-item):only-child {
+  animation-name: slide-out;
+  /* Specify an animation duration if you want something different than the UA default of 0.5s */
+  animation-duration: 1s;
+}
+
+@keyframes slide-in {
+  from {
+    translate: -100vw 0;
+  }
+}
+@keyframes slide-out {
+  to {
+    translate: -100vw 0;
+  }
+}
+```
+
+4. **Trigger the transition**
+
+Wrap the DOM update in `document.startViewTransition()`. The browser will capture the old state, perform the update, and then animate to the new state.
+
+```javascript
+function updateList(newData) {
+  document.startViewTransition(() => {
+    // All DOM changes inside this callback will be transitioned
+    render(newData);
+  });
+}
+```
+
+5. **Maintain interactivity of non-transitioned elements**
+
+View transitions work by overlaying snapshots of the DOM elements, and then transitioning the snapshots. This means that during the transition, elements are not interactive. If there are interactive elements that are not transitioned, you can make them interactive by disabling touch events on the view transitions.
+
+```css
+::view-transition {
+  /* Non-transitioned elements below the view transitions remain interactive */
+  pointer-events: none;
+}
+```
+
+In addition, by default, the `:root` element has a view transition named `root`, which enables default full-page transitions. If there are no changes to the root element, this will be a transition between two identical snapshots, which are not interactive. Because we are only transitioning specific elements, and not the entire screen, we can disable the `root` transition. 
+
+```css
+:root {
+  /* Disable the root transition because we are only transitioning specific elements. */
+  view-transition-name: none;
+}
+```
+
+### Fallback strategies
+
+Baseline status for view-transition-class: Newly available. It's been Baseline since 2025-10-14.
+Supported by: Chrome 125 (May 2024), Edge 125 (May 2024), Firefox 144 (Oct 2025), and Safari 18.2 (Dec 2024).
+
+View Transitions are a progressive enhancement. If the browser does not support `document.startViewTransition`, the DOM update should still occur immediately, providing a functional but non-animated experience.
+
+```javascript
+if (document.startViewTransition) {
+  document.startViewTransition(() => updateDOM());
+} else {
+  // Fallback: Perform the update without animation
+  updateDOM();
+}
+```
+
+For CSS, browsers that do not recognize `view-transition-class` or the `::view-transition-group()` class selector will simply ignore those rules, and no animation will be applied.

package/.agents/skills/modern-web-guidance/guides/user-experience/improve-text-layout-and-legibility.md

@@ -0,0 +1,76 @@
+# Improve Text Layout and Legibility
+
+The layout of text, particularly at the ends of lines and and ends of paragraphs, can impact the legibility and aesthetic appeal of a page. CSS provides several text wrapping options that can improve specific use cases.
+
+For short text blocks like headings, use `text-wrap: balance`. This property instructs the browser to distribute text as evenly as possible across lines, creating a more symmetrical appearance.
+
+The `text-wrap: pretty` CSS property allows you to improve the typographic quality of body text by enabling a more sophisticated wrapping algorithm. It is specifically designed to prevent "orphans" (single words on the last line of a paragraph) and create a more pleasing visual "rag" for long blocks of text.
+
+## Implementation
+
+### 1. **Identify text elements**: 
+
+For `text-wrap: balance`, select short text blocks like headings and table headers. Avoid elements that have visible boxes such as borders or backgrounds, as this can create unexpected visually empty areas in the layout.
+
+For `text-wrap: pretty`, select elements potentially containing long runs of text where orphaned words (runts) or poor line breaks are most noticeable. This includes the following elements:
+  - `<p>`
+  - `<blockquote>`
+  - `<li>`
+  - Any other element potentially containing long runs of text.
+
+#### Choosing the Right Wrapping Method
+
+| Criteria | `text-wrap: balance` | `text-wrap: pretty` | `text-wrap: wrap` (Default) |
+| :--- | :--- | :--- | :--- |
+| **Best For** | Short blocks (Headings, Titles) | Long blocks (Paragraphs, Lists) | Performance-critical content |
+| **Visual Goal** | Symmetrical line lengths | Avoiding orphans ("runts") | Fast, standard wrapping |
+| **Line Constraints** | Up to 6–10 lines (algorithm limit) | Best for 3 to many lines | No limit |
+| **Perf Cost** | **High**: Binary search algorithm | **Medium**: Look-back algorithm | **Low**: Standard greedy algorithm |
+
+### 2. **Apply the chosen wrapping**: 
+
+Apply `text-wrap: balance` specifically to short, multi-line elements such as headings (`h1`-`h6`), subheadings, or pullquotes.
+
+```css
+/* Target specific heading elements for balanced wrapping */
+h1, h2, h3, h4, h5, h6 {
+  /* Enables balanced line-breaking logic */
+  text-wrap: balance;
+}
+```
+
+Use `text-wrap: pretty` to enable an optimized algorithm that evaluates the last few lines of a paragraph to find the best break points.
+
+```css
+/* Apply to multi-line text blocks to prevent orphaned words */
+p, blockquote, li, .pretty-text {
+  /* Enables pretty line-breaking logic for body copy */
+  text-wrap: pretty;
+}
+```
+
+### Critical Constraints and Performance
+
+#### text-wrap: balance
+
+*   **Line Limit:** Browsers impose a limit on the number of lines they will attempt to balance to maintain performance (typically **6 lines** in Chromium and **10 lines** in Firefox). If the text exceeds this limit, the browser reverts to standard `wrap` behavior. Avoid using `text-wrap: balance` on text blocks that are likely to exceed these limits.
+*   **Targeted Application:** DO NOT apply `text-wrap: balance` globally (e.g., `* { text-wrap: balance; }`). The iterative "binary search" algorithm used by browsers is computationally expensive. Limit its use to specific, short text elements.
+*   **Interaction with Width:** `text-wrap: balance` does not change the container's width (`inline-size`). It only affects how text wraps *within* that width. This can leave empty space at the end of the container, which may affect layouts relying on full-width text blocks.
+
+#### text-wrap: pretty
+
+*   **Performance vs. Quality**: MANDATORY: `text-wrap: pretty` is more computationally expensive than the default `wrap` (greedy) algorithm because it evaluates multiple lines (typically the last four) to optimize the break points. Avoid applying it globally to every element if your page has an extreme amount of text content.
+*   **Best for multi-line text**: The benefits of `pretty` are most apparent in paragraphs of three or more lines. It has little to no effect on short, single-line text.
+*   **Browser-specific behavior**: Be aware that implementation details vary. Chromium-based browsers typically focus on the last four lines, while other engines may evaluate the entire paragraph.
+
+### Fallback strategies
+
+Baseline status for text-wrap: balance: Newly available. It's been Baseline since 2024-05-13.
+Supported by: Chrome 114 (May 2023), Edge 114 (Jun 2023), Firefox 121 (Dec 2023), and Safari 17.5 (May 2024).
+text-wrap: pretty has limited availability.
+Supported by: Chrome 117 (Sep 2023), Edge 117 (Sep 2023), and Safari 26 (Sep 2025).
+Unsupported in: Firefox.
+
+In browsers that do not support `text-wrap: balance` or `text-wrap: pretty`, the property is ignored, and the text will wrap using the default `wrap` behavior. This is a progressive enhancement that gracefully degrades to standard typography. This ensures that your content remains perfectly readable across all browsers while providing a superior experience to those that support it.
+
+For critical layouts where refined text layout is a requirement, use a JavaScript library, but be aware that this may be slow and cause performance issues.

package/.agents/skills/modern-web-guidance/guides/user-experience/individual-transform-properties.md

@@ -0,0 +1,92 @@
+The `transform` property allows you to apply multiple transformations in a specified order, but any changes to a single transformation require re-specifying the entire transformation chain. This makes it tricky to animate or transition a single transformation.
+
+The individual CSS transform properties (`translate`, `rotate`, and `scale`) allow you to apply transformations independently of the `transform` property. This approach makes it simpler to override a single transformation, for instance on `:hover`.
+
+### Key Implementation Details
+
+Individual transform properties are always applied in a **fixed order**, regardless of their order in your CSS:
+1. `translate`
+2. `rotate`
+3. `scale`
+4. `transform` (applied last)
+
+If you require a different order (e.g., scaling *before* rotating), you must continue using the `transform` property functions.
+
+Transform functions do not override the individual transform properties. In other words, `scale: 2; transform: scale(3);` will first scale by 2x, then again by 3x, for a total of 6x.
+
+### Preventing Unexpected Changes in Stacking Contexts and Containing Blocks
+
+The `transform` property and individual transform properties impact the layout and rendering of the page and may cause unexpected behavior with the z-index or anchor positioning. MANDATORY: If an element may have a transform applied as part of a state change like `:hover`, or a transition or animation, apply an identity transformation to the base element. This ensures that the element's stacking context and containment do not change when a transform is applied.
+
+```css
+.element{
+  /* MANDATORY: Apply identity transformations for properties that will
+     change on state changes (like :hover). This prevents unexpected layout
+     or z-index shifts caused by creating a new stacking context only on hover. */
+  translate: 0px;
+  rotate: 0deg;
+  scale: 1;
+}
+.element:hover{
+  translate: 10px 10px;
+  rotate: 20deg;
+  scale: 0.8;
+}
+```
+
+### Independent Animation and Transitions
+
+The primary benefit is the ability to define overlapping animations or transitions that target different properties without conflict.
+
+```css
+.card {
+  /* Define independent animations that don't overwrite each other */
+  animation: float 3s infinite ease-in-out;
+  
+  /* Transition only the scale property for hover states */
+  transition: scale 0.3s ease;
+
+  /* Establish the base scale to prevent a sudden stacking context shift when transitioning on hover. */
+  scale: 1;
+}
+
+.card:hover {
+  /* Only the scale changes; the 'float' animation (translate) continues uninterrupted */
+  scale: 1.05;
+}
+
+@keyframes float {
+  0%, 100% { translate: 0 0; }
+  50% { translate: 0 -10px; }
+}
+```
+
+### Fallback strategies
+
+Baseline status for Individual transform properties: Widely available. It's been Baseline since 2022-08-05.
+Supported by: Chrome 104 (Aug 2022), Edge 104 (Aug 2022), Firefox 72 (Jan 2020), Safari 14.1 (Apr 2021), and Safari iOS 14.5 (Apr 2021).
+
+For browsers that do not support individual transform properties, use the traditional `transform` property. Note that this requires re-declaring the entire transform stack if you want to modify one part in a different state.
+
+```css
+.element {
+  /* Base transform */
+  transform: translate(100px, 0) rotate(45deg);
+  /* Specify the identity for the scale property. */
+  scale: 1;
+}
+
+@supports not (translate: 0px) {
+  .element:hover {
+    /* Fallback: Must repeat translate and rotate even if only scale changes */
+    transform: translate(100px, 0) rotate(45deg) scale(1.1);
+  }
+}
+
+@supports (translate: 0px) {
+  .element:hover {
+    /* Modern: Only declare the change */
+    scale: 1.1;
+  }
+}
+```