@daydreamui/good-css 0.0.0-stage → 0.3.0

package/knowledge/recipes/intrinsic-grid.md

@@ -0,0 +1,41 @@
+---
+topic: "good-css-intrinsic-grid"
+title: "Intrinsic grid"
+tier: "reference"
+tags:
+  - "good-css"
+  - "layout"
+  - "intrinsic"
+  - "grid"
+summary: "Use it for any set of equal cards or tiles. It replaces a column count per breakpoint."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# Intrinsic grid
+
+Use it for any set of equal cards or tiles. It replaces a column count per breakpoint.
+
+```css
+.grid {
+  display: grid;
+  gap: 1rem;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr));
+}
+```
+
+Why it works:
+
+- `auto-fit` creates as many 16rem columns as the row holds, and `1fr` shares what is left. The column count follows the container.
+- `min(100%, 16rem)` lets the minimum shrink to the container. Without it a 200px container overflows.
+
+Rules:
+
+- `auto-fit` stretches a short row to fill the width. Use `auto-fill` when the item count changes, such as a filtered list, so cards keep their size.
+
+Support: Chrome 79, Firefox 76, Safari 11.1.
+
+- Borrowed from: Kevin Powell, [Breakpoint-Free CSS Grid Layouts](https://www.youtube.com/watch?v=bj0Z_GncIwY), 2025-02-19 · Stephanie Eckles, [Smol Responsive CSS Grid](https://smolcss.dev/#smol-css-grid) · Una Kravets, [Ten modern layouts in one line of CSS](https://web.dev/articles/one-line-layouts)
+
+Source: [Good CSS](https://good-css.com/specimen/intrinsic-grid), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#intrinsic-grid).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.

package/knowledge/recipes/label-centered-on-its-letters-with-text-box.md

@@ -0,0 +1,59 @@
+---
+topic: "good-css-label-centered-on-its-letters-with-text-box"
+title: "Label centered on its letters with text-box"
+tier: "reference"
+tags:
+  - "good-css"
+  - "text"
+  - "media"
+  - "label"
+  - "centered"
+  - "letters"
+  - "box"
+summary: "Use it on single-line labels in buttons, badges and chips, so equal padding looks equal in any font."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# Label centered on its letters with `text-box`
+
+Use it on single-line labels in buttons, badges and chips, so equal padding looks equal in any font.
+
+```css
+.button {
+  display: inline-block;
+  padding: 0.75rem 1.25rem;
+  text-box: trim-both cap alphabetic;
+}
+
+.button-with-icon {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.75rem 1.25rem;
+}
+
+.button-with-icon > span { text-box: trim-both cap alphabetic; }
+```
+
+Why it works:
+
+- A line of text reserves space above the capitals and below the baseline, and the two amounts differ from font to font. Equal padding around that line puts the letters off-center.
+- `trim-both cap alphabetic` cuts the box down to the cap height and the baseline. The padding then starts at the letters.
+- A font swap or a fallback font no longer moves the label.
+
+Rules:
+
+- It does nothing on a flex or grid container. A button that is `inline-flex` because it holds an icon needs the declaration on the element that wraps the text, as in the second rule of the block.
+- The button gets shorter, because the padding now starts at the letters. With `0.75rem` of padding it went from 48px tall to 35px in Chrome and Safari. Raise the padding to keep the height.
+- Use it for one line. Descenders hang into the bottom padding, which is the intent.
+- Scope it to labels. Never set it on `*`, because it shrinks every text block. A one-line paragraph at 16px/1.5 went from 25px tall to 11px.
+- Write no fallback. Without support the label keeps its normal line box.
+
+Support: Chrome 133, Firefox 154, Safari 18.2.
+
+- Borrowed from: Stripe, which ships it on its buttons at stripe.com. There the button is a flex container, so the declaration has no effect and uneven padding does the centering. The first rule above is the fix.
+- Docs: [MDN: text-box](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/text-box)
+
+Source: [Good CSS](https://good-css.com/specimen/label-centered-on-its-letters-with-text-box), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#label-centered-on-its-letters-with-text-box).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.

package/knowledge/recipes/logical-properties.md

@@ -0,0 +1,48 @@
+---
+topic: "good-css-logical-properties"
+title: "Logical properties"
+tier: "reference"
+tags:
+  - "good-css"
+  - "foundations"
+  - "logical"
+  - "properties"
+summary: "Use them in place of every left, right, top and bottom, in spacing, borders, offsets and alignment."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# Logical properties
+
+Use them in place of every left, right, top and bottom, in spacing, borders, offsets and alignment.
+
+```css
+.card {
+  position: relative;
+  padding-inline: 1.5rem;
+  margin-block-end: 2rem;
+  border-inline-start: 4px solid;
+  text-align: start;
+}
+
+.card .close {
+  position: absolute;
+  inset-block-start: 1rem;
+  inset-inline-end: 1rem;
+}
+```
+
+Why it works:
+
+- `inline` is the direction text runs and `block` the direction blocks stack. Start and end follow `dir` and `writing-mode`, so one set of declarations renders mirrored in a right-to-left page.
+
+Rules:
+
+- The four-value `margin`, `padding` and `inset` shorthands stay physical. Use the `-inline` and `-block` shorthands.
+
+Support: Chrome 87, Firefox 66, Safari 14.1.
+
+- Borrowed from: Ahmad Shadeed, [Digging Into CSS Logical Properties](https://ishadeed.com/article/css-logical-properties/), 2021-03-10
+
+Source: [Good CSS](https://good-css.com/specimen/logical-properties), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#logical-properties).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.

package/knowledge/recipes/long-text-that-wraps-truncates-or-clamps.md

@@ -0,0 +1,62 @@
+---
+topic: "good-css-long-text-that-wraps-truncates-or-clamps"
+title: "Long text that wraps, truncates or clamps"
+tier: "reference"
+tags:
+  - "good-css"
+  - "text"
+  - "media"
+  - "long"
+  - "wraps"
+  - "truncates"
+  - "clamps"
+summary: "Use it on any text that comes from a user or a CMS, such as names, titles, URLs and excerpts. Decide for each one what happens when the content is longer than the design. It wraps, it is cut to one line, or it is cut to a few lines."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# Long text that wraps, truncates or clamps
+
+Use it on any text that comes from a user or a CMS, such as names, titles, URLs and excerpts. Decide for each one what happens when the content is longer than the design. It wraps, it is cut to one line, or it is cut to a few lines.
+
+```css
+:root { overflow-wrap: break-word; }
+
+.name {
+  white-space: nowrap;
+  overflow: clip;
+  text-overflow: ellipsis;
+}
+
+.excerpt {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 3;
+  overflow: clip;
+}
+```
+
+Why it works:
+
+- `overflow-wrap: break-word` breaks a word only when it cannot fit on a line by itself. Ordinary text wraps as before. It inherits, so the one declaration in the reset covers the page.
+- The reset's `min-width: 0` lets a flex or grid item get narrower than its longest word. It does nothing for the word, which then paints over the next column. The two rules need each other.
+- `nowrap` keeps the text on one line, `overflow` cuts it and `text-overflow` draws the ellipsis at the cut.
+- `-webkit-line-clamp` counts lines, so the clamp holds at any font size and any width.
+
+Rules:
+
+- Put the truncation on the element that holds the text. On a flex or grid container the text is cut and no ellipsis appears.
+- Every flex item between the row and the truncated text must be able to shrink. The reset's `min-width: 0` covers that. Without the reset, set `min-inline-size: 0` on each of them.
+- The clamp needs all four declarations. Unprefixed `line-clamp` is in no browser yet.
+- Put padding on a wrapper, never on the clamped element. The next line shows through the bottom padding.
+- Use `break-word` on the root and not `anywhere`. `anywhere` also shrinks the minimum content width, so a box sized by its content collapses to one letter per line.
+- A table with automatic layout ignores `break-word`. Set `overflow-wrap: anywhere` on the cell.
+- Truncate only text the reader can get in full somewhere else. Never truncate text they have to read.
+
+Support: `text-overflow`, `-webkit-line-clamp` and `overflow-wrap: break-word` work everywhere. With `overflow: clip` the ellipsis and the clamp draw in Chrome 150 and Safari 27, tested on 2026-10-01. Firefox is untested, and `overflow: hidden` is the form to fall back to. `overflow-wrap: anywhere` in Chrome 80, Firefox 65, Safari 15.4.
+
+- Borrowed from: Ahmad Shadeed, [Defensive CSS](https://defensivecss.dev/), the tips [Long content](https://defensivecss.dev/tip/long-content/) and [Minimum content size in flexbox](https://defensivecss.dev/tip/flexbox-min-content-size/) · Ahmad Shadeed, [Handling Short And Long Content In CSS](https://ishadeed.com/article/css-short-long-content/), 2020-12-16
+- Docs: [MDN: overflow-wrap](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/overflow-wrap) · [MDN: text-overflow](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/text-overflow) · [MDN: line-clamp](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/line-clamp)
+
+Source: [Good CSS](https://good-css.com/specimen/long-text-that-wraps-truncates-or-clamps), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#long-text-that-wraps-truncates-or-clamps).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.

package/knowledge/recipes/motion-tokens.md

@@ -0,0 +1,46 @@
+---
+topic: "good-css-motion-tokens"
+title: "Motion tokens"
+tier: "reference"
+tags:
+  - "good-css"
+  - "motion"
+  - "tokens"
+summary: "Use them in every transition and animation. Two easing curves, defined once, and a rule for durations."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# Motion tokens
+
+Use them in every transition and animation. Two easing curves, defined once, and a rule for durations.
+
+```css
+:root {
+  --ease-out: cubic-bezier(0.23, 1, 0.32, 1);
+  --ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);
+}
+
+.dropdown { transition: opacity 180ms var(--ease-out); }
+```
+
+Why it works:
+
+- An ease-out curve starts fast, so the interface moves at the moment the user is watching. Use `--ease-out` for anything entering or leaving.
+- An ease-in-out curve suits something that is already on screen and moves to a new place. Use `--ease-in-out` there.
+- The built-in `ease-out` and `ease-in-out` keywords are weak versions of the same shapes. These two are stronger.
+
+Rules:
+
+- Never use `ease-in` on UI. It starts slow and reads as lag.
+- Keep a UI transition at 300ms or less. Press feedback takes 100 to 160ms, tooltips and small popovers 125 to 200ms, dropdowns 150 to 250ms. The one exception is a modal or drawer, which takes 200 to 500ms.
+- Name the properties in a transition. Never write `transition: all`.
+- Other entries write `var(--ease-out, ease-out)`, so their snippets work before these tokens exist.
+- Whether something should animate at all is not a CSS question. Emil Kowalski's `animate` and `review-animations` skills answer it.
+
+Support: every browser.
+
+- Borrowed from: Emil Kowalski, [emil-design-eng skill](https://github.com/emilkowalski/skills/blob/main/skills/emil-design-eng/SKILL.md) and [7 Practical Animation Tips](https://emilkowal.ski/ui/7-practical-animation-tips)
+
+Source: [Good CSS](https://good-css.com/specimen/motion-tokens), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#motion-tokens).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.

package/knowledge/recipes/no-rubber-band-bounce-on-desktop.md

@@ -0,0 +1,47 @@
+---
+topic: "good-css-no-rubber-band-bounce-on-desktop"
+title: "No rubber-band bounce on desktop"
+tier: "reference"
+tags:
+  - "good-css"
+  - "scroll"
+  - "viewport"
+  - "no"
+  - "rubber"
+  - "band"
+  - "bounce"
+  - "desktop"
+summary: "Use it on app-like pages with fixed UI, such as a sidebar or a sticky header. On macOS a trackpad scroll stretches the whole page past its edge and drags the fixed UI along."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# No rubber-band bounce on desktop
+
+Use it on app-like pages with fixed UI, such as a sidebar or a sticky header. On macOS a trackpad scroll stretches the whole page past its edge and drags the fixed UI along.
+
+```css
+html { overscroll-behavior-y: none; }
+
+@media (any-pointer: coarse) {
+  html { overscroll-behavior-y: auto; }
+}
+```
+
+Why it works:
+
+- `overscroll-behavior-y: none` on the root turns off the bounce.
+- Touch devices get the default back, because pull to refresh depends on it.
+- `any-pointer` checks every input, where `pointer` checks only the primary one. A device with a touchscreen plus a mouse or stylus keeps pull to refresh. Jhey's example is a foldable.
+
+Rules:
+
+- Set it on `html`. The viewport takes its overscroll behavior from the root element.
+- Use the `-y` longhand. `overscroll-behavior-x: none` also turns off swipe to go back.
+- Give inner scroll containers, such as a sheet, a chat list or a sidebar, `overscroll-behavior: contain`. They keep their own bounce and stop the page behind them from moving. Never use a `touchmove` listener with `preventDefault()` for this.
+
+- Borrowed from: wits, @witsdev on X, 2026-09-30, describing how Vercel gates it behind `pointer: fine` · Jhey Tompkins, @jh3yy on X, for the `any-pointer` version · Emil Kowalski, [mobile-native skill](https://github.com/emilkowalski/skills/blob/main/skills/mobile-native/SKILL.md), for the inner containers
+- Docs: [MDN: overscroll-behavior](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/overscroll-behavior) · [MDN: any-pointer](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/any-pointer)
+
+Source: [Good CSS](https://good-css.com/specimen/no-rubber-band-bounce-on-desktop), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#no-rubber-band-bounce-on-desktop).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.

package/knowledge/recipes/oklch-color.md

@@ -0,0 +1,41 @@
+---
+topic: "good-css-oklch-color"
+title: "OKLCH color"
+tier: "reference"
+tags:
+  - "good-css"
+  - "foundations"
+  - "oklch"
+  - "color"
+summary: "Write colors in `oklch()` and derive every related color from a base with `color-mix(in oklch, …)`. Never hardcode a second hex or an `rgba()` for a hover, tint or transparent version."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# OKLCH color
+
+Write colors in `oklch()` and derive every related color from a base with `color-mix(in oklch, …)`. Never hardcode a second hex or an `rgba()` for a hover, tint or transparent version.
+
+```css
+:root {
+  --primary: oklch(55% 0.15 250);
+  --primary-hover: color-mix(in oklch, var(--primary), black 15%);
+  --primary-subtle: color-mix(in oklch, var(--primary) 12%, transparent);
+}
+```
+
+Why it works:
+
+- The three channels are lightness, chroma and hue. Lightness is perceptual, so two colors with the same L look equally light whatever their hue. Scales and contrast become predictable.
+- Mixing in OKLCH keeps the hue of the base color, where sRGB mixing drifts toward gray.
+- One base value drives the whole family. Change the base and the hover and subtle versions follow.
+
+Rules:
+
+- Write grays, white and black with `none` as the hue, as in `oklch(98% 0 none)`. A written hue of `0` is red, and it pulls every mix toward red. Half white `oklch(1 0 0)` and half a blue at hue 264 came out at hue 312 in Chrome and Safari. With `none`, or with the keyword `white`, it stayed at 264.
+
+- Borrowed from: Andrey Sitnik and Travis Turner (Evil Martians), [OKLCH in CSS: why we moved from RGB and HSL](https://evilmartians.com/chronicles/oklch-in-css-why-quit-rgb-hsl) · Björn Ottosson, [A perceptual color space for image processing](https://bottosson.github.io/posts/oklab/)
+- Docs: [MDN: oklch()](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/oklch) · [MDN: color-mix()](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/color-mix) · [oklch.com picker](https://oklch.com/)
+
+Source: [Good CSS](https://good-css.com/specimen/oklch-color), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#oklch-color).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.

package/knowledge/recipes/one-fluid-scale-for-type-and-space.md

@@ -0,0 +1,85 @@
+---
+topic: "good-css-one-fluid-scale-for-type-and-space"
+title: "One fluid scale for type and space"
+tier: "reference"
+tags:
+  - "good-css"
+  - "foundations"
+  - "one"
+  - "fluid"
+  - "scale"
+  - "type"
+  - "space"
+summary: "Use it when a design has more than two or three font sizes. Six numbers describe every size, and the browser derives the steps. It replaces a table of sizes per breakpoint, and it replaces a generator that someone has to find and run again."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# One fluid scale for type and space
+
+Use it when a design has more than two or three font sizes. Six numbers describe every size, and the browser derives the steps. It replaces a table of sizes per breakpoint, and it replaces a generator that someone has to find and run again.
+
+```css
+:root {
+  --narrow: 20;
+  --wide: 77.5;
+  --size-narrow: 1.125;
+  --size-wide: 1.25;
+  --ratio-narrow: 1.2;
+  --ratio-wide: 1.25;
+
+  --fluid: clamp(0rem, (100vw - var(--narrow) * 1rem) / (var(--wide) - var(--narrow)), 1rem);
+  --at-narrow: calc(var(--size-narrow) * (1rem - var(--fluid)));
+  --at-wide: calc(var(--size-wide) * var(--fluid));
+
+  --step--1: calc(var(--step-0) / var(--ratio-narrow));
+  --step-0: calc(var(--at-narrow) + var(--at-wide));
+  --step-1: calc(var(--at-narrow) * var(--ratio-narrow) + var(--at-wide) * var(--ratio-wide));
+  --step-2: calc(var(--at-narrow) * pow(var(--ratio-narrow), 2) + var(--at-wide) * pow(var(--ratio-wide), 2));
+  --step-3: calc(var(--at-narrow) * pow(var(--ratio-narrow), 3) + var(--at-wide) * pow(var(--ratio-wide), 3));
+  --step-4: calc(var(--at-narrow) * pow(var(--ratio-narrow), 4) + var(--at-wide) * pow(var(--ratio-wide), 4));
+
+  --space-s: var(--step-0);
+  --space-m: calc(1.5 * var(--step-0));
+  --space-l: calc(2 * var(--step-0));
+  --space-s-l: calc(var(--at-narrow) + 2 * var(--at-wide));
+}
+
+body { font-size: var(--step-0); }
+h1 { font-size: var(--step-4); }
+h2 { font-size: var(--step-2); }
+small { font-size: var(--step--1); }
+
+.card {
+  display: grid;
+  gap: var(--space-s);
+  padding: var(--space-s-l);
+}
+```
+
+Why it works:
+
+- The first six lines are the whole design decision. Widths and sizes are in rem, written as plain numbers, so 20 is 320px and 1.125 is 18px. Body text runs from 18px on a 320px screen to 20px on a 1240px one, and each heading step is 1.2 times the last on the phone and 1.25 times on the desktop.
+- `--fluid` is a length that is 0 at the narrow width, 1rem at the wide width and a straight line between. It holds the only `clamp()`, and that one bounds every token.
+- `--at-narrow` and `--at-wide` are the two base sizes, each weighted by how close the viewport is to its width. Their sum is step 0.
+- `pow()` raises each ratio to the step number. A step is the narrow scale's size times one weight plus the wide scale's size times the other, which is the line [Fluid sizes with `clamp()`](https://good-css.com/#fluid-sizes-with-clamp) draws between two points.
+- A space token is a multiple of step 0, so it grows as much as body text does. A pair such as `--space-s-l` gives the two terms different multipliers. It is the small size on the phone and the large size on the desktop, 18px to 40px here.
+
+Rules:
+
+- Write the inputs as plain numbers. With `20rem` and `77.5rem` the `--fluid` line divides a length by a length, and Firefox does not support that.
+- Change an input in the rule that declares the steps. A step takes its value where it is declared, so a ratio set on a descendant changes nothing below it.
+- Derive sizes below step 0 from step 0 and the narrow ratio, as `--step--1` does. With both ratios a small size shrinks as the screen grows.
+- Check the top step against the limit in [Fluid sizes with `clamp()`](https://good-css.com/#fluid-sizes-with-clamp). Step `n` passes when `(size-wide / size-narrow) × (ratio-wide / ratio-narrow)ⁿ` is 2.5 or less. The example gives 1.31 at step 4.
+- Write a pair only where a layout uses it, and never use one for a font size. A pair is steep on purpose and breaks that limit.
+- For a scale that follows the container, write `100cqi` in place of `100vw`. [Container queries with container units](https://good-css.com/#container-queries-with-container-units) has the rules.
+- Components use the tokens and never repeat the math.
+
+Support: Chrome 120, Firefox 118, Safari 15.4, set by `pow()`. Tested in Chrome 150 and real Safari 27 on 2026-10-01, where every step came out within 0.001px of the formula.
+
+- Borrowed from: James Gilyead, [Designing with fluid type scales](https://utopia.fyi/blog/designing-with-fluid-type-scales), 2020-02-01, for the two scales · Trys Mudford, [CSS-only fluid modular type scales](https://utopia.fyi/blog/css-modular-scales), 2020-02-02, and [Fluid custom properties](https://utopia.fyi/blog/fluid-custom-properties), 2020-02-03 · James Gilyead, [Designing with a fluid space palette](https://utopia.fyi/blog/designing-with-a-fluid-space-palette), 2021-03-16, for space pairs. Utopia prints one finished `clamp()` per step from a calculator, because CSS had no powers in 2020. With `pow()` the browser does that math.
+- Background: Miriam Suzanne, [Responsive and Fluid Typography with Baseline CSS Features](https://web.dev/articles/baseline-in-action-fluid-type), 2025-12-16
+- Docs: [MDN: pow()](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/pow) · [Utopia type calculator](https://utopia.fyi/type/calculator/)
+
+Source: [Good CSS](https://good-css.com/specimen/one-fluid-scale-for-type-and-space), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#one-fluid-scale-for-type-and-space).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.

package/knowledge/recipes/one-focus-ring-with-focus-visible.md

@@ -0,0 +1,44 @@
+---
+topic: "good-css-one-focus-ring-with-focus-visible"
+title: "One focus ring with :focus-visible"
+tier: "reference"
+tags:
+  - "good-css"
+  - "interaction"
+  - "one"
+  - "focus"
+  - "ring"
+  - "visible"
+summary: "Use it as the focus style for every interactive element. Never write `outline: none`."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# One focus ring with `:focus-visible`
+
+Use it as the focus style for every interactive element. Never write `outline: none`.
+
+```css
+:focus-visible {
+  outline: max(2px, 0.08em) solid currentColor;
+  outline-offset: 0.25em;
+}
+```
+
+Why it works:
+
+- The browser decides when a ring helps. Keyboard focus gets one, a mouse click on a button does not, and text inputs always do.
+- `currentColor` and `em` make the ring follow each component's color and size.
+- `outline` takes no layout space and survives forced-colors mode, which removes `box-shadow`.
+
+Rules:
+
+- On a filled button `currentColor` can fail contrast. Set the outline to the button's background color there.
+- A component that draws its ring with `box-shadow` keeps `outline-color: transparent`, never `outline: none`, so forced-colors mode can repaint it.
+
+Support: Chrome 86, Firefox 85, Safari 15.4.
+
+- Borrowed from: Stephanie Eckles, [Modern CSS Upgrades To Improve Accessibility](https://moderncss.dev/modern-css-upgrades-to-improve-accessibility/), 2021-04-09, and [Smol Focus Styles](https://smolcss.dev/#smol-focus-styles) · Kevin Powell, [3 super small changes to improve your CSS](https://www.youtube.com/watch?v=zT9Ftmw0-uc), 2023-03-07
+
+Source: [Good CSS](https://good-css.com/specimen/one-focus-ring-with-focus-visible), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#one-focus-ring-with-focus-visible).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.

package/knowledge/recipes/one-set-of-color-tokens-for-light-and-dark.md

@@ -0,0 +1,53 @@
+---
+topic: "good-css-one-set-of-color-tokens-for-light-and-dark"
+title: "One set of color tokens for light and dark"
+tier: "reference"
+tags:
+  - "good-css"
+  - "foundations"
+  - "one"
+  - "set"
+  - "color"
+  - "tokens"
+  - "light"
+  - "dark"
+summary: "Use it on any site with a dark mode. Each token holds both values, so there is no second block of variables under a media query or a `.dark` class."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# One set of color tokens for light and dark
+
+Use it on any site with a dark mode. Each token holds both values, so there is no second block of variables under a media query or a `.dark` class.
+
+```css
+:root {
+  color-scheme: light dark;
+  --background: light-dark(oklch(1 0 none), oklch(0.145 0 none));
+  --foreground: light-dark(oklch(0.145 0 none), oklch(0.985 0 none));
+}
+
+[data-theme="light"] { color-scheme: light; }
+[data-theme="dark"] { color-scheme: dark; }
+```
+
+Why it works:
+
+- `color-scheme: light dark` says the page supports both and follows the system setting. It also switches the browser's own UI, such as form controls, scrollbars and the default page background.
+- `light-dark(a, b)` returns `a` in a light scheme and `b` in a dark one.
+- It resolves per element. Set `color-scheme` on any subtree and every token used inside it flips. The same tokens serve a manual toggle and a section that is always dark.
+
+Rules:
+
+- Switch themes by setting `color-scheme`. Never redefine the tokens.
+- The grays use `none` for the hue, so they can be mixed with a color later without drifting toward red. [OKLCH color](https://good-css.com/#oklch-color) has the measurement.
+- `light-dark()` takes two colors. Anything else that differs by theme, such as an image, needs its own rule.
+- Add `<meta name="color-scheme" content="light dark">` so the browser paints the right background before the CSS loads.
+
+Support: Chrome 123, Firefox 120, Safari 17.5. Baseline since May 2024.
+
+- Borrowed from: IP, @ipwanciu on X, 2025-10-30
+- Docs: [MDN: light-dark()](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/light-dark) · [MDN: color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme) · Bramus Van Damme, [CSS color-scheme-dependent colors with light-dark()](https://web.dev/articles/light-dark)
+
+Source: [Good CSS](https://good-css.com/specimen/one-set-of-color-tokens-for-light-and-dark), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#one-set-of-color-tokens-for-light-and-dark).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.

package/knowledge/recipes/opt-in-motion.md

@@ -0,0 +1,43 @@
+---
+topic: "good-css-opt-in-motion"
+title: "Opt-in motion"
+tier: "reference"
+tags:
+  - "good-css"
+  - "motion"
+  - "opt"
+summary: "Use it for every transition or animation that moves or scales something."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# Opt-in motion
+
+Use it for every transition or animation that moves or scales something.
+
+```css
+@media (hover: hover) and (pointer: fine) {
+  .box:hover { transform: scale(1.2); }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .box { transition: transform 300ms var(--ease-out, ease-out); }
+}
+```
+
+Why it works:
+
+- Motion exists only inside the query, so the default is none. People who never touched the setting match `no-preference` and see it.
+
+Rules:
+
+- Build the state change first and add the motion inside the query. Do not strip motion afterwards with a global rule that sets every duration to `0.01ms`.
+- Fades of opacity and color are not motion and can stay outside the query.
+- Animation driven by a script checks the same query with `matchMedia`.
+
+Support: Chrome 74, Firefox 63, Safari 10.1.
+
+- Borrowed from: Josh W. Comeau, [Accessible Animations in React with "prefers-reduced-motion"](https://www.joshwcomeau.com/react/prefers-reduced-motion/) · Kevin Powell, [3 super small changes to improve your CSS](https://www.youtube.com/watch?v=zT9Ftmw0-uc), 2023-03-07
+
+Source: [Good CSS](https://good-css.com/specimen/opt-in-motion), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#opt-in-motion).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.

package/knowledge/recipes/overflow-clip-over-hidden.md

@@ -0,0 +1,41 @@
+---
+topic: "good-css-overflow-clip-over-hidden"
+title: "overflow: clip over hidden"
+tier: "reference"
+tags:
+  - "good-css"
+  - "layout"
+  - "overflow"
+  - "clip"
+  - "over"
+  - "hidden"
+summary: "Use it whenever you want to cut off overflow and do not need scrolling."
+---
+
+<!-- Generated by pnpm good-css:sync. Local notes belong in compatibility.md. -->
+# `overflow: clip` over `hidden`
+
+Use it whenever you want to cut off overflow and do not need scrolling.
+
+```css
+.hero { overflow-x: clip; }
+```
+
+Why it works:
+
+- `hidden` turns the element into a scroll container and sets the other axis to `auto`. That causes stray scrollbars and breaks `position: sticky` inside it.
+- `clip` cuts the overflow and does neither.
+
+Rules:
+
+- Put it on the element that overflows, not on `html` or `body`.
+- Keep `hidden` or `auto` for elements a script scrolls. `clip` blocks that too.
+- Keep `hidden` or `auto` on an element with `resize`. With `clip` the browser draws no resize handle.
+
+Support: Chrome 90, Firefox 81, Safari 16.
+
+- Borrowed from: Kevin Powell, [2 better alternatives to overflow: hidden](https://www.youtube.com/watch?v=72pUm4tQesw), 2023-12-14
+
+Source: [Good CSS](https://good-css.com/specimen/overflow-clip-over-hidden), [pinned source](https://github.com/vojtaholik/good-css/blob/6d16d2fd27f4892e2aea4b5c5c2b016f45be7eef/PRACTICES.md#overflow-clip-over-hidden).
+
+Copyright (c) 2026 Vojta Holik. License: upstream/LICENSE in this plugin.