@daydreamui/good-css 0.0.0-stage → 0.3.0

package/knowledge/recipes/content-grid-with-breakouts.md

@@ -0,0 +1,69 @@
+---
+topic: "good-css-content-grid-with-breakouts"
+title: "Content grid with breakouts"
+tier: "reference"
+tags:
+  - "good-css"
+  - "layout"
+  - "content"
+  - "grid"
+  - "breakouts"
+summary: "Use it wherever you would reach for a centered max-width container. One grid on the section replaces the `section > .container` wrapper pair, and any child can be content width, wider, or edge to edge. Put it on `main` for a page of flowing content, or on each section. It suits CMS content well, because an editor widens a block with one class and no extra wrapper."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# Content grid with breakouts
+
+Use it wherever you would reach for a centered max-width container. One grid on the section replaces the `section > .container` wrapper pair, and any child can be content width, wider, or edge to edge. Put it on `main` for a page of flowing content, or on each section. It suits CMS content well, because an editor widens a block with one class and no extra wrapper.
+
+The container defines three nested widths with named grid lines:
+
+```css
+.content-grid {
+  --gutter: 1.5rem;
+  --content: 64rem;
+  --breakout: 80rem;
+
+  display: grid;
+  grid-template-columns:
+    [full-width-start] minmax(var(--gutter), 1fr)
+    [breakout-start] minmax(0, calc((var(--breakout) - var(--content)) / 2))
+    [content-start] min(100% - var(--gutter) * 2, var(--content)) [content-end]
+    minmax(0, calc((var(--breakout) - var(--content)) / 2)) [breakout-end]
+    minmax(var(--gutter), 1fr) [full-width-end];
+}
+```
+
+Each child picks a width with `grid-column`. Content is the default:
+
+```css
+:is(.content-grid, .full-width) > * { grid-column: content; }
+:is(.content-grid, .full-width) > .breakout { grid-column: breakout; }
+:is(.content-grid, .full-width) > .full-width {
+  grid-column: full-width;
+  display: grid;
+  grid-template-columns: inherit;
+}
+```
+
+Why it works:
+
+- Two lines named `content-start` and `content-end` create a named area, `content`. That is why `grid-column: content` works with no line numbers.
+- `min(100% - 2 × gutter, max)` shrinks the content column on small screens with no media query.
+- `minmax(0, …)` lets the breakout tracks collapse, so a breakout falls back to content width when there is no room. With a fixed breakout size the page overflows on small screens.
+- `grid-template-columns: inherit` gives a full-width band the same grid, so content inside it lines up with the page column without another wrapper. This is Kevin Powell's addition. In Ryan Mulligan's original the full-width child is a plain box.
+
+Rules:
+
+- Every child must be placed. An unplaced child of the grid lands in the gutter track.
+- Every direct child is a grid item. Wrap a run of inline elements in one element.
+- Change a width by overriding `--content`, not by writing a new column template.
+
+In other systems: the column template goes wherever the project defines reusable styles. Where child selectors are not available, as in StyleX or Tailwind without a custom variant, each child sets its own `grid-column` to `content`, `breakout` or `full-width`.
+
+- Borrowed from: Kevin Powell, [A new approach to container and wrapper classes](https://www.youtube.com/watch?v=c13gpBrnGEw), 2023-11-09 · Ryan Mulligan, [Layout Breakouts with CSS Grid](https://ryanmulligan.dev/blog/layout-breakouts/) · Stephanie Eckles, [SmolCSS breakout grid](https://smolcss.dev/#smol-breakout-grid)
+- Docs: [MDN: named grid lines](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Grid_layout/Named_grid_lines) · [MDN: min()](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/min)
+
+Source: [Good CSS](https://good-css.com/specimen/content-grid-with-breakouts), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#content-grid-with-breakouts).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.

package/knowledge/recipes/cross-document-view-transitions.md

@@ -0,0 +1,39 @@
+---
+topic: "good-css-cross-document-view-transitions"
+title: "Cross-document view transitions"
+tier: "reference"
+tags:
+  - "good-css"
+  - "motion"
+  - "cross"
+  - "document"
+  - "view"
+  - "transitions"
+summary: "Use it on any multi-page site to crossfade between pages. It replaces a client-side router or a page-transition script."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# Cross-document view transitions
+
+Use it on any multi-page site to crossfade between pages. It replaces a client-side router or a page-transition script.
+
+```css
+@view-transition { navigation: auto; }
+```
+
+Why it works:
+
+- On a same-origin navigation the browser snapshots the old and new page and crossfades them. Parts that do not change, such as the header, appear to stay in place.
+
+Rules:
+
+- Both pages must include the rule.
+- The default crossfade adds no movement and needs no reduced-motion guard. If you add slides, put the rule inside `@media (prefers-reduced-motion: no-preference)`.
+
+Support: Chrome 126, Safari 18.2. Firefox navigates as normal.
+
+- Borrowed from: Jen Simmons and James Craig, [Two lines of Cross-Document View Transitions code you can use on every website today](https://webkit.org/blog/16967/two-lines-of-cross-document-view-transitions-code-you-can-use-on-every-website-today/), 2025-05-21 · Bramus Van Damme, [Cross-document view transitions for multi-page applications](https://developer.chrome.com/docs/web-platform/view-transitions/cross-document)
+
+Source: [Good CSS](https://good-css.com/specimen/cross-document-view-transitions), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#cross-document-view-transitions).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.

package/knowledge/recipes/enter-and-exit-transitions-from-display-none.md

@@ -0,0 +1,87 @@
+---
+topic: "good-css-enter-and-exit-transitions-from-display-none"
+title: "Enter and exit transitions from display: none"
+tier: "reference"
+tags:
+  - "good-css"
+  - "show"
+  - "hide"
+  - "enter"
+  - "exit"
+  - "transitions"
+  - "display"
+  - "none"
+summary: "Use it for dialogs, popovers and anything else toggled with `display`. It replaces a script that adds classes and waits for `transitionend`."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# Enter and exit transitions from `display: none`
+
+Use it for dialogs, popovers and anything else toggled with `display`. It replaces a script that adds classes and waits for `transitionend`.
+
+```css
+dialog,
+[popover] {
+  opacity: 0;
+  transition:
+    opacity 0.2s var(--ease-out, ease-out),
+    translate 0.2s var(--ease-out, ease-out),
+    display 0.2s allow-discrete,
+    overlay 0.2s allow-discrete;
+}
+
+dialog::backdrop {
+  opacity: 0;
+  transition:
+    opacity 0.2s var(--ease-out, ease-out),
+    display 0.2s allow-discrete,
+    overlay 0.2s allow-discrete;
+}
+
+dialog[open],
+dialog[open]::backdrop { opacity: 1; }
+
+[popover]:popover-open { opacity: 1; }
+
+@starting-style {
+  dialog[open],
+  [popover]:popover-open,
+  dialog[open]::backdrop { opacity: 0; }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  dialog,
+  [popover] { translate: 0 0.5rem; }
+
+  dialog[open] { translate: 0 0; }
+
+  [popover]:popover-open { translate: 0 0; }
+
+  @starting-style {
+    dialog[open],
+    [popover]:popover-open { translate: 0 0.5rem; }
+  }
+}
+```
+
+Why it works:
+
+- `@starting-style` gives the browser a "before open" state to transition from when the element leaves `display: none`. That is the entry.
+- `allow-discrete` on `display` delays the switch to `display: none` until the other transitions finish. That is the exit. `overlay` keeps the element in the top layer meanwhile.
+- The fade is not motion, so it runs for everyone. Only the slide sits inside the reduced-motion query.
+
+Rules:
+
+- Put `@starting-style` after the open-state rule. It has no extra weight in the cascade.
+- Never start from `scale(0)`. If the element scales in, start at `scale(0.95)` with `opacity: 0`.
+- The dialog's `::backdrop` needs the same three states and its own transition, as in the block. Without them it snaps while the dialog fades.
+- Write no fallback. Where the exit is not supported the element closes at once.
+- Keep `[popover]:popover-open` out of the selector list that opens the dialog. A browser that does not know one selector in a list drops the whole rule, and the dialog would open at `opacity: 0`. Inside `@starting-style` the shared list is safe, because every browser that reads the block knows the selector.
+
+Support: both directions in Chrome 117. In Safari 27 the entry animates and `<dialog>` and popovers close at once, tested in real Safari on 2026-10-01. An element toggled with a class animates both ways there. Firefox 129 animates the entry only.
+
+- Borrowed from: Una Kravets and Joey Arhar, [Four new CSS features for smooth entry and exit animations](https://developer.chrome.com/blog/entry-exit-animations) · Kevin Powell, [Transition to and from display: none](https://www.youtube.com/watch?v=KD3_l3S_D6M), 2026-07-22 · Chris Coyier, [In-N-Out Animations: Dialogs](https://blog.master.dev/in-n-out-animations-dialogs-part-1-3/), 2026-06-01 · Adam Argyle, [Steal this popover code](https://nerdy.dev/steal-this-popover-starter-kit), 2024-03-15 · Ahmad Shadeed, [Grouping vendor selectors](https://defensivecss.dev/tip/grouping-selectors/), Defensive CSS, for the split rules
+
+Source: [Good CSS](https://good-css.com/specimen/enter-and-exit-transitions-from-display-none), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#enter-and-exit-transitions-from-display-none).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.

package/knowledge/recipes/fluid-sizes-with-clamp.md

@@ -0,0 +1,46 @@
+---
+topic: "good-css-fluid-sizes-with-clamp"
+title: "Fluid sizes with clamp()"
+tier: "reference"
+tags:
+  - "good-css"
+  - "foundations"
+  - "fluid"
+  - "sizes"
+  - "clamp"
+summary: "Use it for anything that should grow with the screen, starting with font sizes and section spacing. One declaration replaces a ladder of breakpoint overrides."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# Fluid sizes with `clamp()`
+
+Use it for anything that should grow with the screen, starting with font sizes and section spacing. One declaration replaces a ladder of breakpoint overrides.
+
+```css
+:root {
+  --text-body: clamp(1rem, 0.75rem + 1vw, 1.75rem);
+  --space-section: clamp(3rem, 1rem + 6vw, 8rem);
+}
+```
+
+Why it works:
+
+- `clamp(min, preferred, max)` uses the preferred value and stops at the two bounds.
+- The `vw` part of the preferred value grows with the viewport. The `rem` part sets where the growth starts.
+- `--text-body` above is 16px up to a 400px viewport, 28px from 1600px, and a straight line between.
+
+Rules:
+
+- Write the preferred value as `rem + vw`, never `vw` alone. `clamp(1rem, 1vw, 1.75rem)` stays at 16px on every screen narrower than 1600px, because 1vw is smaller than 1rem until then. A bare `vw` value also ignores the reader's font size setting.
+- Work the preferred value out from two points. The slope is `(max - min) / (wide - narrow)`, in px over px, and times 100 it is the `vw` number. The `rem` part is `min - slope × narrow`.
+- Keep both bounds in `rem` so they follow the reader's font size.
+- For a font size, keep the maximum at or below 2.5 times the minimum. The `vw` part does not grow when the reader zooms, so fluid text grows less than the page. Past 2.5 times, 500% zoom cannot double the text at some widths, and that fails WCAG 1.4.4.
+- Put fluid values in tokens. Components use the token and never repeat the math.
+- For more than two or three sizes, derive a whole scale as [One fluid scale for type and space](https://good-css.com/#one-fluid-scale-for-type-and-space) does.
+
+- Borrowed from: Kyrylo Silin, @kyrylo on X, 2026-05-10 · James Gilyead and Trys Mudford, [Utopia](https://utopia.fyi/) · Adrian Roselli, [Responsive Type and Zoom](https://adrianroselli.com/2019/12/responsive-type-and-zoom.html) · Maxwell Barvian, [Addressing Accessibility Concerns With Using Fluid Type](https://www.smashingmagazine.com/2023/11/addressing-accessibility-concerns-fluid-type/), 2023-11-07, for the 2.5 limit
+- Docs: [MDN: clamp()](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/clamp) · Adrian Bece, [Modern Fluid Typography Using CSS Clamp](https://www.smashingmagazine.com/2022/01/modern-fluid-typography-css-clamp/)
+
+Source: [Good CSS](https://good-css.com/specimen/fluid-sizes-with-clamp), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#fluid-sizes-with-clamp).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.

package/knowledge/recipes/form-feedback-with-user-invalid.md

@@ -0,0 +1,45 @@
+---
+topic: "good-css-form-feedback-with-user-invalid"
+title: "Form feedback with :user-invalid"
+tier: "reference"
+tags:
+  - "good-css"
+  - "interaction"
+  - "form"
+  - "feedback"
+  - "user"
+  - "invalid"
+summary: 'Use it for inline form validation, in place of blur listeners and a "touched" class.'
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# Form feedback with `:user-invalid`
+
+Use it for inline form validation, in place of blur listeners and a "touched" class.
+
+```css
+input:user-invalid { border-color: var(--danger); }
+input:user-valid { border-color: var(--success); }
+```
+
+```html
+<input type="password" required minlength="8">
+```
+
+Why it works:
+
+- `:invalid` matches an empty required field on page load. The `:user-` versions match only after the user has edited the field or tried to submit.
+- Validity comes from HTML attributes: `required`, `minlength`, `type`, `pattern`.
+
+Rules:
+
+- Color alone is not enough feedback. Pair it with text or an icon.
+- The server still validates.
+
+Support: Chrome 119, Firefox 88, Safari 16.5.
+
+- Borrowed from: Kevin Powell, [Improve forms with :user-valid and :user-invalid](https://www.youtube.com/watch?v=NmSifR3dS7o), 2025-02-20, and [Use these CSS features instead of JavaScript](https://www.youtube.com/watch?v=qu1jE41O_8o), 2026-09-23
+
+Source: [Good CSS](https://good-css.com/specimen/form-feedback-with-user-invalid), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#form-feedback-with-user-invalid).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.

package/knowledge/recipes/has-for-parent-and-page-state.md

@@ -0,0 +1,46 @@
+---
+topic: "good-css-has-for-parent-and-page-state"
+title: ":has() for parent and page state"
+tier: "reference"
+tags:
+  - "good-css"
+  - "interaction"
+  - "has"
+  - "parent"
+  - "page"
+  - "state"
+summary: "Use it wherever a script adds a class to a parent because of what it contains or what state a child is in."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# `:has()` for parent and page state
+
+Use it wherever a script adds a class to a parent because of what it contains or what state a child is in.
+
+```css
+article:has(img) { grid-column: span 2; }
+h2:has(+ p) { margin-block-end: 0; }
+form:has(:focus-visible) { background: var(--surface-raised); }
+
+html { scrollbar-gutter: stable; }
+html:has(dialog:modal) { overflow: hidden; }
+```
+
+Why it works:
+
+- `:has()` matches an element by its descendants or following siblings, and it accepts state pseudo-classes. Content and form state can style any ancestor.
+- On the root it works as a page-wide listener. The last rule locks page scroll while a modal dialog is open and lifts the lock when it closes, with nothing to clean up.
+
+Rules:
+
+- `:modal` matches `showModal()` only, so a non-modal dialog does not lock the page.
+- Keep `scrollbar-gutter: stable` with the scroll lock. Without it the page shifts sideways when the scrollbar disappears. [The reset](https://good-css.com/#the-reset) sets it.
+- `:has()` cannot be nested inside `:has()`.
+
+Support: Chrome 105, Firefox 121, Safari 15.4.
+
+- Borrowed from: Jen Simmons, [Using :has() as a CSS Parent Selector and much more](https://webkit.org/blog/13096/css-has-pseudo-class/), 2022-08-18 · Josh W. Comeau, [The Undeniable Utility Of CSS :has](https://www.joshwcomeau.com/css/has/), 2024-09-09 · Chris Coyier, [Scroll-Locked Dialogs](https://blog.master.dev/scroll-locked-dialogs/), 2024-02-19
+
+Source: [Good CSS](https://good-css.com/specimen/has-for-parent-and-page-state), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#has-for-parent-and-page-state).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.

package/knowledge/recipes/hit-area-larger-than-the-visual.md

@@ -0,0 +1,47 @@
+---
+topic: "good-css-hit-area-larger-than-the-visual"
+title: "Hit area larger than the visual"
+tier: "reference"
+tags:
+  - "good-css"
+  - "interaction"
+  - "hit"
+  - "area"
+  - "larger"
+  - "than"
+  - "visual"
+summary: "Use it on icon buttons, close buttons and any target that looks smaller than 44px."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# Hit area larger than the visual
+
+Use it on icon buttons, close buttons and any target that looks smaller than 44px.
+
+```css
+.icon-button { position: relative; }
+
+.icon-button::after {
+  content: "";
+  position: absolute;
+  inset: min(0px, (100% - 44px) / 2);
+}
+```
+
+Why it works:
+
+- The pseudo-element belongs to the button, so a click on it hits the button.
+- The negative inset grows the area to exactly 44px. `min(0px, …)` leaves larger targets alone.
+
+Rules:
+
+- `overflow: hidden` or `clip` on the button cuts the area off.
+- It does not work on `<input>`, which has no pseudo-elements. Wrap it in a `<label>`.
+
+Support: Chrome 87, Firefox 66, Safari 14.1.
+
+- Borrowed from: Emil Kowalski, [Agents with Taste](https://emilkowal.ski/ui/agents-with-taste), for the rule · [Vercel Web Interface Guidelines](https://vercel.com/design/guidelines). The `inset` formula was written for this list.
+
+Source: [Good CSS](https://good-css.com/specimen/hit-area-larger-than-the-visual), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#hit-area-larger-than-the-visual).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.

package/knowledge/recipes/hover-styles-only-where-hover-exists.md

@@ -0,0 +1,43 @@
+---
+topic: "good-css-hover-styles-only-where-hover-exists"
+title: "Hover styles only where hover exists"
+tier: "reference"
+tags:
+  - "good-css"
+  - "interaction"
+  - "hover"
+  - "styles"
+  - "only"
+  - "where"
+  - "exists"
+summary: "Use it on every `:hover` rule, so a tap on a touch screen does not leave the hover state stuck."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# Hover styles only where hover exists
+
+Use it on every `:hover` rule, so a tap on a touch screen does not leave the hover state stuck.
+
+```css
+@media (hover: hover) and (pointer: fine) {
+  .button:hover { background: var(--primary-hover); }
+}
+```
+
+Why it works:
+
+- Touch browsers apply `:hover` on tap and keep it until the next tap elsewhere. `hover: hover` asks whether the primary input can hover.
+- `pointer: fine` asks whether it is precise, like a mouse. It rules out styluses and the Android devices that claim hover support.
+
+Rules:
+
+- Tailwind v4's `hover:` variant wraps itself in `(hover: hover)` only. Write the full query by hand everywhere else.
+- Touch users still need feedback on press. Give it with `:active`, which works for every input.
+
+Support: Chrome 38, Firefox 64, Safari 9.
+
+- Borrowed from: Emil Kowalski, [mobile-native skill](https://github.com/emilkowalski/skills/blob/main/skills/mobile-native/SKILL.md) and [emil-design-eng skill](https://github.com/emilkowalski/skills/blob/main/skills/emil-design-eng/SKILL.md) · Rauno Freiberg, [Web Interface Guidelines](https://interfaces.rauno.me/)
+
+Source: [Good CSS](https://good-css.com/specimen/hover-styles-only-where-hover-exists), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#hover-styles-only-where-hover-exists).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.

package/knowledge/recipes/icon-sized-by-the-text-beside-it.md

@@ -0,0 +1,69 @@
+---
+topic: "good-css-icon-sized-by-the-text-beside-it"
+title: "Icon sized by the text beside it"
+tier: "reference"
+tags:
+  - "good-css"
+  - "text"
+  - "media"
+  - "icon"
+  - "sized"
+  - "beside"
+summary: "Use it on every icon that sits next to a label, in buttons, links, list rows and notices. The icon takes its size from the font, so it follows the text and never needs a size per variant."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# Icon sized by the text beside it
+
+Use it on every icon that sits next to a label, in buttons, links, list rows and notices. The icon takes its size from the font, so it follows the text and never needs a size per variant.
+
+```css
+.with-icon {
+  display: inline-flex;
+  align-items: baseline;
+  gap: 0.5em;
+}
+
+.with-icon > svg {
+  flex: none;
+  block-size: 1cap;
+  inline-size: auto;
+}
+
+.notice {
+  display: flex;
+  align-items: start;
+  gap: 0.5em;
+}
+
+.notice > svg {
+  flex: none;
+  inline-size: 1em;
+  block-size: 1lh;
+}
+```
+
+Why it works:
+
+- `1cap` is the height of the font's capital letters. An icon that tall reads as one more capital.
+- An `svg` has no baseline of its own. `align-items: baseline` rests its bottom edge on the baseline of the text, so the icon stands where a capital stands.
+- `1lh` is the height of one line. The second rule makes the icon's box as tall as the first line of the label, and the drawing centers itself in that box. The icon stays beside the first line when the label wraps.
+- A `gap` in `em` keeps the space in proportion.
+
+Rules:
+
+- Never size an icon in `px`. A 16px icon that matches 16px text is 5px to 7px shorter than the capitals of 32px text.
+- Keep `flex: none`. Without it a long label squeezes the icon.
+- The `svg` needs a `viewBox`. `inline-size: auto` then follows the drawing's ratio.
+- Many icon sets leave padding inside the drawing, and `1cap` looks small on those. Raise the number and keep the unit, as in `1.2cap`.
+- Do not use `align-items: center` on a label that can wrap. The icon then sits beside the middle line.
+- With [Label centered on its letters with `text-box`](https://good-css.com/#label-centered-on-its-letters-with-text-box) the trimmed label is `1cap` tall, so `align-items: center` lines the icon up with it at both edges.
+
+Support: `cap` in Chrome 118, Firefox 97, Safari 17.2. `lh` in Chrome 109, Firefox 120, Safari 16.4. Tested in Chrome 150 and real Safari 27 on 2026-10-01, where the icon came out within 0.01px of the capital height at 16px and at 32px.
+
+- Borrowed from: Andy Bell, [How I build a button component](https://piccalil.li/blog/how-i-build-a-button-component/), 2024-09-18, for `cap` and `flex: none`, and [LH units are cool](https://piccalil.li/blog/lh-units-are-cool/), 2023-12-13 · Heydon Pickering and Andy Bell, [The Icon](https://every-layout.dev/layouts/icon/), Every Layout
+- Docs: [MDN: length units](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/length)
+
+Source: [Good CSS](https://good-css.com/specimen/icon-sized-by-the-text-beside-it), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#icon-sized-by-the-text-beside-it).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.

package/knowledge/recipes/image-box-that-holds-any-upload.md

@@ -0,0 +1,67 @@
+---
+topic: "good-css-image-box-that-holds-any-upload"
+title: "Image box that holds any upload"
+tier: "reference"
+tags:
+  - "good-css"
+  - "text"
+  - "media"
+  - "image"
+  - "box"
+  - "holds"
+  - "any"
+  - "upload"
+summary: "Use it on every image, video or embed whose file you do not control, such as thumbnails, cover photos and avatars. The box keeps its shape whatever the file's ratio, and it has that shape before the file loads."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# Image box that holds any upload
+
+Use it on every image, video or embed whose file you do not control, such as thumbnails, cover photos and avatars. The box keeps its shape whatever the file's ratio, and it has that shape before the file loads.
+
+```css
+.thumb {
+  inline-size: 100%;
+  block-size: auto;
+  aspect-ratio: 16 / 9;
+  object-fit: cover;
+  background-color: var(--surface-muted, oklch(0.9 0 none));
+}
+
+.avatar {
+  flex: none;
+  inline-size: 3.5rem;
+  block-size: 3.5rem;
+  border-radius: 50%;
+  object-fit: cover;
+  outline: 1px solid light-dark(oklch(0 0 none / 0.1), oklch(1 0 none / 0.1));
+  outline-offset: -1px;
+}
+```
+
+Why it works:
+
+- `aspect-ratio` works out the height from the width, so the space is there before the file loads.
+- `object-fit: cover` scales the picture until it fills the box and crops the rest. The default stretches it.
+- The background color shows until the image paints, and in its place when the load fails.
+- An outline with a negative offset draws inside the image's edge. It takes no space and follows the `border-radius`, so a white avatar on a white card still has an edge.
+- `flex: none` stops the text beside the avatar from squeezing it.
+
+Rules:
+
+- One axis must be `auto`. A `height` attribute or a fixed height wins over the ratio. The reset sets `height: auto` on `img`, `svg` and `video`, and `block-size: auto` here does the same for an `iframe`.
+- `object-fit` does nothing until the box has both sizes or a ratio.
+- `cover` crops. Use `contain` for logos, product shots and anything that must stay whole. Move the crop with `object-position`.
+- Leave the background color off an image that has transparent areas. It shows through them.
+- A fixed-size image in a flex row needs both sizes, as the avatar has. With only a width it stretches to the height of the row.
+- In Safari a failed image ignores `aspect-ratio` and draws a square box. Where a failed load must not move the layout, put the ratio on a wrapper and give the image `inline-size: 100%` and `block-size: 100%`.
+- `light-dark()` needs the `color-scheme` from [One set of color tokens for light and dark](https://good-css.com/#one-set-of-color-tokens-for-light-and-dark). Without it the outline stays black on a dark page.
+
+Support: `aspect-ratio` in Chrome 88, Firefox 89, Safari 15. An outline that follows the radius in Chrome 94, Firefox 88, Safari 16.4. `light-dark()` in Chrome 123, Firefox 120, Safari 17.5. The square box of a failed image is from real Safari 27, tested on 2026-10-01. Chrome 150 keeps the ratio.
+
+- Borrowed from: Ahmad Shadeed, [Defensive CSS](https://defensivecss.dev/), the tips [Image distortion](https://defensivecss.dev/tip/image-compressed/), [Image inner border](https://defensivecss.dev/tip/inner-shadow/) and [Default flexbox stretching](https://defensivecss.dev/tip/default-flexbox-stretching/). This version draws the inner edge with an outline where his adds an element · Heydon Pickering and Andy Bell, [The Frame](https://every-layout.dev/layouts/frame/), Every Layout, which wraps the media. On `img`, `video` and `iframe` the rule goes on the element.
+- Docs: [MDN: aspect-ratio](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/aspect-ratio) · [MDN: object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/object-fit) · [MDN: outline-offset](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/outline-offset)
+
+Source: [Good CSS](https://good-css.com/specimen/image-box-that-holds-any-upload), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#image-box-that-holds-any-upload).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.

package/knowledge/recipes/indicator-that-slides-to-the-active-item.md

@@ -0,0 +1,80 @@
+---
+topic: "good-css-indicator-that-slides-to-the-active-item"
+title: "Indicator that slides to the active item"
+tier: "reference"
+tags:
+  - "good-css"
+  - "motion"
+  - "indicator"
+  - "slides"
+  - "active"
+  - "item"
+summary: "Use it for the underline on a tab row or the bar beside a side nav. It replaces a script that measures the active item and writes a `transform` and a width."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# Indicator that slides to the active item
+
+Use it for the underline on a tab row or the bar beside a side nav. It replaces a script that measures the active item and writes a `transform` and a width.
+
+```html
+<nav class="tabs">
+  <ul>
+    <li><a href="/overview" aria-current="page">Overview</a></li>
+    <li><a href="/pricing">Pricing and billing</a></li>
+    <li><a href="/docs">Docs</a></li>
+  </ul>
+</nav>
+```
+
+```css
+.tabs { anchor-scope: --active; }
+
+.tabs ul {
+  position: relative;
+  display: flex;
+}
+
+.tabs [aria-current="page"] { anchor-name: --active; }
+
+.tabs ul::after {
+  content: "";
+  position: absolute;
+  position-anchor: --active;
+  inset-block-end: 0;
+  inset-inline-start: anchor(start);
+  inline-size: anchor-size(inline);
+  block-size: 2px;
+  background: currentColor;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .tabs ul::after {
+    transition:
+      inset-inline-start 0.25s var(--ease-out, ease-out),
+      inline-size 0.25s var(--ease-out, ease-out);
+  }
+}
+```
+
+Why it works:
+
+- The anchor name sits on whichever item carries `aria-current`. Move the attribute and the anchor moves with it. The same attribute tells a screen reader which item is current, so there is no separate "active" class to keep in sync.
+- `anchor()` and `anchor-size()` resolve to the item's edge and size. A longer label, a larger font or a wrapped line needs no new measurement.
+- The bar is one element whose inset and size change, so a plain transition slides it.
+
+Rules:
+
+- Keep `anchor-scope` on the component root. Without it an anchor name is global, and two navs on one page both follow the last active item.
+- The list needs `position: relative`, so the bar is positioned against the box that holds the items.
+- For a vertical list swap the axes. Use `inset-block-start: anchor(top)` and `block-size: anchor-size(height)`, and transition those two.
+- Give the active item a second cue such as weight or color. A browser without anchor positioning drops the `anchor()` declarations and the bar has no width.
+
+Support: Chrome 131, Firefox 147, Safari 26. Firefox places the bar and does not slide it.
+
+- Borrowed from: Stripe, which ships the vertical form for a side nav in its home page stylesheet. The research found the rules and no page that renders the component, so this is from the stylesheet alone.
+- Docs: [MDN: anchor-name](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/anchor-name) · [MDN: anchor-scope](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/anchor-scope) · [MDN: anchor-size()](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/anchor-size)
+
+Source: [Good CSS](https://good-css.com/specimen/indicator-that-slides-to-the-active-item), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#indicator-that-slides-to-the-active-item).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.