@janga/norna 0.7.17 → 0.7.18

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

@@ -151,6 +151,19 @@ const addConfigHelp = (jsonSchema) => {
 		'Sets the page language and selects Norna\'s built-in English or Swedish interface text. The default is `en`.',
 		documentationLink('Language reference', 'configuration.md', 'language'),
 	], ['en', 'sv', 'en-GB', 'sv-SE']);
+	addHelp(jsonSchema, 'navigation', [
+		yamlExample('navigation:\n  mode: automatic'),
+		'Sets one navigation model for the complete site. `automatic` selects from the page hierarchy.',
+		documentationLink('Navigation reference', 'pages.md', 'navigation'),
+	]);
+	addFieldHelp(
+		jsonSchema,
+		'navigation.mode',
+		'navigation:\n  mode: automatic',
+		'pages.md',
+		'navigation',
+		['automatic', 'sections', 'top', 'tree'],
+	);
 	addHelp(jsonSchema, 'scrollBehavior', [
 		yamlExample('scrollBehavior: smooth'),
 		'Controls same-page anchor movement. `instant` is the default; `smooth` uses the browser\'s native smooth scrolling.',
@@ -166,25 +179,17 @@ const addThemeHelp = (jsonSchema) => {
 	].join('\n\n');
 	addHelp(jsonSchema, 'preset', [
 		yamlExample('preset: documentation'),
-		'Selects coordinated navigation, layout, image sizing, typography, palette and section surfaces. This is the normal starting point for a theme.',
+		'Selects coordinated shapes, layout, image sizing, typography, palette and section backgrounds. This is the normal starting point for a theme.',
 		documentationLink('Compare theme presets', 'theme.md', 'theme-presets'),
 	]);
-	addHelp(jsonSchema, 'navigation', [
-		yamlExample('navigation:\n  mode: automatic'),
-		'Sets the site-wide navigation model. Only the root theme may override this preset value.',
+	addHelp(jsonSchema, 'shape', [
+		yamlExample('shape: soft'),
+		'Chooses one consistent corner treatment for navigation, cards and framed content throughout the site.',
 		documentationLink('Theme reference', 'theme.md'),
-	]);
-	addFieldHelp(
-		jsonSchema,
-		'navigation.mode',
-		'navigation:\n  mode: automatic',
-		'theme.md',
-		undefined,
-		['automatic', 'sections', 'top', 'tree'],
-	);
+	], ['square', 'soft']);
 	addHelp(jsonSchema, 'layout', [
-		yamlExample('layout:\n  density: compact\n  pageWidth: 72rem'),
-		'Overrides page width, gutters and structural spacing after the selected preset.',
+		yamlExample('layout:\n  contentSpacing: compact\n  textWidth: narrow'),
+		'Overrides text width, content spacing, page width and gutters after the selected preset.',
 		documentationLink('Layout reference', 'theme.md', 'layout'),
 	]);
 	addHelp(jsonSchema, 'images', [
@@ -202,14 +207,16 @@ const addThemeHelp = (jsonSchema) => {
 		'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']);
-	addHelp(jsonSchema, 'sectionSurfaces', [
-		yamlExample('sectionSurfaces: [base, soft, emphasis]'),
-		'Lists one to three semantic surfaces. Norna cycles through them in section order; omit this field to keep the preset sequence.',
+	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'),
-	], [['base'], ['base', 'soft'], ['base', 'soft', 'emphasis']]);
+	]);
+	addFieldHelp(jsonSchema, 'sections.backgroundPattern', 'sections:\n  backgroundPattern: alternating', 'theme.md', 'palette-and-section-surfaces', ['uniform', 'alternating', 'cycling']);
 
 	const layoutFields = [
-		['layout.density', 'layout:\n  density: compact'],
+		['layout.contentSpacing', 'layout:\n  contentSpacing: compact'],
+		['layout.textWidth', 'layout:\n  textWidth: narrow'],
 		['layout.pageWidth', 'layout:\n  pageWidth: 72rem'],
 		['layout.gutter', 'layout:\n  gutter:\n    desktop: clamp(1.25rem, 4vw, 3rem)\n    mobile: 1rem'],
 		['layout.gutter.desktop', 'layout:\n  gutter:\n    desktop: clamp(1.25rem, 4vw, 3rem)'],
@@ -301,9 +308,9 @@ const addThemeHelp = (jsonSchema) => {
 		['typography.fontFamily', 'typography:\n  fontFamily: "Arial, sans-serif"'],
 		['typography.profile', 'typography:\n  profile: reading'],
 		['typography.rhythm', 'typography:\n  rhythm: normal'],
-		['typography.overrides', 'typography:\n  overrides:\n    body:\n      width: narrow'],
+		['typography.overrides', 'typography:\n  overrides:\n    body:\n      lineHeight: 1.55'],
 		['typography.overrides.headings', 'typography:\n  overrides:\n    headings:\n      h2:\n        size: medium'],
-		['typography.overrides.body', 'typography:\n  overrides:\n    body:\n      width: narrow'],
+		['typography.overrides.body', 'typography:\n  overrides:\n    body:\n      lineHeight: 1.55'],
 		['typography.overrides.caption', 'typography:\n  overrides:\n    caption:\n      size: small'],
 	];
 	for (const [propertyPath, example] of typographyFields) {
@@ -346,7 +353,6 @@ const addThemeHelp = (jsonSchema) => {
 		textOverrideHelp(propertyPath, `${prefix}\n      `, true);
 	}
 	textOverrideHelp('typography.overrides.body', 'typography:\n  overrides:\n    body:');
-	addFieldHelp(jsonSchema, 'typography.overrides.body.width', 'typography:\n  overrides:\n    body:\n      width: narrow', 'typography.md', 'configuration-shape');
 	addFieldHelp(jsonSchema, 'typography.overrides.body.paragraphSpacing', 'typography:\n  overrides:\n    body:\n      paragraphSpacing: 1em', 'typography.md', 'configuration-shape');
 	textOverrideHelp('typography.overrides.caption', 'typography:\n  overrides:\n    caption:');
 	addFieldHelp(jsonSchema, 'typography.overrides.caption.spacingBefore', 'typography:\n  overrides:\n    caption:\n      spacingBefore: 0.5em', 'typography.md', 'configuration-shape');
@@ -359,9 +365,8 @@ const addThemeHelp = (jsonSchema) => {
 					weight: '${2:600}',
 				},
 			},
-			body: {
-				width: '${3:narrow}',
-				lineHeight: '${4:1.55}',
+		body: {
+				lineHeight: '${3:1.55}',
 			},
 		},
 		description: 'Start a focused set of heading and body-text overrides.',
@@ -370,6 +375,44 @@ 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.',
+		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.',
+		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.',
+		documentationLink('Image sizing reference', 'theme.md', 'image-sizing'),
+	]);
+	const imageFields = [
+		['images.width', 'images:\n  width: 900px'],
+		['images.maxAvailableWidthPercent', 'images:\n  maxAvailableWidthPercent:\n    desktop: 100\n    mobile: 100'],
+		['images.maxAvailableWidthPercent.desktop', 'images:\n  maxAvailableWidthPercent:\n    desktop: 100'],
+		['images.maxAvailableWidthPercent.mobile', 'images:\n  maxAvailableWidthPercent:\n    mobile: 100'],
+		['images.maxAvailableHeightPercent', 'images:\n  maxAvailableHeightPercent:\n    desktop: 74\n    mobile: 68'],
+		['images.maxAvailableHeightPercent.desktop', 'images:\n  maxAvailableHeightPercent:\n    desktop: 74'],
+		['images.maxAvailableHeightPercent.mobile', 'images:\n  maxAvailableHeightPercent:\n    mobile: 68'],
+	];
+	for (const [propertyPath, example] of imageFields) {
+		addFieldHelp(jsonSchema, propertyPath, example, 'theme.md', 'image-sizing');
+	}
+	addHelp(jsonSchema, 'sections', [
+		yamlExample('sections:\n  backgroundPattern: alternating'),
+		'Adjusts the section background sequence for this page and its descendants.',
+		documentationLink('Page theme reference', 'theme.md', 'page-themes'),
+	]);
+	addFieldHelp(jsonSchema, 'sections.backgroundPattern', 'sections:\n  backgroundPattern: alternating', 'theme.md', 'page-themes', ['uniform', 'alternating', 'cycling']);
+};
+
 const addSitewideHelp = (jsonSchema) => {
 	jsonSchema.markdownDescription = [
 		yamlExample('footer:\n  copyrightMessage: Copyright Example Owner.'),
@@ -469,6 +512,7 @@ export const applySchemaEditorMetadata = (filename, jsonSchema) => {
 		addConfigHelp(jsonSchema);
 	}
 	if (filename === 'theme.schema.json') addThemeHelp(jsonSchema);
+	if (filename === 'page-theme.schema.json') addPageThemeHelp(jsonSchema);
 	if (filename === 'sitewide-content.schema.json') addSitewideHelp(jsonSchema);
 	if (filename === 'content-frontmatter.schema.json') addContentHelp(jsonSchema);
 	return jsonSchema;

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

@@ -61,6 +61,20 @@ export const schemaValueDefinitions = Object.freeze([
 		light: option('Light', 'White and cool light surfaces with dark text.'),
 		paper: option('Paper', 'Warm off-white surfaces with dark text.'),
 	}),
+	definition(['square', 'soft'], {
+		square: option('Square', 'Use square corners for navigation, cards and framed content.'),
+		soft: option('Soft', '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(['compact', 'normal', 'spacious'], {
+		compact: option('Compact', 'Use restrained spacing between sections and structured blocks.'),
+		normal: option('Normal', 'Use balanced content spacing.'),
+		spacious: option('Spacious', 'Use more expansive spacing between sections and structured blocks.'),
+	}),
 	definition(['base', 'soft', 'emphasis'], {
 		base: option('Base', 'Use the palette\'s normal page surface.'),
 		soft: option('Soft', 'Use the palette\'s subtle contrasting surface.'),

package/scripts/lib/site-content.mjs

@@ -2,10 +2,9 @@ import { access, readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import {
 	siteContentLabel,
-	siteContentPath,
 	siteDir,
 	siteDirLabel,
-	siteImagesDir,
+	homePageDirectory,
 	siteImagesLabel,
 	sitePagesDir,
 	sitePagesLabel,
@@ -25,7 +24,7 @@ const knownConfigTopLevelFrontmatterKeys = new Set(schemaTopLevelKeys.config);
 const knownContentTopLevelFrontmatterKeys = new Set(schemaTopLevelKeys.content);
 const knownThemeTopLevelFrontmatterKeys = new Set(schemaTopLevelKeys.theme);
 const knownPageThemeTopLevelFrontmatterKeys = new Set(
-	[...knownThemeTopLevelFrontmatterKeys].filter((key) => key !== 'navigation'),
+	schemaTopLevelKeys.pageTheme,
 );
 const knownSitewideTopLevelFrontmatterKeys = new Set(schemaTopLevelKeys.sitewide);
 const knownNestedFrontmatterKeys = new Set([
@@ -35,7 +34,7 @@ const knownNestedFrontmatterKeys = new Set([
 	'blockGap',
 	'caption',
 	'carousel',
-	'density',
+	'contentSpacing',
 	'desktop',
 	'fontFamily',
 	'from',
@@ -67,11 +66,14 @@ const knownNestedFrontmatterKeys = new Set([
 	'profile',
 	'rhythm',
 	'sectionGap',
-	'sectionSurfaces',
+	'backgroundPattern',
+	'sections',
+	'shape',
 	'size',
 	'spacingAfter',
 	'spacingBefore',
 	'theme',
+	'textWidth',
 	'typography',
 	'until',
 	'visible',
@@ -83,6 +85,18 @@ export const toPosixPath = (filePath) => filePath.split(path.sep).join('/');
 const fileExists = async (filePath) => access(filePath).then(() => true, () => false);
 
 export const getContentFiles = async () => {
+	const legacyContentPath = path.join(siteDir, 'content.md');
+	const legacyImagesPath = path.join(siteDir, 'images');
+	const legacyPaths = [];
+	if (await fileExists(legacyContentPath)) legacyPaths.push(`${siteDirLabel}/content.md`);
+	if (await fileExists(legacyImagesPath)) legacyPaths.push(`${siteDirLabel}/images`);
+	if (legacyPaths.length > 0) {
+		throw new Error([
+			`The old root-page structure is no longer supported: ${legacyPaths.join(', ')}.`,
+			`Move the homepage content to ${sitePagesLabel}/${homePageDirectory}/content.md and its images to ${sitePagesLabel}/${homePageDirectory}/images/.`,
+		].join('\n'));
+	}
+
 	const legacyRoutesDir = path.join(siteDir, 'routes');
 	const legacyRoutes = await readdir(legacyRoutesDir).catch((error) => {
 		if (error?.code === 'ENOENT') return null;
@@ -92,22 +106,7 @@ export const getContentFiles = async () => {
 		throw new Error(`${siteDirLabel}/routes is no longer supported. Rename it to ${sitePagesLabel} and use NNN-page-id directory names.`);
 	}
 
-	const contentFiles = [{
-		contentLabel: siteContentLabel,
-		contentPath: siteContentPath,
-		imagesDir: siteImagesDir,
-		imagesLabel: siteImagesLabel,
-		isHome: true,
-		pageDirectory: null,
-		pageDirectories: [],
-		pageId: null,
-		pageIds: [],
-		pageOrder: 0,
-		pageOrders: [],
-		pagePath: '',
-		parentPagePath: null,
-		depth: 0,
-	}];
+	const contentFiles = [];
 	const collectPageContentFiles = async (pagesDir, pagesLabel, parentPageDirectory = '') => {
 		const pageEntries = await readdir(pagesDir, { withFileTypes: true }).catch((error) => {
 		if (error?.code === 'ENOENT') {
@@ -138,16 +137,36 @@ export const getContentFiles = async () => {
 				continue;
 			}
 			const pageMetadata = parsePageDirectoryPath(pageDirectory, pageLabel);
+			const isHome = pageDirectory === homePageDirectory;
 
 			contentFiles.push({
 				contentLabel: `${pageLabel}/content.md`,
 				contentPath: pageContentPath,
 				imagesDir: path.join(pageDir, 'images'),
 				imagesLabel: `${pageLabel}/images`,
-				isHome: false,
+				isHome,
 				...pageMetadata,
+				pagePath: isHome ? '' : pageMetadata.pagePath,
+				parentPagePath: isHome ? null : pageMetadata.parentPagePath,
 			});
 
+			if (isHome) {
+				const homePagesDir = path.join(pageDir, 'pages');
+				const homeChildEntries = await readdir(homePagesDir, { withFileTypes: true }).catch((error) => {
+					if (error?.code === 'ENOENT') return [];
+					throw error;
+				});
+				const homeChildDirectories = homeChildEntries.filter((childEntry) => childEntry.isDirectory());
+				if (homeChildDirectories.length > 0) {
+					throw new Error([
+						`${pageLabel} is the homepage and cannot contain child pages.`,
+						`Move these page directories beside ${homePageDirectory} under ${sitePagesLabel}/, or below another non-home page:`,
+						...homeChildDirectories.map(({ name }) => `- ${pageLabel}/pages/${name}`),
+					].join('\n'));
+				}
+				continue;
+			}
+
 			await collectPageContentFiles(
 				path.join(pageDir, 'pages'),
 				`${pageLabel}/pages`,
@@ -157,6 +176,9 @@ export const getContentFiles = async () => {
 	};
 
 	await collectPageContentFiles(sitePagesDir, sitePagesLabel);
+	if (!contentFiles.some(({ isHome }) => isHome)) {
+		throw new Error(`Homepage content is missing. Create ${siteContentLabel}.`);
+	}
 
 	return contentFiles;
 };
@@ -303,9 +325,12 @@ export const validateFrontmatterStructure = (frontmatter, addIssue, {
 			fix = 'Put local image references in norna-image-stack or norna-image-carousel blocks in the Markdown body.';
 		} else if (fileKind === 'content' && knownThemeTopLevelFrontmatterKeys.has(key)) {
 			fix = `Move "${key}:" to theme.yaml. Visual settings do not belong in content frontmatter.`;
-		} else if (fileKind === 'page theme' && key === 'navigation') {
-			message = `Frontmatter line ${lineNumber}: page themes may not define navigation.`;
-			fix = 'Set the site-wide navigation mode under "navigation:" in the root theme.yaml.';
+		} else if ((fileKind === 'theme' || fileKind === 'page theme') && key === 'navigation') {
+			message = `Frontmatter line ${lineNumber}: navigation is technical, site-wide configuration and does not belong in ${fileKind}. Set it in config.yaml.`;
+			fix = 'Set the navigation mode under "navigation:" in config.yaml.';
+		} else if (fileKind === 'page theme' && ['preset', 'shape', 'palette', 'typography'].includes(key)) {
+			message = `Frontmatter line ${lineNumber}: page themes may not define site-wide visual identity through "${key}".`;
+			fix = `Move "${key}:" to the root theme.yaml. Page themes may set only layout.textWidth, layout.contentSpacing, images, and sections.backgroundPattern.`;
 		} else if ((fileKind === 'theme' || fileKind === 'page theme') && ['logo', 'site'].includes(key)) {
 			message = `Frontmatter line ${lineNumber}: ${fileKind} may not define navigation logo settings. Optional logo display settings belong under "logo:" in ${sitewideContentLabel}.`;
 			fix = `Move only the logo display settings under "logo:" in ${sitewideContentLabel}; the homepage Markdown H1 supplies navigation text and logo alternative text.`;

package/scripts/lib/site-conventions.mjs

@@ -0,0 +1 @@
+export const homePageDirectory = '000-home';

package/scripts/lib/site-paths.mjs

@@ -1,10 +1,12 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { homePageDirectory } from './site-conventions.mjs';
 
 const siteDirectoryEnvName = 'NORNA_SITE_DIR';
 const invocationRootEnvName = 'NORNA_INVOCATION_ROOT';
 const defaultSiteDirectory = 'site';
+export { homePageDirectory };
 
 const currentFile = fileURLToPath(import.meta.url);
 const currentDirectory = path.dirname(currentFile);
@@ -23,7 +25,10 @@ export const invocationRoot = configuredInvocationRoot
 const hasSiteFilesInDirectory = (siteDir) => {
 	return (
 		existsSync(path.join(siteDir, 'config.yaml'))
-		&& existsSync(path.join(siteDir, 'content.md'))
+		&& (
+			existsSync(path.join(siteDir, 'pages', homePageDirectory, 'content.md'))
+			|| existsSync(path.join(siteDir, 'content.md'))
+		)
 	);
 };
 
@@ -116,10 +121,11 @@ const getPathLabel = (filePath) => {
 export const siteDir = resolvedSitePaths.siteDir;
 export const siteConfigPath = path.join(siteDir, 'config.yaml');
 export const siteThemePath = path.join(siteDir, 'theme.yaml');
-export const siteContentPath = path.join(siteDir, 'content.md');
 export const sitewideContentPath = path.join(siteDir, 'sitewide-content.yaml');
-export const siteImagesDir = path.join(siteDir, 'images');
 export const sitePagesDir = path.join(siteDir, 'pages');
+export const siteHomePageDir = path.join(sitePagesDir, homePageDirectory);
+export const siteContentPath = path.join(siteHomePageDir, 'content.md');
+export const siteImagesDir = path.join(siteHomePageDir, 'images');
 export const sitePublicDir = path.join(siteDir, 'public');
 export const siteStateDir = path.join(siteDir, '.norna');
 export const astroPublicDir = path.join(siteStateDir, 'public');

package/scripts/lib/theme-config.mjs

@@ -12,6 +12,7 @@ import {
 } from './site-paths.mjs';
 import { resolveThemePresentation } from './presentation.mjs';
 import { resolveThemeConfig } from './theme-presets.mjs';
+import { pageThemeSchema, themeVisualSchema } from './schema-definitions.mjs';
 import { parseYamlConfig } from './yaml-config.mjs';
 
 export const readThemeConfig = async () => {
@@ -23,6 +24,7 @@ export const readThemeConfig = async () => {
 		throw error;
 	});
 	const config = parseYamlConfig(themeFile, siteThemeLabel, {
+		schema: themeVisualSchema,
 		validateStructure: validateThemeYamlStructure,
 	});
 	resolveThemeConfig(config, siteThemeLabel);
@@ -64,10 +66,9 @@ export const validatePageThemeFiles = async () => {
 	for (const file of files) {
 		const source = await readFile(file.path, 'utf8');
 		const config = parseYamlConfig(source, file.label, {
+			schema: pageThemeSchema,
 			validateStructure: validatePageThemeYamlStructure,
 		});
-		resolveThemeConfig(config, file.label);
-		resolveThemePresentation(config, file.label);
 
 		configs.push({ ...file, config });
 	}

package/scripts/lib/theme-presets.mjs

@@ -2,10 +2,12 @@ import { mergeDeep } from './typography.mjs';
 
 const themePresetConfigurations = Object.freeze({
 	portfolio: Object.freeze({
-		navigation: { mode: 'automatic' },
+		shape: 'square',
 		layout: {
-			density: 'normal',
+			contentSpacing: 'normal',
+			textWidth: 'wide',
 			pageWidth: '1240px',
+			localNavigationGap: 'clamp(1.5rem, 3vw, 3rem)',
 			gutter: {
 				desktop: 'clamp(1.25rem, 4vw, 3rem)',
 				mobile: '1rem',
@@ -22,13 +24,15 @@ const themePresetConfigurations = Object.freeze({
 			rhythm: 'normal',
 		},
 		palette: 'dark',
-		sectionSurfaces: ['base'],
+		sections: { backgroundPattern: 'uniform' },
 	}),
 	documentation: Object.freeze({
-		navigation: { mode: 'automatic' },
+		shape: 'soft',
 		layout: {
-			density: 'compact',
+			contentSpacing: 'compact',
+			textWidth: 'narrow',
 			pageWidth: '1240px',
+			localNavigationGap: 'clamp(1.5rem, 3vw, 3rem)',
 			gutter: {
 				desktop: 'clamp(1.25rem, 4vw, 3rem)',
 				mobile: '1rem',
@@ -45,13 +49,15 @@ const themePresetConfigurations = Object.freeze({
 			rhythm: 'compact',
 		},
 		palette: 'paper',
-		sectionSurfaces: ['base', 'soft'],
+		sections: { backgroundPattern: 'alternating' },
 	}),
 	project: Object.freeze({
-		navigation: { mode: 'automatic' },
+		shape: 'soft',
 		layout: {
-			density: 'compact',
+			contentSpacing: 'compact',
+			textWidth: 'normal',
 			pageWidth: '1120px',
+			localNavigationGap: 'clamp(1.5rem, 3vw, 3rem)',
 			gutter: {
 				desktop: 'clamp(1.25rem, 4vw, 3rem)',
 				mobile: '1rem',
@@ -68,13 +74,15 @@ const themePresetConfigurations = Object.freeze({
 			rhythm: 'compact',
 		},
 		palette: 'light',
-		sectionSurfaces: ['base', 'soft'],
+		sections: { backgroundPattern: 'alternating' },
 	}),
 	statement: Object.freeze({
-		navigation: { mode: 'automatic' },
+		shape: 'square',
 		layout: {
-			density: 'airy',
+			contentSpacing: 'spacious',
+			textWidth: 'normal',
 			pageWidth: '1280px',
+			localNavigationGap: 'clamp(1.5rem, 3vw, 3rem)',
 			gutter: {
 				desktop: 'clamp(1.5rem, 5vw, 4rem)',
 				mobile: '1rem',
@@ -91,7 +99,7 @@ const themePresetConfigurations = Object.freeze({
 			rhythm: 'airy',
 		},
 		palette: 'paper',
-		sectionSurfaces: ['base', 'emphasis'],
+		sections: { backgroundPattern: 'cycling' },
 	}),
 });
 
@@ -158,6 +166,30 @@ export const resolveThemeConfig = (theme = {}, sourceLabel = 'theme.yaml') => {
 	};
 };
 
+const mergePageThemePart = (base, override, keys) => Object.fromEntries(keys
+	.filter((key) => override?.[key] !== undefined || base?.[key] !== undefined)
+	.map((key) => [key, override?.[key] ?? base?.[key]]));
+
+export const mergePageThemeConfig = (base = {}, override = {}) => ({
+	...base,
+	layout: {
+		...(base.layout ?? {}),
+		...mergePageThemePart(base.layout, override.layout, ['contentSpacing', 'textWidth']),
+	},
+	images: {
+		...(base.images ?? {}),
+		...mergePageThemePart(base.images, override.images, [
+			'width',
+			'maxAvailableWidthPercent',
+			'maxAvailableHeightPercent',
+		]),
+	},
+	sections: {
+		...(base.sections ?? {}),
+		...mergePageThemePart(base.sections, override.sections, ['backgroundPattern']),
+	},
+});
+
 const quote = (value) => JSON.stringify(value);
 const responsiveValueLines = (label, value, indent = 2) => {
 	const prefix = ' '.repeat(indent);
@@ -171,7 +203,7 @@ const responsiveValueLines = (label, value, indent = 2) => {
 export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml') => {
 	const preset = getThemePreset(presetName, sourceLabel);
 	const metadata = getThemePresetMetadata(presetName);
-	const { navigation, layout, images, typography, palette, sectionSurfaces } = preset;
+	const { shape, layout, images, typography, palette, sections } = preset;
 
 	return [
 		`# Original values for Norna's "${presetName}" theme preset.`,
@@ -181,13 +213,14 @@ export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml
 		`# Available theme presets: ${themePresetNames.join(', ')}.`,
 		`preset: ${presetName}`,
 		'',
-		'navigation:',
-		'  # Alternatives: automatic, sections, top, tree.',
-		`  mode: ${navigation.mode}`,
+		'# Alternatives: square, soft.',
+		`shape: ${shape}`,
 		'',
 		'layout:',
-		'  # Alternatives: compact, normal, airy.',
-		`  density: ${layout.density}`,
+		'  # Alternatives: compact, normal, spacious.',
+		`  contentSpacing: ${layout.contentSpacing}`,
+		'  # Alternatives: narrow, normal, wide.',
+		`  textWidth: ${layout.textWidth}`,
 		'  # Any positive CSS length, including px, rem, em, %, or clamp(...).',
 		`  pageWidth: ${layout.pageWidth}`,
 		'  gutter:',
@@ -219,9 +252,9 @@ export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml
 		'',
 		'# Alternatives: dark, light, paper.',
 		`palette: ${palette}`,
-		'# One value keeps every section on the same surface; multiple values cycle.',
-		'# Use one to three unique values from: base, soft, emphasis.',
-		`sectionSurfaces: [${sectionSurfaces.join(', ')}]`,
+		'sections:',
+		'  # Alternatives: uniform, alternating, cycling.',
+		`  backgroundPattern: ${sections.backgroundPattern}`,
 		'',
 	].join('\n');
 };

package/scripts/show-typography.mjs

@@ -1,5 +1,3 @@
-import { readFile } from 'node:fs/promises';
-import path from 'node:path';
 import {
 	defaultTypography,
 	resolveTypographyConfig,
@@ -13,20 +11,12 @@ import {
 	readSiteFile,
 	validateContentFrontmatterStructure,
 	validateFrontmatterIndentation,
-	validatePageThemeYamlStructure,
 } from './lib/site-content.mjs';
 import {
-	siteContentLabel,
-	siteContentPath,
-	sitePagesDir,
-	sitePagesLabel,
 	siteThemeLabel,
-	siteThemePath,
 } from './lib/site-paths.mjs';
-import { getPageDirectoryAncestors } from './lib/page-model.mjs';
 import { readThemeConfig } from './lib/theme-config.mjs';
 import { resolveThemeConfig } from './lib/theme-presets.mjs';
-import { parseYamlConfig } from './lib/yaml-config.mjs';
 
 const mode = process.argv[2] ?? 'show';
 
@@ -199,28 +189,6 @@ const readThemeTypography = async () => {
 	return resolveAnnotatedTypographyConfig(themeTypographyConfig ?? defaultTypography, siteThemeLabel);
 };
 
-const readPageThemeTypography = async (contentFile, themeTypography) => {
-	if (contentFile.isHome) return themeTypography;
-
-	for (const pageDirectory of getPageDirectoryAncestors(contentFile.pageDirectory).reverse()) {
-		const pageThemePath = path.join(sitePagesDir, pageDirectory, 'theme.yaml');
-		const pageThemeFile = await readFile(pageThemePath, 'utf8').catch((error) => {
-			if (error?.code === 'ENOENT') return null;
-			throw error;
-		});
-		if (!pageThemeFile) continue;
-		const pageThemeLabel = `${sitePagesLabel}/${pageDirectory}/theme.yaml`;
-
-		const pageThemeConfig = resolveThemeConfig(parseYamlConfig(pageThemeFile, pageThemeLabel, {
-			validateStructure: validatePageThemeYamlStructure,
-		}), pageThemeLabel);
-		const typographyConfig = pageThemeConfig.typography;
-		return resolveAnnotatedTypographyConfig(typographyConfig ?? defaultTypography, pageThemeLabel);
-	}
-
-	return themeTypography;
-};
-
 const readPageTypography = async (contentFile, siteThemeTypography) => {
 	const { frontmatter, body } = await readSiteFile(contentFile.contentPath, contentFile.contentLabel);
 	const indentationIssues = [];
@@ -233,7 +201,7 @@ const readPageTypography = async (contentFile, siteThemeTypography) => {
 		].join('\n'));
 	}
 
-	const pageTypography = await readPageThemeTypography(contentFile, siteThemeTypography);
+	const pageTypography = siteThemeTypography;
 	const sections = (await getBodySections(body)).sections
 		.filter((section) => section.id)
 		.map((section) => {

package/scripts/sync-content-sections.mjs

@@ -182,9 +182,7 @@ const getGlobalImageCandidates = (globalImageCandidatesByName, imageName, expect
 
 const getReferenceLabel = (contentFile, section) => `${contentFile.contentLabel} [${section.id ?? 'page title'}]`;
 
-const getRootLabel = (contentFile) => contentFile.isHome
-	? contentFile.imagesLabel
-	: contentFile.imagesLabel.replace(/\/images$/, '');
+const getRootLabel = (contentFile) => contentFile.imagesLabel.replace(/\/images$/, '');
 
 const getCandidateLabel = ({ contentFile, imagePath }) =>
 	`${contentFile.imagesLabel}/${toPosixPath(path.relative(contentFile.imagesDir, imagePath))}`;

package/scripts/test-banner-visibility.mjs

@@ -34,7 +34,7 @@ const runCli = (args, env = {}) => {
 };
 
 try {
-	await mkdir(path.join(siteDir, 'images'), { recursive: true });
+	await mkdir(path.join(siteDir, 'pages', '000-home'), { recursive: true });
 	await mkdir(path.join(siteDir, 'public'), { recursive: true });
 	await writeFile(path.join(siteDir, 'public', 'robots.txt'), 'User-agent: *\nAllow: /\n');
 	await writeFile(path.join(siteDir, 'config.yaml'), 'url: https://example.com/\n');
@@ -55,7 +55,7 @@ palette: dark
     title: Active banner
     text: Active banner text.
 `);
-	await writeFile(path.join(siteDir, 'content.md'), `---
+	await writeFile(path.join(siteDir, 'pages', '000-home', 'content.md'), `---
 page:
   description: Test site for temporary banners.
 ---