@janga/norna 0.7.18 → 0.7.22

package/scripts/lib/project-config.mjs

@@ -51,6 +51,16 @@ const readEnum = (object, key, path, allowedValues, fallback, sourceLabel = site
 	return value;
 };
 
+const readBoolean = (object, key, path, fallback, sourceLabel = siteConfigLabel) => {
+	const value = object[key] ?? fallback;
+
+	if (typeof value !== 'boolean') {
+		throw new Error(`${path}.${key} must be true or false in ${sourceLabel}.`);
+	}
+
+	return value;
+};
+
 const readFontFamily = (object, key, path, fallback, sourceLabel = siteConfigLabel) => {
 	const value = object[key] ?? fallback;
 
@@ -184,26 +194,54 @@ const readSiteUrl = (config) => {
 const localeLabels = Object.freeze({
 	en: Object.freeze({
 		breadcrumb: 'Breadcrumb',
+		colorMode: 'Color mode',
+		colorModeDark: 'Dark',
+		colorModeLight: 'Light',
+		colorModeSystem: 'System',
+		displaySettings: 'Display',
+		focusReading: 'Focus reading',
+		readingWidth: 'Reading width',
+		readingWidthNarrow: 'Narrow',
+		readingWidthStandard: 'Standard',
+		readingWidthWide: 'Wide',
+		resetDisplaySettings: 'Reset',
 		dismissBanner: 'Dismiss notice',
 		built: 'Built',
 		images: 'Images',
+		imageCarousel: 'image carousel',
 		navigationChildren: 'Child pages',
 		navigationMenu: 'Menu',
+		nextImage: 'Next image',
 		note: 'Note',
 		pageNavigation: 'Page contents',
+		previousImage: 'Previous image',
 		siteBanners: 'Site notices',
 		siteNavigation: 'Pages',
 		skipToContent: 'Skip to content',
 	}),
 	sv: Object.freeze({
 		breadcrumb: 'Brödsmulor',
+		colorMode: 'Färgläge',
+		colorModeDark: 'Mörkt',
+		colorModeLight: 'Ljust',
+		colorModeSystem: 'System',
+		displaySettings: 'Visning',
+		focusReading: 'Fokuserad läsning',
+		readingWidth: 'Textbredd',
+		readingWidthNarrow: 'Smal',
+		readingWidthStandard: 'Standard',
+		readingWidthWide: 'Bred',
+		resetDisplaySettings: 'Återställ',
 		dismissBanner: 'Stäng meddelande',
 		built: 'Byggd',
 		images: 'Bilder',
+		imageCarousel: 'bildkarusell',
 		navigationChildren: 'Undersidor',
 		navigationMenu: 'Meny',
+		nextImage: 'Nästa bild',
 		note: 'Not',
 		pageNavigation: 'Sidinnehåll',
+		previousImage: 'Föregående bild',
 		siteBanners: 'Meddelanden',
 		siteNavigation: 'Sidor',
 		skipToContent: 'Hoppa till innehållet',
@@ -326,7 +364,7 @@ export const resolveThemeVisualConfig = (theme, sourceLabel = siteThemeLabel) =>
 	const rawTypographyConfig = assertObject(rawThemeConfig.typography ?? {}, 'typography', sourceLabel);
 	const resolvedContentSpacing = readEnum(rawLayoutConfig, 'contentSpacing', 'layout', contentSpacingNames, 'normal', sourceLabel);
 	const resolvedLayoutSpacingDefaults = contentSpacingProfiles[resolvedContentSpacing];
-	const shape = readEnum(rawThemeConfig, 'shape', 'theme', ['square', 'soft'], 'soft', sourceLabel);
+	const corners = readEnum(rawThemeConfig, 'corners', 'theme', ['square', 'rounded'], 'rounded', sourceLabel);
 
 	return Object.freeze({
 		layout: Object.freeze({
@@ -337,6 +375,8 @@ export const resolveThemeVisualConfig = (theme, sourceLabel = siteThemeLabel) =>
 				'layout.localNavigationGap',
 				sourceLabel,
 			),
+			noteWidth: readCssLengthValue(rawLayoutConfig.noteWidth ?? '12rem', 'layout.noteWidth', sourceLabel),
+			noteGap: readCssLengthValue(rawLayoutConfig.noteGap ?? '1.25rem', 'layout.noteGap', sourceLabel),
 			gutter: readResponsiveCssLength(rawLayoutConfig, 'gutter', 'layout', Object.freeze({
 				desktop: 'clamp(1.25rem, 4vw, 3rem)',
 				mobile: '1rem',
@@ -365,11 +405,11 @@ export const resolveThemeVisualConfig = (theme, sourceLabel = siteThemeLabel) =>
 		typography: Object.freeze({
 			fontFamily: readFontFamily(rawTypographyConfig, 'fontFamily', 'typography', defaultFontFamily, sourceLabel),
 		}),
-		shape: Object.freeze({
-			name: shape,
-			radiusSmall: shape === 'square' ? '0' : '2px',
-			radiusMedium: shape === 'square' ? '0' : '6px',
-			radiusLarge: shape === 'square' ? '0' : '8px',
+		corners: Object.freeze({
+			name: corners,
+			radiusSmall: corners === 'square' ? '0' : '2px',
+			radiusMedium: corners === 'square' ? '0' : '6px',
+			radiusLarge: corners === 'square' ? '0' : '8px',
 		}),
 	});
 };
@@ -386,6 +426,13 @@ export const resolveNavigationConfig = (config, sourceLabel = siteConfigLabel) =
 			'automatic',
 			sourceLabel,
 		),
+		sectionTracking: readBoolean(
+			rawNavigation,
+			'sectionTracking',
+			'navigation',
+			false,
+			sourceLabel,
+		),
 	});
 };
 

package/scripts/lib/schema-definitions.mjs

@@ -1,5 +1,6 @@
 import { z } from 'astro/zod';
 import { navigationModeNames } from './navigation-model.mjs';
+import { presentationPaletteNames } from './presentation-palette-metadata.mjs';
 import { themePresetNames } from './theme-presets.mjs';
 
 const isDateOnly = (value) => {
@@ -15,16 +16,33 @@ const textWidth = z.enum(['narrow', 'normal', 'wide']).describe('Maximum width o
 const headingWeight = z.union([z.literal(400), z.literal(500), z.literal(600), z.literal(700)]).describe('CSS font weight.');
 const typographyProfile = z.enum(['restrained', 'dense', 'reading', 'statement']).describe('Coordinated typography defaults. Omit this to use the selected preset.');
 const themePreset = z.enum(themePresetNames).describe('Complete Norna visual preset. Start here and add overrides only when needed.');
-const presentationPalette = z.enum(['dark', 'light', 'paper']).describe('Coordinated site color palette. Omit this to use the selected preset.');
+const presentationPalette = z.enum(presentationPaletteNames).describe('Coordinated site color palette. Every palette provides light and dark variants. Omit this to use the selected preset.');
+const themeColorMode = z.object({
+	default: z.enum(['system', 'light', 'dark']).optional().describe('Initial color mode. System follows the visitor\'s operating-system preference.'),
+}).strict().refine(
+	(value) => value.default !== undefined,
+	'Specify default.',
+).describe('Site-wide light and dark mode behaviour.');
+const readerControls = z.object({
+	colorMode: z.boolean().optional().describe('Let readers choose System, Light, or Dark color mode in the site-wide Display panel.'),
+	focusReading: z.boolean().optional().describe('Let readers temporarily hide navigation and other secondary page chrome while reading. Tree navigation always provides this control.'),
+}).strict().refine(
+	(value) => value.colorMode !== undefined || value.focusReading !== undefined,
+	'Specify colorMode, focusReading, or both.',
+).describe('Optional site-wide reader choices grouped with the always-available reading-width choice in the Display panel.');
 const spacingDensity = z.enum(['compact', 'normal', 'airy']).describe('Coordinated spacing density. Omit this to use the selected preset.');
 const contentSpacing = z.enum(['compact', 'normal', 'spacious']).describe('Vertical spacing between page sections and structured content blocks.');
-const backgroundPattern = z.enum(['uniform', 'alternating', 'cycling']).describe('How sections cycle through the active palette surfaces.');
-const shapeProfile = z.enum(['square', 'soft']).describe('Site-wide corner treatment for interface and content surfaces.');
+const backgroundPattern = z.enum(['uniform', 'alternating', 'accented']).describe('How coordinated backgrounds are assigned to H2 sections. Non-uniform patterns are unavailable with tree navigation.');
+const cornerTreatment = z.enum(['square', 'rounded']).describe('Site-wide corner treatment for navigation, cards and framed content.');
+const cardListWidth = z.enum(['text', 'narrow', 'normal', 'wide']).describe('Default maximum width for card lists. A width written in a norna-card-list block overrides this value.');
 const navigationMode = z.enum(navigationModeNames).describe('Site-wide navigation model. Automatic selects from the site structure.');
-const lineHeight = z.number()
-	.min(1, 'Use a unitless line height of at least 1.')
-	.max(3, 'Use a unitless line height of at most 3.')
-	.describe('Unitless line height between 1 and 3.');
+const createLineHeight = (minimum, role) => z.number()
+	.min(minimum, `Use a unitless ${role} line height of at least ${minimum}.`)
+	.max(3, `Use a unitless ${role} line height of at most 3.`)
+	.describe(`Unitless ${role} line height between ${minimum} and 3.`);
+const headingLineHeight = createLineHeight(1, 'heading');
+const bodyLineHeight = createLineHeight(1.4, 'body-text');
+const captionLineHeight = createLineHeight(1.25, 'caption');
 const cssLength = z.string().regex(
 	/^(?:0|(?:\d+(?:\.\d+)?|\.\d+)(?:px|rem|em|ch|lh))$/,
 	'Use a CSS length such as "0", "0.8em", "1rem", or "12px".',
@@ -59,10 +77,10 @@ const overrideResponsiveTextAlign = z.object({
 const commonTextPresentationOverride = {
 	align: overrideResponsiveTextAlign.optional().describe('Responsive text alignment override.'),
 	size: textSize.optional(),
-	lineHeight: lineHeight.optional(),
 };
 const headingPresentationOverride = z.object({
 	...commonTextPresentationOverride,
+	lineHeight: headingLineHeight.optional(),
 	weight: headingWeight.optional().describe('Heading font weight. Omit this to keep the profile value.'),
 	spacingBefore: cssLength.optional().describe('Vertical space before the heading.'),
 	spacingAfter: cssLength.optional().describe('Vertical space after the heading.'),
@@ -75,10 +93,12 @@ const headingLevelsPresentationOverride = z.object({
 }).strict().describe('Heading overrides by Markdown level.');
 const bodyPresentationOverride = z.object({
 	...commonTextPresentationOverride,
+	lineHeight: bodyLineHeight.optional(),
 	paragraphSpacing: cssLength.optional().describe('Vertical space between body paragraphs.'),
 }).strict().describe('Focused overrides for body text.');
 const captionPresentationOverride = z.object({
 	...commonTextPresentationOverride,
+	lineHeight: captionLineHeight.optional(),
 	spacingBefore: cssLength.optional().describe('Vertical space between an image and its caption.'),
 }).strict().describe('Focused overrides for image captions.');
 const typographyOverrides = z.object({
@@ -140,14 +160,24 @@ const themeImages = z.object({
 	maxAvailableWidthPercent: responsivePercent.optional().describe('Maximum percentage of available horizontal space used by managed images.'),
 	maxAvailableHeightPercent: responsivePercent.optional().describe('Maximum percentage of viewport height used by managed images.'),
 }).strict().describe('Optional defaults for managed image presentation.');
+const themeCardList = z.object({
+	width: cardListWidth,
+}).strict().describe('Site-wide card-list defaults.');
+const themeBlocks = z.object({
+	cardList: themeCardList.optional(),
+}).strict().refine(
+	(value) => value.cardList !== undefined,
+	'Specify cardList.',
+).describe('Optional site-wide defaults for structured Norna content blocks.');
 const configNavigation = z.object({
 	mode: navigationMode.optional().describe('Navigation model. Omit this to let Norna choose from the site structure.'),
+	sectionTracking: z.boolean().optional().default(false).describe('As the reader scrolls in tree navigation, mark the last H2 or H3 that has reached the reading area below the sticky header. The URL and keyboard focus do not change.'),
 }).strict().describe('Site-wide navigation behavior.');
 const themeSections = z.object({
-	backgroundPattern: backgroundPattern.optional().describe('Section background sequence. Omit this to keep the selected preset or inherited page setting.'),
+	backgroundPattern: backgroundPattern.optional().describe('Section background pattern. Alternating and accented create full-width bands with sections or top navigation; tree navigation requires uniform.'),
 }).strict().describe('Defaults for page section presentation.');
 const pageThemeSections = z.object({
-	backgroundPattern: backgroundPattern.optional().describe('Section background sequence inherited by descendant pages.'),
+	backgroundPattern: backgroundPattern.optional().describe('Section background sequence inherited by descendant pages. Non-uniform patterns are invalid with tree navigation.'),
 }).strict().refine(
 	(value) => value.backgroundPattern !== undefined,
 	'Specify backgroundPattern.',
@@ -159,7 +189,7 @@ const pageMetadata = z.object({
 	description: z.string().min(1).optional().describe('Optional page-specific meta description.'),
 }).strict().describe('Optional metadata for this homepage or additional page. The Markdown H1 supplies the page title.');
 const sitewideLogo = z.object({
-	height: visualCssLength.optional().describe('Displayed logo height. Width follows the intrinsic aspect ratio.'),
+	height: visualCssLength.optional().describe('Displayed logo height on wider screens. Omit it to use 2.6rem; narrow screens cap the height at 2.15rem. Width follows the intrinsic aspect ratio.'),
 }).strict().describe('Optional display settings for a convention-based navigation logo.');
 
 const banner = z.object({
@@ -192,9 +222,12 @@ const siteShape = {
 
 const themeVisualShape = {
 	preset: themePreset.optional().describe('Complete visual starting point. Add only the overrides the site actually needs.'),
-	shape: shapeProfile.optional().describe('Site-wide shape profile. Omit this to use the selected preset.'),
+	colorMode: themeColorMode.optional(),
+	readerControls: readerControls.optional(),
+	corners: cornerTreatment.optional().describe('Site-wide corner treatment. Omit this to use the selected preset.'),
 	layout: themeLayout.optional(),
 	images: themeImages.optional(),
+	blocks: themeBlocks.optional(),
 	typography: themeTypography.optional(),
 	palette: presentationPalette.optional(),
 	sections: themeSections.optional(),
@@ -212,8 +245,13 @@ const sitewideShape = {
 	footer: sitewideFooter.optional().describe('Site-wide footer content.'),
 };
 
+const categoryShape = {
+	label: z.string().trim().min(1).describe('Navigation label for this non-routable page category.'),
+};
+
 export const schemaTopLevelKeys = Object.freeze({
 	config: Object.freeze(Object.keys(configShape)),
+	category: Object.freeze(Object.keys(categoryShape)),
 	content: Object.freeze(Object.keys(siteShape)),
 	sitewide: Object.freeze(Object.keys(sitewideShape)),
 	theme: Object.freeze(Object.keys(themeVisualShape)),
@@ -222,6 +260,8 @@ export const schemaTopLevelKeys = Object.freeze({
 
 export const configSchema = z.object(configShape).strict()
 	.describe('Technical settings for one Norna site. Additional pages cannot provide technical configuration.');
+export const categorySchema = z.object(categoryShape).strict()
+	.describe('A non-routable navigation category containing child pages.');
 export const siteSchema = z.object(siteShape).strict()
 	.describe('Frontmatter for a homepage or additional page content.md file.');
 export const themeVisualSchema = z.object(themeVisualShape).strict()
@@ -231,6 +271,6 @@ export const pageThemeSchema = z.object(pageThemeShape).strict()
 		(value) => value.layout !== undefined || value.images !== undefined || value.sections !== undefined,
 		'Specify layout, images, sections, or a combination of them.',
 	)
-	.describe('Limited page presentation overrides inherited by descendant pages. Site colors, shapes, typography and navigation remain global.');
+	.describe('Limited page presentation overrides inherited by descendant pages. Site colors, corners, typography, content-block defaults and navigation remain global.');
 export const sitewideSchema = z.object(sitewideShape).strict()
 	.describe('Editorial content and optional navigation logo display settings shared by every page.');

package/scripts/lib/schema-editor-metadata.mjs

@@ -1,4 +1,5 @@
 import { documentationLink } from './documentation-links.mjs';
+import { presentationPaletteNames } from './presentation-palette-metadata.mjs';
 import { getSchemaValueDefinition } from './schema-value-definitions.mjs';
 
 const yamlExample = (source) => `\`\`\`yaml\n${source}\n\`\`\``;
@@ -121,7 +122,7 @@ const addSitewideLogoHelp = (jsonSchema) => {
 
 	logo.markdownDescription = [
 		yamlExample('logo:\n  height: 2rem'),
-		'`logo` optionally overrides the displayed height of the convention-based logo file. The logo links home, and its alternative text comes from the homepage Markdown H1. This setting does not enable or select the file.',
+		'`logo` optionally overrides the displayed height of the convention-based logo file. Without an override, Norna uses 2.6rem on wider screens and caps the logo at 2.15rem on narrow screens. The logo links home, and its alternative text comes from the homepage Markdown H1. This setting does not enable or select the file.',
 		documentationLink('Navigation logo filenames and placement', 'public-files.md', 'navigation-logo'),
 	].join('\n\n');
 	logo.properties.height.examples = ['2rem'];
@@ -164,6 +165,14 @@ const addConfigHelp = (jsonSchema) => {
 		'navigation',
 		['automatic', 'sections', 'top', 'tree'],
 	);
+	addFieldHelp(
+		jsonSchema,
+		'navigation.sectionTracking',
+		'navigation:\n  sectionTracking: true',
+		'configuration.md',
+		'navigationsectiontracking',
+		[true, false],
+	);
 	addHelp(jsonSchema, 'scrollBehavior', [
 		yamlExample('scrollBehavior: smooth'),
 		'Controls same-page anchor movement. `instant` is the default; `smooth` uses the browser\'s native smooth scrolling.',
@@ -179,14 +188,14 @@ const addThemeHelp = (jsonSchema) => {
 	].join('\n\n');
 	addHelp(jsonSchema, 'preset', [
 		yamlExample('preset: documentation'),
-		'Selects coordinated shapes, layout, image sizing, typography, palette and section backgrounds. This is the normal starting point for a theme.',
+		'Selects coordinated corners, layout, image sizing, content-block defaults, typography, palette and section backgrounds. This is the normal starting point for a theme.',
 		documentationLink('Compare theme presets', 'theme.md', 'theme-presets'),
 	]);
-	addHelp(jsonSchema, 'shape', [
-		yamlExample('shape: soft'),
+	addHelp(jsonSchema, 'corners', [
+		yamlExample('corners: rounded'),
 		'Chooses one consistent corner treatment for navigation, cards and framed content throughout the site.',
-		documentationLink('Theme reference', 'theme.md'),
-	], ['square', 'soft']);
+		documentationLink('Corner reference', 'theme.md', 'corners'),
+	], ['square', 'rounded']);
 	addHelp(jsonSchema, 'layout', [
 		yamlExample('layout:\n  contentSpacing: compact\n  textWidth: narrow'),
 		'Overrides text width, content spacing, page width and gutters after the selected preset.',
@@ -197,22 +206,88 @@ const addThemeHelp = (jsonSchema) => {
 		'Overrides the available width and height used by Norna-managed images.',
 		documentationLink('Image sizing reference', 'theme.md', 'image-sizing'),
 	]);
+	addHelp(jsonSchema, 'blocks', [
+		yamlExample('blocks:\n  cardList:\n    width: text'),
+		'Overrides preset defaults for structured Norna content blocks throughout the site. Options written directly in a Markdown block take priority.',
+		documentationLink('Content block defaults', 'theme.md', 'content-block-defaults'),
+	]);
+	addHelp(jsonSchema, 'blocks.cardList', [
+		yamlExample('blocks:\n  cardList:\n    width: text'),
+		'Sets site-wide defaults for card lists. A `width` option in an individual `norna-card-list` block overrides this setting.',
+		documentationLink('Content block defaults', 'theme.md', 'content-block-defaults'),
+	]);
+	addFieldHelp(
+		jsonSchema,
+		'blocks.cardList.width',
+		'blocks:\n  cardList:\n    width: text',
+		'theme.md',
+		'content-block-defaults',
+		['text', 'narrow', 'normal', 'wide'],
+	);
+	addSnippets(jsonSchema, 'blocks', [schemaSnippet({
+		label: 'Override content-block defaults',
+		body: {
+			cardList: {
+				width: '${1:text}',
+			},
+		},
+		description: 'Override a preset default for structured content blocks across the site.',
+		file: 'theme.md',
+		anchor: 'content-block-defaults',
+	})]);
 	addHelp(jsonSchema, 'typography', [
 		yamlExample('typography:\n  profile: reading\n  rhythm: normal'),
 		'Overrides the preset\'s font stack, typography profile, rhythm or individual text settings.',
 		documentationLink('Typography configuration reference', 'typography.md', 'configuration-shape'),
 	]);
 	addHelp(jsonSchema, 'palette', [
-		yamlExample('palette: paper'),
-		'Chooses a coordinated color system for the page frame, navigation, footer and section surfaces.',
-		documentationLink('Palette and section surfaces', 'theme.md', 'palette-and-section-surfaces'),
-	], ['dark', 'light', 'paper']);
+		yamlExample('palette: warm-paper'),
+		'Chooses the site color character. Every palette provides coordinated light and dark variants.',
+		documentationLink('Palette and color mode', 'theme.md', 'palette-and-color-mode'),
+	], presentationPaletteNames);
+	addHelp(jsonSchema, 'colorMode', [
+		yamlExample('colorMode:\n  default: system'),
+		'Controls the initial light or dark appearance. Enable the reader-facing choice under readerControls.',
+		documentationLink('Color mode', 'theme.md', 'color-mode'),
+	]);
+	addFieldHelp(jsonSchema, 'colorMode.default', 'colorMode:\n  default: system', 'theme.md', 'color-mode', ['system', 'light', 'dark']);
+	addSnippets(jsonSchema, 'colorMode', [schemaSnippet({
+		label: 'Set the initial color mode',
+		body: 'colorMode:\n  default: ${1:system}',
+		description: 'Follow the system color preference or choose a fixed initial appearance.',
+		file: 'theme.md',
+		anchor: 'color-mode',
+	})]);
+	addHelp(jsonSchema, 'readerControls', [
+		yamlExample('readerControls:\n  colorMode: true\n  focusReading: true'),
+		'Adds optional color-mode and focus-reading choices to the site-wide Display panel. Reading width is always available, and tree navigation always provides Focus reading.',
+		documentationLink('Reader Display controls', 'theme.md', 'reader-display-controls'),
+	]);
+	for (const [propertyPath, example] of [
+		['readerControls.colorMode', 'readerControls:\n  colorMode: true'],
+		['readerControls.focusReading', 'readerControls:\n  focusReading: true'],
+	]) {
+		addFieldHelp(
+			jsonSchema,
+			propertyPath,
+			example,
+			'theme.md',
+			'reader-display-controls',
+		);
+	}
+	addSnippets(jsonSchema, 'readerControls', [schemaSnippet({
+		label: 'Configure the Display panel',
+		body: 'readerControls:\n  colorMode: ${1:true}\n  focusReading: ${2:true}',
+		description: 'Offer optional color-mode and focus-reading choices alongside the universal reading-width control. Tree navigation always provides Focus reading.',
+		file: 'theme.md',
+		anchor: 'reader-display-controls',
+	})]);
 	addHelp(jsonSchema, 'sections', [
 		yamlExample('sections:\n  backgroundPattern: alternating'),
-		'Chooses whether section backgrounds stay uniform, alternate between two surfaces or cycle through three.',
-		documentationLink('Palette and section surfaces', 'theme.md', 'palette-and-section-surfaces'),
+		'Chooses whether H2 section backgrounds stay uniform, alternate between two backgrounds or move from base to soft to emphasis and back through soft. Non-uniform patterns are available with sections and top navigation; tree navigation requires uniform.',
+		documentationLink('Section backgrounds', 'theme.md', 'section-backgrounds'),
 	]);
-	addFieldHelp(jsonSchema, 'sections.backgroundPattern', 'sections:\n  backgroundPattern: alternating', 'theme.md', 'palette-and-section-surfaces', ['uniform', 'alternating', 'cycling']);
+	addFieldHelp(jsonSchema, 'sections.backgroundPattern', 'sections:\n  backgroundPattern: alternating', 'theme.md', 'section-backgrounds', ['uniform', 'alternating', 'accented']);
 
 	const layoutFields = [
 		['layout.contentSpacing', 'layout:\n  contentSpacing: compact'],
@@ -378,19 +453,19 @@ const addThemeHelp = (jsonSchema) => {
 const addPageThemeHelp = (jsonSchema) => {
 	jsonSchema.markdownDescription = [
 		yamlExample('layout:\n  textWidth: narrow\n  contentSpacing: compact'),
-		'A page theme may adjust only page layout, managed-image sizing and the section background pattern. Descendant pages inherit these values. Site colors, shapes and typography stay consistent.',
+		'A limited theme in a page or category directory may adjust only page layout, managed-image sizing and the section background pattern. Descendant pages inherit these values. Tree navigation requires a uniform section background. Site colors, corners, typography, content-block defaults and navigation stay consistent.',
 		documentationLink('Page theme reference', 'theme.md', 'page-themes'),
 	].join('\n\n');
 	addHelp(jsonSchema, 'layout', [
 		yamlExample('layout:\n  textWidth: narrow\n  contentSpacing: compact'),
-		'Adjusts body-text line length and vertical content spacing for this page and its descendants.',
+		'Adjusts body-text line length and vertical content spacing for pages below this directory.',
 		documentationLink('Page theme reference', 'theme.md', 'page-themes'),
 	]);
 	addFieldHelp(jsonSchema, 'layout.textWidth', 'layout:\n  textWidth: narrow', 'theme.md', 'page-themes', ['narrow', 'normal', 'wide']);
 	addFieldHelp(jsonSchema, 'layout.contentSpacing', 'layout:\n  contentSpacing: compact', 'theme.md', 'page-themes', ['compact', 'normal', 'spacious']);
 	addHelp(jsonSchema, 'images', [
 		yamlExample('images:\n  width: 900px'),
-		'Adjusts managed-image sizing for this page and its descendants.',
+		'Adjusts managed-image sizing for pages below this directory.',
 		documentationLink('Image sizing reference', 'theme.md', 'image-sizing'),
 	]);
 	const imageFields = [
@@ -407,10 +482,10 @@ const addPageThemeHelp = (jsonSchema) => {
 	}
 	addHelp(jsonSchema, 'sections', [
 		yamlExample('sections:\n  backgroundPattern: alternating'),
-		'Adjusts the section background sequence for this page and its descendants.',
+		'Adjusts the H2 section background pattern for pages below this directory. Alternating and accented create full-width bands but are invalid when navigation resolves to tree.',
 		documentationLink('Page theme reference', 'theme.md', 'page-themes'),
 	]);
-	addFieldHelp(jsonSchema, 'sections.backgroundPattern', 'sections:\n  backgroundPattern: alternating', 'theme.md', 'page-themes', ['uniform', 'alternating', 'cycling']);
+	addFieldHelp(jsonSchema, 'sections.backgroundPattern', 'sections:\n  backgroundPattern: alternating', 'theme.md', 'page-themes', ['uniform', 'alternating', 'accented']);
 };
 
 const addSitewideHelp = (jsonSchema) => {
@@ -505,8 +580,22 @@ const addContentHelp = (jsonSchema) => {
 	addFieldHelp(jsonSchema, 'navigation.listed', 'navigation:\n  listed: false', 'pages.md', 'navigation', [true, false]);
 };
 
+const addCategoryHelp = (jsonSchema) => {
+	jsonSchema.markdownDescription = [
+		yamlExample('label: Guides'),
+		'`category.yaml` creates a navigation-only group for child pages. It has no page content and produces no URL of its own.',
+		documentationLink('Navigation category reference', 'pages.md', 'navigation-categories'),
+	].join('\n\n');
+	addHelp(jsonSchema, 'label', [
+		yamlExample('label: Guides'),
+		'The category label shown in global navigation, tree navigation, mobile navigation, and breadcrumbs.',
+		documentationLink('Navigation category reference', 'pages.md', 'navigation-categories'),
+	]);
+};
+
 export const applySchemaEditorMetadata = (filename, jsonSchema) => {
 	addValueDescriptions(jsonSchema);
+	if (filename === 'category.schema.json') addCategoryHelp(jsonSchema);
 	if (filename === 'config.schema.json') {
 		addLanguageSuggestions(jsonSchema);
 		addConfigHelp(jsonSchema);

package/scripts/lib/schema-value-definitions.mjs

@@ -2,6 +2,10 @@ import {
 	getThemePresetMetadata,
 	themePresetNames,
 } from './theme-presets.mjs';
+import {
+	getPresentationPaletteMetadata,
+	presentationPaletteNames,
+} from './presentation-palette-metadata.mjs';
 
 const option = (title, description) => Object.freeze({ title, description });
 const definition = (values, options) => Object.freeze({
@@ -44,6 +48,12 @@ export const schemaValueDefinitions = Object.freeze([
 		normal: option('Normal', 'Use the balanced default line length.'),
 		wide: option('Wide', 'Allow body text to use more horizontal space.'),
 	}),
+	definition(['text', 'narrow', 'normal', 'wide'], {
+		text: option('Text width', 'Match the active body-text width, including a reader-selected reading width.'),
+		narrow: option('Narrow', 'Limit the complete card list to at most 48rem.'),
+		normal: option('Normal', 'Limit the complete card list to at most 56rem.'),
+		wide: option('Wide', 'Allow the complete card list to use the available page-layout width.'),
+	}),
 	definition([400, 500, 600, 700], {
 		400: option('Regular', 'Use regular font weight.'),
 		500: option('Medium', 'Use medium font weight.'),
@@ -56,19 +66,23 @@ export const schemaValueDefinitions = Object.freeze([
 		reading: option('Reading', 'Reading-focused typography with narrower text and relaxed line height.'),
 		statement: option('Statement', 'Stronger headings and tighter body rhythm for short, expressive pages.'),
 	}),
-	definition(['dark', 'light', 'paper'], {
-		dark: option('Dark', 'Black page and section surfaces with light text.'),
-		light: option('Light', 'White and cool light surfaces with dark text.'),
-		paper: option('Paper', 'Warm off-white surfaces with dark text.'),
+	definition(presentationPaletteNames, Object.fromEntries(presentationPaletteNames.map((name) => {
+		const metadata = getPresentationPaletteMetadata(name);
+		return [name, option(metadata.title, `${metadata.description} Includes coordinated light and dark variants.`)];
+	}))),
+	definition(['system', 'light', 'dark'], {
+		system: option('System', 'Follow the visitor\'s operating-system light or dark preference.'),
+		light: option('Light', 'Start with the palette\'s light appearance.'),
+		dark: option('Dark', 'Start with the palette\'s dark appearance.'),
 	}),
-	definition(['square', 'soft'], {
+	definition(['square', 'rounded'], {
 		square: option('Square', 'Use square corners for navigation, cards and framed content.'),
-		soft: option('Soft', 'Use restrained rounded corners consistently across the site.'),
+		rounded: option('Rounded', 'Use restrained rounded corners consistently across the site.'),
 	}),
-	definition(['uniform', 'alternating', 'cycling'], {
-		uniform: option('Uniform', 'Use the palette base surface for every section.'),
-		alternating: option('Alternating', 'Alternate between the palette base and soft surfaces.'),
-		cycling: option('Cycling', 'Cycle through the palette base, soft and emphasis surfaces.'),
+	definition(['uniform', 'alternating', 'accented'], {
+		uniform: option('Uniform', 'Use the normal page background for every H2 section. Tree navigation requires this pattern.'),
+		alternating: option('Alternating', 'Alternate normal and subtly contrasting full-width section backgrounds. Available with sections and top navigation.'),
+		accented: option('Accented', 'Move through base, soft, emphasis and soft full-width section backgrounds before repeating. Available with sections and top navigation.'),
 	}),
 	definition(['compact', 'normal', 'spacious'], {
 		compact: option('Compact', 'Use restrained spacing between sections and structured blocks.'),