@janga/norna 0.7.17 → 0.7.18

package/scripts/check-config.mjs

@@ -45,7 +45,8 @@ try {
 	console.log(`Theme preset: ${themeConfig.preset ?? '(none)'}`);
 	console.log(`Page width: ${projectConfig.layout.pageWidth}`);
 	console.log(`Gutter: desktop ${projectConfig.layout.gutter.desktop}, mobile ${projectConfig.layout.gutter.mobile}`);
-	console.log(`Layout density: ${projectConfig.layout.density}`);
+	console.log(`Content spacing: ${projectConfig.layout.contentSpacing}`);
+	console.log(`Text width: ${projectConfig.layout.textWidth}`);
 	console.log(`Image area width: ${projectConfig.images.width}`);
 	console.log(`Image max available width: desktop ${projectConfig.images.maxAvailableWidthPercent.desktop}%, mobile ${projectConfig.images.maxAvailableWidthPercent.mobile}%`);
 	console.log(`Image max available height: desktop ${projectConfig.images.maxAvailableHeightPercent.desktop}%, mobile ${projectConfig.images.maxAvailableHeightPercent.mobile}%`);

package/scripts/deploy-site.mjs

@@ -211,7 +211,7 @@ const assertDeployableStatus = async (entries, expectedImagePaths) => {
 	if (unexpectedUntracked.length > 0) {
 		fail([
 			'Refusing to deploy: unexpected untracked files are present.',
-			`Only new referenced images directly under ${siteImagesLabel}/ or ${sitePagesLabel}/<NNN-page-id>/images/ are staged automatically.`,
+			`Only new referenced images directly under a page's images/ directory in ${sitePagesLabel}/ are staged automatically.`,
 			...unexpectedUntracked.map((entry) => `- ${formatEntry(entry)}`),
 		].join('\n'));
 	}

package/scripts/generate-images.mjs

@@ -23,7 +23,6 @@ import {
 	generatedImagesManifestPath,
 	originalImagesDir,
 	siteDir,
-	siteImagesDir,
 } from './lib/site-paths.mjs';
 
 const execFileAsync = promisify(execFile);
@@ -88,10 +87,8 @@ const getFilePathFromPublicPath = (publicPath) => path.join(astroPublicDir, publ
 
 const getSourceHashSlug = (sourceHash) => sourceHash.slice(0, sourceHashSlugLength);
 
-const getGeneratedPath = (sourcePath, sourceHash, width) => {
-	const parsed = path.parse(path.relative(siteImagesDir, sourcePath).startsWith('..')
-		? path.relative(path.dirname(siteImagesDir), sourcePath)
-		: path.relative(siteImagesDir, sourcePath));
+const getGeneratedPath = (sourceKey, sourceHash, width) => {
+	const parsed = path.parse(sourceKey);
 	return path.join(generatedImagesDir, parsed.dir, `${parsed.name}-${getSourceHashSlug(sourceHash)}-${width}.webp`);
 };
 
@@ -104,11 +101,7 @@ const fail = (message) => {
 	throw new Error(message);
 };
 
-const getImageSourceKey = (contentFile, image) => (
-	contentFile.isHome
-		? `images/${image}`
-		: `pages/${contentFile.pageDirectory}/images/${image}`
-);
+const getImageSourceKey = (contentFile, image) => `pages/${contentFile.pageDirectory}/images/${image}`;
 
 const getReferencedImages = async (contentFile) => {
 	const { body } = await readSiteFile(contentFile.contentPath, contentFile.contentLabel);
@@ -241,8 +234,8 @@ const getVariantWidths = ({ width }) => {
 	return variantWidths;
 };
 
-const getVariants = (sourcePath, sourceHash, variantWidths) => variantWidths.map((width) => ({
-	src: getPublicPath(getGeneratedPath(sourcePath, sourceHash, width)),
+const getVariants = (sourceKey, sourceHash, variantWidths) => variantWidths.map((width) => ({
+	src: getPublicPath(getGeneratedPath(sourceKey, sourceHash, width)),
 	width,
 }));
 
@@ -417,9 +410,9 @@ for (const { sourcePath, sourceKey } of sources) {
 
 	const dimensions = await identify(sourcePath);
 	const variantWidths = getVariantWidths(dimensions);
-	const variants = getVariants(sourcePath, sourceHash, variantWidths);
+	const variants = getVariants(sourceKey, sourceHash, variantWidths);
 	for (const width of variantWidths) {
-		const outputPath = getGeneratedPath(sourcePath, sourceHash, width);
+		const outputPath = getGeneratedPath(sourceKey, sourceHash, width);
 		await convert(sourcePath, outputPath, width);
 	}
 

package/scripts/generate-schemas.mjs

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { z } from 'astro/zod';
 import {
 	configSchema,
+	pageThemeSchema,
 	siteSchema,
 	sitewideSchema,
 	themeVisualSchema,
@@ -15,6 +16,7 @@ const schemaDirectory = path.join(root, 'schemas');
 const definitions = [
 	['config.schema.json', 'Norna site configuration', configSchema],
 	['theme.schema.json', 'Norna visual theme', themeVisualSchema],
+	['page-theme.schema.json', 'Norna page theme', pageThemeSchema],
 	['sitewide-content.schema.json', 'Norna site-wide content', sitewideSchema],
 	['content-frontmatter.schema.json', 'Norna page frontmatter', siteSchema],
 ];
@@ -30,12 +32,13 @@ for (const [filename, title, schema] of definitions) {
 
 schemaFiles.set('manifest.json', `${JSON.stringify({
 	editorApiVersion: 1,
-	schemaVersion: 1,
+	schemaVersion: 2,
 	files: {
 		config: 'config.schema.json',
 		contentFrontmatter: 'content-frontmatter.schema.json',
 		sitewideContent: 'sitewide-content.schema.json',
 		theme: 'theme.schema.json',
+		pageTheme: 'page-theme.schema.json',
 	},
 }, null, 2)}\n`);
 

package/scripts/lib/editor-language-service.mjs

@@ -116,15 +116,6 @@ export const getSitePublicAssetStatus = async (documentPath) => {
 const getPageContext = (siteRoot, documentPath) => {
 	const absoluteDocumentPath = path.resolve(documentPath);
 	const relativePath = toPosixPath(path.relative(siteRoot, absoluteDocumentPath));
-	if (relativePath === 'content.md') {
-		return {
-			contentPath: absoluteDocumentPath,
-			imagesRoot: path.join(siteRoot, 'images'),
-			pageLabel: 'Home',
-			pageDirectory: null,
-		};
-	}
-
 	const match = relativePath.match(/^pages\/(.+)\/content\.md$/);
 	if (!match) return null;
 
@@ -316,8 +307,6 @@ const collectPageImageRoots = async (directory, siteRoot, roots) => {
 
 const getContentFiles = async (siteRoot) => {
 	const files = [];
-	const homePath = path.join(siteRoot, 'content.md');
-	if (await fileExists(homePath)) files.push(homePath);
 
 	const visit = async (directory) => {
 		const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
@@ -350,9 +339,6 @@ const getReferencesByFilename = async (siteRoot) => {
 
 export const createSiteImageIndex = async (siteRoot) => {
 	const files = [];
-	const homeImageRoot = path.join(siteRoot, 'images');
-	await collectImageFiles(homeImageRoot, homeImageRoot, 'Home', files);
-
 	const pageRoots = [];
 	await collectPageImageRoots(path.join(siteRoot, 'pages'), siteRoot, pageRoots);
 	for (const root of pageRoots) {

package/scripts/lib/example-sites.mjs

@@ -1,9 +1,19 @@
 import { existsSync } from 'node:fs';
 import { readdir } from 'node:fs/promises';
 import path from 'node:path';
+import { homePageDirectory } from './site-conventions.mjs';
 
 export const exampleCategories = ['complete-sites', 'feature-demos'];
 
+const isGeneratedOnlyCacheDirectory = async (exampleDirectory, siteDirectory) => {
+	if (!existsSync(path.join(siteDirectory, '.norna'))) return false;
+
+	const exampleEntries = await readdir(exampleDirectory);
+	const siteEntries = await readdir(siteDirectory);
+	return exampleEntries.every((name) => name === 'site' || name === '.DS_Store')
+		&& siteEntries.every((name) => name === '.norna' || name === '.DS_Store');
+};
+
 export const getExampleSites = async (root) => {
 	const examples = [];
 
@@ -12,12 +22,14 @@ export const getExampleSites = async (root) => {
 		const entries = await readdir(categoryDirectory, { withFileTypes: true });
 
 		for (const entry of entries.filter((candidate) => candidate.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
-			const siteDirectory = path.join(categoryDirectory, entry.name, 'site');
+			const exampleDirectory = path.join(categoryDirectory, entry.name);
+			const siteDirectory = path.join(exampleDirectory, 'site');
 			if (!existsSync(path.join(siteDirectory, 'config.yaml'))) {
+				if (await isGeneratedOnlyCacheDirectory(exampleDirectory, siteDirectory)) continue;
 				throw new Error(`Example ${path.relative(root, siteDirectory)} is missing config.yaml.`);
 			}
-			if (!existsSync(path.join(siteDirectory, 'content.md'))) {
-				throw new Error(`Example ${path.relative(root, siteDirectory)} is missing content.md.`);
+			if (!existsSync(path.join(siteDirectory, 'pages', homePageDirectory, 'content.md'))) {
+				throw new Error(`Example ${path.relative(root, siteDirectory)} is missing pages/${homePageDirectory}/content.md.`);
 			}
 
 			examples.push({

package/scripts/lib/page-model.mjs

@@ -1,4 +1,6 @@
-export const pageDirectoryPattern = /^(?!000)(\d{3})-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+import { homePageDirectory } from './site-conventions.mjs';
+
+export const pageDirectoryPattern = /^(\d{3})-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
 
 const pageEntryPathSeparator = '--';
 
@@ -7,9 +9,12 @@ export const parsePageDirectory = (pageDirectory, label = 'page directory') => {
 
 	if (!match) {
 		throw new Error(
-			`Invalid ${label} "${pageDirectory}". Page directories must use the form NNN-page-id, for example 010-getting-started. The prefix must be 001-999 and page-id may contain only lowercase letters, numbers, and single hyphens.`,
+			`Invalid ${label} "${pageDirectory}". Page directories must use the form NNN-page-id, for example 010-getting-started. Page ids may contain only lowercase letters, numbers, and single hyphens.`,
 		);
 	}
+	if (match[1] === '000' && pageDirectory !== homePageDirectory) {
+		throw new Error(`Invalid ${label} "${pageDirectory}". The 000 prefix is reserved for ${homePageDirectory}.`);
+	}
 
 	return {
 		pageDirectory,
@@ -47,17 +52,31 @@ export const parsePageDirectoryPath = (pageDirectoryPath, label = 'page director
 	const pageIds = pageDirectories.map(({ pageId }) => pageId);
 	const pageOrders = pageDirectories.map(({ pageOrder }) => pageOrder);
 	const currentPage = pageDirectories.at(-1);
+	const homeIndex = pageDirectories.findIndex(({ pageDirectory }) => pageDirectory === homePageDirectory);
+	if (homeIndex > 0) {
+		throw new Error(`Invalid ${label} "${pageDirectoryPath}". ${homePageDirectory} is allowed only as a top-level page.`);
+	}
+	if (homeIndex === 0 && pageDirectories.length > 1) {
+		throw new Error(
+			`Invalid ${label} "${pageDirectoryPath}". ${homePageDirectory} is the homepage and cannot contain child pages. Place the page beside it under site/pages/, or below another non-home page.`,
+		);
+	}
+	const isHome = homeIndex === 0;
+	const logicalPageIds = isHome ? [] : pageIds;
+	const logicalPageOrders = isHome ? [] : pageOrders;
 
 	return {
 		pageDirectory: normalizedPath,
 		pageDirectories: pageDirectories.map(({ pageDirectory }) => pageDirectory),
 		pageId: currentPage.pageId,
-		pageIds,
+		pageIds: logicalPageIds,
 		pageOrder: currentPage.pageOrder,
-		pageOrders,
-		pagePath: pageIds.join('/'),
-		parentPagePath: pageIds.length > 1 ? pageIds.slice(0, -1).join('/') : null,
-		depth: pageIds.length,
+		pageOrders: logicalPageOrders,
+		pagePath: logicalPageIds.join('/'),
+		parentPagePath: logicalPageIds.length > 1
+			? logicalPageIds.slice(0, -1).join('/')
+			: null,
+		depth: pageDirectories.length,
 	};
 };
 

package/scripts/lib/presentation.mjs

@@ -5,7 +5,11 @@ import {
 import { resolveThemeConfig } from './theme-presets.mjs';
 
 export const presentationPaletteNames = ['dark', 'light', 'paper'];
-const sectionSurfaceNames = ['base', 'soft', 'emphasis'];
+const sectionBackgroundPatterns = Object.freeze({
+	uniform: ['base'],
+	alternating: ['base', 'soft'],
+	cycling: ['base', 'soft', 'emphasis'],
+});
 
 const presentationPalettes = Object.freeze({
 	dark: {
@@ -92,34 +96,30 @@ export const getPresentationCssVariables = (presentation) => {
 	};
 };
 
-const getSectionSurfaces = (value = ['base'], sourceLabel = 'theme.yaml') => {
-	if (!Array.isArray(value) || value.length < 1 || value.length > 3) {
-		throw new Error(`sectionSurfaces must contain one to three values in ${sourceLabel}.`);
-	}
-
-	for (const surface of value) {
-		if (!sectionSurfaceNames.includes(surface)) {
-			throw new Error(`Unknown section surface "${surface}" in ${sourceLabel}. Use one of: ${sectionSurfaceNames.join(', ')}.`);
-		}
-	}
-
-	if (new Set(value).size !== value.length) {
-		throw new Error(`Each section surface may appear only once in ${sourceLabel}.`);
+const getSectionSurfaces = (pattern = 'uniform', sourceLabel = 'theme.yaml') => {
+	const surfaces = sectionBackgroundPatterns[pattern];
+	if (!surfaces) {
+		throw new Error(`sections.backgroundPattern must be one of ${Object.keys(sectionBackgroundPatterns).join(', ')} in ${sourceLabel}.`);
 	}
 
-	return value;
+	return surfaces;
 };
 
 export const resolveThemePresentation = (theme, sourceLabel = 'theme.yaml') => {
 	const normalizedTheme = resolveThemeConfig(theme, sourceLabel);
 	const paletteName = normalizedTheme.palette ?? 'dark';
 	const palette = getPresentationPalette(paletteName);
+	const typography = resolveTypographyConfig(normalizedTheme.typography ?? defaultTypography);
+	const textWidth = normalizedTheme.layout?.textWidth;
+	if (textWidth !== undefined) {
+		typography.values.body.width = textWidth;
+	}
 
 	return {
 		paletteName,
 		palette,
-		sectionSurfaces: getSectionSurfaces(normalizedTheme.sectionSurfaces, sourceLabel),
-		typography: resolveTypographyConfig(normalizedTheme.typography ?? defaultTypography),
+		sectionSurfaces: getSectionSurfaces(normalizedTheme.sections?.backgroundPattern, sourceLabel),
+		typography,
 	};
 };
 
@@ -129,6 +129,14 @@ export const resolvePagePresentation = (theme, sourceLabel) => {
 	return resolvedThemePresentation;
 };
 
+const textWidthCssValues = Object.freeze({
+	narrow: 'min(60ch, var(--text-width))',
+	normal: 'min(72ch, var(--text-width))',
+	wide: 'min(72ch, var(--image-layout-width))',
+});
+
+export const getTextWidthCssValue = (textWidth) => textWidthCssValues[textWidth];
+
 export const resolveSectionSurface = (pagePresentation, sectionIndex) => {
 	const surfaceName = pagePresentation.sectionSurfaces[sectionIndex % pagePresentation.sectionSurfaces.length];
 

package/scripts/lib/project-config.mjs

@@ -187,11 +187,10 @@ const localeLabels = Object.freeze({
 		dismissBanner: 'Dismiss notice',
 		built: 'Built',
 		images: 'Images',
-		navigationBack: 'Back to pages',
+		navigationChildren: 'Child pages',
 		navigationMenu: 'Menu',
-		navigationOverview: 'Overview',
 		note: 'Note',
-		pageNavigation: 'On this page',
+		pageNavigation: 'Page contents',
 		siteBanners: 'Site notices',
 		siteNavigation: 'Pages',
 		skipToContent: 'Skip to content',
@@ -201,11 +200,10 @@ const localeLabels = Object.freeze({
 		dismissBanner: 'Stäng meddelande',
 		built: 'Byggd',
 		images: 'Bilder',
-		navigationBack: 'Tillbaka till sidor',
+		navigationChildren: 'Undersidor',
 		navigationMenu: 'Meny',
-		navigationOverview: 'Översikt',
 		note: 'Not',
-		pageNavigation: 'På den här sidan',
+		pageNavigation: 'Sidinnehåll',
 		siteBanners: 'Meddelanden',
 		siteNavigation: 'Sidor',
 		skipToContent: 'Hoppa till innehållet',
@@ -239,8 +237,8 @@ const siteUrl = readSiteUrl(rawConfig);
 const scrollBehaviorNames = ['instant', 'smooth'];
 
 const defaultFontFamily = "Arial, 'Helvetica Neue', Helvetica, sans-serif";
-const layoutDensityNames = ['compact', 'normal', 'airy'];
-const layoutDensityProfiles = Object.freeze({
+const contentSpacingNames = ['compact', 'normal', 'spacious'];
+const contentSpacingProfiles = Object.freeze({
 	compact: Object.freeze({
 		blockGap: Object.freeze({
 			desktop: '1.25em',
@@ -293,7 +291,7 @@ const layoutDensityProfiles = Object.freeze({
 			mobile: '1.5rem',
 		}),
 	}),
-	airy: Object.freeze({
+	spacious: Object.freeze({
 		blockGap: Object.freeze({
 			desktop: '1.75em',
 			mobile: '1.5em',
@@ -326,12 +324,19 @@ export const resolveThemeVisualConfig = (theme, sourceLabel = siteThemeLabel) =>
 	const rawLayoutSpacingConfig = assertObject(rawLayoutConfig.spacing ?? {}, 'layout.spacing', sourceLabel);
 	const rawImagesConfig = assertObject(rawThemeConfig.images ?? {}, 'images', sourceLabel);
 	const rawTypographyConfig = assertObject(rawThemeConfig.typography ?? {}, 'typography', sourceLabel);
-	const resolvedLayoutDensity = readEnum(rawLayoutConfig, 'density', 'layout', layoutDensityNames, 'normal', sourceLabel);
-	const resolvedLayoutSpacingDefaults = layoutDensityProfiles[resolvedLayoutDensity];
+	const resolvedContentSpacing = readEnum(rawLayoutConfig, 'contentSpacing', 'layout', contentSpacingNames, 'normal', sourceLabel);
+	const resolvedLayoutSpacingDefaults = contentSpacingProfiles[resolvedContentSpacing];
+	const shape = readEnum(rawThemeConfig, 'shape', 'theme', ['square', 'soft'], 'soft', sourceLabel);
 
 	return Object.freeze({
 		layout: Object.freeze({
-			density: resolvedLayoutDensity,
+			contentSpacing: resolvedContentSpacing,
+			textWidth: readEnum(rawLayoutConfig, 'textWidth', 'layout', ['narrow', 'normal', 'wide'], 'normal', sourceLabel),
+			localNavigationGap: readCssLengthValue(
+				rawLayoutConfig.localNavigationGap ?? 'clamp(1.5rem, 3vw, 3rem)',
+				'layout.localNavigationGap',
+				sourceLabel,
+			),
 			gutter: readResponsiveCssLength(rawLayoutConfig, 'gutter', 'layout', Object.freeze({
 				desktop: 'clamp(1.25rem, 4vw, 3rem)',
 				mobile: '1rem',
@@ -360,12 +365,17 @@ 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',
+		}),
 	});
 };
 
-export const resolveThemeNavigationConfig = (theme, sourceLabel = siteThemeLabel) => {
-	const resolvedTheme = assertObject(resolveThemeConfig(theme, sourceLabel), 'theme YAML', sourceLabel);
-	const rawNavigation = assertObject(resolvedTheme.navigation ?? {}, 'navigation', sourceLabel);
+export const resolveNavigationConfig = (config, sourceLabel = siteConfigLabel) => {
+	const rawNavigation = assertObject(config.navigation ?? {}, 'navigation', sourceLabel);
 
 	return Object.freeze({
 		mode: readEnum(
@@ -386,7 +396,7 @@ export const projectConfig = Object.freeze({
 	}),
 	...resolveThemeVisualConfig(rawTheme, siteThemeLabel),
 	navigation: Object.freeze({
-		...resolveThemeNavigationConfig(rawTheme, siteThemeLabel),
+		...resolveNavigationConfig(rawConfig, siteConfigLabel),
 		scrollBehavior: readEnum(
 			rawConfig,
 			'scrollBehavior',

package/scripts/lib/schema-definitions.mjs

@@ -11,13 +11,15 @@ const isDateOnly = (value) => {
 
 const textAlign = z.enum(['left', 'center', 'right']).describe('Text alignment. Omit an override to keep the active typography profile.');
 const textSize = z.enum(['small', 'medium', 'large', 'xlarge']).describe('Text size from the active typography system. Omit an override to keep the profile value.');
-const textWidth = z.enum(['narrow', 'normal', 'wide']).describe('Maximum width of body text. Omit an override to keep the profile value.');
+const textWidth = z.enum(['narrow', 'normal', 'wide']).describe('Maximum width of body text. Omit this to keep the inherited page setting.');
 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 sectionSurface = z.enum(['base', 'soft', 'emphasis']).describe('Semantic section surface from the active palette.');
 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 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.')
@@ -73,7 +75,6 @@ const headingLevelsPresentationOverride = z.object({
 }).strict().describe('Heading overrides by Markdown level.');
 const bodyPresentationOverride = z.object({
 	...commonTextPresentationOverride,
-	width: textWidth.optional().describe('Maximum body-text line length.'),
 	paragraphSpacing: cssLength.optional().describe('Vertical space between body paragraphs.'),
 }).strict().describe('Focused overrides for body text.');
 const captionPresentationOverride = z.object({
@@ -121,23 +122,36 @@ const themeLayoutSpacing = z.object({
 	sectionGap: responsiveCssLength.optional().describe('Vertical separation between page sections.'),
 }).strict().describe('Fine-grained spacing overrides applied after layout density.');
 const themeLayout = z.object({
-	density: spacingDensity.optional().describe('Overall spacing density. Omit this to keep the selected preset.'),
+	contentSpacing: contentSpacing.optional().describe('Page content spacing. Omit this to keep the selected preset or inherited page setting.'),
+	textWidth: textWidth.optional().describe('Body-text line length. Omit this to keep the selected preset or inherited page setting.'),
 	pageWidth: visualCssLength.optional().describe('Maximum width of the site layout. Omit this to keep the selected preset.'),
 	gutter: responsiveCssLength.optional().describe('Horizontal page gutter as one value or separate desktop and mobile values.'),
 	spacing: themeLayoutSpacing.optional().describe('Fine-grained spacing overrides.'),
 }).strict().describe('Optional layout overrides applied after the preset.');
+const pageThemeLayout = z.object({
+	contentSpacing: contentSpacing.optional().describe('Page content spacing. Descendant pages inherit this value.'),
+	textWidth: textWidth.optional().describe('Body-text line length. Descendant pages inherit this value.'),
+}).strict().refine(
+	(value) => value.contentSpacing !== undefined || value.textWidth !== undefined,
+	'Specify contentSpacing, textWidth, or both.',
+).describe('Page-local layout settings inherited by descendant pages.');
 const themeImages = z.object({
 	width: visualCssLength.optional().describe('Maximum managed-image width. Omit this to keep the selected preset.'),
 	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 themeNavigation = z.object({
-	mode: navigationMode.optional().describe('Navigation model. Omit this to keep the selected preset.'),
-}).strict().describe('Site-wide navigation behavior. This may be set only in the root theme.');
-const sectionSurfaces = z.array(sectionSurface).min(1).max(3).refine(
-	(value) => new Set(value).size === value.length,
-	'Each section surface may appear only once.',
-).describe('Surface sequence cycled across page sections.');
+const configNavigation = z.object({
+	mode: navigationMode.optional().describe('Navigation model. Omit this to let Norna choose from the site structure.'),
+}).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.'),
+}).strict().describe('Defaults for page section presentation.');
+const pageThemeSections = z.object({
+	backgroundPattern: backgroundPattern.optional().describe('Section background sequence inherited by descendant pages.'),
+}).strict().refine(
+	(value) => value.backgroundPattern !== undefined,
+	'Specify backgroundPattern.',
+).describe('Page-local section presentation inherited by descendant pages.');
 const pageNavigation = z.object({
 	listed: z.boolean().optional().default(true).describe('List this page in site navigation. The page remains public when false.'),
 }).strict();
@@ -167,6 +181,7 @@ const sitewideFooter = z.object({
 const configShape = {
 	url: z.string().url().describe('Absolute public URL for the built site.'),
 	language: z.string().regex(/^(?:en|sv)(?:-[a-zA-Z0-9]+)*$/).optional().describe('Site language tag using Norna\'s English or Swedish interface text; the default is en.'),
+	navigation: configNavigation.optional(),
 	scrollBehavior: z.enum(['instant', 'smooth']).optional().default('instant').describe('Use instant anchors by default or the browser\'s native smooth scrolling.'),
 };
 
@@ -177,12 +192,18 @@ const siteShape = {
 
 const themeVisualShape = {
 	preset: themePreset.optional().describe('Complete visual starting point. Add only the overrides the site actually needs.'),
-	navigation: themeNavigation.optional(),
+	shape: shapeProfile.optional().describe('Site-wide shape profile. Omit this to use the selected preset.'),
 	layout: themeLayout.optional(),
 	images: themeImages.optional(),
 	typography: themeTypography.optional(),
 	palette: presentationPalette.optional(),
-	sectionSurfaces: sectionSurfaces.optional().describe('Surface sequence cycled through page sections. Omit this to keep the selected preset.'),
+	sections: themeSections.optional(),
+};
+
+const pageThemeShape = {
+	layout: pageThemeLayout.optional(),
+	images: themeImages.optional(),
+	sections: pageThemeSections.optional(),
 };
 
 const sitewideShape = {
@@ -196,6 +217,7 @@ export const schemaTopLevelKeys = Object.freeze({
 	content: Object.freeze(Object.keys(siteShape)),
 	sitewide: Object.freeze(Object.keys(sitewideShape)),
 	theme: Object.freeze(Object.keys(themeVisualShape)),
+	pageTheme: Object.freeze(Object.keys(pageThemeShape)),
 });
 
 export const configSchema = z.object(configShape).strict()
@@ -203,6 +225,12 @@ export const configSchema = z.object(configShape).strict()
 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()
-	.describe('Visual settings for a site or page. A page theme replaces the inherited visual theme; navigation logo settings remain site-wide.');
+	.describe('Site-wide visual identity and default page presentation. Presets may be selected only in the root theme.');
+export const pageThemeSchema = z.object(pageThemeShape).strict()
+	.refine(
+		(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.');
 export const sitewideSchema = z.object(sitewideShape).strict()
 	.describe('Editorial content and optional navigation logo display settings shared by every page.');