@tenphi/cookbook 0.28.0 → 0.30.0

package/docs/es/index.md

@@ -42,7 +42,7 @@ cd docs-site
 npm run dev
 ```
 
-Cookbook lee los archivos donde ya están. También puedes [crear un sitio nuevo](./getting-started.md), [documentar exactamente los archivos publicados en npm](./getting-started.md) o [añadir Cookbook a un proyecto Astro](./getting-started.md).
+Cookbook lee los archivos donde ya están. También puedes [crear un sitio nuevo](./getting-started.md#crea-tu-primer-sitio), [documentar exactamente los archivos publicados en npm](./getting-started.md#documenta-un-paquete-npm-publicado) o [añadir Cookbook a un proyecto Astro](./getting-started.md#añádelo-a-un-proyecto-astro-existente).
 
 ## Este sitio es el ejemplo
 

package/docs/examples.md

@@ -1,10 +1,15 @@
 ---
 title: Working examples
-description: Complete configuration patterns for repositories, monorepos, npm content, and shared themes.
+description: Complete configurations for repositories, monorepos, npm content, languages, and preview sites.
 sidebar:
   order: 3
 ---
 
+These are complete `docs.config.ts` files for common content layouts. For
+branding, component styles, fonts, and shared themes, see the
+[theme recipes](./recipes.md). Every example marked for verification is
+type-checked and built by Cookbook's test suite.
+
 Each example uses the same Astro integration:
 
 ```ts
@@ -40,16 +45,31 @@ export default defineDocsConfig({
   site: { title: "SDK documentation" },
   content: {
     sources: [
-      { id: "api", root: "packages/api", glob: "**/*.md", routeBase: "/api" },
-      { id: "ui", root: "packages/ui", glob: "**/*.md", routeBase: "/ui" },
+      {
+        id: "api",
+        root: "packages/api",
+        glob: "**/*.md",
+        exclude: ["node_modules/**", "dist/**", "CHANGELOG.md"],
+        routeBase: "/api",
+      },
+      {
+        id: "ui",
+        root: "packages/ui",
+        glob: "**/*.md",
+        exclude: ["node_modules/**", "dist/**", "CHANGELOG.md"],
+        routeBase: "/ui",
+      },
     ],
   },
 });
 ```
 
-Use `source:ui/README.md` for an explicit link to the UI package. Ordinary relative
-links stay in their own source mount when the same file appears in several
-versions. A relative frontmatter slug is appended to that source's `routeBase`.
+Glob sources skip only paths beginning with `_` and the declared `exclude`
+patterns, so exclude each package's dependencies, build output, and changelog.
+Use `source:ui/README.md` for an explicit link to the UI package. Ordinary
+relative links stay in their own source mount when the same file appears in
+several mounts. A frontmatter `slug`, even one starting with `/`, is appended
+to that source's `routeBase`.
 
 ## Locked npm documentation
 
@@ -71,34 +91,51 @@ with instructions instead of rendering the old version.
 A package source can specify `registry` for an alternative registry. The default
 is the npm public registry. Keep credentials out of committed configuration.
 
-## Share configuration and themes
+## English and French
 
-A preset is an ordinary exported `DocsConfig` object:
+Create `docs/index.md`, `docs/guide.md`, `docs/fr/index.md`, and
+`docs/fr/guide.md`. Routes are `/`, `/guide`, `/fr`, and `/fr/guide`.
 
-```ts cookbook-verify=shared-theme
-import { defineDocsConfig, mergeDocsConfig } from "@tenphi/cookbook/config";
+```ts cookbook-verify=locales
+import { defineDocsConfig } from "@tenphi/cookbook/config";
 
-const company = defineDocsConfig({
-  theme: {
-    brand: { from: "#315efb" },
-    tokens: { $radius: "8px" },
+export default defineDocsConfig({
+  site: { title: "Acme docs", url: "https://docs.example.com" },
+  content: { sources: [{ glob: "docs/**/*.md", base: "docs" }] },
+  locales: {
+    root: { label: "English", lang: "en" },
+    fr: { label: "Français" },
   },
-  markdown: { rawHtml: "sanitize" },
-});
-
-export default mergeDocsConfig(company, {
-  site: { title: "Product docs" },
-  theme: { tokens: { "$content-width": "52rem" } },
+  defaultLocale: "root",
+  navigation: ["/", "/guide"],
+  translations: { fr: { appearance: "Présentation" } },
 });
 ```
 
