@olives/devos 2.1.0

package/.agents/skills/modern-web-guidance/guides/css-layout/css-layout.md

@@ -0,0 +1,305 @@
+# CSS Layouts and Responsive Design
+
+1. [1 Fundamentals](#1-fundamentals)
+   1. [Which layout mode to use?](#11-which-layout-mode-to-use)
+   2. [Working principles](#12-working-principles)
+2. [2 Flexbox](#2-flexbox)
+3. [3 Grid and subgrid](#3-grid-and-subgrid)
+   1. [Code example: grid and subgrid](#31-code-example-grid-and-subgrid)
+4. [4 Container queries](#4-container-queries)
+   1. [Code example: fluid typography using container query units](#41-code-example-fluid-typography-using-container-query-units)
+5. [5 Native overlays, anchor positioning, and stacking contexts](#5-native-overlays-anchor-positioning-and-stacking-contexts)
+6. [6 Overflow tracking and layout stability](#6-overflow-tracking-and-layout-stability)
+7. [7 Viewport mechanics and track distribution](#7-viewport-mechanics-and-track-distribution)
+8. [8 Grid lanes (aka masonry)](#8-grid-lanes-aka-masonry)
+
+## 1 Fundamentals
+
+Lean on the browser's layout engine when possible for better performance. Reach for intrinsic sizing, logical properties, and `aspect-ratio` before resorting to hardcoded dimensions or complicated media-queries.
+
+### 1.1 Which layout mode to use?
+
+Walk the decision tree top-to-bottom and stop at the first match. Note that layouts can be nested within each-other and each decision is based on the use-case for that container.
+
+1. **Is it a simple row OR column of items?** Use **flexbox** — 1D, content-first, content distributes along a single axis.
+2. **Does a nested element need to line up with its grandparent grid's tracks?** Use **subgrid** — 2D, relationship-first, inherits parent tracks so grandchildren can align across siblings.
+3. **Is it a complex page or component structure with rows AND columns?** Use **grid** — 2D, layout-first, you define the skeleton and content fills it.
+4. **Is the content a long flow of prose that should split into balanced columns?** Use **multi-column** — 1D flow, newspaper-style.
+5. **Are items of varied heights that need to be packed tightly?** Use **grid** with `grid-auto-flow: dense` today; reach for native masonry (aka "grid lanes") only when it ships in your Baseline target (see [§8](#8-grid-lanes-aka-masonry)).
+6. **Does an element need to float above the page and stay spatially tethered to a trigger, even across DOM boundaries or stacking contexts?** Use **anchor positioning** — `anchor-name` on the trigger, `position-anchor` on the overlay (see [§5](#5-native-overlays-anchor-positioning-and-stacking-contexts)).
+
+### 1.2 Working principles
+
+**Do:**
+
+- Use logical properties (`inline-size`, `block-size`, `margin-inline`, `padding-block`, `inset-inline-start`) for layout dimensions and spacing — see `css` (via `npx -y modern-web-guidance@latest retrieve "css"`) for full coverage.
+- Apply the content-first vs layout-first mental model: flexbox when items dictate flow, grid when you define the skeleton first.
+- Use the `place-*` shorthands (`place-content`, `place-items`, `place-self`) to align across both axes in one declaration.
+- Reach for intrinsic sizing (`min-content`, `max-content`, `fit-content()`) and flexible tracks (`fr`, `minmax()`) before fixed `width`/`height` — fewer media queries, more resilient layouts.
+- Use `aspect-ratio` to reserve space for media and prevent layout shift before assets load.
+
+```css
+.sidebar       { inline-size: max-content; }    /* Size to longest unbreakable token. */
+.main-content  { inline-size: fit-content; }    /* Grow to available space, no further. */
+.media         { aspect-ratio: 16 / 9; inline-size: 100%; block-size: auto; }
+body.centered  { display: grid; place-content: center; min-block-size: 100dvb; }
+```
+
+> For `calc-size()` and constraint-aware intrinsic sizing, see `calculate-with-intrinsic-sizes` (via `npx -y modern-web-guidance@latest retrieve "calculate-with-intrinsic-sizes"`).
+
+## 2 Flexbox
+
+One-dimensional layout — items flow along a single **main** axis with alignment on the **cross** axis. Reach for it for navbars, toolbars, item rows, and any single-row-or-column distribution.
+
+**Do:**
+
+- Establish a context with `display: flex` and set the main axis with `flex-direction` (`row` default).
+- Use `flex-wrap: wrap` whenever overflow is a possibility — `nowrap` without `overflow: auto/hidden` will spill on narrow viewports.
+- Use the `flex` shorthand `<grow> <shrink> <basis>` (e.g., `flex: 1 1 250px`) on items rather than setting `flex-grow`/`flex-shrink`/`flex-basis` individually.
+- Use `gap` (or the `row-gap`/`column-gap` longhand) for spacing between items instead of child margins.
+- Prefix positional alignment with `safe` (e.g., `align-items: safe center`) so focusable content isn't clipped when the container is narrower than its content.
+- Push a single item to the far end of the main axis with `margin-inline-start: auto` (or `margin-block-start: auto`) — that's the standard escape hatch.
+- Override cross-axis alignment per item with `align-self`.
+- Use `align-items` to center all items on the cross axis; use `margin: auto` on a single item to center it on both axes independently; use `align-content` only when the container wraps and has extra space across rows.
+- Set `min-inline-size: 0` (or `min-width: 0`) on flex items that contain long unbreakable content (URLs, code, long strings) — flex items won't shrink below their content size by default, causing overflow.
+
+**Do not:**
+
+- Don't reach for `justify-self` on flex items — it only works on grid, block, and absolutely-positioned layouts. Use auto margins instead.
+- Don't use `order` or `flex-direction: *-reverse` to reorder interactive content. They change visual order only; the DOM order still drives sequential focus, so keyboard tab flow won't match what the user sees.
+- Don't confuse `space-around` (half-gap at the ends) with `space-evenly` (equal gaps before, between, and after).
+- Don't forget the axis flip: when `flex-direction: column`, `justify-content` aligns on the block axis and `align-items` aligns on the inline axis — the opposite of the default.
+- Don't size both the container and its children to fill each other — that's a common source of overflow and surprising results. Give one side a definite size.
+- Don't set both `flex-basis` and `width`/`inline-size` on the same item — `flex-basis` takes precedence in a flex context and `width` is ignored. Use `flex-basis` (or the `flex` shorthand) as the single source of truth for sizing flex items.
+
+```css
+.card-grid        { display: flex; flex-flow: row wrap; gap: 1rem; }
+.card-item        { flex: 1 1 250px; }                  /* grow, shrink, basis */
+.card-item-action { margin-inline-start: auto; }        /* Push to main-axis end. */
+.toolbar          { display: flex; align-items: safe center; }
+```
+
+## 3 Grid and subgrid
+
+Baseline status for Subgrid: Widely available. It's been Baseline since 2023-09-15.
+Supported by: Chrome 117 (Sep 2023), Edge 117 (Sep 2023), Firefox 71 (Dec 2019), and Safari 16 (Sep 2022).
+
+Two-dimensional layout — define rows AND columns explicitly, or let the engine derive them. Subgrid lets a nested grid inherit its parent's tracks so grandchildren align across siblings.
+
+**Choosing grid features:**
+
+- Do you know exactly how many columns you need?
+  - **Yes** — use explicit tracks (`grid-template-columns: 200px 1fr`, `repeat(3, 1fr)`, etc.)
+    - Do different columns need different sizes (sidebar + main, header spanning all)? → use `grid-template-areas` for named, readable regions
+    - Are all columns uniform or positioned purely by line number? → use `repeat(N, ...)` or named lines
+  - **No** (responsive, unknown item count) — use `repeat(auto-fit, minmax(min, 1fr))`
+    - Should items on the last row stretch to fill remaining space? → `auto-fit`
+    - Should empty last-row tracks hold their min size (preserving column ghost slots)? → `auto-fill`
+- Do you need to place an item at a specific location?
+  - **Yes** — use `grid-column: <start> / <end>` or `grid-area: <name>`
+  - **No** (just spanning multiple tracks, flow position doesn't matter) — use `grid-column: span <n>`
+- Do child elements need to inherit the parent grid's track sizes (ragged-edge alignment across siblings)?
+  - **Yes** — use subgrid on the affected axis
+    - Is the number of children per cell variable? → subgrid **one axis only**; use `grid-auto-rows`/`grid-auto-columns` for the other
+    - Is the child count fixed? → subgrid on both axes is fine
+  - **No** — standard grid, no subgrid needed
+
+**Do:**
+
+- Establish a context with `display: grid`.
+- Use `grid-template-areas` for complex page-level layouts — area names are self-documenting and the declaration can be aligned in rows and columns for at-a-glance readability.
+- Use `repeat(auto-fit, minmax(200px, 1fr))` for responsive card grids that stretch filled tracks to fill the row, or `auto-fill` to preserve empty repeated tracks at their min size.
+- Use `fr` for proportional track distribution and `minmax(min, max)` for flexible-but-bounded tracks.
+- Position items with `grid-column: span <n>` to size across tracks, `grid-column: <start> / <end>` to place at specific lines, or `grid-area: <name>` for named regions.
+- Use subgrid (`grid-template-columns: subgrid` or `grid-template-rows: subgrid`) to solve the "ragged edge" problem in card lists — internal elements like titles, metadata, and CTAs line up across siblings.
+- Pair a subgrid declaration with a preceding explicit `grid-template-rows`/`-columns` declaration as a same-cascade fallback for older browsers.
+
+**Do not:**
+
+- Don't expect `auto-fit`/`auto-fill` track size to come from item content — it comes from the `repeat()` size argument.
+- Don't use `grid-auto-flow: dense` on interactive content. It packs items efficiently but reorders them visually, breaking DOM-order keyboard tab flow.
+- Don't apply subgrid to both axes when the child count is variable. Extras land in the last track; use `grid-auto-rows`/`grid-auto-columns` for the implicit axis instead.
+- Don't confuse `justify-items`/`align-items` (aligns item content *within its track*) with `justify-content`/`align-content` (aligns the grid tracks *within the container*). Using the wrong one silently has no effect.
+- Don't use `repeat(auto-fit/auto-fill, ...)` without a definite `inline-size` on the container — inside `display: inline-grid` or an unsized flex item, the container has no width to divide, making track counts unpredictable.
+
+### 3.1 Code example: grid and subgrid
+
+Page shell: `<main class="page-layout">` contains `<header>`, `<aside>`, a `<section class="card-grid">` with `<div class="card">` children, and `<footer>`.
+
+```css
+/* Align grid-template-areas in rows and columns for readability. */
+.page-layout {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  grid-template-areas:
+    "header  header  header"
+    "sidebar main    main"
+    "footer  footer  footer";
+  gap: 1.5rem;
+}
+
+header  { grid-area: header; }
+aside   { grid-area: sidebar; }
+footer  { grid-area: footer; }
+
+.card-grid {
+  grid-area: main;
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));
+  grid-template-rows: auto 1fr; /* title block, body block */
+  gap: 1rem;
+}
+
+.card {
+  grid-row: span 2;
+  display: grid;
+  /* Same-cascade fallback: ignored when subgrid is supported. */
+  grid-template-rows: auto 1fr;
+  grid-template-rows: subgrid;
+}
+```
+
+## 4 Container queries
+
+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).
+
+Query the size (or computed style) of an ancestor container rather than the viewport. Mental model: container queries = component context; media queries = global page layout and user preferences (`prefers-color-scheme`, `prefers-reduced-motion`).
+
+**Do:**
+
+- Establish a containment context with `container-type: inline-size` (width-only queries) or `container-type: size` (both axes) on a wrapper before its descendants can be queried.
+- Name containers with `container-name` (or the `container` shorthand: `container: inline-size card`) when nested contexts could collide.
+- Include container query units in calculating fluid type and spacing: `cqi`/`cqb` (logical inline/block), `cqw`/`cqh` (physical), `cqmin`/`cqmax`.
+- Give the container a definite `block-size` whenever `container-type: size` is used — without one, descendants collapse because size containment forces the container to ignore its content.
+
+**Do not:**
+
+- Don't use `block-size` as a `container-type` value — it isn't valid. Use `size` for both axes.
+- Don't expect children's intrinsic size to influence the container after declaring `container-type`. The container is computed as if it has no children once containment is active.
+- Don't rely on container query units inside descendants of a non-qualifying ancestor; they fall back to the small viewport (`svw`/`svh`).
+
+### 4.1 Code example: fluid typography using container query units
+
+```css
+.card-wrapper {
+  container: inline-size / card; /* shorthand for container-type + container-name */
+}
+
+@container card (inline-size > 400px) {
+  .content {
+    display: flex;
+    gap: 2rem;
+  }
+}
+
+.title {
+  /* Fluid type bound to the container width, not the viewport. */
+  font-size: clamp(1rem, 4cqi, 2rem);
+}
+```
+
+> For component-driven responsive styling patterns, see `size-aware-styling` (via `npx -y modern-web-guidance@latest retrieve "size-aware-styling"`) and `fluid-scaling` (via `npx -y modern-web-guidance@latest retrieve "fluid-scaling"`).
+
+## 5 Native overlays, anchor positioning, and stacking contexts
+
+Baseline status for <dialog>: Widely available. It's been Baseline since 2022-03-14.
+Supported by: Chrome 37 (Aug 2014), Edge 79 (Jan 2020), Firefox 98 (Mar 2022), and Safari 15.4 (Mar 2022).
+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).
+Anchor positioning is not natively supported by any major browser yet.
+
+**When to use each overlay primitive:**
+
+- Use `popover` for transient, non-modal UI (flyouts, toasts, tooltips) — lives in the top layer, no `z-index` management needed.
+- Use `<dialog>` with `.showModal()` for modal interactions that require focus trapping and an inert backdrop.
+- Don't combine `popover` and `.showModal()` on the same element — they're mutually exclusive runtime states.
+
+**Anchor positioning (spatial layout of overlays):**
+
+- Use `position-area` (or `anchor()` on insets) and `anchor-size()` to position and size an overlay relative to its trigger.
+- Use `position-try-fallbacks: flip-block` (or `flip-inline`) to let the browser reposition when the overlay overflows the viewport.
+- Don't mix physical and logical keywords in a single `position-area` value — pick one coordinate system.
+- Feature-detect with `@supports (anchor-name: --x)` and provide an absolute-position fallback.
+
+> For full implementation detail, polyfill strategies, and `popover` value reference, see `declarative-dialog-popover-control` (via `npx -y modern-web-guidance@latest retrieve "declarative-dialog-popover-control"`) and `position-aware-tooltips` (via `npx -y modern-web-guidance@latest retrieve "position-aware-tooltips"`). For anchor positioning applied to menus and tab indicators, see `resilient-context-menus-and-nested-dropdowns` (via `npx -y modern-web-guidance@latest retrieve "resilient-context-menus-and-nested-dropdowns"`) and `anchor-positioning-tab-underline` (via `npx -y modern-web-guidance@latest retrieve "anchor-positioning-tab-underline"`).
+
+## 6 Overflow tracking and layout stability
+
+Baseline status for scrollbar-gutter: Newly available. It's been Baseline since 2024-12-11.
+Supported by: Chrome 94 (Sep 2021), Edge 94 (Sep 2021), Firefox 97 (Feb 2022), and Safari 18.2 (Dec 2024).
+line-clamp is not natively supported by any major browser yet.
+
+Manage layout shifts, scrollbars, and clipping predictably.
+
+**Do:**
+
+- Use `overflow: auto` so scrollbars appear only when content actually overflows.
+- Use `overflow: clip` to clip content **without** establishing a scroll container; opt into spillover with `overflow-clip-margin`.
+- Use `scrollbar-gutter: stable` to reserve space for scrollbars and prevent layout shifts when content grows.
+- Use `overscroll-behavior: contain` (or `none`) on scrollable containers to stop scroll chains from bubbling into the parent or document.
+- Use the `-webkit-line-clamp` + `display: -webkit-box` + `-webkit-box-orient: vertical` triad for multi-line truncation — despite the prefix, this pattern is fully specified and not deprecated. Declare the unprefixed `line-clamp` shorthand alongside it; browsers that don't yet support it ignore the property harmlessly.
+**Do not:**
+
+- Don't use `overflow: scroll` when `auto` will do — `scroll` forces scrollbars even when there's nothing to scroll.
+- Don't reach for `overflow: hidden` when you only want to clip — `hidden` establishes a scroll container that can be programmatically scrolled.
+
+```css
+.scrollable-list {
+  max-block-size: 400px;
+  overflow-y: auto;
+  scrollbar-gutter: stable;       /* Reserve scrollbar space. */
+  overscroll-behavior: contain;   /* No scroll chaining into the page. */
+}
+
+.snippet {
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+  line-clamp: 3;                  /* Ignored where unsupported. */
+  overflow: clip;
+}
+```
+
+> For `overflow: clip` and `overflow-clip-margin` in depth, see `overflow-clipping-control` (via `npx -y modern-web-guidance@latest retrieve "overflow-clipping-control"`). For scrollbar color, sizing, and theming, see `customize-scrollbar-color-and-thickness` (via `npx -y modern-web-guidance@latest retrieve "customize-scrollbar-color-and-thickness"`), `dark-mode` (via `npx -y modern-web-guidance@latest retrieve "dark-mode"`), and `adapt-scrollbar-to-contrast-preferences` (via `npx -y modern-web-guidance@latest retrieve "adapt-scrollbar-to-contrast-preferences"`).
+
+## 7 Viewport mechanics and track distribution
+
+Baseline status for Small, large, and dynamic viewport units: Widely available. It's been Baseline since 2022-12-05.
+Supported by: Chrome 108 (Nov 2022), Edge 108 (Dec 2022), Firefox 101 (May 2022), and Safari 15.4 (Mar 2022).
+
+- Use `dvh`/`dvw` for mobile layout containers that must account for browser UI shifting (URL bar collapse/expand).
+- Don't use `100vw` for full-width layout — it ignores scrollbar width and causes horizontal overflow. Use `100%`, `100dvw`, or `100svw` instead.
+
+> For the full viewport unit reference (`svh`, `lvh`, `dvi`, `dvb`, etc.), see `css` (via `npx -y modern-web-guidance@latest retrieve "css"`).
+
+## 8 Grid lanes (aka masonry)
+
+Masonry is not natively supported by any major browser yet.
+
+The spec is in development. The currently agreed-upon name is "grid lanes" (e.g., `display: grid-lanes`). Firefox ships `grid-template-rows: masonry` behind a flag; no other engines ship it in stable as of this writing.
+
+**Do:**
+
+- Use grid with `grid-auto-flow: dense` for tight packing today, accepting that DOM order may not match visual order.
+- Use multi-column (`columns: 3; column-gap: 1rem`) for content-heavy masonry-like flow when items are document fragments rather than equal-weight cards.
+- Treat `grid-template-rows: masonry` as a progressive enhancement only — feature-detect with `@supports`.
+
+**Do not:**
+
+- Don't ship `grid-template-rows: masonry` as a hard requirement until your Baseline target catches up.
+
+```css
+.gallery       { columns: 3 200px; column-gap: 1rem; }
+.gallery > *   { break-inside: avoid; margin-block-end: 1rem; }
+
+@supports (grid-template-rows: masonry) {
+  .gallery {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+    grid-template-rows: masonry;
+    gap: 1rem;
+    columns: unset;
+  }
+}
+```

package/.agents/skills/modern-web-guidance/guides/forms/animated-select-picker.md

@@ -0,0 +1,178 @@
+# Animated Select Picker
+
+The customizable select API offers a declarative, CSS-driven way to animate `<select>` elements and their dropdown pickers. By combining `appearance: base-select` with modern CSS animation techniques—such as `@starting-style` and the `allow-discrete` transition behavior—you can create fluid, premium UI transitions for top-layer elements without relying on heavy JavaScript libraries.
+
+Previously, animating native select dropdowns was impossible because their UI was rendered outside the accessible viewport constraints. With `appearance: base-select`, the picker becomes styleable and animatable like any other page element.
+
+## How to Implement
+
+To implement an animated select picker:
+
+1. **Opt-in to customization:** Apply `appearance: base-select` to both the `<select>` element and the `::picker(select)` pseudo-element.
+2. **Enable auto-sizing transitions (Optional):** Define `interpolate-size: allow-keywords` (usually on `:root`) to allow the browser to transition between discrete metric values like `height: auto` and `height: 0`.
+3. **Animate the top-layer container:** Apply standard entry/exit styles to `::picker(select)`. To make sure the opacity transition works when moving between `display: none` and `display: block`, you must use `transition-behavior: allow-discrete` (often written inline as `transition: display 0.3s allow-discrete`).
+4. **Hook into the opening state with `@starting-style`:** Use `@starting-style` to define the baseline styles the browser should compute *before* the transition begins. For example, if you want it to fade in, set the opacity to `0` inside the `@starting-style` block.
+5. **Rotate the icon:** Use pseudo-element focus or active selectors like `:open::picker-icon` to apply transitions (such as rotation or translation) to the arrow indicator.
+
+## Example Code: Smooth Select Scale and Fade
+
+The following example demonstrates a custom select styled with standard page animations for the picker container.
+
+```html
+<!-- Always use a <label> linked via 'for' to the select for accessibility -->
+<label for="theme-select">Visual Theme</label>
+<select id="theme-select" class="animated-select" name="theme">
+  <!-- The <button> inside <select> becomes the visible trigger when appearance: base-select is used -->
+  <button>
+    <!-- <selectedcontent> automatically displays the content of the chosen <option> -->
+    <selectedcontent></selectedcontent>
+  </button>
+  <option value="system">
+    <!-- MANDATORY: Decorative inline SVGs MUST set aria-hidden="true" to prevent redundant screen reader announcement -->
+    <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <rect x="2" y="3" width="20" height="14" rx="2" ry="2"></rect>
+      <line x1="8" y1="21" x2="16" y2="21"></line>
+      <line x1="12" y1="17" x2="12" y2="21"></line>
+    </svg>
+    System Default
+  </option>
+  <option value="light">
+    <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <circle cx="12" cy="12" r="5"></circle>
+      <line x1="12" y1="1" x2="12" y2="3"></line>
+      <line x1="12" y1="21" x2="12" y2="23"></line>
+      <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
+      <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
+      <line x1="1" y1="12" x2="3" y2="12"></line>
+      <line x1="21" y1="12" x2="23" y2="12"></line>
+      <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
+      <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
+    </svg>
+    Light UI
+  </option>
+</select>
+```
+
+```css
+/* Opt-in to customizable select */
+.animated-select,
+.animated-select::picker(select) {
+  appearance: base-select;
+}
+
+/* Enable auto-keyword transitions (usually set globally at :root) */
+:root {
+  interpolate-size: allow-keywords;
+}
+
+/* Style the visible trigger and icon rotation */
+.animated-select {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  padding: 0.875rem 1rem;
+  font-size: 1rem;
+  border-radius: 8px;
+  cursor: pointer;
+  transition: border-color 0.2s ease;
+}
+
+.animated-select::picker-icon {
+  transition: transform 0.3s cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.animated-select:open::picker-icon {
+  transform: rotate(180deg);
+}
+
+/*
+ * The Picker Container
+ * Uses top-layer animations with `allow-discrete` visibility hooks
+ */
+.animated-select::picker(select) {
+  background: white;
+  border-radius: 12px;
+  box-shadow: 0 10px 25px -3px rgba(0,0,0,0.1);
+  padding: 0.5rem;
+  margin-top: 0.25rem;
+  width: anchor-size(width);
+  overflow: hidden;
+
+  /* The crucial transition setting for popover animations */
+  transition:
+    display 0.4s allow-discrete,
+    overlay 0.4s allow-discrete,
+    opacity 0.4s cubic-bezier(0.16, 1, 0.3, 1),
+    height 0.4s cubic-bezier(0.16, 1, 0.3, 1);
+  opacity: 0;
+  height: 0;
+}
+
+/* Open State */
+.animated-select:open::picker(select) {
+  opacity: 1;
+  height: auto;
+}
+
+/* @starting-style to hook the transition on initial popover open */
+@starting-style {
+  .animated-select:open::picker(select) {
+    opacity: 0;
+    height: 0;
+  }
+}
+
+/* Support for SVG inside Options and Selected Content */
+.animated-select option svg,
+.animated-select selectedcontent svg {
+  flex-shrink: 0; /* Prevent icons from shrinking */
+  width: 1.25rem;
+  height: 1.25rem;
+}
+
+/* MANDATORY: Provide multiple indicators (e.g. bold font and distinct background) for the checked state to avoid color-only state communication */
+.animated-select option:checked {
+  font-weight: 700;
+  background-color: #f1f5f9;
+}
+
+/* Ensure copy-paste safety for users with motion sensitivities */
+@media (prefers-reduced-motion: reduce) {
+  .animated-select::picker(select),
+  .animated-select::picker-icon {
+    transition: none !important;
+  }
+}
+```
+
+## Strategic Implementation & Best Practices
+
+- **DO** use `@starting-style` when you need animations to trigger exactly when an element transitions from `display: none` to visible.
+- **DO NOT** use ad-hoc scroll locking. Top-layer elements managed by ‘base-select’ should allow natural backdrop dismiss behaviors.
+- **DO** verify reduced motion preferences. Always wrap animation constraints in a `prefers-reduced-motion` media query to ensure accessible environments for those affected by motion sickness.
+- **DO** test layout behavior. Setting `appearance: base-select` removes the default browser behavior of sizing the select based on its longest option width. You may need to set a fixed width or use flex/grid constraints to prevent layout shifts.
+- **DO** ensure your `<select>` has a `name` attribute and an associated `<label>`. This ensures that even with a custom UI, the component remains accessible to screen readers and works correctly with standard form submissions.
+
+## Fallback strategies
+
+### Fallbacks & browser support for Customizable <select>
+
+Customizable <select> has limited availability.
+Supported by: Chrome 135 (Apr 2025) and Edge 135 (Apr 2025).
+Unsupported in: Firefox and Safari.
+
+For browsers that do not yet support `appearance: base-select`, the `<select>` element degrades gracefully to a standard operating system dropdown.
+
+- **Non-Text Content Ignored**: Older browsers strip HTML tags (like `<svg>` or `<div>`) inside `<option>` tags and render only the text nodes. Ensure the text content of the `<option>` is readable and meaningful on its own.
+- **HTML Structure Handling**: Standard parsers may ignore the `<button>` and `<selectedcontent>` tags inside `<select>` or treat them as invalid. No heavy JavaScript polyfills are strictly required for progressive enhancement if you view standard text as a readable fallback.
+
+
+```javascript
+document.addEventListener("DOMContentLoaded", () => {
+  // Check if browser supports base-select value
+  if (!CSS.supports("appearance", "base-select")) {
+    // Custom select overrides are not supported natively.
+  }
+});
+```

package/.agents/skills/modern-web-guidance/guides/forms/autofill-address-form.md

@@ -0,0 +1,75 @@
+# Build an address form that follows best practice
+
+Create a form that makes it as easy as possible for users to enter address data on desktop and mobile. Ensure the form makes the most of built-in browser features for autofill, validation and data entry constraints.
+
+## How to implement
+
+Outlined below are the most important guidelines for building successful address forms.
+
+### Use meaningful, valid HTML
+
+Make the most of the elements and attributes built for creating forms:
+
+-   `<form>`, `<input>`, `<label>`, and `<button>`
+-   `type`, `autocomplete`, and `inputmode`
+
+These enable built-in browser functionality, improve accessibility, and add meaning to markup.
+
+### Use the `<label>` element to label form fields for data entry
+
+To label an `<input>`, `<select>`, or `<textarea>`, use a `<label>`. Associate a label with an input by giving the label's `for` attribute the same value as the input's `id`.
+
+### Make the most of HTML attributes
+
+Make it easy for users to enter data, by using the appropriate `<input>` element `<type>` attribute to provide the right keyboard on mobile and enable basic built-in validation by the browser.
+
+Always use `type="email"` for email addresses and `type="tel"` for phone numbers.
+
+```html
+<!-- type="email"/"tel" gives mobile users the right keyboard and enables built-in validation -->
+<input type="email" id="email" name="email" autocomplete="email" required>
+<input type="tel" id="phone" name="phone" autocomplete="tel">
+```
+
+Every `<input>`, `<select>`, and `<textarea>` element SHOULD have an appropriate `autocomplete` attribute, to improve accessibility and help users avoid re-entering data.
+
+### Make buttons helpful
+
+Use `<button>` for buttons. You can also use `<input type="submit">`, but don't use a `div` or some other random element acting as a button. Button elements provide accessible behaviour, built-in form submission functionality, and can easily be styled.
+
+Give each form submit button a value that says what it does. For each step towards checkout, use a descriptive call-to-action that shows progress and makes the next step obvious. For example, label the submit button on your delivery address form **Proceed to Payment** rather than **Continue** or **Save**.
+
+### Use a single name input where possible
+
+Allow your users to enter their name using a single input, unless you have a good reason for separately storing given names, family names, honorifics, or other name parts. Using a single name input makes forms less complex, enables cut-and-paste, and makes autofill simpler.
+
+Allow international names. For validation, avoid using regular expressions that only match Latin characters. Latin-only excludes users with names or addresses that include characters that aren't in the Latin alphabet. Allow Unicode letter matching instead—and ensure your backend supports Unicode securely as both input and output. Unicode in regular expressions is well supported by modern browsers.
+
+### Allow for a variety of address formats
+
+When building an address form, be aware of the variety of address formats, even within a single country. Do not make assumptions about "normal" addresses.
+
+Use a single `<textarea>` element for the street address if possible.
+
+```html
+<!-- textarea handles multi-line international address formats that split inputs can't accommodate -->
+<textarea id="address" name="address" autocomplete="street-address" required></textarea>
+```
+
+This is the most flexible option for a variety of local and international address formats.
+
+### Help save users from accidentally missing data fields
+
+Add the `required` attribute to mandatory fields.
+
+```html
+<input type="text" id="city" name="city" autocomplete="address-level2" required>
+```
+
+### Fallback strategies
+
+:autofill has limited availability.
+Supported by: Chrome 110 (Feb 2023), Edge 110 (Feb 2023), and Safari 15 (Sep 2021).
+Unsupported in: Firefox.
+
+Autofill is a progressive enhancement. In browsers that do not support autofill, users will simply need to manually enter their address details. The semantic HTML constraints (such as `type`, `inputmode`, and `required`) will still function appropriately as standard form validation.

package/.agents/skills/modern-web-guidance/guides/forms/autofill-highlight-inputs.md

@@ -0,0 +1,45 @@
+# Use the CSS :autofill pseudo-class to highlight form fields that have been autofilled by the browser and not edited by the user
+
+Use the CSS `:autofill` to highlight fields that have (or have not been) autofilled, to help guide the user to successful form completion.
+
+## How to implement
+
+To highlight a form field that has been autofilled by the browser (and not edited by the user) add a selector to your CSS using the `:autofill` class. This can be used for an `<input>`, `<select>`, or `<textarea>` element.
+
+When styling autofilled states, you must adhere to accessibility best practices:
+- **Multiple State Indicators**: Do not rely on border color alone to indicate the autofilled state. Use multiple indicators such as border thickness and custom background shading to ensure the state is perceivable.
+- **Preserve Focus Indicators**: Never remove focus outlines (`outline: none`) without providing a clear, high-contrast replacement for keyboard users.
+
+The following example uses `:autofill` to set a custom border and background, along with explicit focus styles:
+
+```css
+input:autofill,
+input:-webkit-autofill {
+  /* Multiple indicators: use both a distinct border and background color via box-shadow to avoid color-only state */
+  border: 2px solid #2e7d32;
+  box-shadow: 0 0 0 100vmax #e8f5e9 inset;
+}
+
+/* MANDATORY: Always provide an explicit focus indicator when styling autofilled states */
+input:autofill:focus-visible,
+input:-webkit-autofill:focus-visible {
+  outline: 3px solid #000;
+  outline-offset: 2px;
+}
+```
+
+As shown in this example, the `box-shadow` property is used to customize the background, since `background-color` cannot be overridden directly on autofilled fields.
+
+## Use the correct CSS pseudo-class name
+
+**Do not** use `:auto-fill`: this is incorrect.
+
+MANDATORY: Use `:autofill` as this is the correct pseudo-class name.
+
+### Fallback strategies
+
+:autofill has limited availability.
+Supported by: Chrome 110 (Feb 2023), Edge 110 (Feb 2023), and Safari 15 (Sep 2021).
+Unsupported in: Firefox.
+
+The `:autofill` pseudo-class is a progressive enhancement. In browsers that do not support it, the form will still function normally, but the inputs will simply not receive the custom autofill highlighting. Users will still be able to successfully complete the form. No additional JavaScript fallback should be used.