@daydreamui/good-css 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# Good CSS for Daydream
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A local, pinned import of [Good CSS](https://good-css.com/) with searchable
+recipes and five editable layout playgrounds. The plugin contributes guidance
+through Daydream's knowledge tools; it registers no gates and makes no runtime
+network requests. It replaces `mrbavio.css-author`.
+
+## Update the source
+
+Run from the plugins repository with Node 24. Regeneration and the full index
+check use an installed Daydream checkout beside it. For a different location
+set `DAYDREAM_KERNEL=/path/to/daydream`.
+The checkout supplies its single knowledge-index implementation, only while
+generating or checking the corpus.
+
+```sh
+pnpm good-css:sync --revision <full-upstream-commit-sha>
+pnpm good-css:check
+pnpm test
+pnpm test:kernel /path/to/daydream plugins/daydream.good-css
+```
+
+Choose a commit on `vojtaholik/good-css`'s default-branch history and review
+the resulting diff before shipping. The updater verifies upstream ancestry
+before downloading `PRACTICES.md` and `LICENSE` at that exact commit and
+recording their SHA-256 hashes in `upstream/lock.json`. Fetches, entry-shape
+checks, and kernel parsing of the complete candidate corpus finish before
+generated files are written. Publication rolls back changed files if a later
+write fails. Missing recipe prerequisites, credits, or a playground's source
+recipe stop the import.
+
+`pnpm good-css:sync` regenerates offline from the pinned source;
+`pnpm good-css:check` checks source hashes, generated recipes and examples,
+and the index without network access, including scalar roundtrips through
+the kernel parser. `pnpm good-css:check-source` checks source hashes and
+generated recipes, guidance, and playgrounds without any kernel checkout or
+private dependencies; it excludes the kernel-rendered index. Fork PRs run
+that check and `pnpm test:good-css` with Node alone. Upstream removals remove
+generated recipes. New upstream recipes become searchable references automatically.
+
+Keep local edits in `knowledge/procedures.md`, `knowledge/compatibility.md`,
+`playgrounds/fixtures.json`, and `playgrounds/base.css`. The updater owns
+`knowledge/recipes/`, `knowledge/examples/`, `knowledge/upstream-guidance.md`,
+the index, and the generated playground HTML/CSS. It preserves the upstream entry's CSS, Rules, Support
+notes, and attribution; internal links become absolute specimen-site links.
+The imported material is MIT licensed; retain `upstream/LICENSE` when distributing.
+
+## Use and migrate
+
+Install a Daydream build containing the core CSS diagnostics merged in
+[Daydream #176](https://github.com/mbavio-phota/daydream/pull/176) before
+migrating an existing CSS Author installation. Older compatible hosts can
+serve the guidance but do not supply the new diagnostics. The catalog pins
+the merged kernel commit for builds and integration checks. After validating
+that kernel build, switch the plugins:
+
+```sh
+pnpm build plugins/daydream.good-css
+daydream plugin install plugins/daydream.good-css --enable
+daydream plugin uninstall mrbavio.css-author
+```
+
+Existing project-specific plugin settings may explicitly select CSS Author;
+replace that enabled id with `daydream.good-css` and remove its old gate
+severity overrides. Keep other plugins' settings as they are. Re-read agent
+instructions after switching. The old necessity, redundancy, unused class,
+and unused face policies are retired; this plugin does not recreate them.
+
+Copy this plugin's `playgrounds/` folder into a separate project directory,
+then open the copy in Daydream to resize and edit the examples. The installed
+plugin's files participate in its trust hash; editing them (including the
+canvas layout Daydream saves) requires trusting the plugin again.
+Agents can also retrieve them through `knowledge_bundle`, and retrieve the
+full recipes through `knowledge_search` and `knowledge_read`.
+
+The legacy eval runner remains retired since Daydream switched to project
+files (decision #78); it stops before its obsolete CSS Author gate preflight.
+This plugin does not restore whole-document eval grading.

package/dist/index.js

@@ -0,0 +1,2 @@
+function activate() {}
+export { activate as default };

package/icon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none">
+  <!-- Good CSS mark: https://good-css.com/mark.svg; Daydream palette and small-size optical adjustments. -->
+  <g transform="translate(1.744 2) scale(.357143)">
+    <path d="M54.5283 26.5641C54.9013 33.3467 52.6617 40.0145 48.27 45.1968C43.8782 50.379 37.6681 53.682 30.9162 54.4266C24.1642 55.1712 17.3836 53.3009 11.9681 49.2002C6.55264 45.0995 2.91388 39.0799 1.79986 32.379C0.685835 25.6781 2.1812 18.8051 5.97854 13.1727C9.77588 7.54038 15.5866 3.57677 22.2163 2.09668C28.846 0.616601 35.7908 1.73252 41.623 5.21505C47.4553 8.69757 51.7318 14.2821 53.5735 20.8205" stroke="#839999" stroke-width="4.48"/>
+    <path d="M19.399 33.2123C18.6379 33.2123 17.9415 33.0831 17.3026 32.8246C16.6708 32.5662 16.1179 32.2 15.6585 31.7405C15.1918 31.2667 14.8328 30.7138 14.5744 30.082C14.3159 29.4359 14.1795 28.7323 14.1795 27.9713C14.1795 27.2103 14.3159 26.5138 14.5744 25.8749C14.8328 25.2287 15.1918 24.6759 15.6585 24.2164C16.1179 23.7426 16.6708 23.3764 17.3026 23.1179C17.9415 22.8595 18.6379 22.7231 19.399 22.7231C20.0595 22.7231 20.6769 22.8308 21.2441 23.0318C21.8256 23.2185 22.3354 23.5056 22.7805 23.879C23.2328 24.2451 23.6062 24.6903 23.9077 25.2072C24.2021 25.7241 24.4103 26.2913 24.5251 26.9303H21.7826C21.6174 26.442 21.3231 26.0472 20.8995 25.76C20.4831 25.4728 20.0021 25.3292 19.4564 25.3292C19.0974 25.3292 18.7672 25.3938 18.4585 25.5303C18.1497 25.6523 17.8841 25.839 17.6615 26.0759C17.4533 26.3056 17.281 26.5856 17.159 26.9159C17.0369 27.2318 16.9723 27.5836 16.9723 27.9713C16.9723 28.3518 17.0369 28.7108 17.159 29.041C17.281 29.3569 17.4533 29.6369 17.6615 29.8738C17.8841 30.1108 18.1497 30.2903 18.4585 30.4267C18.7672 30.5487 19.0974 30.6133 19.4564 30.6133C20.0236 30.6133 20.519 30.4626 20.9426 30.1538C21.3662 29.8451 21.6605 29.4287 21.8256 28.9118H24.5538C24.4462 29.5508 24.2451 30.1395 23.9508 30.6708C23.6492 31.202 23.2759 31.6544 22.8236 32.0277C22.3785 32.401 21.8615 32.6954 21.2728 32.9108C20.6985 33.1118 20.0738 33.2123 19.399 33.2123ZM29.2995 33.1692C28.6892 33.1692 28.1436 33.0974 27.6482 32.9538C27.1672 32.7959 26.7508 32.5805 26.3918 32.2862C26.0472 31.999 25.7744 31.6472 25.5733 31.2164C25.3795 30.7856 25.2646 30.2974 25.2359 29.7446H27.9138C27.9713 30.4267 28.4308 30.7713 29.2995 30.7713C29.6944 30.7713 29.9959 30.7067 30.2041 30.5703C30.4267 30.4267 30.5415 30.24 30.5415 30.0031C30.5415 29.7446 30.4051 29.5364 30.1323 29.3856C29.8738 29.2349 29.4287 29.1056 28.8041 29.0123C28.2944 28.9333 27.8277 28.8185 27.4041 28.6749C26.9805 28.5241 26.6144 28.3303 26.3056 28.1005C26.0113 27.8564 25.7744 27.562 25.6021 27.2174C25.4369 26.8656 25.3508 26.442 25.3508 25.961C25.3508 25.4513 25.4513 24.999 25.6451 24.6041C25.8318 24.2092 26.0974 23.879 26.4349 23.6062C26.7867 23.3262 27.1959 23.1179 27.6626 22.9744C28.1364 22.8308 28.6533 22.7518 29.2133 22.7518C29.7662 22.7518 30.2759 22.8308 30.7282 22.9887C31.1877 23.1395 31.5826 23.3549 31.9128 23.6349C32.2503 23.9149 32.5159 24.2595 32.7097 24.6615C32.9108 25.0636 33.0256 25.5231 33.0687 26.0328H30.441C30.3549 25.4297 29.9313 25.121 29.1846 25.121C28.8185 25.121 28.5313 25.1928 28.3303 25.3292C28.1292 25.4513 28.0287 25.6379 28.0287 25.8892C28.0287 26.1405 28.1436 26.3272 28.3877 26.4564C28.639 26.5785 29.0841 26.6933 29.7159 26.801C30.2472 26.88 30.7282 26.9949 31.159 27.1456C31.5969 27.3036 31.9631 27.5046 32.2718 27.7559C32.5877 28 32.8318 28.3087 32.9969 28.6605C33.1692 29.0195 33.2554 29.4359 33.2554 29.9169C33.2554 30.4482 33.1549 30.9149 32.9538 31.3241C32.76 31.7262 32.4872 32.0708 32.1282 32.3436C31.7692 32.6164 31.3528 32.8246 30.8718 32.9682C30.3908 33.1046 29.8667 33.1692 29.2995 33.1692ZM37.9723 33.1692C37.362 33.1692 36.8164 33.0974 36.321 32.9538C35.84 32.7959 35.4236 32.5805 35.0646 32.2862C34.72 31.999 34.4472 31.6472 34.2462 31.2164C34.0523 30.7856 33.9374 30.2974 33.9087 29.7446H36.5795C36.6441 30.4267 37.1036 30.7713 37.9723 30.7713C38.3672 30.7713 38.6687 30.7067 38.8769 30.5703C39.0995 30.4267 39.2144 30.24 39.2144 30.0031C39.2144 29.7446 39.0779 29.5364 38.8051 29.3856C38.5467 29.2349 38.1015 29.1056 37.4769 29.0123C36.9672 28.9333 36.5005 28.8185 36.0769 28.6749C35.6533 28.5241 35.2872 28.3303 34.9785 28.1005C34.6841 27.8564 34.4472 27.562 34.2749 27.2174C34.1097 26.8656 34.0236 26.442 34.0236 25.961C34.0236 25.4513 34.1241 24.999 34.3179 24.6041C34.5046 24.2092 34.7703 23.879 35.1077 23.6062C35.4595 23.3262 35.8687 23.1179 36.3354 22.9744C36.8092 22.8308 37.3262 22.7518 37.8862 22.7518C38.439 22.7518 38.9487 22.8308 39.401 22.9887C39.8605 23.1395 40.2554 23.3549 40.5856 23.6349C40.9231 23.9149 41.1887 24.2595 41.3754 24.6615C41.5836 25.0636 41.6985 25.5231 41.7415 26.0328H39.1138C39.0277 25.4297 38.6041 25.121 37.8574 25.121C37.4913 25.121 37.2041 25.1928 37.0031 25.3292C36.8021 25.4513 36.7015 25.6379 36.7015 25.8892C36.7015 26.1405 36.8164 26.3272 37.0605 26.4564C37.3118 26.5785 37.7497 26.6933 38.3887 26.801C38.92 26.88 39.401 26.9949 39.8318 27.1456C40.2697 27.3036 40.6359 27.5046 40.9446 27.7559C41.2605 28 41.5046 28.3087 41.6697 28.6605C41.8421 29.0195 41.9282 29.4359 41.9282 29.9169C41.9282 30.4482 41.8277 30.9149 41.6267 31.3241C41.4328 31.7262 41.16 32.0708 40.801 32.3436C40.4421 32.6164 40.0256 32.8246 39.5446 32.9682C39.0636 33.1046 38.5395 33.1692 37.9723 33.1692Z" transform="translate(28 28) scale(.95) translate(-28 -28)" fill="#E7E5DE"/>
+    <path d="M56 28H48.8205" stroke="#F66A2C" stroke-width="4.48" stroke-linecap="square"/>
+  </g>
+</svg>

package/knowledge/INDEX.md

@@ -0,0 +1,67 @@
+# Knowledge index
+
+Generated by `pnpm knowledge:index` from each file's frontmatter — do not edit by hand. Read a file with the MCP `knowledge_read` tool by the path in parentheses, or search with `knowledge_search`.
+
+## Procedures — read first, every time
+
+- procedure · good-css-procedures — Select a technique, retain its prerequisites, and check its behavior in the intended environment. (procedures.md)
+
+## Examples — intent → minimal document
+
+- example · good-css-example-container-queries-with-container-units — Resize the slot above and below 30rem. The card changes layout against its ancestor container, while its title scales with cqi. Change the slot width independently of the viewport. (examples/container-queries-with-container-units.md)
+- example · good-css-example-content-grid-with-breakouts — Compare the content, breakout and full-width tracks at 1440px and 320px. Change --content, --breakout and --gutter; every child stays on a named track. (examples/content-grid-with-breakouts.md)
+- example · good-css-example-intrinsic-grid — Resize from 960 to 320px. Columns wrap at their 16rem minimum without a media query; change that minimum and compare auto-fit with auto-fill. (examples/intrinsic-grid.md)
+- example · good-css-example-sidebar-that-wraps-on-its-own — Resize from 960 to 320px. The sidebar and article wrap into separate rows. Adjust flex-basis and min-inline-size to move the wrap point. (examples/sidebar-that-wraps-on-its-own.md)
+- example · good-css-example-subgrid-rows-shared-across-cards — At 960px, card headings, descriptions and footers share rows despite different text lengths. At 320px cards form a single column. Edit a heading to see its neighbors respond. (examples/subgrid-rows-shared-across-cards.md)
+
+## Reference — read on demand
+
+- reference · good-css-daydream-compatibility — Distinguish the stored page, the canvas simulation, and behavior that needs its own browser document. (compatibility.md)
+- reference · good-css-accordion-that-animates-its-height — Use it for FAQs and any other disclosure. `<details>` already gives you the toggle, keyboard support and find-in-page. These rules animate the open and the close with no JavaScript. (recipes/accordion-that-animates-its-height.md)
+- reference · good-css-anchor-targets-that-clear-a-sticky-header — Use it on any page with in-page links and a fixed or sticky header. (recipes/anchor-targets-that-clear-a-sticky-header.md)
+- reference · good-css-carousel-on-native-scroll — Use it for any horizontal row of cards. The carousel is a real scroll container, so swipe, trackpad, keyboard and momentum all work before any script loads. (recipes/carousel-on-native-scroll.md)
+- reference · good-css-concentric-nested-radius — Use it wherever a rounded element sits inside a padded rounded parent, such as an image in a card or a button in an input. (recipes/concentric-nested-radius.md)
+- reference · good-css-container-queries-with-container-units — Use it for any component that appears in slots of different widths. The component responds to the space it is given, where a media query only knows the viewport. (recipes/container-queries-with-container-units.md)
+- reference · good-css-content-clear-of-the-notch — Use it on fixed headers, bottom bars, toasts and sheets in anything that should feel like an app on a phone. Add `viewport-fit=cover` to the viewport meta tag, then pad those elements by the safe-area insets. (recipes/content-clear-of-the-notch.md)
+- reference · good-css-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. (recipes/content-grid-with-breakouts.md)
+- reference · good-css-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. (recipes/cross-document-view-transitions.md)
+- reference · good-css-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`. (recipes/enter-and-exit-transitions-from-display-none.md)
+- reference · good-css-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. (recipes/fluid-sizes-with-clamp.md)
+- reference · good-css-form-feedback-with-user-invalid — Use it for inline form validation, in place of blur listeners and a "touched" class. (recipes/form-feedback-with-user-invalid.md)
+- reference · good-css-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. (recipes/has-for-parent-and-page-state.md)
+- reference · good-css-hit-area-larger-than-the-visual — Use it on icon buttons, close buttons and any target that looks smaller than 44px. (recipes/hit-area-larger-than-the-visual.md)
+- reference · good-css-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. (recipes/hover-styles-only-where-hover-exists.md)
+- reference · good-css-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. (recipes/icon-sized-by-the-text-beside-it.md)
+- reference · good-css-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. (recipes/image-box-that-holds-any-upload.md)
+- reference · good-css-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. (recipes/indicator-that-slides-to-the-active-item.md)
+- reference · good-css-intrinsic-grid — Use it for any set of equal cards or tiles. It replaces a column count per breakpoint. (recipes/intrinsic-grid.md)
+- reference · good-css-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. (recipes/label-centered-on-its-letters-with-text-box.md)
+- reference · good-css-logical-properties — Use them in place of every left, right, top and bottom, in spacing, borders, offsets and alignment. (recipes/logical-properties.md)
+- reference · good-css-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. (recipes/long-text-that-wraps-truncates-or-clamps.md)
+- reference · good-css-motion-tokens — Use them in every transition and animation. Two easing curves, defined once, and a rule for durations. (recipes/motion-tokens.md)
+- reference · good-css-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. (recipes/no-rubber-band-bounce-on-desktop.md)
+- reference · good-css-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. (recipes/oklch-color.md)
+- reference · good-css-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. (recipes/one-fluid-scale-for-type-and-space.md)
+- reference · good-css-one-focus-ring-with-focus-visible — Use it as the focus style for every interactive element. Never write `outline: none`. (recipes/one-focus-ring-with-focus-visible.md)
+- reference · good-css-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. (recipes/one-set-of-color-tokens-for-light-and-dark.md)
+- reference · good-css-opt-in-motion — Use it for every transition or animation that moves or scales something. (recipes/opt-in-motion.md)
+- reference · good-css-overflow-clip-over-hidden — Use it whenever you want to cut off overflow and do not need scrolling. (recipes/overflow-clip-over-hidden.md)
+- reference · good-css-popover-anchored-to-its-trigger — Use it for dropdown menus and other popovers opened by a click. It replaces a positioning library or a script that reads `getBoundingClientRect()`. (recipes/popover-anchored-to-its-trigger.md)
+- reference · good-css-press-feedback — Use it on every button and anything else that can be pressed. (recipes/press-feedback.md)
+- reference · good-css-push-one-item-away-with-an-auto-margin — Use it when one item in a flex row or column sits apart from the rest, such as the actions at the bottom of a card, the account link at the end of a toolbar, or a title centered in a full-height section between a header and a footer. (recipes/push-one-item-away-with-an-auto-margin.md)
+- reference · good-css-reveal-with-clip-path — Use it for dropdowns, menus and panels that open over the page and whose height is not known. It unrolls the panel without animating `height`, and it works in every browser. (recipes/reveal-with-clip-path.md)
+- reference · good-css-safe-alignment — Use it wherever content is centered or end-aligned in a container that can become too small, such as a tab row, a toolbar or a vertically centered modal. (recipes/safe-alignment.md)
+- reference · good-css-scroll-area-between-a-fixed-header-and-footer — Use it for the body of a modal, a chat list, a drawer or a sidebar. The panel grows with its content up to a limit, then the middle scrolls and the header and footer stay put. (recipes/scroll-area-between-a-fixed-header-and-footer.md)
+- reference · good-css-section-spacing-that-depends-on-its-neighbors — Use it on any page built from reorderable sections, above all in a CMS where an editor decides the order. When two particular sections meet, the spacing between them changes on its own. (recipes/section-spacing-that-depends-on-its-neighbors.md)
+- reference · good-css-shadow-change-that-fades-and-does-not-repaint — Use it on cards that lift on hover, most of all in a grid of many cards or with a large blur. (recipes/shadow-change-that-fades-and-does-not-repaint.md)
+- reference · good-css-sidebar-that-wraps-on-its-own — Use it for any pair where one side has an ideal width and the other takes the rest, such as a media object, an input with a button, or a page with an aside. (recipes/sidebar-that-wraps-on-its-own.md)
+- reference · good-css-space-between-siblings-set-by-the-parent — Use it wherever elements sit one above another, such as form fields, the parts of a card or the blocks of an article. The parent sets one space between its children, and no child carries a block margin of its own. (recipes/space-between-siblings-set-by-the-parent.md)
+- reference · good-css-stack-layers-with-grid — Use it whenever things sit on top of each other, such as text over an image, a badge on a card, or two icons that swap. It replaces `position: absolute` with its offsets, sizes and transforms. (recipes/stack-layers-with-grid.md)
+- reference · good-css-styles-that-apply-only-when-a-scroller-overflows — Use it on any row that may or may not fit, such as tabs, a toolbar or a table wrapper. It fades the edges only when there is something to scroll to. It replaces a `ResizeObserver` that compares `scrollWidth` with `clientWidth`. (recipes/styles-that-apply-only-when-a-scroller-overflows.md)
+- reference · good-css-subgrid-rows-shared-across-cards — Use it when cards in a row have parts that should line up, such as title, body and footer, whatever the length of their content. (recipes/subgrid-rows-shared-across-cards.md)
+- reference · good-css-tabular-numbers — Use it on any number that changes or sits in a column, such as prices, tables, timers and counters. (recipes/tabular-numbers.md)
+- reference · good-css-textarea-that-grows-with-its-content — Use it for any multi-line input, such as a chat composer or a comment box. `field-sizing: content` sizes the textarea to its text, so there is no auto-grow script and no hidden mirror element. (recipes/textarea-that-grows-with-its-content.md)
+- reference · good-css-the-reset — Start every new project with it. In an existing project add one rule at a time and look at the result, because `min-width: 0` and the font rules change how things already render. (recipes/the-reset.md)
+- reference · good-css-transition-a-custom-property-with-property — Use it when one state change should drive several values together, or when a script feeds a number such as pointer position or progress into CSS and the result should ease. (recipes/transition-a-custom-property-with-property.md)
+- reference · good-css-whole-card-clickable-from-one-link — Use it for cards, list rows and tiles where the whole area should navigate. It replaces an `<a>` wrapped around the card, which makes a screen reader read every word as the link text, and it replaces a click handler on a `div`. (recipes/whole-card-clickable-from-one-link.md)
+- reference · good-css-upstream-guidance — Upstream principles, intentionally excluded techniques, deferred ideas, and references. (upstream-guidance.md)

package/knowledge/compatibility.md

@@ -0,0 +1,33 @@
+---
+topic: good-css-daydream-compatibility
+title: Previewing Good CSS in Daydream
+tier: reference
+tags: [good-css, preview, container, popover, dialog, motion, viewport]
+summary: Distinguish the stored page, the canvas simulation, and behavior that needs its own browser document.
+---
+
+# Previewing recipes
+
+The recipes describe the web platform. Their Support lines are upstream
+observations at the pinned revision, not a promise about every browser or
+the Daydream canvas. Check the project's target browsers when a feature matters.
+
+- **Container units.** Give component examples an explicit ancestor size
+  container. On a page that declares a container elsewhere, a canvas element
+  without an eligible ancestor can use the app window for its container-unit
+  fallback. Daydream's measure report calls this `canvas-container-units`.
+- **Popovers and modal dialogs.** The canvas removes `popovertarget`,
+  `commandfor`, and `interestfor` from its render copy because the top layer
+  would cover the app. The file retains them. Test invocation, anchoring,
+  dismissal, and entry/exit transitions in the page's own browser document.
+- **Motion and scripts.** The canvas does not run page scripts. A geometry
+  report samples a state; it does not verify transitions, focus, hover,
+  reduced-motion behavior, or scroll-driven motion. Exercise these in a browser.
+- **Navigation and viewport environment.** Cross-document view transitions,
+  mobile safe areas, dynamic browser chrome, and user preferences need the
+  corresponding browser environment. A canvas frame is not a mobile device.
+- **Imports.** Daydream does not follow CSS `@import`. Use linked local sheets
+  or materialize imports while preserving their layer and conditions.
+
+Keep the page's CSS intact when documenting a preview limitation. The kernel's
+CSS diagnostics are advisory browser observations; this plugin adds no policy gates.

package/knowledge/examples/container-queries-with-container-units.md

@@ -0,0 +1,150 @@
+---
+topic: "good-css-example-container-queries-with-container-units"
+title: "Container query card playground"
+tier: "example"
+tags:
+  - "good-css"
+  - "container"
+  - "queries"
+  - "units"
+summary: "Resize the slot above and below 30rem. The card changes layout against its ancestor container, while its title scales with cqi. Change the slot width independently of the viewport."
+intent: "Container query card"
+---
+
+
+# Container query card
+
+Resize the slot above and below 30rem. The card changes layout against its ancestor container, while its title scales with cqi. Change the slot width independently of the viewport.
+
+Read [the recipe](../recipes/container-queries-with-container-units.md) for its prerequisites and credits.
+The page uses the pinned recipe verbatim, with a separate teaching fixture.
+
+## daydream.json
+
+```json
+{
+  "version": 9,
+  "pages": [
+    {
+      "path": "container-queries-with-container-units.html"
+    }
+  ],
+  "canvases": [
+    {
+      "id": "main",
+      "name": "Playground",
+      "items": [
+        {
+          "id": "container-queries-with-container-units",
+          "kind": "daydream.viewport",
+          "position": {
+            "x": 0,
+            "y": 0
+          },
+          "frame": {
+            "width": 960,
+            "height": 720
+          },
+          "payload": {
+            "page": "container-queries-with-container-units.html"
+          },
+          "meta": {
+            "title": "Container query card",
+            "sourceUrl": "https://good-css.com/specimen/container-queries-with-container-units"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+## container-queries-with-container-units.html
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Container query card</title>
+<link rel="stylesheet" href="container-queries-with-container-units.css">
+</head>
+<body>
+<h1>Container query card</h1><main class="slot"><article class="card"><h2>A responsive card</h2><p>Above 30rem of container space the title and text sit side by side. The heading also scales with the container.</p></article></main>
+</body>
+</html>
+```
+
+## container-queries-with-container-units.css
+
+```css
+/* Teaching fixture only; recipe declarations live in the other sheet. */
+* {
+  box-sizing: border-box;
+}
+html {
+  background: #f5f4ef;
+  color: #26352d;
+  font:
+    16px/1.5 system-ui,
+    sans-serif;
+}
+body {
+  margin: 0;
+  padding: 1.5rem;
+}
+h1,
+h2,
+p {
+  margin: 0;
+}
+h1 {
+  font-size: 1.5rem;
+  margin-block-end: 1.5rem;
+}
+h2 {
+  font-size: 1.2rem;
+}
+article,
+aside,
+.main,
+.panel {
+  padding: 1rem;
+  background: #e0e8df;
+}
+section > h2 {
+  padding: 1rem;
+  background: #d2decd;
+}
+footer {
+  padding: 0.5rem;
+  background: #c9d8c5;
+}
+.slot {
+  margin-block: 1rem;
+}
+.card {
+  overflow-wrap: anywhere;
+}
+.card > * {
+  margin: 0;
+}
+.cards h2 {
+  background: #c9d8c5;
+}
+.cards p {
+  background: #eaf0e7;
+}
+
+.slot { container-type: inline-size; }
+
+.card h2 { font-size: clamp(1.25rem, 1rem + 2cqi, 2rem); }
+
+@container (width > 30rem) {
+  .card {
+    display: grid;
+    grid-template-columns: 12rem 1fr;
+  }
+}
+```

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

@@ -0,0 +1,161 @@
+---
+topic: "good-css-example-content-grid-with-breakouts"
+title: "Content grid with breakouts playground"
+tier: "example"
+tags:
+  - "good-css"
+  - "content"
+  - "grid"
+  - "breakouts"
+summary: "Compare the content, breakout and full-width tracks at 1440px and 320px. Change --content, --breakout and --gutter; every child stays on a named track."
+intent: "Content grid with breakouts"
+---
+
+
+# Content grid with breakouts
+
+Compare the content, breakout and full-width tracks at 1440px and 320px. Change --content, --breakout and --gutter; every child stays on a named track.
+
+Read [the recipe](../recipes/content-grid-with-breakouts.md) for its prerequisites and credits.
+The page uses the pinned recipe verbatim, with a separate teaching fixture.
+
+## daydream.json
+
+```json
+{
+  "version": 9,
+  "pages": [
+    {
+      "path": "content-grid-with-breakouts.html"
+    }
+  ],
+  "canvases": [
+    {
+      "id": "main",
+      "name": "Playground",
+      "items": [
+        {
+          "id": "content-grid-with-breakouts",
+          "kind": "daydream.viewport",
+          "position": {
+            "x": 0,
+            "y": 0
+          },
+          "frame": {
+            "width": 960,
+            "height": 720
+          },
+          "payload": {
+            "page": "content-grid-with-breakouts.html"
+          },
+          "meta": {
+            "title": "Content grid with breakouts",
+            "sourceUrl": "https://good-css.com/specimen/content-grid-with-breakouts"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+## content-grid-with-breakouts.html
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Content grid with breakouts</title>
+<link rel="stylesheet" href="content-grid-with-breakouts.css">
+</head>
+<body>
+<h1>Content grid with breakouts</h1><main class="content-grid"><section class="panel"><h2>Content width</h2><p>The default column.</p></section><section class="panel breakout"><h2>Breakout width</h2></section><section class="full-width"><h2>Full width</h2><p>Its child returns to the content column.</p></section></main>
+</body>
+</html>
+```
+
+## content-grid-with-breakouts.css
+
+```css
+/* Teaching fixture only; recipe declarations live in the other sheet. */
+* {
+  box-sizing: border-box;
+}
+html {
+  background: #f5f4ef;
+  color: #26352d;
+  font:
+    16px/1.5 system-ui,
+    sans-serif;
+}
+body {
+  margin: 0;
+  padding: 1.5rem;
+}
+h1,
+h2,
+p {
+  margin: 0;
+}
+h1 {
+  font-size: 1.5rem;
+  margin-block-end: 1.5rem;
+}
+h2 {
+  font-size: 1.2rem;
+}
+article,
+aside,
+.main,
+.panel {
+  padding: 1rem;
+  background: #e0e8df;
+}
+section > h2 {
+  padding: 1rem;
+  background: #d2decd;
+}
+footer {
+  padding: 0.5rem;
+  background: #c9d8c5;
+}
+.slot {
+  margin-block: 1rem;
+}
+.card {
+  overflow-wrap: anywhere;
+}
+.card > * {
+  margin: 0;
+}
+.cards h2 {
+  background: #c9d8c5;
+}
+.cards p {
+  background: #eaf0e7;
+}
+
+.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];
+}
+
+: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;
+}
+```

package/knowledge/examples/intrinsic-grid.md

@@ -0,0 +1,150 @@
+---
+topic: "good-css-example-intrinsic-grid"
+title: "Intrinsic grid playground"
+tier: "example"
+tags:
+  - "good-css"
+  - "intrinsic"
+  - "grid"
+summary: "Resize from 960 to 320px. Columns wrap at their 16rem minimum without a media query; change that minimum and compare auto-fit with auto-fill."
+intent: "Intrinsic grid"
+---
+
+
+# Intrinsic grid
+
+Resize from 960 to 320px. Columns wrap at their 16rem minimum without a media query; change that minimum and compare auto-fit with auto-fill.
+
+Read [the recipe](../recipes/intrinsic-grid.md) for its prerequisites and credits.
+The page uses the pinned recipe verbatim, with a separate teaching fixture.
+
+## daydream.json
+
+```json
+{
+  "version": 9,
+  "pages": [
+    {
+      "path": "intrinsic-grid.html"
+    }
+  ],
+  "canvases": [
+    {
+      "id": "main",
+      "name": "Playground",
+      "items": [
+        {
+          "id": "intrinsic-grid",
+          "kind": "daydream.viewport",
+          "position": {
+            "x": 0,
+            "y": 0
+          },
+          "frame": {
+            "width": 960,
+            "height": 720
+          },
+          "payload": {
+            "page": "intrinsic-grid.html"
+          },
+          "meta": {
+            "title": "Intrinsic grid",
+            "sourceUrl": "https://good-css.com/specimen/intrinsic-grid"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+## intrinsic-grid.html
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Intrinsic grid</title>
+<link rel="stylesheet" href="intrinsic-grid.css">
+</head>
+<body>
+<h1>Intrinsic grid</h1>
+<main class="grid"><article><h2>Card 1</h2><p>Content determines how the row wraps.</p></article>
+<article><h2>Card 2</h2><p>Content determines how the row wraps.</p></article>
+<article><h2>Card 3</h2><p>Content determines how the row wraps.</p></article>
+<article><h2>Card 4</h2><p>Content determines how the row wraps.</p></article>
+<article><h2>Card 5</h2><p>Content determines how the row wraps.</p></article>
+<article><h2>Card 6</h2><p>Content determines how the row wraps.</p></article></main>
+</body>
+</html>
+```
+
+## intrinsic-grid.css
+
+```css
+/* Teaching fixture only; recipe declarations live in the other sheet. */
+* {
+  box-sizing: border-box;
+}
+html {
+  background: #f5f4ef;
+  color: #26352d;
+  font:
+    16px/1.5 system-ui,
+    sans-serif;
+}
+body {
+  margin: 0;
+  padding: 1.5rem;
+}
+h1,
+h2,
+p {
+  margin: 0;
+}
+h1 {
+  font-size: 1.5rem;
+  margin-block-end: 1.5rem;
+}
+h2 {
+  font-size: 1.2rem;
+}
+article,
+aside,
+.main,
+.panel {
+  padding: 1rem;
+  background: #e0e8df;
+}
+section > h2 {
+  padding: 1rem;
+  background: #d2decd;
+}
+footer {
+  padding: 0.5rem;
+  background: #c9d8c5;
+}
+.slot {
+  margin-block: 1rem;
+}
+.card {
+  overflow-wrap: anywhere;
+}
+.card > * {
+  margin: 0;
+}
+.cards h2 {
+  background: #c9d8c5;
+}
+.cards p {
+  background: #eaf0e7;
+}
+
+.grid {
+  display: grid;
+  gap: 1rem;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr));
+}
+```