@tenphi/cookbook 0.18.0 → 0.18.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/docs/customization-rules.md +3 -0
  2. package/docs/index.md +12 -0
  3. package/docs/theme-and-components.md +71 -9
  4. package/package.json +3 -3
package/docs/customization-rules.md CHANGED
@@ -36,6 +36,9 @@ its complete base styles using Tasty's `mergeStyles`. Do not copy the entire
36
36
  default style tree or rebuild it in user configuration. Built-in names belong
37
37
  in `theme.styles`; custom names belong in `theme.customStyles`.
38
38
 
39
+ This merge happens before CSS extraction, so built-in appearance changes do not
40
+ need a second stylesheet or `!important` rules to override default declarations.
41
+
39
42
  ```ts
40
43
  import { defineDocsConfig } from "@tenphi/cookbook/config";
41
44
 
package/docs/index.md CHANGED
@@ -40,6 +40,18 @@ Broken links, missing assets, duplicate routes, invalid navigation, and unsafe
40
40
  paths fail with source locations. The result is prerendered HTML and CSS ready
41
41
  for GitHub Pages or any static host.
42
42
 
43
+ ### Styling that fits your product
44
+
45
+ [Glaze](./upstream/glaze/README.md) turns a brand and semantic palette into light, dark, and high-contrast
46
+ colors with contrast targets. [Tasty](./upstream/tasty/README.md) applies those color roles alongside shared
47
+ tokens and typography presets, so the docs can follow your design system.
48
+ State maps keep hover, focus, and responsive values beside the styles they
49
+ change. Partial `theme.styles` overrides merge before CSS extraction, letting
50
+ you adjust supported components without selector chains or `!important`.
51
+ The browser receives static CSS, with no Tasty or Glaze styling runtime.
52
+ See the [theme reference](./theme-and-components.md) for the palette, presets,
53
+ states, and named component styles.
54
+
43
55
  ## Choose a path
44
56
 
45
57
  | I want to… | Start here | Then read |
package/docs/theme-and-components.md CHANGED
@@ -125,7 +125,7 @@ Cookbook keeps literal surface seeds desaturated in the dark scheme so a nearly
125
125
  white tint does not become vivid dark chrome when its tone is inverted.
126
126
 
127
127
  Components consume semantic colors consistently: `surface`, `header`, `surface-2`,
128
- `surface-3`, `text`, `heading`, `text-soft`, `border`, `border-strong`, `accent-text`,
128
+ `surface-3`, `text`, `heading`, `text-soft`, `sidebar-text`, `border`, `border-strong`, `accent-text`,
129
129
  `accent-surface`, `accent-surface-text`, `logo-surface`, `logo-mark`, and `focus`.
130
130
  Tasty components can use these as `#surface`, `#text`, `#border`, and so on; the Astro shell consumes the
131
131
  same resolved values. Glaze also generates hover and pressed states, subtle
@@ -159,9 +159,14 @@ Interactive controls step up exactly one surface level: a control on `surface`
159
159
  uses `surface-2`, while a control on `surface-2` uses `surface-3`. Hover and
160
160
  pressed states build on that elevated surface without changing the border.
161
161
  Inputs stay on their surrounding surface so their border remains the visual
162
- boundary. Selected navigation uses the fixed-mode `accent-surface` and its
163
- paired `accent-surface-text`, so the brand fill does not drift toward the
164
- adaptive link color in dark mode.
162
+ boundary. Primary buttons and selected navigation use the fixed-mode
163
+ `accent-surface` and its paired light `accent-surface-text`. The brand fill
164
+ keeps its polarity in dark mode while Glaze adjusts it to preserve label
165
+ contrast.
166
+
167
+ Page navigation keeps Next first in the keyboard order. It appears above
168
+ Previous on narrow screens; wider layouts show Previous at the start and Next
169
+ at the end.
165
170
 
166
171
  ## Design tokens
167
172
 
@@ -326,6 +331,10 @@ headings use a medium `610` weight and progressively gentle negative tracking.
326
331
  The separate `720` heading bold weight keeps emphasized heading text distinct.
327
332
  Navigation uses a lighter `450` weight with `580` for the current sidebar page,
328
333
  while smaller group labels establish hierarchy without oversized bold text.
334
+ Inactive sidebar links use `sidebar-text`, a slightly softer blend of `text-soft`
335
+ and the surface. In high-contrast mode it matches `text-soft`. Set
336
+ `theme.palette['sidebar-text']` to adjust that color without changing other
337
+ secondary text, or `theme.styles.Sidebar.Control` to customize the control.
329
338
  Top-level sidebar groups are always-visible section headings with their direct
