Theme and components
Cookbook resolves Glaze colors and Tasty styles during the build, then ships static CSS. Start with a brand color; add semantic palette roles, typography, and component overrides only where the default needs to change. The theme recipes show complete, build-checked starting points. Read the customization rules before writing new styles.
| To change | Start here |
|---|---|
| Brand, color roles, design tokens, and logo | This page |
| Font files, families, and typography | Fonts and typography |
| Built-in UI surfaces and named parts | Component styles |
| Your own Astro or MDX components and linting | Custom components |
| Complete configuration fields | Configuration reference |
Glaze derives light, dark, and high-contrast values from the brand and palette inputs. Tasty applies those values through semantic tokens. See the Glaze reference for color declarations and the Tasty style DSL for state maps, tokens, units, and sub-elements.
The default brand is a calm blue with 68% OKHSL saturation. Set a brand color
with Glaze’s from declaration:
import { defineDocsConfig } from "@tenphi/cookbook/config";
export default defineDocsConfig({
theme: { brand: { from: "#2f5bff" } },
});Add a higher contrast target when brand-colored text needs more contrast:
theme: {
brand: {
from: "#2f5bff",
contrast: { apca: [80, 95] }
}
}The default brand target is APCA 45 (60 in high contrast).
The brand supplies the hue and saturation seed. Cookbook derives separate text, filled-control, and focus roles from it. Small accent text keeps APCA floors of 75 (90 in high contrast), and filled-control labels keep 80 (95 in high contrast); diagnostics also enforce WCAG 4.5:1 / 7:1 on their actual backgrounds. Only authored brand targets above these floors raise them. Glaze adjusts tones only as far as these floors require; dark and high-contrast schemes resolve independently.
Cookbook rejects a normal APCA target below 45 unless
unsafeContrast: true is present. That escape hatch is intentionally visible
in configuration reviews. Literal color shorthand and structured
hue/saturation/tone input also remain supported for the brand.
brand controls accent text, fills, and focus. The optional palette roles
control the reading surface, text, and callout colors. Declare color
relationships with Glaze’s tone, base, and contrast properties:
theme: {
brand: { from: "#2f5bff" },
palette: {
surface: { tone: 98, saturation: 0.05 },
text: {
base: "surface",
tone: 0,
saturation: 0,
contrast: { wcag: [7, 10] }
},
heading: {
base: "surface",
tone: [4, 0],
saturation: 0,
contrast: { wcag: [7, 10] }
},
"text-soft": {
base: "surface",
tone: [25, 10],
saturation: 0.05,
contrast: { wcag: [4.5, 7] }
}
},
contrastLevel: "auto"
}Glaze resolves each declaration for light, dark, normal, and high-contrast
modes. In a tone or contrast pair, the first value applies to normal mode;
the second applies to high contrast. Use absolute tones for reading text:
text starts at tone 0 and heading at tone 4, giving headings only a slight
reduction in contrast. Glaze applies its tone boundaries in normal mode, so
body text is not pure black, then inverts the tones for dark mode. High-contrast
mode uses the full range. text-soft is reserved for secondary text.
heading follows an explicitly configured text declaration unless it has
its own declaration, preserving existing custom palettes.
Contrast requirements are minimum safeguards: Glaze preserves the authored
tone when it already meets the floor. A small relative tone step from the
surface would instead leave the solver to produce text at that minimum.
Palette declarations inherit the brand hue and saturation:
saturation is a 0–1 factor of that seed, and tone is 0–100. They can set
an absolute tone or a tone relative to base. Use from on a palette role
when it needs its own color seed; otherwise relative declarations keep its
relationship to the brand and surrounding surface as the scheme or contrast
changes. info, success, warning, and danger also accept Glaze
declarations and expose border, -text, and -surface semantic tokens. For
orange, green, blue, purple, and red, an override changes that role
and its -surface tint only; set the matching -text role as well.
Cookbook keeps literal surface seeds desaturated in the dark scheme so a nearly
white tint does not become vivid dark chrome when its tone is inverted.
Components consume semantic colors consistently: surface, header, surface-2,
surface-3, text, heading, text-soft, sidebar-text, border, border-strong, accent-text,
accent-surface, accent-surface-text, logo-surface, logo-mark, and focus.
Tasty components can use these as #surface, #text, #border, and so on; the Astro shell consumes the
same resolved values. Glaze also generates hover and pressed states, subtle
accent fills, overlays, shadows, and the orange, green, blue, purple, and red
roles available to content components. No browser color mixes or
upstream fallback palette values participate in the rendered theme. Surface
elevation uses Glaze’s contrast-uniform tone axis: surface-2 advances two tone
steps and surface-3 advances four from the base surface, with proportionally
wider steps in high-contrast mode. Their saturation also steps down to 75% and
65% of the authored surface seed so tinted surfaces remain restrained as they
move farther from the base tone.
Borders stay intentionally quiet: Glaze derives their hue from brand but
uses only about one fifth (a 0.205 factor) of the brand saturation. Normal and high-contrast modes
change border tone, not that restrained saturation relationship.
Every theme.palette entry participates in one Glaze color graph. Use lowercase
names with hyphens; a role named review-panel becomes the Tasty token
#review-panel. Declaration order does not matter. References can target custom
colors or built-in roles, including header, border, overlay, and syntax colors.
theme: {
brand: { from: "#315efb" },
palette: {
"review-ink": {
base: "review-panel",
tone: [4, 0],
saturation: 0.05,
contrast: { wcag: [7, 10] },
},
"review-panel": { base: "surface", tone: "-2", saturation: 0.05 },
},
styles: {
Callout: { fill: "#review-panel", color: "#review-ink" },
},
},Relative and absolute declarations inherit the brand’s hue and saturation.
Use saturation factors from 0 (neutral) to 1 (full seed saturation), and
hue to choose a different hue. All roles resolve for light, dark, and both
high-contrast modes. Configuration diagnostics and rendering use the same graph.
Missing references and cycles fail with the color name; layered configurations
resolve references after merging.
Palette names use lowercase letters, digits, and hyphens, such as text-soft.
The names current, constructor, and prototype are reserved.
Declaring a built-in name intentionally overrides that role; use a project
prefix for additional roles to avoid future naming collisions.
When a status role such as info uses a mix, shadow, or glow definition, its
derived info-text defaults to neutral, contrast-corrected text. Override
info-text explicitly for a colored label; the dependency graph stays intact.
A shadow or glow status also uses a neutral derived surface, because Glaze does
not allow a shadow or glow to be a mix target. Override the surface separately
when needed.
theme.glaze accepts lightTone, darkTone, darkDesaturation, autoFlip,
pastel, inferRole, and shadowTuning. Tone windows accept [lo, hi], false
for the full range, or the advanced { lo, hi, eps } form. The example below
uses Glaze’s default windows. Continue to use
theme.contrastLevel for manual contrast interpolation. Cookbook always emits
all four appearance variants.
theme: {
glaze: { lightTone: [10, 100], darkTone: [15, 95] },
palette: {
"accent-surface-subtle": {
type: "mix", base: "surface", target: "accent-surface", value: [12, 20],
},
shadow: { type: "shadow", bg: "surface", intensity: [6, 0] },
},
},Palette roles accept Glaze’s regular, mix, shadow, and glow declarations. Mix, shadow, and glow references use the same graph as other roles. Native Glaze restrictions still apply, including the requirement for shadow and glow backgrounds and foregrounds to reference colors that are neither shadows nor glows.
Without fg, a shadow’s intensity is the exact number of tones the page
darkens under it (a glow’s, how many it lightens), with an optional
high-contrast value. fg names the element that casts the shadow, not a
contrast reference, and scales the step by that element’s tone;
tuning: { objectInfluence: 0 } turns this off. A step can’t pass black: the
default dark page sits about 9 tones above it, and the default dark
high-contrast page is black, so give a shadow on the page 0 as its
high-contrast value. A step that doesn’t fit paints at full strength, and Glaze
logs a “cannot reach” warning.
The built-in shadow role steps 8 tones in light and dark, and is transparent
in high contrast, where borders carry the edges. On the default surface, a
darkTone whose dark end is below about 14 (including false), or a numeric
theme.contrastLevel from about 25 to 99, leaves the dark page too close to
black for the step, so the built-in shadow reaches full strength and Glaze
warns. shadowTuning exposes Glaze’s objectInfluence, tint, reach, and
hueBleed for every shadow; a role’s own tuning takes precedence, and a glow
takes only its own tuning. See
Glaze shadows and glows.
Every generated role below can be overridden in theme.palette. Names map
directly to Tasty #name tokens. COOKBOOK_PALETTE_NAMES, exported from
@tenphi/cookbook, lists the same roles for tooling.
| Area | Roles |
|---|---|
| Surfaces | surface, header, overlay, surface-2, surface-3, surface-2-hover, surface-2-pressed, surface-3-hover, surface-3-pressed |
| Reading | text, heading, text-soft, text-muted, sidebar-text |
| Brand and focus | accent-text, accent-surface, accent-surface-text, accent-surface-subtle, accent-surface-2-subtle, logo-surface, logo-mark, focus |
| Borders and effects | border, border-strong, shadow |
| Status | info, success, warning, danger, each with -text and -surface variants |
| Additional hues | orange, green, blue, purple, red, each with -text and -surface variants |
| Syntax | syntax-bg, syntax-text, syntax-comment, syntax-punctuation, syntax-keyword, syntax-string, syntax-token, syntax-property, syntax-number, syntax-function, syntax-value, syntax-operator |
Cookbook checks text, headings, secondary text-soft text, brand links,
filled-control labels, the logo mark on its surface, status text on its tinted
surface, focus rings on each elevated surface, and every palette declaration
with a contrast floor. The same Glaze
resolution powers rendering and cookbook doctor, in light, dark, and both
high-contrast modes. Manual theme.contrastLevel targets interpolate with
Glaze’s contrast level.
resolveDocsTheme(theme).contrastChecks, exported from @tenphi/cookbook,
lists each foreground/background pair with its mode, metric, target,
measured value, and passed result. APCA uses display-channel
luminance; WCAG ratios use the sRGB transfer function. Transparent foregrounds
are composited onto their background before measuring. These checks cover
Cookbook’s semantic pairs; test actual pages after changing component styles,
backgrounds, typography, or layout.
A DOCS_SEMANTIC_CONTRAST_UNMET or DOCS_BRAND_CONTRAST_UNMET error names the
pair, mode, and required target. Adjust that pair’s theme.palette declarations:
use an absolute tone for reading text, reduce saturation when needed, and keep
autoFlip enabled when the solver needs to cross its base. Cookbook’s default
fixed brand fill is anchored to a light label and darkens when needed to meet
contrast, including for orange, yellow, and pale brands. A custom fixed
middle-tone fill can make its label’s contrast impossible.
Focus uses a WCAG 3:1 floor (4.5:1 in high contrast) against the surface ramp.
Keep contrast requirements when adjusting colors. Extreme custom tone windows, fixed colors, or opacity can prevent a requested floor from being met. A palette check does not replace keyboard, screen-reader, and rendered-page testing.
Token names follow Tasty’s
token and unit syntax: $name
becomes the CSS custom property --name. Configure tokens with $name keys.
These are the defaults:
theme: {
tokens: {
"$gap": "0.5rem",
"$radius": "8px",
"$header-control-radius": "999px",
"$card-radius": "16px",
"$border-width": "1px",
"$outline-width": "2px",
"$outline-offset": "2px",
"$control-height": "2.5rem",
"$layout-width": "87.5rem",
"$content-width": "58rem",
"$sidebar-width": "17.5rem"
}
}layout-width caps and centers the complete documentation shell, while
content-width limits the reading column inside it. The column stays centered
as the viewport narrows: horizontal padding shrinks to 1.5rem before the column
itself shrinks. Mobile layouts use 1rem padding. radius is the control
and navigation radius; card-radius is the larger surface radius. Keeping
those roles separate makes a sharp control theme or a soft card theme possible
without one-off component overrides. header-control-radius shapes the header
buttons; see header control shape.
Register custom units and flat recipes in theme; Cookbook configures Tasty
before evaluating your components:
theme: {
brand: { from: "#315efb" },
palette: {
"review-panel": { base: "surface", tone: "-2", saturation: 0.05 },
"review-ink": { base: "review-panel", tone: 0, contrast: { wcag: [7, 10] } },
},
units: { rh: "6px" },
recipes: {
"review-panel": {
fill: "#review-panel",
color: "#review-ink",
padding: "2rh",
radius: "3px",
},
},
customStyles: { DemoBadge: { Label: { color: "#review-ink" } } },
},import { defineComponent } from "@tenphi/cookbook/styling";
export const DemoBadge = defineComponent("DemoBadge", {
as: "aside",
elements: { Label: "strong" },
styles: {
display: "block",
recipe: "review-panel",
Label: { preset: "h4" },
},
});Use <DemoBadge><DemoBadge.Label>Review ready</DemoBadge.Label></DemoBadge> in
MDX. Keep these styled components server-rendered: their CSS is extracted at
build time. Add behavior with a small client script targeting the rendered
markup. This recipe produces 12px padding. Units merge by name, with the later
configuration winning. Recipes merge using Tasty mergeStyles, including state
maps. Recipes are flat: define named sub-elements on the owning component, and
compose recipes with recipe: "base elevated" rather than referencing a recipe
inside another recipe. none is a reserved recipe name. Cookbook’s built-in
units are x, r, cr, and bw; overriding one changes its meaning globally.
To keep editor and linter validation synchronized with these names, build the lint configuration from your theme; see custom theme names.
Set site.logo once to use your artwork in the header and mobile drawer:
site: {
title: "Acme",
logo: "./assets/acme.svg"
}Paths are local files relative to the resolved project root, just like
site.favicon. Cookbook reads the intrinsic dimensions and copies the image to
a content-hashed URL under the deployment base. SVG, PNG, JPEG, WebP, AVIF, and
GIF are supported. Missing or invalid files fail during setup.
site: {
title: "Acme",
logo: {
light: "./assets/acme-light.svg",
dark: "./assets/acme-dark.svg",
href: "/",
decorative: true
},
favicon: "./assets/acme-icon.svg"
}Use src for one image, or both light and dark. Variants follow the
appearance control and the system preference in Auto mode. They must share an
aspect ratio to prevent layout shifts. Optional width and height describe
intrinsic dimensions; Tasty controls display size. Customize
theme.styles.SiteLogo and its complete anatomy: Image, Light, and Dark.
Wide wordmarks retain their proportions within the header.
The logo is decorative by default because the neighboring title labels the
site. Set decorative: false and alt when the image itself carries meaningful
text. The header logo link still has a name when the image is decorative.
href defaults to the localized documentation home; it accepts a root-relative
documentation route or HTTP(S) destination. The header title and drawer use the
same destination. site.logo: false removes the mark from both locations.
A logo does not change the favicon or touch icons. Configure
site.favicon separately for square artwork;
the default Cookbook icon set remains in place until changed. The
Logo component remains available as the
standalone Cookbook book mark.
The built-in mark uses theme.palette["logo-surface"] and theme.palette["logo-mark"].
The default homepage hero artwork also uses logo-surface for its brand fill.
Both default to Glaze mode: "fixed": the brand background and light book keep
their polarity in dark mode while respecting Glaze’s tone boundaries and
high-contrast settings. The mark-to-background contrast floor is 3:1 normally
and 4.5:1 in high contrast. These colors are separate from interactive accents.
For example, to customize the logo background while retaining brand hue:
theme: {
brand: { from: "#315efb" },
palette: {
"logo-surface": {
base: "logo-mark",
tone: 40,
saturation: 0.8,
mode: "fixed",
contrast: { wcag: [3, 4.5] },
},
"logo-mark": { tone: 100, saturation: 0, mode: "fixed" },
},
}Custom image assets keep their authored colors; use light/dark files when
you want distinct artwork. Header and drawer home links center logos with the
site title regardless of their aspect ratio. Use theme.styles.SiteLogo for
image size and theme.styles.Header.SiteTitle / Sidebar.HomeLink
for typography; they do not need baseline offsets for a different preset.
To combine your own logo and title in one custom link, see
Replace built-in markup.
Cookbook supplies semantic body, heading, h1–h6, navigation, small,
and code presets. Use theme.fonts to load Google families by name or local
font files, and theme.presets to change sizes, weights, and other typography
fields. See Fonts and typography for both paths,
cache behavior, and preset details.
Use a partial Tasty style object at theme.styles.<ComponentName> to change a
built-in surface. Cookbook merges it with the complete base style object before
CSS extraction. The component styles reference gives
examples and the complete list of named sub-elements for every surface.
For your own components, use defineComponent() for a configurable component
root and resolveComponentStyles() for an owned global style tree, then adopt
Cookbook’s Tasty lint preset. The custom component guide
covers both patterns and linting.
The Appearance menu stores each reader’s color scheme and contrast in one
localStorage entry. Its key and format are a stable contract, so another app
on the same origin can share the preference with the documentation. A typical
example is a product site that serves Cookbook under /docs/.
// localStorage["cookbook-appearance"], stored as JSON
type CookbookAppearance = {
theme?: "light" | "dark" | "system";
contrast?: "normal" | "more" | "system";
};A missing or unrecognized field means "system", which follows the reader’s
operating system. Keep any other fields when you write the object:
const key = "cookbook-appearance";
const appearance = JSON.parse(localStorage.getItem(key) ?? "{}") ?? {};
localStorage.setItem(key, JSON.stringify({ ...appearance, theme: "dark" }));Cookbook applies the stored choice before the first paint, as data-theme and
data-contrast on <html>. Open pages follow changes made in other tabs through
the storage event. Your app can map the same values onto its own attributes.
Browsers keep localStorage per origin: the scheme, host, and port must all
match, so a docs subdomain does not share the preference.
The page content remains readable without client JavaScript. Search, menus, copy controls, and appearance persistence enhance the static HTML. See Component styles for the boundary and responsive UI behavior.