@janga/norna 0.7.25 → 0.7.26

package/scripts/lib/presentation.mjs

@@ -87,16 +87,16 @@ const presentationPalettes = Object.freeze({
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
-				page: { backgroundColor: '#f3f6f8', textColor: '#202932' },
+				page: { backgroundColor: '#e8f1f8', textColor: '#202932' },
 				surfaces: {
-					base: { backgroundColor: '#f3f6f8', textColor: '#202932' },
+					base: { backgroundColor: '#e8f1f8', textColor: '#202932' },
 					soft: { backgroundColor: '#e4eaf0', textColor: '#202932' },
 					emphasis: { backgroundColor: '#d3dee8', textColor: '#202932' },
 				},
-				frame: { backgroundColor: '#f3f6f8', textColor: '#202932' },
+				frame: { backgroundColor: '#e8f1f8', textColor: '#202932' },
 				css: {
 					surface: '#e9eef2',
-					muted: '#5d6a76',
+					muted: '#56636f',
 					soft: '#d5dfe7',
 					accent: '#2a5877',
 					border: 'rgb(32 41 50 / 16%)',
@@ -127,13 +127,13 @@ const presentationPalettes = Object.freeze({
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
-				page: { backgroundColor: '#eef4f1', textColor: '#203631' },
+				page: { backgroundColor: '#e3f1eb', textColor: '#203631' },
 				surfaces: {
-					base: { backgroundColor: '#eef4f1', textColor: '#203631' },
+					base: { backgroundColor: '#e3f1eb', textColor: '#203631' },
 					soft: { backgroundColor: '#dce9e4', textColor: '#203631' },
 					emphasis: { backgroundColor: '#c8ddd5', textColor: '#203631' },
 				},
-				frame: { backgroundColor: '#eef4f1', textColor: '#203631' },
+				frame: { backgroundColor: '#e3f1eb', textColor: '#203631' },
 				css: {
 					surface: '#e3ece8',
 					muted: '#536560',
@@ -167,16 +167,16 @@ const presentationPalettes = Object.freeze({
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
-				page: { backgroundColor: '#f7f3fa', textColor: '#2e2736' },
+				page: { backgroundColor: '#f0e8f8', textColor: '#2e2736' },
 				surfaces: {
-					base: { backgroundColor: '#f7f3fa', textColor: '#2e2736' },
+					base: { backgroundColor: '#f0e8f8', textColor: '#2e2736' },
 					soft: { backgroundColor: '#ebe4f1', textColor: '#2e2736' },
 					emphasis: { backgroundColor: '#ddd3e8', textColor: '#2e2736' },
 				},
-				frame: { backgroundColor: '#f7f3fa', textColor: '#2e2736' },
+				frame: { backgroundColor: '#f0e8f8', textColor: '#2e2736' },
 				css: {
 					surface: '#eee8f3',
-					muted: '#6c6273',
+					muted: '#655b6c',
 					soft: '#ded5e7',
 					accent: '#604678',
 					border: 'rgb(46 39 54 / 16%)',
@@ -207,13 +207,13 @@ const presentationPalettes = Object.freeze({
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
-				page: { backgroundColor: '#f8f5ee', textColor: '#272522' },
+				page: { backgroundColor: '#fdf6e3', textColor: '#272522' },
 				surfaces: {
-					base: { backgroundColor: '#f8f5ee', textColor: '#272522' },
+					base: { backgroundColor: '#fdf6e3', textColor: '#272522' },
 					soft: { backgroundColor: '#ebe5d9', textColor: '#272522' },
 					emphasis: { backgroundColor: '#ded4c5', textColor: '#272522' },
 				},
-				frame: { backgroundColor: '#f8f5ee', textColor: '#272522' },
+				frame: { backgroundColor: '#fdf6e3', textColor: '#272522' },
 				css: {
 					surface: '#f0ebe1',
 					muted: '#6b655b',
@@ -247,13 +247,13 @@ const presentationPalettes = Object.freeze({
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
-				page: { backgroundColor: '#f7efd9', textColor: '#34291c' },
+				page: { backgroundColor: '#fbf1c7', textColor: '#34291c' },
 				surfaces: {
-					base: { backgroundColor: '#f7efd9', textColor: '#34291c' },
+					base: { backgroundColor: '#fbf1c7', textColor: '#34291c' },
 					soft: { backgroundColor: '#eadbb8', textColor: '#34291c' },
 					emphasis: { backgroundColor: '#d8c18c', textColor: '#34291c' },
 				},
-				frame: { backgroundColor: '#f7efd9', textColor: '#34291c' },
+				frame: { backgroundColor: '#fbf1c7', textColor: '#34291c' },
 				css: {
 					surface: '#efe2c4',
 					muted: '#6c5e4c',
@@ -287,13 +287,13 @@ const presentationPalettes = Object.freeze({
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
-				page: { backgroundColor: '#f7efed', textColor: '#3c2929' },
+				page: { backgroundColor: '#f8e9e7', textColor: '#3c2929' },
 				surfaces: {
-					base: { backgroundColor: '#f7efed', textColor: '#3c2929' },
+					base: { backgroundColor: '#f8e9e7', textColor: '#3c2929' },
 					soft: { backgroundColor: '#ecdeda', textColor: '#3c2929' },
 					emphasis: { backgroundColor: '#ddc7c1', textColor: '#3c2929' },
 				},
-				frame: { backgroundColor: '#f7efed', textColor: '#3c2929' },
+				frame: { backgroundColor: '#f8e9e7', textColor: '#3c2929' },
 				css: {
 					surface: '#f0e3e0',
 					muted: '#6d5558',
@@ -327,13 +327,13 @@ const presentationPalettes = Object.freeze({
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
-				page: { backgroundColor: '#f1f3e8', textColor: '#263225' },
+				page: { backgroundColor: '#eaf0da', textColor: '#263225' },
 				surfaces: {
-					base: { backgroundColor: '#f1f3e8', textColor: '#263225' },
+					base: { backgroundColor: '#eaf0da', textColor: '#263225' },
 					soft: { backgroundColor: '#e1e6d2', textColor: '#263225' },
 					emphasis: { backgroundColor: '#cbd5b7', textColor: '#263225' },
 				},
-				frame: { backgroundColor: '#f1f3e8', textColor: '#263225' },
+				frame: { backgroundColor: '#eaf0da', textColor: '#263225' },
 				css: {
 					surface: '#e7eadb',
 					muted: '#52604c',
@@ -367,16 +367,16 @@ const presentationPalettes = Object.freeze({
 		modes: Object.freeze({
 			light: createPaletteMode({
 				appearance: 'light',
-				page: { backgroundColor: '#f2f4fb', textColor: '#25243a' },
+				page: { backgroundColor: '#e8ebfa', textColor: '#25243a' },
 				surfaces: {
-					base: { backgroundColor: '#f2f4fb', textColor: '#25243a' },
+					base: { backgroundColor: '#e8ebfa', textColor: '#25243a' },
 					soft: { backgroundColor: '#e2e6f3', textColor: '#25243a' },
 					emphasis: { backgroundColor: '#d0d7eb', textColor: '#25243a' },
 				},
-				frame: { backgroundColor: '#f2f4fb', textColor: '#25243a' },
+				frame: { backgroundColor: '#e8ebfa', textColor: '#25243a' },
 				css: {
 					surface: '#e8eaf5',
-					muted: '#62647a',
+					muted: '#5b5d73',
 					soft: '#d5daec',
 					accent: '#3b568f',
 					border: 'rgb(37 36 58 / 16%)',
@@ -467,7 +467,6 @@ export const resolveThemePresentation = (theme, sourceLabel = 'theme.yaml') => {
 	const paletteName = normalizedTheme.palette ?? 'near-monochrome';
 	const palette = getPresentationPalette(paletteName);
 	const appearance = normalizedTheme.appearance ?? {};
-	const readerControls = normalizedTheme.readerControls ?? {};
 	const defaultAppearance = appearance.default ?? 'system';
 	if (!appearanceNames.includes(defaultAppearance)) {
 		throw new Error(`appearance.default must be one of ${appearanceNames.join(', ')} in ${sourceLabel}.`);
@@ -488,9 +487,9 @@ export const resolveThemePresentation = (theme, sourceLabel = 'theme.yaml') => {
 		},
 		readerPreferences: {
 			controls: {
-				appearance: readerControls.appearance === true,
+				appearance: true,
 				readingWidth: true,
-				focusReading: readerControls.focusReading === true,
+				focusReading: false,
 			},
 			defaults: {
 				appearance: defaultAppearance,

package/scripts/lib/project-config.mjs

@@ -14,6 +14,7 @@ import {
 	siteThemeLabel,
 } from './site-paths.mjs';
 import { localEditorNames, normalizeEditLinkBaseUrl } from './edit-source-link.mjs';
+import { resolveLocale } from './locale-registry.mjs';
 import { readThemeConfig } from './theme-config.mjs';
 import { resolveThemeConfig } from './theme-presets.mjs';
 import { parseYamlConfig } from './yaml-config.mjs';
@@ -197,178 +198,6 @@ const readSiteUrl = (config) => {
 	return url;
 };
 
-const localeLabels = Object.freeze({
-	en: Object.freeze({
-		breadcrumb: 'Breadcrumb',
-		appearance: 'Appearance',
-		appearanceDark: 'Dark',
-		appearanceLight: 'Light',
-		appearanceSystem: 'System',
-		codeCopied: 'Copied',
-		codeCopyFailed: 'Could not copy code',
-		copyCode: 'Copy code',
-		calloutCaution: 'Caution',
-		calloutDanger: 'Danger',
-		calloutImportant: 'Important',
-		calloutNote: 'Note',
-		calloutTip: 'Tip',
-		calloutWarning: 'Warning',
-		closeNavigation: 'Close navigation',
-		editSource: 'Edit this page',
-		displaySettings: 'Display',
-		focusReading: 'Focus reading',
-		footnoteBackReference: 'Back to reference {reference}',
-		footnotes: 'Footnotes',
-		readingWidth: 'Reading width',
-		readingWidthNarrow: 'Narrow',
-		readingWidthStandard: 'Standard',
-		readingWidthWide: 'Wide',
-		resetDisplaySettings: 'Reset',
-		dismissBanner: 'Dismiss notice',
-		built: 'Built',
-		images: 'Images',
-		imageCarousel: 'image carousel',
-		imageInspection: 'Image inspection',
-		imageInspectionActualSize: 'Show actual size',
-		imageInspectionClose: 'Close image inspection',
-		imageInspectionFit: 'Fit image to window',
-		inspectImage: 'Inspect image: {description}',
-		navigationCollapsedAll: 'All navigation items collapsed.',
-		navigationCollapseAll: 'Collapse all',
-		navigationControls: 'Navigation tree controls',
-		navigationChildren: 'Child pages',
-		navigationExpandedAll: 'All navigation items expanded.',
-		navigationExpandAll: 'Expand all',
-		navigationFilter: 'Filter pages and groups',
-		navigationFilterEmpty: 'No matching pages or groups. The current page remains available.',
-		navigationFilterMatches: 'Matching navigation items: {count}',
-		navigationLocatedCurrent: 'Current page located.',
-		navigationLocateCurrent: 'Locate current page',
-		navigationMenu: 'Menu',
-		nextImage: 'Next image',
-		nextPage: 'Next page',
-		note: 'Note',
-		openInVsCode: 'Open in VS Code',
-		notFound: 'Page not found',
-		notFoundText: 'The requested page does not exist or may have moved.',
-		pageMoved: 'Page moved',
-		pageMovedText: 'This address now identifies',
-		pageNavigation: 'Page contents',
-		pageSequence: 'Page sequence',
-		pageSections: 'Sections',
-		previousImage: 'Previous image',
-		previousPage: 'Previous page',
-		returnHome: 'Go to the homepage',
-		search: 'Search',
-		searchDescription: 'Search the published content on this site.',
-		searchLoading: 'Loading search…',
-		searchNoScript: 'Search requires JavaScript. Use the page navigation when JavaScript is unavailable.',
-		searchUnavailable: 'Search is unavailable. During local work, run norna build:local to create or refresh the search index.',
-		siteBanners: 'Site notices',
-		siteNavigation: 'Pages',
-		skipToContent: 'Skip to content',
-		tableColumns: 'Table columns',
-		tableNextColumns: 'Show next columns',
-		tableOverflowDescription: 'More table columns are available horizontally.',
-		tablePreviousColumns: 'Show previous columns',
-	}),
-	sv: Object.freeze({
-		breadcrumb: 'Brödsmulor',
-		appearance: 'Utseende',
-		appearanceDark: 'Mörkt',
-		appearanceLight: 'Ljust',
-		appearanceSystem: 'System',
-		codeCopied: 'Kopierat',
-		codeCopyFailed: 'Kunde inte kopiera koden',
-		copyCode: 'Kopiera kod',
-		calloutCaution: 'Var försiktig',
-		calloutDanger: 'Fara',
-		calloutImportant: 'Viktigt',
-		calloutNote: 'Notera',
-		calloutTip: 'Tips',
-		calloutWarning: 'Varning',
-		closeNavigation: 'Stäng navigationen',
-		editSource: 'Redigera den här sidan',
-		displaySettings: 'Visning',
-		focusReading: 'Fokuserad läsning',
-		footnoteBackReference: 'Tillbaka till referens {reference}',
-		footnotes: 'Fotnoter',
-		readingWidth: 'Textbredd',
-		readingWidthNarrow: 'Smal',
-		readingWidthStandard: 'Standard',
-		readingWidthWide: 'Bred',
-		resetDisplaySettings: 'Återställ',
-		dismissBanner: 'Stäng meddelande',
-		built: 'Byggd',
-		images: 'Bilder',
-		imageCarousel: 'bildkarusell',
-		imageInspection: 'Bildgranskning',
-		imageInspectionActualSize: 'Visa faktisk storlek',
-		imageInspectionClose: 'Stäng bildgranskning',
-		imageInspectionFit: 'Anpassa bilden till fönstret',
-		inspectImage: 'Granska bild: {description}',
-		navigationCollapsedAll: 'Alla navigationsposter har fällts ihop.',
-		navigationCollapseAll: 'Fäll ihop alla',
-		navigationControls: 'Kontroller för navigationsträdet',
-		navigationChildren: 'Undersidor',
-		navigationExpandedAll: 'Alla navigationsposter har fällts ut.',
-		navigationExpandAll: 'Fäll ut alla',
-		navigationFilter: 'Filtrera sidor och grupper',
-		navigationFilterEmpty: 'Inga sidor eller grupper matchar. Den aktuella sidan är fortfarande tillgänglig.',
-		navigationFilterMatches: 'Matchande navigationsposter: {count}',
-		navigationLocatedCurrent: 'Den aktuella sidan har hittats.',
-		navigationLocateCurrent: 'Hitta aktuell sida',
-		navigationMenu: 'Meny',
-		nextImage: 'Nästa bild',
-		nextPage: 'Nästa sida',
-		note: 'Not',
-		openInVsCode: 'Öppna i VS Code',
-		notFound: 'Sidan hittades inte',
-		notFoundText: 'Den begärda sidan finns inte eller kan ha flyttats.',
-		pageMoved: 'Sidan har flyttats',
-		pageMovedText: 'Den här adressen identifierar nu',
-		pageNavigation: 'Sidinnehåll',
-		pageSequence: 'Sidföljd',
-		pageSections: 'Avsnitt',
-		previousImage: 'Föregående bild',
-		previousPage: 'Föregående sida',
-		returnHome: 'Gå till startsidan',
-		search: 'Sök',
-		searchDescription: 'Sök i det publicerade innehållet på webbplatsen.',
-		searchLoading: 'Laddar sökning…',
-		searchNoScript: 'Sökning kräver JavaScript. Använd sidnavigeringen när JavaScript inte är tillgängligt.',
-		searchUnavailable: 'Sökningen är inte tillgänglig. Kör norna build:local under lokalt arbete för att skapa eller uppdatera sökindexet.',
-		siteBanners: 'Meddelanden',
-		siteNavigation: 'Sidor',
-		skipToContent: 'Hoppa till innehållet',
-		tableColumns: 'Tabellkolumner',
-		tableNextColumns: 'Visa nästa kolumner',
-		tableOverflowDescription: 'Fler tabellkolumner är tillgängliga i sidled.',
-		tablePreviousColumns: 'Visa föregående kolumner',
-	}),
-});
-
-const readLocale = (config) => {
-	const lang = config.language ?? 'en';
-
-	if (typeof lang !== 'string' || !/^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]+)*$/.test(lang.trim())) {
-		throw new Error(`language must be a valid language tag such as "en" or "sv" in ${siteConfigLabel}.`);
-	}
-
-	const normalizedLang = lang.trim();
-	const languageKey = normalizedLang.toLowerCase().split('-')[0];
-	const labels = localeLabels[languageKey];
-
-	if (!labels) {
-		throw new Error(`language "${normalizedLang}" has no built-in Norna UI text. Supported languages: ${Object.keys(localeLabels).join(', ')}.`);
-	}
-
-	return Object.freeze({
-		lang: normalizedLang,
-		labels,
-	});
-};
-
 const rawConfig = assertObject(siteConfig, 'config YAML');
 const rawTheme = assertObject(themeConfig, 'theme YAML', siteThemeLabel);
 const siteUrl = readSiteUrl(rawConfig);
@@ -609,7 +438,7 @@ export const projectConfig = Object.freeze({
 			'instant',
 		),
 	}),
-	locale: readLocale(rawConfig),
+	locale: resolveLocale(rawConfig.language, siteConfigLabel),
 });
 
 export default projectConfig;

package/scripts/lib/schema-definitions.mjs

@@ -1,6 +1,7 @@
 import { z } from 'astro/zod';
 import { localEditorNames } from './edit-source-link.mjs';
 import { imagePresentationNames } from './image-presentation.mjs';
+import { supportedLocaleTagPattern } from './locale-registry.mjs';
 import { navigationModeNames } from './navigation-model.mjs';
 import { presentationPaletteNames } from './presentation-palette-metadata.mjs';
 import { themePresetNames } from './theme-presets.mjs';
@@ -25,13 +26,6 @@ const themeAppearance = z.object({
 	(value) => value.default !== undefined,
 	'Specify default.',
 ).describe('Site-wide initial appearance. The default is system.');
-const readerControls = z.object({
-	appearance: z.boolean().optional().describe('Show an Appearance control that lets readers choose System, Light, or Dark.'),
-	focusReading: z.boolean().optional().describe('Show a Focus reading control that lets readers hide navigation, breadcrumbs, and the footer. Sites with tree navigation always show this control.'),
-}).strict().refine(
-	(value) => value.appearance !== undefined || value.focusReading !== undefined,
-	'Specify appearance, focusReading, or both.',
-).describe('Optional controls for the site-wide 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', 'accented']).describe('How coordinated backgrounds are assigned to H2 sections. Non-uniform patterns are unavailable with tree navigation.');
@@ -196,7 +190,7 @@ const themeBlocks = z.object({
 	'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.'),
+	mode: navigationMode.optional().describe('How Norna presents the discovered page and heading hierarchy. Omit this to select automatic.'),
 }).strict().describe('Site-wide navigation behavior.');
 const themeSections = z.object({
 	backgroundPattern: backgroundPattern.optional().describe('Section background pattern. Alternating and accented create full-width bands with sections or top navigation; tree navigation requires uniform.'),
@@ -244,7 +238,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.'),
+	language: z.string().regex(supportedLocaleTagPattern).optional().describe('Site language tag selecting one complete built-in Norna interface language; the default is en.'),
 	editLink: editLink.optional(),
 	navigation: configNavigation.optional(),
 	search: z.boolean().optional().default(false).describe('Generate a static site search page and Pagefind index. The default is false.'),
@@ -259,7 +253,6 @@ const siteShape = {
 const themeVisualShape = {
 	preset: themePreset.optional().describe('Complete visual starting point. Add only the overrides the site actually needs.'),
 	appearance: themeAppearance.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(),

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

@@ -1,4 +1,8 @@
 import { documentationLink } from './documentation-links.mjs';
+import {
+	localeDefinitions,
+	supportedQualifiedLocaleTagPatternSource,
+} from './locale-registry.mjs';
 import { presentationPaletteNames } from './presentation-palette-metadata.mjs';
 import { getSchemaValueDefinition } from './schema-value-definitions.mjs';
 
@@ -105,20 +109,21 @@ const addValueDescriptions = (schema) => {
 const addLanguageSuggestions = (jsonSchema) => {
 	const language = jsonSchema.properties?.language;
 	if (!language) throw new Error('Generated config schema has no language property.');
-	const definition = getSchemaValueDefinition(['en', 'sv']);
 	language.default = 'en';
-	language.examples = ['en', 'sv', 'en-GB', 'sv-SE'];
+	language.examples = ['en', 'sv', 'es', 'el', 'uk', 'sr-Cyrl', 'en-GB', 'pt-BR'];
 	language.oneOf = [
-		...definition.values.map((value) => ({
-			const: value,
-			title: definition.options[value].title,
-			description: definition.options[value].description,
+		...localeDefinitions.map(({ tag, name, nativeName, script, requiresScript }) => ({
+			const: tag,
+			title: nativeName === name ? name : `${nativeName} — ${name}`,
+			description: requiresScript
+				? `Use Norna's built-in ${name} interface text in the ${script} script.`
+				: `Use Norna's built-in ${name} interface text.`,
 		})),
 		{
 			type: 'string',
-			pattern: '^(?:en|sv)-[a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)*$',
-			title: 'Regional language tag',
-			description: 'Use an English or Swedish regional language tag such as en-GB or sv-SE.',
+			pattern: supportedQualifiedLocaleTagPatternSource,
+			title: 'Regional or script-qualified tag',
+			description: 'Add a region to a supported language, such as en-GB, pt-BR, or sr-Cyrl-RS. Norna preserves the complete tag in generated HTML.',
 		},
 	];
 };
@@ -156,9 +161,9 @@ const addConfigHelp = (jsonSchema) => {
 	], ['https://example.com/', 'https://owner.github.io/repository-name/']);
 	addHelp(jsonSchema, 'language', [
 		yamlExample('language: en-GB'),
-		'Sets the page language and selects Norna\'s built-in English or Swedish interface text. The default is `en`.',
+		'Sets the language of the complete site and selects the matching built-in Norna interface text. Regional tags are preserved. The default is `en`; editorial Markdown is not translated.',
 		documentationLink('Language reference', 'configuration.md', 'language'),
-	], ['en', 'sv', 'en-GB', 'sv-SE']);
+	], ['en', 'sv', 'es', 'el', 'uk', 'sr-Cyrl', 'en-GB', 'pt-BR']);
 	addHelp(jsonSchema, 'editLink', [
 		yamlExample('editLink:\n  localEditor: vscode\n  baseUrl: https://github.com/owner/repository/edit/main/'),
 		'Links each rendered page to its `content.md` source. A loopback development preview uses the explicitly selected local editor; published output and LAN previews use the optional remote base URL. Specify either destination or both.',
@@ -188,19 +193,19 @@ const addConfigHelp = (jsonSchema) => {
 	], ['vscode']);
 	addHelp(jsonSchema, 'navigation', [
 		yamlExample('navigation:\n  mode: automatic'),
-		'Sets the site-wide navigation policy. `automatic` uses sections for one page, top navigation for a flat multi-page site, and a stable left rail throughout a hierarchical site.',
-		documentationLink('Navigation reference', 'pages.md', 'navigation'),
+		'Chooses how Norna presents the discovered page and heading hierarchy. Keep `automatic` unless the site deliberately needs to retain one presentation as its structure changes.',
+		documentationLink('Navigation setting reference', 'configuration.md', 'navigation'),
 	]);
 	addHelp(jsonSchema, 'search', [
 		yamlExample('search: true'),
-		'Generates a localized `/search/` page and a static Pagefind index during each build. Search is off by default, and only the search page loads the search JavaScript.',
+		'Generates a localized `/search/` page and a static Pagefind index during each build. Search is off by default. Only the search page loads the search engine and index; a small navigation script remembers where readers opened it.',
 		documentationLink('Search reference', 'configuration.md', 'search'),
 	], [true, false]);
 	addFieldHelp(
 		jsonSchema,
 		'navigation.mode',
 		'navigation:\n  mode: automatic',
-		'pages.md',
+		'configuration.md',
 		'navigation',
 		['automatic', 'sections', 'top', 'tree'],
 	);
@@ -278,7 +283,7 @@ const addThemeHelp = (jsonSchema) => {
 	], presentationPaletteNames);
 	addHelp(jsonSchema, 'appearance', [
 		yamlExample('appearance:\n  default: system'),
-		'Selects the initial Appearance. Omit this setting to follow the visitor\'s system preference. Enable the reader-facing choice under readerControls.',
+		'Selects the initial Appearance. The Appearance choice is always available in the site-wide Display panel. Omit this setting to follow the visitor\'s system preference.',
 		documentationLink('Appearance', 'theme.md', 'appearance'),
 	]);
 	addFieldHelp(jsonSchema, 'appearance.default', 'appearance:\n  default: system', 'theme.md', 'appearance', ['system', 'light', 'dark']);
@@ -289,32 +294,6 @@ const addThemeHelp = (jsonSchema) => {
 		file: 'theme.md',
 		anchor: 'appearance',
 	})]);
-	addHelp(jsonSchema, 'readerControls', [
-		yamlExample('readerControls:\n  appearance: true\n  focusReading: true'),
-		'Choose which optional controls readers can use in the site-wide Display panel.',
-		'`appearance: true` lets readers choose System, Light, or Dark. `focusReading: true` lets them hide navigation, breadcrumbs, and the footer while reading.',
-		'Reading width is always included. Sites with tree navigation always include Focus reading, even when it is not enabled here.',
-		documentationLink('Reader Display controls', 'theme.md', 'reader-display-controls'),
-	]);
-	for (const [propertyPath, example] of [
-		['readerControls.appearance', 'readerControls:\n  appearance: 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  appearance: ${1:true}\n  focusReading: ${2:true}',
-		description: 'Show optional Appearance and Focus reading controls. Reading width is already included, and tree navigation always includes Focus reading.',
-		file: 'theme.md',
-		anchor: 'reader-display-controls',
-	})]);
 	addHelp(jsonSchema, 'sections', [
 		yamlExample('sections:\n  backgroundPattern: alternating'),
 		'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.',
@@ -628,7 +607,7 @@ const addContentHelp = (jsonSchema) => {
 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.',
+		'`category.yaml` groups child pages without editorial content. Its URL opens the first listed direct page, or a generated child list when the first child is a category.',
 		documentationLink('Navigation category reference', 'pages.md', 'navigation-categories'),
 	].join('\n\n');
 	addHelp(jsonSchema, 'label', [

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

@@ -23,14 +23,10 @@ export const schemaValueDefinitions = Object.freeze([
 		smooth: option('Browser smooth', 'Use the browser\'s native smooth scrolling for anchor navigation.'),
 	}),
 	definition(['automatic', 'sections', 'top', 'tree'], {
-		automatic: option('Automatic', 'Choose sections for one page, top navigation for a flat multi-page site, and a stable left rail throughout a site with listed child pages or categories.'),
-		sections: option('Sections', 'Navigate the sections of the current page.'),
-		top: option('Top', 'Use pages in the top navigation and sections below them.'),
-		tree: option('Tree', 'Use a left page rail and a separate right H2/H3 contents rail where the page has enough headings.'),
-	}),
-	definition(['en', 'sv'], {
-		en: option('English', 'Use Norna\'s built-in English interface text.'),
-		sv: option('Swedish', 'Use Norna\'s built-in Swedish interface text.'),
+		automatic: option('Automatic', 'Choose one site-wide navigation presentation from the listed page hierarchy. This is the default.'),
+		sections: option('Sections', 'Keep a one-page site title and its H2 sections in sticky page navigation.'),
+		top: option('Top', 'Keep top-level pages in the global row and give the current page section navigation when needed.'),
+		tree: option('Tree', 'Keep top-level areas global and add a persistent left page tree. Deep branches can add a right H2/H3 contents rail.'),
 	}),
 	definition(['vscode'], {
 		vscode: option('Visual Studio Code', 'Open the current page source in the locally installed Visual Studio Code application.'),

package/scripts/lib/semantic-callouts.mjs

@@ -62,6 +62,7 @@ const formatDiagnostic = ({ code, fix, label, line, message, offset }) => ({
 	line,
 	message: `${label} line ${line}: ${message}`,
 	offset,
+	severity: 'error',
 });
 
 export const getSemanticCalloutDiagnostics = (tree, options = {}) => {
@@ -101,7 +102,8 @@ export const getSemanticCalloutDiagnostics = (tree, options = {}) => {
 				issue = {
 					code: 'unknown-semantic-callout-type',
 					message: `Unknown semantic callout type "${marker.rawType}".`,
-					fix: `Use one of: ${semanticCalloutTypes.join(', ')}.`,
+					fix: `Use one of: ${semanticCalloutTypes.join(', ')}. The block will remain a neutral blockquote until then.`,
+					severity: 'warning',
 				};
 			} else if (marker.title) {
 				issue = {
@@ -117,7 +119,7 @@ export const getSemanticCalloutDiagnostics = (tree, options = {}) => {
 				};
 			}
 
-			if (issue) diagnostics.push(formatDiagnostic({ ...issue, label, line, offset }));
+			if (issue) diagnostics.push({ ...formatDiagnostic({ ...issue, label, line, offset }), severity: issue.severity ?? 'error' });
 		}
 
 		for (const child of node.children ?? []) visit(child, nextBlockquoteDepth);

package/scripts/lib/site-content.mjs

@@ -67,7 +67,6 @@ const knownNestedFrontmatterKeys = new Set([
 	'palette',
 	'preset',
 	'profile',
-	'readerControls',
 	'readingWidth',
 	'rhythm',
 	'sectionGap',
@@ -171,7 +170,10 @@ export const validateFrontmatterStructure = (frontmatter, addIssue, {
 			fix = fileKind === 'page theme'
 				? 'Remove "colorMode:" from this page theme. Set "appearance:" in the root theme.yaml when an override is needed.'
 				: 'Replace "colorMode:" with "appearance:".';
-		} else if (fileKind === 'page theme' && ['preset', 'appearance', 'readerControls', 'corners', 'palette', 'typography'].includes(key)) {
+		} else if ((fileKind === 'theme' || fileKind === 'page theme') && key === 'readerControls') {
+			message = `Frontmatter line ${lineNumber}: Theme setting "readerControls" was removed. Appearance and reading width are always available; Focus reading follows tree navigation.`;
+			fix = 'Remove "readerControls:". Use "appearance.default" for the initial Appearance; reading width is always available and tree navigation provides Focus reading.';
+		} else if (fileKind === 'page theme' && ['preset', 'appearance', 'corners', '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)) {