330
339
  links aligned beneath them. Deeper groups expand on click or keyboard activation;
331
340
  the current group and its ancestors start open. Groups can have a parent-page
@@ -357,6 +366,53 @@ bridge. Customize either kind by name under `theme.styles`; the configuration
357
366
  is resolved before CSS generation, so this is not a selector-based CSS
358
367
  override.
359
368
 
369
+ > **Direct styles, without a specificity battle.** Cookbook merges your partial
370
+ > style object with the component's base styles before Tasty extracts CSS. The
371
+ > generated stylesheet reflects that result; changing a supported property
372
+ > does not add a competing rule just to beat the original. You can customize
373
+ > existing elements without long selectors or `!important`.
374
+
375
+ Start with the area you want to change, then use the complete sub-element table
376
+ below to find its exact anatomy:
377
+
378
+ | Page area | Style names to inspect |
379
+ | ----------------------------- | ------------------------------------------------------------------------------------ |
380
+ | Header, title, and navigation | `HeaderFrame`, `StarlightHeader`, `SiteLogo`, `HeaderLinks`, `TopNavigation` |
381
+ | Sidebar and mobile menu | `Sidebar`, `MobileMenuToggle`, `MobileNavigationTabs`, `MobileMenuFooter` |
382
+ | Article text and headings | `Markdown`, `MarkdownHeading`, `Heading`, `MainContent` |
383
+ | Code and diagrams | `MarkdownCodeBlock`, `MarkdownInlineCode`, `SyntaxHighlight`, `CodeGroup`, `Mermaid` |
384
+ | Search | `SearchButton`, `Search`, `SearchResults` |
385
+ | Table of contents | `TableOfContents`, `MobileTableOfContents`, `TableOfContentsLayout` |
386
+ | Cards, notes, and tabs | `Card`, `StarlightCard`, `StarlightAside`, `Tabs` |
387
+ | Footer and page controls | `Footer`, `Pagination`, `PageActions`, `ThemeSelect` |
388
+
389
+ For example, this changes a typography role and one named element without
390
+ copying a component's full style tree:
391
+
392
+ ```ts
393
+ theme: {
394
+ presets: { h2: { fontSize: "1.75rem" } },
395
+ styles: {
396
+ Sidebar: {
397
+ LinkLabel: {
398
+ preset: "body",
399
+ whiteSpace: { "": "nowrap", "@mobile": "normal" }
400
+ }
401
+ }
402
+ }
403
+ }
404
+ ```
405
+
406
+ The `@mobile` value sits with the default value in one Tasty state map. Shared
407
+ tokens and presets keep the component aligned with the rest of the site, while
408
+ Glaze resolves semantic colors across the configured schemes and contrast
409
+ modes.
410
+
411
+ In a generated site, run `npm run validate` (or the matching package manager's
412
+ command) after editing `docs.config.ts`. It checks TypeScript theme properties,
413
+ then runs Cookbook's preflight and production output checks. A misspelled
414
+ preset or built-in sub-element property fails type checking.
415
+
360
416
  Provide only the root and named