-Each `theme.brand` or `theme.palette` color replaces the corresponding color in
-the preset. Supply the complete Glaze declaration for a color you override.
+Navigation adapts to real translations. Missing translations use a real fallback
+in the language picker; they do not generate phantom routes or alternate links.
+See [languages](./configuration.md#languages) and
+[translations](./configuration.md#translations).
+
+## Preview publishing
+
+Set the preview's own URL and Astro `base` if hosted in a subdirectory. Serve
+private previews behind host authentication.
 
-Objects merge recursively, arrays replace, and inputs are not mutated. Tasty
-styles preserve their default values when adding conditional overrides. A preset
-can live in a shared workspace package. Component overrides remain partial Tasty
-objects and merge into Cookbook's complete base styles inside the renderer.
+```ts cookbook-verify=preview
+import { defineDocsConfig } from "@tenphi/cookbook/config";
+
+export default defineDocsConfig({
+  site: {
+    title: "Acme preview",
+    url: "https://preview.example.com",
+    seo: { index: false, copyPage: false },
+  },
+  tableOfContents: { mobile: true },
+});
+```
 
-For complete branding, font, locale, and preview configurations, see
-[configuration recipes](./recipes.md).
+Build, run `cookbook check-build`, deploy that output, then run
+`cookbook check-build --url https://preview.example.com/`. See
+[deployment](./deployment.md) for production metadata, host headers, and sitemap
+checks, and [troubleshooting](./troubleshooting.md) when a check fails.

package/docs/fonts-and-typography.md

@@ -6,12 +6,10 @@ Start with the [theme overview](./theme-and-components.md) for brand colors and
 design tokens. Cookbook configures font loading at build time and applies
 named presets to the rendered site.
 
-## Typography presets
+## Default fonts
 
-The base [typography presets](./upstream/tasty/docs/styles.md#preset) are
-`body`, `heading`, `h1` through `h6`, `navigation`, `small`, and `code`. Onest
-Variable is self-hosted and used for body and heading text by default, with a
-continuous weight range from `100` to `900`. This supports intermediate preset
+Onest Variable is self-hosted and used for body and heading text by default,
+with a continuous weight range from `100` to `900`. This supports intermediate preset
 weights such as `450` for navigation and `610` for headings. JetBrains Mono
 Variable is self-hosted for code with weights from `100` to `800`.
 
@@ -19,19 +17,7 @@ Both default fonts bundle their Latin subset and require no Google Fonts
 requests at build time or in the browser. For other character sets, configure
 `theme.fonts` with a Google family or local files as described below.
 
-Specialized roles preserve the component sizes while sharing their base typography:
-
-| Preset         | Used for          | Base typography                                     |
-| -------------- | ----------------- | --------------------------------------------------- |
-| `hero-title`   | Hero heading      | `h1`, with a larger responsive size                 |
-| `hero-tagline` | Hero description  | `body`, with a responsive size and 1.55 line height |
-| `prose`        | Markdown content  | `body`, at 1.025rem                                 |
-| `inline-code`  | Code within prose | `code`, at 0.875em                                  |
-
-Customize these through `theme.presets` as well. Changes to the base font family,
-weight, tracking, and other shared fields continue to flow into the derived roles.
-
-### Change font families
+## Change font families
 
 Set `theme.fonts` to load fonts and apply them to the matching presets. A Google
 Fonts family needs only its name:
@@ -84,11 +70,14 @@ theme: {
 
 The `body` role also feeds navigation and small text. `heading` feeds `h1`
 through `h6`, while `code` covers code text. Each role has a system fallback.
+
+### Font loading and caching
+
 Cookbook emits font faces through Tasty with `font-display: swap`. Google CSS
 and font files are downloaded at build time and cached in
 `<Astro cacheDir>/cookbook-fonts`. Files are served from your own site's
 `_cookbook/fonts/` path by default, including the deployment base. Visitors make
-no Google Fonts requests. Existing local-file definitions keep working.
+no Google Fonts requests.
 
 ```ts
 theme: {
@@ -111,13 +100,24 @@ for other axes. Styles and weights that do not exist are rejected for explicit
 requests. For static fonts, browsers select their nearest real weight;
 intermediate weights require a variable font.
 
-Migration: name-only Google font configuration now downloads the required
-weights and italics and serves them locally. This increases the initial build's
-font downloads and removes visitors' external font dependency. Set
-`fontLoading.google: "remote"` to retain CDN delivery. Existing CSS-variable
-weights that cannot be resolved from presets require explicit `weights`.
+## Typography presets
+
+The base [typography presets](./upstream/tasty/docs/styles.md#preset) are
+`body`, `heading`, `h1` through `h6`, `navigation`, `small`, and `code`.
+
+Specialized roles preserve the component sizes while sharing their base typography:
+
+| Preset         | Used for          | Base typography                                     |
+| -------------- | ----------------- | --------------------------------------------------- |
+| `hero-title`   | Hero heading      | `h1`, with a larger responsive size                 |
+| `hero-tagline` | Hero description  | `body`, with a responsive size and 1.55 line height |
+| `prose`        | Markdown content  | `body`, at 1.025rem                                 |
+| `inline-code`  | Code within prose | `code`, at 0.875em                                  |
 
-### Adjust presets
+Customize these through `theme.presets` as well. Changes to the base font family,
+weight, tracking, and other shared fields continue to flow into the derived roles.
+
+## Adjust presets
 
 Presets merge property-by-property, so changing size, weight, or line height
 does not require copying the rest of the preset. `theme.presets` takes precedence
@@ -144,7 +144,11 @@ theme: {
 
 For a system or already loaded font, set its CSS family directly with
 `theme.presets.<role>.fontFamily`. This does not load a font file. Additional
-named presets are available to custom MDX components.
+named presets are available to custom MDX components; a new preset starts from
+the `body` values.
+
+Each preset accepts `fontFamily`, `fontSize`, `lineHeight`, `letterSpacing`,
+`fontWeight`, `boldFontWeight`, `fontStyle`, `textTransform`, and `iconSize`.
 
 Heading presets reference the `heading` family and weights; body, navigation,
 and controls reference `body`. Semantic `strong` and `b` elements use Tasty's
@@ -171,5 +175,6 @@ Cookbook applies each semantic typography role through its complete Tasty
 `preset`, so configured fields such as `fontStyle` and `textTransform` are not
 silently omitted.
 
-The exported `DEFAULT_THEME_TOKENS` and `DEFAULT_TYPOGRAPHY_PRESETS` constants
+The `DEFAULT_THEME_TOKENS` and `DEFAULT_TYPOGRAPHY_PRESETS` constants exported
+from `@tenphi/cookbook`
 are useful when building a theme editor or presenting a reset action.

package/docs/getting-started.md

@@ -75,11 +75,6 @@ With no documentation configuration, it uses README/docs conventions.
 
 ## Configure the site
 
-Start with the complete [brand, logo, and font recipes](./recipes.md).
-For deeper style changes or new components, read the
-[customization rules](./customization-rules.md). These rules and upstream
-references are also included in the installed Cookbook package.
-
 Create `docs.config.ts` next to `astro.config.ts`:
 
 ```ts
@@ -105,11 +100,19 @@ and `defineComponent()` with `theme.customStyles` to add a new element. The
 [component styles reference](./component-styles.md) lists every customizable
 sub-element.
 
+For complete starting points, see the [brand, logo, and font recipes](./recipes.md).
+Before deeper style changes or new components, read the
+[customization rules](./customization-rules.md). These rules and upstream
+references are also included in the installed Cookbook package.
+
 The integration and CLI load the same configuration. Supported filenames are
 `docs.config.ts`, `.mts`, `.js`, and `.mjs`, in that order. An explicit integration
 `config` object takes precedence; `configFile: false` disables discovery.
 Use `cookbook({ configFile: "./config/manual.ts" })` and
 `cookbook doctor --config ./config/manual.ts` for a nonstandard location.
+Because `root` resolves from the configuration file's directory, that file
+needs `root: ".."` to keep reading `README.md` and `docs/` from the app
+directory.
 
 ## Monorepo roots
 
@@ -133,9 +136,13 @@ npm run validate
 npm run preview
 ```
 
-See [working examples](./examples.md), [authoring components](./authoring.mdx),
-the [AI agent workflow](./ai-agents.md), and [deployment](./deployment.md). Existing users should read the
-[version-specific upgrade guide](./migration.md).
+`validate` type-checks the project, runs Cookbook's preflight, builds the site,
+and checks the output. In a project you set up yourself, add the scripts listed
+in [CLI commands](./cli.md) or run `npx @tenphi/cookbook doctor`. Then
+[deploy](./deployment.md) the `dist/` directory. If validation fails, see
+[troubleshooting](./troubleshooting.md).
 
-For a complete configuration to adapt, start with the [recipes](./recipes.md).
-If validation fails, see [troubleshooting](./troubleshooting.md).
+Continue with [working examples](./examples.md),
+[authoring components](./authoring.mdx), and the
+[AI agent workflow](./ai-agents.md). Existing users should read the
+[version-specific upgrade guide](./migration.md).

package/docs/ja/getting-started.md

@@ -63,8 +63,6 @@ Cookbook には Astro 用レンダラーが含まれ、`docs.config.ts` を自
 
 ## サイトを設定する
 
-まずは[ブランド、ロゴ、フォントのレシピ](../recipes.md)をご覧ください。より細かなスタイル変更や新しいコンポーネントには、[カスタマイズのルール](../customization-rules.md)を参照してください。これらのルールと参照先は、インストールされる Cookbook パッケージにも含まれます。
-
 `astro.config.ts` と同じ場所に `docs.config.ts` を作成します。
 
 ```ts
@@ -83,9 +81,11 @@ export default defineDocsConfig({
 });
 ```
 
-`theme.fonts` を変更すると、[名前で指定する Google Fonts や独自のフォントファイル](../fonts-and-typography.md)を使えます。タイポグラフィの詳細には `theme.presets`、組み込み要素には `theme.styles`、新しい要素には `defineComponent()` と `theme.customStyles` を使用します。[テーマガイド](../theme-and-components.md)が出発点となり、[コンポーネントスタイルのリファレンス](../component-styles.md)にはカスタマイズ可能なすべてのパーツが載っています。
+`theme.fonts` を変更すると、[名前で指定する Google Fonts や独自のフォントファイル](../fonts-and-typography.md#change-font-families)を使えます。タイポグラフィの詳細には `theme.presets`、組み込み要素には `theme.styles`、新しい要素には `defineComponent()` と `theme.customStyles` を使用します。[テーマガイド](../theme-and-components.md)が出発点となり、[コンポーネントスタイルのリファレンス](../component-styles.md)にはカスタマイズ可能なすべてのパーツが載っています。
+
+完全な出発点として[ブランド、ロゴ、フォントのレシピ](../recipes.md)を用意しています。より細かなスタイル変更や新しいコンポーネントには、[カスタマイズのルール](../customization-rules.md)を参照してください。これらのルールと参照先は、インストールされる Cookbook パッケージにも含まれます。
 
-統合と CLI は同じ設定を読み込みます。対応するファイル名は優先順に `docs.config.ts`、`.mts`、`.js`、`.mjs` です。統合に明示した `config` オブジェクトが優先され、`configFile: false` で自動検出を無効にできます。標準以外の場所では `cookbook({ configFile: "./config/manual.ts" })` と `cookbook doctor --config ./config/manual.ts` を使用してください。
+統合と CLI は同じ設定を読み込みます。対応するファイル名は優先順に `docs.config.ts`、`.mts`、`.js`、`.mjs` です。統合に明示した `config` オブジェクトが優先され、`configFile: false` で自動検出を無効にできます。標準以外の場所では `cookbook({ configFile: "./config/manual.ts" })` と `cookbook doctor --config ./config/manual.ts` を使用してください。 `root` は設定ファイルのディレクトリを基準に解決されるため、このファイルでは `root: ".."` を指定して、アプリのディレクトリにある `README.md` と `docs/` を引き続き読み込むようにします。
 
 ## モノレポのルート
 
@@ -106,4 +106,6 @@ npm run validate
 npm run preview
 ```
 
-ほかのガイドは現在英語で公開されています。[使用例](../examples.md)、[執筆用コンポーネント](../authoring.mdx)、[AI エージェントの作業手順](../ai-agents.md)、[デプロイ](../deployment.md)、[バージョン別のアップグレードガイド](../migration.md)を参照してください。設定例には[レシピ](../recipes.md)、検証に失敗した場合には[トラブルシューティング](../troubleshooting.md)が役立ちます。
+`validate` はプロジェクトの型チェック、Cookbook の事前チェック、サイトのビルド、出力の検証を行います。自分で構成したプロジェクトでは、[CLI コマンド](../cli.md)に記載されたスクリプトを追加するか、`npx @tenphi/cookbook doctor` を実行してください。
+
+ほかのガイドは現在英語で公開されています。[使用例](../examples.md)、[執筆用コンポーネント](../authoring.mdx)、[AI エージェントの作業手順](../ai-agents.md)、[デプロイ](../deployment.md)、[バージョン別のアップグレードガイド](../migration.md)を参照してください。検証に失敗した場合は[トラブルシューティング](../troubleshooting.md)を参照してください。

package/docs/ja/index.md

@@ -42,7 +42,7 @@ cd docs-site
 npm run dev
 ```
 
-Cookbook はファイルを現在の場所から読み込みます。[新しいサイトを作る](./getting-started.md)、[npm に公開されたファイルをそのまま文書化する](./getting-started.md)、[既存の Astro プロジェクトに追加する](./getting-started.md)方法もあります。
+Cookbook はファイルを現在の場所から読み込みます。[新しいサイトを作る](./getting-started.md#最初のサイトを作る)、[npm に公開されたファイルをそのまま文書化する](./getting-started.md#公開済みの-npm-パッケージを文書化する)、[既存の Astro プロジェクトに追加する](./getting-started.md#既存の-astro-プロジェクトに追加する)方法もあります。
 
 ## このサイト自体が使用例
 

package/docs/migration.md

@@ -5,6 +5,9 @@ sidebar:
   order: 9
 ---
 
+Upgrade the Cookbook runtime with your package manager, then apply the notes
+for every version range you cross, starting with the oldest.
+
 ## Upgrade the site runtime
 
 Check your current `@tenphi/cookbook`, Astro, and Node versions first. Read the
@@ -38,7 +41,179 @@ upgrade the site's Cookbook runtime or package-manager dependencies. Commit the
 documentation lock separately when intentionally updating imported content.
 Local Markdown needs no lock update.
 
-## Upcoming theme API cleanup
+## Upcoming Tasty upgrade
+
+Cookbook now uses Tasty 3.14 and the Tasty ESLint plugin 1.12. Built-in themes
+need no configuration migration. Review custom styles for these changes from
+Tasty 3.12:
+
+- Color opacity suffixes such as `#accent-text.5` now emit `color-mix()`. If the
+  palette color is already translucent, the suffix multiplies its alpha rather
+  than replacing it. For `#accent-text.$fade`, set `$fade` to a number such as
+  `".5"`, rather than a percentage such as `"50%"`.
+- `false` now omits spacing, size, and `outlineOffset` declarations. Use an
+  explicit value such as `"0"` or `"auto"` if a custom style relied on the old
+  implicit default. `transition: "none"` now correctly disables transitions,
+  including the built-in reduced-motion states.
+
+The linter now checks `mergeStyles` arguments directly: the first argument is a
+base style object and later arguments are partial overrides. Remove a custom
+`styleFunctions.mergeStyles` registration if you copied the old configuration;
+it is superseded by the built-in signature. Module-scope constants no longer
+need `tasty/no-runtime-styles-mutation` suppressions; values computed during
+rendering still do.
+
+## 0.28.x to 0.29
+
+Cookbook 0.29 updates Tasty to 3.11, aligns the built-in styles with Tasty's
+style guidelines, and checks component overrides the way the build uses them.
+
+### Style overrides
+
+Review overrides of the properties below.
+
+Direction-dependent styles now follow the page's writing direction. Override
+`Steps` with `inlinePadding` and `inlineBorder`, `Steps.Item`,
+`MarkdownCodeBlock.Pre`, and `SearchButton` with `inlinePadding` (and
+`blockPadding`), and the `SkipLink`, `HeaderLinks.Panel`, and
+`HeaderLinks.Close` positions with `blockInset` and `inlineInset`. A physical
+`padding`, `border`, or `inset` override no longer replaces those
+declarations. `MarkdownTable.HeaderCell` rounds both top corners of each cell
+in the first header row.
+
+Built-in styles hide elements with Tasty's `hide` instead of `display: none`.
+`hide` takes priority over `display`, so override `hide` to show or hide
+`MobileMenuToggle`, `Pagination`, `Search.Close`,
+`SearchResults.EngineControls`, `SearchResults.SuppressedClear`, and the
+`Document` utilities `PrintHidden`, `DesktopBlock`, `DesktopFlex`,
+`NarrowBlock`, and `MobileBlock`.
+
+`theme.styles.Card` overrides of `fill`, `shadow`, and `translate` now also
+apply to linked Cards. Their hover and pressed values are `:any-link & :hover`
+and `:any-link & :active` states of those properties, so a plain value such as
+`fill: "#surface"` also replaces them.
+
+The `clear` palette role is removed. Tasty 3.11 compiles `#clear` to
+`transparent` without reading a theme token, so a customized
+`theme.palette.clear` no longer has any effect. A leftover entry now defines an
+unused custom color; delete it.
+
+GitHub alerts (`MarkdownAlert`) now use the status palette roles that `Callout`
+uses: `info`, `success`, `warning`, and `danger`, instead of `blue`, `green`,
+and `red`. The default colors are unchanged. If you set `theme.palette.blue`,
+`green`, or `red` to restyle alerts, set `info`, `success`, or `danger`
+instead; those also restyle Callouts.
+
+### Component overrides and edit links
+
+`components.overrides` accepts only the
+[documented slot names](./configuration.md#components). An unknown name, such
+as a misspelled `Foter`, used to be ignored and now fails validation with
+`DOCS_CONFIG_UNKNOWN_KEY`.
+
+`cookbook doctor` resolves override paths from the Astro project directory,
+as the build does. Start local paths with `./`: a value such as
+`src/Header.astro` is a package specifier, which the build cannot resolve
+either, and doctor now reports it as `DOCS_COMPONENT_UNRESOLVED`.
+
+Package pages no longer get an edit link from `editLink.baseUrl`. That link
+pointed into your repository at a file that exists only in the npm artifact.
+A package page still shows an edit link when its own frontmatter sets
+`editUrl`.
+
+## 0.23.x to 0.28
+
+These releases need no configuration changes, but they can affect custom
+scripts, hard-coded links, and apps that share the reader's appearance:
+
+- **Client navigation (0.24):** internal links swap pages without a full
+  reload. Bundled scripts are not rerun after a client navigation, so attach
+  custom browser behavior through custom-element lifecycle callbacks or
+  initialize it on `astro:page-load`. See
+  [client navigation](./site-navigation.md#client-navigation).
+- **Prefetching (0.25):** Astro's hover and focus prefetching is enabled by
+  default. Set `prefetch: false` in the Astro configuration to turn it off;
+  explicit Astro `prefetch` settings are preserved.
+- **Page URLs (0.25.1):** page URLs follow Astro's `trailingSlash` and
+  `build.format`. With the default directory output, internal links, canonicals,
+  and `llms.txt` use a trailing slash, such as `/guide/`. See
+  [deployment](./deployment.md#public-url-and-base-path).
+- **Appearance storage (0.25.4):** the reader's color scheme and contrast are
+  stored together in one `cookbook-appearance` entry. A scheme saved under the
+  previous `cookbook-theme` key is still read and moves to the new entry on the
+  next change. See [reader appearance](./theme-and-components.md#reader-appearance).
+
+## 0.22.x to 0.23
+
+Cookbook 0.23 extends Tasty `data-element` identities to all owned anatomy,
+expresses state with data modifiers, and uses one responsive width scale.
+
+### Root hooks, anatomy, and button variants
+
+Existing component root classes and Logo’s root `class` prop remain supported.
+Stable generated-content root classes remain available for global ownership, including
+`.cookbook-markdown-content`, `.cookbook-heading-wrapper`, `.td-code-block`,
+`.tasty-code`, `.cookbook-alert`, and `.td-mermaid`. Custom roots may also use classes
+or `data-component`.
+
+Owned sub-elements use `data-element` identities, and state uses data modifiers.
+Keep identity matching in structural `$` selectors. For example, hero actions use
+`data-element="Action"` with `data-primary`, `data-secondary`, or `data-minimal`.
+When customizing `Hero.PrimaryAction`, keep its variant condition in a property
+map, such as `color: { "@own(primary)": "#accent-text" }`.
+
+The code-block wrapper owns `data-diff` and `data-copy-state`; code and line rules
+use plain `diff` or `copy-state=copied` state keys. Line insertion/deletion flags
+belong to the line itself and use `@own(inserted)` / `@own(deleted)`.
+
+Heading wrappers carry `data-heading` and `level=h1` through `level=h6` states.
+Linked Cards carry `data-block` for prose spacing. Shared `@prose`, `@prose-block`,
+and `@prose-heading` conditions keep repeated Markdown declarations readable while
+preserving isolated `data-not-content` descendants and conditional omissions.
+
+Syntax transformers may emit root classes. Token/category hooks use modifiers,
+for example `SyntaxHighlight: { Keyword: { color: { "@own(syntax-keyword)": "#accent-text" } } }`.
+Tasty-generated style hashes and library-owned Pagefind sub-element classes remain.
+
+Hero buttons stay stationary on hover. Minimal actions share secondary outline
+padding, background, and border width, with a transparent border (`border: "#clear"`).
+Pagination links keep their border at rest; hover changes only colors,
+preserving `theme.styles.Pagination.Link` border width and style.
+
+### Responsive states
+
+Responsive aliases now use one width scale: `@sm` (>40rem), `@md` (≥50rem), and
+`@lg` (≥72rem). The conditions select wider viewports;
+the exclusive 40rem boundary preserves the former `@small` behavior. The renderer
+keeps its existing responsive thresholds.
+Use these replacements for the removed shortcuts in custom style maps:
+
+| Removed alias    | Replacement          |
+| ---------------- | -------------------- |
+| `@small`         | `!@sm`               |
+| `@mobile`        | `!@md`               |
+| `@narrow-layout` | `!@lg`               |
+| `@desktop`       | `@md`                |
+| `@compact`       | `@media(w <= 23rem)` |
+| `@shell-mobile`  | `@media(w <= 48rem)` |
+| `@shell-desktop` | `@media(w > 48rem)`  |
+| `@medium-layout` | `@md & !@lg`         |
+| `@popover-open`  | `:popover-open`      |
+
+Inside a selected descendant's condition, use `@own(:popover-open)`.
+The shell and medium-layout aliases were unused by built-in components;
+PackageVersion's 23rem rule is now a direct media condition. Define a project
+alias in `theme.states` if you need a named threshold across your own components.
+
+If you customized `theme.states`, rename your breakpoint definitions and invert
+the old upper-bound conditions. For example, `"@mobile": "@media(w < 43rem)"`
+becomes `"@md": "@media(w >= 43rem)"`.
+
+## 0.20.x to 0.21
+
+Cookbook 0.21 removes the legacy theme naming and styling compatibility paths.
+0.21.2 moved Header, Footer, and logo anatomy to `data-element` identities and
+heading levels to state maps.
 
 Use canonical Glaze palette names throughout configuration and color
 references. Replace `theme.palette.textSoft` with `theme.palette["text-soft"]`
@@ -65,6 +240,8 @@ For a custom component, use `defineComponent(name, options)`. For custom global
 rules, pass `resolveComponentStyles(name, baseStyles)` to `useGlobalStyles()`.
 Both merge `theme.customStyles[name]` into the complete base styles during
 server rendering. See [custom components](./custom-components.md).
+The compact language selector's former `Compact` hook is now a root state:
+customize it with `LanguageSelect: { border: { "[data-compact]": "4px solid #border" } }`.
 
 ## 0.19.x to 0.20
 
@@ -118,8 +295,9 @@ These changes were introduced in 0.18:
 - **Google fonts:** family-name shorthand loads preset weights and italics and
   self-hosts the files. The initial build requires network access. Preserve the
   Astro font cache for offline rebuilds, use local files for checked-in assets,
-  or select `theme.fontLoading.google: "remote"` for CDN delivery. See
-  [fonts](./fonts-and-typography.md#change-font-families).
+  or select `theme.fontLoading.google: "remote"` for CDN delivery. Weights set
+  through CSS variables that cannot be resolved from presets require explicit
+  `weights`. See [fonts](./fonts-and-typography.md#change-font-families).
 - **Colors:** body tone 0 and heading tone 4 remain the reading defaults.
   The default logo uses fixed Glaze colors (`logo-surface` and `logo-mark`), so
   its book stays light in dark mode. Customize these independently of accents.
@@ -168,6 +346,13 @@ Version 0.17.1 restored strong body/heading colors with absolute Glaze tones.
 If you added temporary contrast workarounds in 0.17.0, compare them with those
 defaults before carrying them forward.
 
+## 0.14 to 0.15
+
+The Appearance panel combines the color scheme and contrast controls in
+`ThemeSelect`. Replace `ThemeSelect` `Select` and `Picker` overrides with
+`Trigger` and `Panel`, and move `ContrastSelect` overrides to the same
+`ThemeSelect` panel and option sub-elements.
+
 ## Upgrading from before 0.14
 
 The shared-configuration and source-identity changes shipped in **0.14.0**.
@@ -200,65 +385,3 @@ Apply these steps if your project still uses the earlier contracts:
 
 See [authoring](./authoring.mdx) for component usage and
 [working examples](./examples.md) for repository configuration patterns.
-
-## Root hooks, anatomy, and button variants
-
-Existing component root classes and Logo’s root `class` prop remain supported.
-Stable generated-content root classes remain available for global ownership, including
-`.cookbook-markdown-content`, `.cookbook-heading-wrapper`, `.td-code-block`,
-`.tasty-code`, `.cookbook-alert`, and `.td-mermaid`. Custom roots may also use classes
-or `data-component`.
-
-Owned sub-elements use `data-element` identities, and state uses data modifiers.
-Keep identity matching in structural `$` selectors. For example, hero actions use
-`data-element="Action"` with `data-primary`, `data-secondary`, or `data-minimal`.
-When customizing `Hero.PrimaryAction`, keep its variant condition in a property
-map, such as `color: { "@own(primary)": "#accent-text" }`.
-
-The code-block wrapper owns `data-diff` and `data-copy-state`; code and line rules
-use plain `diff` or `copy-state=copied` state keys. Line insertion/deletion flags
-belong to the line itself and use `@own(inserted)` / `@own(deleted)`.
-
-Heading wrappers carry `data-heading` and `level=h1` through `level=h6` states.
-Linked Cards carry `data-block` for prose spacing. Shared `@prose`, `@prose-block`,
-and `@prose-heading` conditions keep repeated Markdown declarations readable while
-preserving isolated `data-not-content` descendants and conditional omissions.
-
-Syntax transformers may emit root classes. Token/category hooks use modifiers,
-for example `SyntaxHighlight: { Keyword: { color: { "@own(syntax-keyword)": "#accent-text" } } }`.
-Tasty-generated style hashes and library-owned Pagefind sub-element classes remain.
-
-Hero buttons stay stationary on hover. Minimal actions share secondary outline
-padding, background, and border width, with a transparent border (`border: "#clear"`).
-Pagination links keep their border at rest; hover changes only colors,
-preserving `theme.styles.Pagination.Link` border width and style.
-
-## Smaller shared state set
-
-Responsive aliases now use one width scale: `@sm` (>40rem), `@md` (≥50rem), and
-`@lg` (≥72rem). The conditions select wider viewports;
-the exclusive 40rem boundary preserves the former `@small` behavior. The renderer
-keeps its existing responsive thresholds.
-Use these replacements for the removed shortcuts in custom style maps:
-
-| Removed alias    | Replacement          |
-| ---------------- | -------------------- |
-| `@small`         | `!@sm`               |
-| `@mobile`        | `!@md`               |
-| `@narrow-layout` | `!@lg`               |
-| `@desktop`       | `@md`                |
-| `@compact`       | `@media(w <= 23rem)` |
-| `@shell-mobile`  | `@media(w <= 48rem)` |
-| `@shell-desktop` | `@media(w > 48rem)`  |
-| `@medium-layout` | `@md & !@lg`         |
-| `@popover-open`  | `:is(:popover-open)` |
-
-Inside a selected descendant's condition, use `@own(:is(:popover-open))`.
-The `:is()` wrapper accommodates the pinned linter's pseudo-class list.
-The shell and medium-layout aliases were unused by built-in components;
-PackageVersion's 23rem rule is now a direct media condition. Define a project
-alias in `theme.states` if you need a named threshold across your own components.
-
-If you customized `theme.states`, rename your breakpoint definitions and invert
-the old upper-bound conditions. For example, `"@mobile": "@media(w < 43rem)"`
-becomes `"@md": "@media(w >= 43rem)"`.