@tenphi/cookbook 0.18.0 → 0.18.1

package/docs/customization-rules.md

@@ -36,6 +36,9 @@ its complete base styles using Tasty's `mergeStyles`. Do not copy the entire
 default style tree or rebuild it in user configuration. Built-in names belong
 in `theme.styles`; custom names belong in `theme.customStyles`.
 
+This merge happens before CSS extraction, so built-in appearance changes do not
+need a second stylesheet or `!important` rules to override default declarations.
+
 ```ts
 import { defineDocsConfig } from "@tenphi/cookbook/config";
 

package/docs/index.md

@@ -40,6 +40,18 @@ Broken links, missing assets, duplicate routes, invalid navigation, and unsafe
 paths fail with source locations. The result is prerendered HTML and CSS ready
 for GitHub Pages or any static host.
 
+### Styling that fits your product
+
+Glaze turns a brand and semantic palette into light, dark, and high-contrast
+colors with contrast targets. Tasty applies those color roles alongside shared
+tokens and typography presets, so the docs can follow your design system.
+State maps keep hover, focus, and responsive values beside the styles they
+change. Partial `theme.styles` overrides merge before CSS extraction, letting
+you adjust supported components without selector chains or `!important`.
+The browser receives static CSS, with no Tasty or Glaze styling runtime.
+See the [theme reference](./theme-and-components.md) for the palette, presets,
+states, and named component styles.
+
 ## Choose a path
 
 | I want to…                           | Start here                              | Then read                                                             |

package/docs/theme-and-components.md

@@ -357,6 +357,53 @@ bridge. Customize either kind by name under `theme.styles`; the configuration
 is resolved before CSS generation, so this is not a selector-based CSS
 override.
 
+> **Direct styles, without a specificity battle.** Cookbook merges your partial
+> style object with the component's base styles before Tasty extracts CSS. The
+> generated stylesheet reflects that result; changing a supported property
+> does not add a competing rule just to beat the original. You can customize
+> existing elements without long selectors or `!important`.
+
+Start with the area you want to change, then use the complete sub-element table
+below to find its exact anatomy:
+
+| Page area                     | Style names to inspect                                                               |
+| ----------------------------- | ------------------------------------------------------------------------------------ |
+| Header, title, and navigation | `HeaderFrame`, `StarlightHeader`, `SiteLogo`, `HeaderLinks`, `TopNavigation`         |
+| Sidebar and mobile menu       | `Sidebar`, `MobileMenuToggle`, `MobileNavigationTabs`, `MobileMenuFooter`            |
+| Article text and headings     | `Markdown`, `MarkdownHeading`, `Heading`, `MainContent`                              |
+| Code and diagrams             | `MarkdownCodeBlock`, `MarkdownInlineCode`, `SyntaxHighlight`, `CodeGroup`, `Mermaid` |
+| Search                        | `SearchButton`, `Search`, `SearchResults`                                            |
+| Table of contents             | `TableOfContents`, `MobileTableOfContents`, `TableOfContentsLayout`                  |
+| Cards, notes, and tabs        | `Card`, `StarlightCard`, `StarlightAside`, `Tabs`                                    |
+| Footer and page controls      | `Footer`, `Pagination`, `PageActions`, `ThemeSelect`                                 |
+
+For example, this changes a typography role and one named element without
+copying a component's full style tree:
+
+```ts
+theme: {
+  presets: { h2: { fontSize: "1.75rem" } },
+  styles: {
+    Sidebar: {
+      LinkLabel: {
+        preset: "body",
+        whiteSpace: { "": "nowrap", "@mobile": "normal" }
+      }
+    }
+  }
+}
+```
+
+The `@mobile` value sits with the default value in one Tasty state map. Shared
+tokens and presets keep the component aligned with the rest of the site, while
+Glaze resolves semantic colors across the configured schemes and contrast
+modes.
+
+In a generated site, run `npm run validate` (or the matching package manager's
+command) after editing `docs.config.ts`. It checks TypeScript theme properties,
+then runs Cookbook's preflight and production output checks. A misspelled
+preset or built-in sub-element property fails type checking.
+
 Provide only the root and named
 [sub-element](./upstream/tasty/docs/dsl.md#sub-element) properties you want to
 override. Cookbook deep-merges that partial style object into the complete
@@ -491,6 +538,10 @@ same.
 Register custom names and their partial Tasty objects in `theme.customStyles`.
 Built-in names belong in `theme.styles` and reject misspelled sub-elements.
 Custom names can also target a matching user-authored `data-tasty-anatomy` attribute.
+The name must match the string passed to `defineComponent()` or
+`resolveComponentStyles()`, or the `data-tasty-anatomy` value. A production
+build warns when a configured custom name has no matching component style
+resolver or rendered anatomy attribute.
 
 The default renderer runs Tasty in Astro extract mode. Direct components and
 the remaining document/vendor bridge styles are collected into shared static

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/cookbook",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "description": "Repository-native static documentation for Astro",
   "type": "module",
   "keywords": [
@@ -68,8 +68,8 @@
   "author": "Andrey Yamanov",
   "license": "MIT",
   "dependencies": {
-    "@tenphi/docs": "0.18.0",
-    "@tenphi/starlight": "0.18.0"
+    "@tenphi/docs": "0.18.1",
+    "@tenphi/starlight": "0.18.1"
   },
   "peerDependencies": {
     "astro": "^7.3.2"