361
417
  [sub-element](./upstream/tasty/docs/dsl.md#sub-element) properties you want to
362
418
  override. Cookbook deep-merges that partial style object into the complete
@@ -445,7 +501,7 @@ sub-elements:
445
501
  | `Banner` | `Link` |
446
502
  | `SkipLink` | `Focus` |
447
503
  | `Search` | `Status`, `Dialog`, `CloseIcon`, `OpenDialog`, `Backdrop`, `Frame`, `Container`, `Close`, `HoverClose`, `ActiveClose` |
448
- | `Pagination` | `Link`, `NextLink`, `NextIcon`, `NextLabel`, `HoverLink`, `ActiveLink`, `Title`, `LoneNextLink`, `NativeIcon`, `Icon`, `PreviousIconRtl`, `NextIconRtl` |
504
+ | `Pagination` | `Link`, `PreviousLink`, `NextLink`, `NextIcon`, `NextLabel`, `HoverLink`, `ActiveLink`, `Title`, `LoneNextLink`, `Icon`, `PreviousIconRtl`, `NextIconRtl` |
449
505
  | `Markdown` | `Block`, `BlockSpacing`, `HeadingSpacing`, `List`, `CompactItem`, `ListItem`, `DefinitionTerm`, `DefinitionDescription`, `Link`, `HoverLink`, `Quote`, `Rule`, `Details`, `HoverDetails`, `Summary`, `OpenSummary`, `SummaryMarker`, `SummaryIcon`, `OpenSummaryIcon`, `Code` |
450
506
  | `MermaidSource` | None |
451
507
  | `StarlightAside` | `Note`, `Tip`, `Caution`, `Danger`, `Title`, `Icon`, `FirstContent` |
@@ -491,6 +547,10 @@ same.
491
547
  Register custom names and their partial Tasty objects in `theme.customStyles`.
492
548
  Built-in names belong in `theme.styles` and reject misspelled sub-elements.
493
549
  Custom names can also target a matching user-authored `data-tasty-anatomy` attribute.
550
+ The name must match the string passed to `defineComponent()` or
551
+ `resolveComponentStyles()`, or the `data-tasty-anatomy` value. A production
552
+ build warns when a configured custom name has no matching component style
553
+ resolver or rendered anatomy attribute.
494
554
 
495
555
  The default renderer runs Tasty in Astro extract mode. Direct components and
496
556
  the remaining document/vendor bridge styles are collected into shared static
@@ -614,6 +674,7 @@ separately for square artwork; the default Cookbook icon set remains in place
614
674
  until changed. `Logo` remains available as the standalone Cookbook book mark.
615
675
 
616
676
  The built-in mark uses `theme.palette["logo-surface"]` and `theme.palette["logo-mark"]`.
677
+ The default homepage hero artwork also uses `logo-surface` for its brand fill.
617
678
  Both default to Glaze `mode: "fixed"`: the brand background and light book keep
618
679
  their polarity in dark mode while respecting Glaze's tone boundaries and
619
680
  high-contrast settings. The mark-to-background contrast floor is 3:1 normally
@@ -1057,7 +1118,7 @@ directly to Tasty `#name` tokens. `COOKBOOK_PALETTE_NAMES`, exported from
1057
1118
  | Area | Roles |
1058
1119
  | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1059
1120
  | Surfaces | `surface`, `header`, `overlay`, `surface-2`, `surface-3`, `surface-2-hover`, `surface-2-pressed`, `surface-3-hover`, `surface-3-pressed` |
1060
- | Reading | `text`, `heading`, `text-soft` (alias `textSoft`), `text-muted` |
1121
+ | Reading | `text`, `heading`, `text-soft` (alias `textSoft`), `text-muted`, `sidebar-text` |
1061
1122
  | Brand and focus | `accent-text`, `accent-surface`, `accent-surface-text`, `accent-surface-subtle`, `accent-surface-2-subtle`, `logo-surface`, `logo-mark`, `focus` |
1062
1123
  | Borders and effects | `border`, `border-strong`, `shadow`, `clear` |
1063
1124
  | Status | `info`, `success`, `warning`, `danger`, each with `-text` and `-surface` variants |
@@ -1083,9 +1144,10 @@ backgrounds, typography, or layout.
1083
1144
  A `DOCS_SEMANTIC_CONTRAST_UNMET` or `DOCS_BRAND_CONTRAST_UNMET` error names the
1084
1145
  pair, mode, and required target. Adjust that pair's `theme.palette` declarations:
1085
1146
  use an absolute tone for reading text, reduce saturation when needed, and keep
1086
- `autoFlip` enabled when the solver needs to cross its base. A fixed middle-tone
1087
- button fill may make its label's contrast impossible. Cookbook's default
1088
- brand fill adapts to avoid this, including for orange, yellow, and pale brands.
1147
+ `autoFlip` enabled when the solver needs to cross its base. Cookbook's default
1148
+ fixed brand fill is anchored to a light label and darkens when needed to meet
1149
+ contrast, including for orange, yellow, and pale brands. A custom fixed
1150
+ middle-tone fill can make its label's contrast impossible.
1089
1151
  Focus uses a WCAG 3:1 floor (4.5:1 in high contrast) against the surface ramp.
1090
1152
 
1091
1153
  Keep contrast requirements when adjusting colors. Extreme custom tone windows,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tenphi/cookbook",
3
- "version": "0.18.0",
3
+ "version": "0.18.2",
4
4
  "description": "Repository-native static documentation for Astro",
5
5
  "type": "module",
6
6
  "keywords": [
@@ -68,8 +68,8 @@
68
68
  "author": "Andrey Yamanov",
69
69
  "license": "MIT",
70
70
  "dependencies": {
71
- "@tenphi/docs": "0.18.0",
72
- "@tenphi/starlight": "0.18.0"
71
+ "@tenphi/docs": "0.18.2",
72
+ "@tenphi/starlight": "0.18.2"
73
73
  },
74
74
  "peerDependencies": {
75
75
  "astro": "^7.3.2"