@janga/norna 0.7.13 → 0.7.15

package/scripts/test-theme-presets.mjs

@@ -3,10 +3,12 @@ import { spawnSync } from 'node:child_process';
 import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { parseYamlMapping } from './lib/frontmatter-yaml.mjs';
-import { splitSiteFile } from './lib/site-content.mjs';
+import { load } from 'js-yaml';
+import { resolveThemePresentation } from './lib/presentation.mjs';
 import {
+	getThemePresetMetadata,
 	resolveThemeConfig,
+	themePresetDefinitions,
 	themePresetNames,
 	themePresets,
 } from './lib/theme-presets.mjs';
@@ -25,36 +27,68 @@ const runCli = (args) => spawnSync(process.execPath, [cliPath, '--site-dir', sit
 
 try {
 	assert.deepEqual(Object.keys(themePresets), themePresetNames);
+	assert.deepEqual(Object.keys(themePresetDefinitions), themePresetNames);
 	for (const presetName of themePresetNames) {
+		const metadata = getThemePresetMetadata(presetName);
+		assert.equal(metadata.name, presetName);
+		assert.ok(metadata.title);
+		assert.ok(metadata.description);
 		const resolved = resolveThemeConfig({ preset: presetName }, 'test theme');
 		assert.equal(resolved.preset, presetName);
 		assert.ok(resolved.layout?.density);
-		assert.ok(resolved.gallery?.width);
+		assert.ok(resolved.images?.width);
 		assert.ok(resolved.typography?.fontFamily);
-		assert.ok(resolved.typography?.preset);
-		assert.ok(resolved.presentation?.palette);
+		assert.ok(resolved.typography?.profile);
+		assert.ok(resolved.palette);
+		assert.ok(resolved.sectionSurfaces);
 	}
 
 	const overridden = resolveThemeConfig({
 		preset: 'documentation',
 		layout: { pageWidth: '1300px' },
-		presentation: { palette: 'dark' },
+		palette: 'dark',
 	}, 'test theme');
 	assert.equal(overridden.layout.density, 'compact');
 	assert.equal(overridden.layout.pageWidth, '1300px');
-	assert.equal(overridden.gallery.width, '920px');
-	assert.equal(overridden.presentation.palette, 'dark');
-	assert.deepEqual(overridden.presentation.sectionSurfaces.sequence, ['base', 'soft']);
+	assert.equal(overridden.images.width, '920px');
+	assert.equal(overridden.palette, 'dark');
+	assert.deepEqual(overridden.sectionSurfaces, ['base', 'soft']);
 	assert.throws(
-		() => resolveThemeConfig({ preset: 'unknown' }, 'test/theme.md'),
-		/Unknown theme preset "unknown" in test\/theme\.md.*portfolio, documentation, project, statement/,
+		() => resolveThemeConfig({ preset: 'unknown' }, 'test/theme.yaml'),
+		/Unknown theme preset "unknown" in test\/theme\.yaml.*portfolio, documentation, project, statement/,
+	);
+	assert.throws(
+		() => resolveThemePresentation({ sectionSurfaces: ['base', 'glowing'] }, 'test/theme.yaml'),
+		/Unknown section surface "glowing" in test\/theme\.yaml.*base, soft, emphasis/,
+	);
+	assert.throws(
+		() => resolveThemePresentation({ sectionSurfaces: ['base', 'base'] }, 'test/theme.yaml'),
+		/Each section surface may appear only once in test\/theme\.yaml/,
 	);
 
+	const listResult = runCli(['theme:presets']);
+	assert.equal(listResult.status, 0, listResult.stderr || listResult.stdout);
+	for (const presetName of themePresetNames) {
+		const metadata = getThemePresetMetadata(presetName);
+		assert.ok(listResult.stdout.includes(`${presetName}\n  ${metadata.description}`));
+	}
+	const invalidListResult = runCli(['theme:presets', 'documentation']);
+	assert.notEqual(invalidListResult.status, 0);
+	assert.match(invalidListResult.stderr, /Usage: norna theme:presets/);
+
+	const themeSchema = JSON.parse(await readFile(path.join(repoRoot, 'schemas', 'theme.schema.json'), 'utf8'));
+	assert.deepEqual(
+		themeSchema.properties.preset.oneOf.map((entry) => entry.const),
+		themePresetNames,
+	);
+	for (const entry of themeSchema.properties.preset.oneOf) {
+		const metadata = getThemePresetMetadata(entry.const);
+		assert.equal(entry.title, metadata.title);
+		assert.equal(entry.description, metadata.description);
+	}
+
 	await mkdir(path.join(siteDir, 'routes', '010-guide'), { recursive: true });
-	await writeFile(path.join(siteDir, 'config.md'), `---
-url: https://example.com/
----
-`);
+	await writeFile(path.join(siteDir, 'config.yaml'), 'url: https://example.com/\n');
 	await writeFile(path.join(siteDir, 'content.md'), `---
 title: Theme preset test
 description: Root page
@@ -64,15 +98,12 @@ description: Root page
 
 Root content.
 `);
-	await writeFile(path.join(siteDir, 'theme.md'), `---
-preset: documentation
+	await writeFile(path.join(siteDir, 'theme.yaml'), `preset: documentation
 layout:
   pageWidth: 1300px
-presentation:
-  palette: dark
----
+palette: dark
 `);
-	await writeFile(path.join(siteDir, 'routes', '010-guide', 'route-content.md'), `---
+	await writeFile(path.join(siteDir, 'routes', '010-guide', 'content.md'), `---
 title: Guide
 description: Route page
 navigation:
@@ -83,13 +114,10 @@ navigation:
 
 Route content.
 `);
-	await writeFile(path.join(siteDir, 'routes', '010-guide', 'theme.md'), `---
-preset: portfolio
+	await writeFile(path.join(siteDir, 'routes', '010-guide', 'theme.yaml'), `preset: portfolio
 layout:
   pageWidth: 1010px
-presentation:
-  palette: light
----
+palette: light
 `);
 
 	const buildResult = runCli(['build']);
@@ -105,31 +133,30 @@ presentation:
 
 	const typographyResult = runCli(['typography', 'show']);
 	assert.equal(typographyResult.status, 0, typographyResult.stderr || typographyResult.stdout);
-	assert.match(typographyResult.stdout, /value: text-forward/);
-	assert.match(typographyResult.stdout, /value: quiet-gallery/);
+	assert.match(typographyResult.stdout, /value: reading/);
+	assert.match(typographyResult.stdout, /value: restrained/);
 
-	const routeThemePath = path.join(siteDir, 'routes', '010-guide', 'theme.md');
+	const routeThemePath = path.join(siteDir, 'routes', '010-guide', 'theme.yaml');
 	const routeThemeSource = await readFile(routeThemePath, 'utf8');
-	await writeFile(routeThemePath, `---\npreset: unknown\n---\n`);
+	await writeFile(routeThemePath, 'preset: unknown\n');
 	const invalidRoutePresetResult = runCli(['config:check']);
 	assert.notEqual(invalidRoutePresetResult.status, 0);
-	assert.match(invalidRoutePresetResult.stderr, /Unknown theme preset "unknown" in .*routes\/010-guide\/theme\.md/);
+	assert.match(invalidRoutePresetResult.stderr, /Unknown theme preset "unknown" in .*routes\/010-guide\/theme\.yaml/);
 	await writeFile(routeThemePath, routeThemeSource);
 
 	const exportResult = runCli(['theme:export', 'documentation']);
 	assert.equal(exportResult.status, 0, exportResult.stderr || exportResult.stdout);
-	assert.match(exportResult.stdout, /orig-documentation-theme\.md/);
-	const exportedPath = path.join(siteDir, 'orig-documentation-theme.md');
+	assert.match(exportResult.stdout, /orig-documentation-theme\.yaml/);
+	const exportedPath = path.join(siteDir, 'orig-documentation-theme.yaml');
 	const exportedSource = await readFile(exportedPath, 'utf8');
-	assert.match(exportedSource, /This is a reference file\. Norna only loads theme\.md\./);
+	assert.match(exportedSource, /This is a reference file\. Norna only loads theme\.yaml\./);
 	assert.match(exportedSource, /Available theme presets: portfolio, documentation, project, statement\./);
 	assert.match(exportedSource, /# Alternatives: dark, light, paper\./);
-	const { frontmatterBody } = splitSiteFile(exportedSource, 'exported theme reference');
-	const exportedConfig = parseYamlMapping(frontmatterBody);
+	const exportedConfig = load(exportedSource);
 	assert.equal(exportedConfig.preset, 'documentation');
 	assert.equal(exportedConfig.layout.pageWidth, themePresets.documentation.layout.pageWidth);
 	assert.equal(exportedConfig.typography.fontFamily, themePresets.documentation.typography.fontFamily);
-	assert.deepEqual(exportedConfig.presentation.sectionSurfaces.sequence, ['base', 'soft']);
+	assert.deepEqual(exportedConfig.sectionSurfaces, ['base', 'soft']);
 
 	const exportAgainResult = runCli(['theme:export', 'documentation']);
 	assert.notEqual(exportAgainResult.status, 0);

package/src/components/CardList.astro

@@ -18,19 +18,16 @@ type CardListWidth = 'text' | 'narrow' | 'normal' | 'wide';
 
 interface Props {
 	cards: Card[];
-	maxAvailableWidthPercent: {
-		desktop: number;
-	};
 	layout?: CardListLayout;
 	flow?: CardListFlow;
 	size?: CardListSize;
 	width?: CardListWidth;
 }
 
-const { cards, maxAvailableWidthPercent, layout = 'image-top', flow = 'grid', size = 'm', width = 'normal' } = Astro.props;
+const { cards, layout = 'image-top', flow = 'grid', size = 'm', width = 'normal' } = Astro.props;
 const cardImageSizes = [
 	'(max-width: 700px) 100vw',
-	`min(20rem, ${maxAvailableWidthPercent.desktop}vw)`,
+	'min(20rem, 100vw)',
 ].join(', ');
 const displayLink = (link: string) => withBasePath(projectConfig.site.basePath, link);
 const cardListClasses = [

package/src/components/ImageCarousel.astro

@@ -4,15 +4,15 @@ import { getImageAttributes } from '../lib/generatedImages';
 import {
 	getCaptionId,
 	getCarouselAspectRatio,
-	getGalleryImageSizes,
+	getManagedImageSizes,
 	getImageClass,
 	getImageLoadingProps,
-	type GalleryImage,
-} from '../lib/galleryImages';
+	type ManagedImage,
+} from '../lib/imagePresentation';
 
 interface Props {
 	title: string;
-	images: GalleryImage[];
+	images: ManagedImage[];
 	maxAvailableWidthPercent: {
 		desktop: number;
 		mobile: number;
@@ -21,16 +21,16 @@ interface Props {
 }
 
 const { title, images, maxAvailableWidthPercent, priorityFirstImage = false } = Astro.props;
-const galleryImageSizes = getGalleryImageSizes(maxAvailableWidthPercent);
+const managedImageSizes = getManagedImageSizes(maxAvailableWidthPercent);
 const carouselAspectRatio = getCarouselAspectRatio(images);
 const carouselStyle = carouselAspectRatio
-	? `--gallery-carousel-aspect-ratio: ${carouselAspectRatio}`
+	? `--image-carousel-aspect-ratio: ${carouselAspectRatio}`
 	: undefined;
 ---
 
-<div class="gallery" aria-label={`${projectConfig.locale.labels.gallery}: ${title}`}>
+<div class="managed-images" aria-label={`${projectConfig.locale.labels.images}: ${title}`}>
 	<section
-		class="gallery-item gallery-carousel"
+		class="managed-image-item image-carousel"
 		data-carousel
 		tabindex="0"
 		role="group"
@@ -38,18 +38,18 @@ const carouselStyle = carouselAspectRatio
 		aria-label={`${title}, bildkarusell`}
 		style={carouselStyle}
 	>
-		<div class="gallery-carousel-stage">
-			<div class="gallery-carousel-viewport" data-carousel-viewport>
-				<div class="gallery-carousel-slides">
+		<div class="image-carousel-stage">
+			<div class="image-carousel-viewport" data-carousel-viewport>
+				<div class="image-carousel-slides">
 					{images.map((image, imageIndex) => {
 						const captionId = image.caption ? getCaptionId(image, 0, imageIndex) : undefined;
 
 						return (
-							<figure class="gallery-carousel-slide" data-carousel-slide>
-								<div class="gallery-carousel-image-frame">
+							<figure class="image-carousel-slide" data-carousel-slide>
+								<div class="image-carousel-frame">
 									<img
-										{...getImageAttributes(image.src ?? image.image, galleryImageSizes)}
-										class:list={['gallery-image', getImageClass(image)]}
+										{...getImageAttributes(image.src ?? image.image, managedImageSizes)}
+										class:list={['managed-image', getImageClass(image)]}
 										alt={image.alt ?? ''}
 										aria-describedby={captionId}
 										{...getImageLoadingProps(priorityFirstImage && imageIndex === 0)}
@@ -61,7 +61,7 @@ const carouselStyle = carouselAspectRatio
 				</div>
 			</div>
 			<button
-				class="gallery-carousel-button gallery-carousel-button-previous"
+				class="image-carousel-button image-carousel-button-previous"
 				type="button"
 				data-carousel-previous
 				aria-label="Föregående bild"
@@ -70,7 +70,7 @@ const carouselStyle = carouselAspectRatio
 				<span aria-hidden="true">‹</span>
 			</button>
 			<button
-				class="gallery-carousel-button gallery-carousel-button-next"
+				class="image-carousel-button image-carousel-button-next"
 				type="button"
 				data-carousel-next
 				aria-label="Nästa bild"
@@ -78,20 +78,20 @@ const carouselStyle = carouselAspectRatio
 			>
 				<span aria-hidden="true">›</span>
 			</button>
-			<output class="gallery-carousel-position" data-carousel-position aria-live="polite">
+			<output class="image-carousel-position" data-carousel-position aria-live="polite">
 				1 / {images.length}
 			</output>
 		</div>
-		<div class="gallery-carousel-captions" data-carousel-captions>
+		<div class="image-carousel-captions" data-carousel-captions>
 			{images.map((image, imageIndex) => (
 				image.caption && (
 					<p
-						class="gallery-meta gallery-carousel-caption"
+						class="image-meta image-carousel-caption"
 						id={getCaptionId(image, 0, imageIndex)}
 						data-carousel-caption
 						data-carousel-caption-index={imageIndex}
 					>
-						<span class="gallery-details">
+						<span class="image-details">
 							<span>{image.caption}</span>
 						</span>
 					</p>

package/src/components/{GalleryGrid.astro → ImageStack.astro}

@@ -3,15 +3,15 @@ import projectConfig from '../../scripts/lib/project-config.mjs';
 import { getImageAttributes } from '../lib/generatedImages';
 import {
 	getCaptionId,
-	getGalleryImageSizes,
+	getManagedImageSizes,
 	getImageClass,
 	getImageLoadingProps,
-	type GalleryImage,
-} from '../lib/galleryImages';
+	type ManagedImage,
+} from '../lib/imagePresentation';
 
 interface Props {
 	title: string;
-	images: GalleryImage[];
+	images: ManagedImage[];
 	maxAvailableWidthPercent: {
 		desktop: number;
 		mobile: number;
@@ -20,28 +20,28 @@ interface Props {
 }
 
 const { title, images, maxAvailableWidthPercent, priorityFirstImage = false } = Astro.props;
-const galleryImageSizes = getGalleryImageSizes(maxAvailableWidthPercent);
+const managedImageSizes = getManagedImageSizes(maxAvailableWidthPercent);
 ---
 
-<div class="gallery" aria-label={`${projectConfig.locale.labels.gallery}: ${title}`}>
+<div class="image-stack" aria-label={`${projectConfig.locale.labels.images}: ${title}`}>
 	{images.map((image, itemIndex) => {
 		const isPriorityItem = priorityFirstImage && itemIndex === 0;
 		const captionId = image.caption ? getCaptionId(image, itemIndex) : undefined;
 
 		return (
-			<figure class="gallery-item">
-				<div class="gallery-image-frame">
+			<figure class="managed-image-item">
+				<div class="managed-image-frame">
 					<img
-						{...getImageAttributes(image.src ?? image.image, galleryImageSizes)}
-						class:list={['gallery-image', getImageClass(image)]}
+						{...getImageAttributes(image.src ?? image.image, managedImageSizes)}
+						class:list={['managed-image', getImageClass(image)]}
 						alt={image.alt ?? ''}
 						aria-describedby={captionId}
 						{...getImageLoadingProps(isPriorityItem)}
 					/>
 				</div>
 				{image.caption && (
-					<figcaption class="gallery-meta" id={captionId}>
-						<div class="gallery-details">
+					<figcaption class="image-meta" id={captionId}>
+						<div class="image-details">
 							<span>{image.caption}</span>
 						</div>
 					</figcaption>

package/src/components/SectionNavigationScript.astro

@@ -0,0 +1,28 @@
+<script>
+	const siteTop = document.querySelector<HTMLElement>('.site-top');
+	const mobileMenu = document.querySelector<HTMLDetailsElement>('.mobile-nav-menu');
+	const mobileSectionLinks = Array.from(document.querySelectorAll<HTMLAnchorElement>('.mobile-page-nav a'));
+
+	const setAnchorOffset = () => {
+		if (!siteTop) return;
+
+		const offset = Math.ceil(siteTop.getBoundingClientRect().height);
+		document.documentElement.style.setProperty('--site-top-anchor-offset', `${offset}px`);
+	};
+
+	mobileSectionLinks.forEach((link) => {
+		link.addEventListener('click', (event) => {
+			const linkUrl = new URL(link.href, window.location.href);
+			if (linkUrl.pathname !== window.location.pathname) return;
+
+			if (mobileMenu) mobileMenu.open = false;
+			if (event.detail > 0) link.blur();
+		});
+	});
+
+	setAnchorOffset();
+
+	if (siteTop && 'ResizeObserver' in window) {
+		new ResizeObserver(setAnchorOffset).observe(siteTop);
+	}
+</script>

package/src/components/SiteNavigation.astro

@@ -3,7 +3,7 @@ import projectConfig from '../../scripts/lib/project-config.mjs';
 import { withBasePath } from '../lib/basePath';
 import type { SectionNavigation } from '../lib/sectionContent';
 import type { SitePage } from '../lib/sitePages';
-import MobileSectionNavigationScript from './MobileSectionNavigationScript.astro';
+import SectionNavigationScript from './SectionNavigationScript.astro';
 
 type FrameColors = {
 	backgroundColor: string;
@@ -11,7 +11,7 @@ type FrameColors = {
 };
 
 interface Props {
-	brandLabel: string;
+	navigationLabel: string;
 	logo?: {
 		src: string;
 		alt: string;
@@ -25,7 +25,7 @@ interface Props {
 	frameColors: FrameColors;
 }
 
-const { brandLabel, logo, currentPage, pageNavigation, frameColors } = Astro.props;
+const { navigationLabel, logo, currentPage, pageNavigation, frameColors } = Astro.props;
 const siteTopBackgroundColor = frameColors.backgroundColor === 'transparent'
 	? 'var(--color-page)'
 	: frameColors.backgroundColor;
@@ -48,6 +48,7 @@ const showSinglePageSectionNavigation = Boolean(
 const hasCurrentPageSectionMenu = Boolean(
 	showSiteNavigation && currentPageNavigation && hasSectionMenu(currentPageNavigation.sections),
 );
+const hasSectionNavigation = showSinglePageSectionNavigation || hasCurrentPageSectionMenu;
 ---
 
 <a class="skip-link" href="#main-content">{projectConfig.locale.labels.skipToContent}</a>
@@ -59,7 +60,7 @@ const hasCurrentPageSectionMenu = Boolean(
 	{showNavigationRow && (
 		<div class="site-nav-row">
 			<a class="site-brand" href={pageHref(homePage)}>
-				{logo ? <img class="site-brand-logo" src={withBasePath(projectConfig.site.basePath, logo.src)} alt={logo.alt} /> : brandLabel}
+				{logo ? <img class="site-brand-logo" src={withBasePath(projectConfig.site.basePath, logo.src)} alt={logo.alt} /> : navigationLabel}
 			</a>
 
 			{showSiteNavigation && (
@@ -140,4 +141,4 @@ const hasCurrentPageSectionMenu = Boolean(
 
 </header>
 
-{hasCurrentPageSectionMenu && <MobileSectionNavigationScript />}
+{hasSectionNavigation && <SectionNavigationScript />}

package/src/components/SitePage.astro

@@ -27,15 +27,15 @@ const siteDirectory = (process.env.NORNA_SITE_DIR ?? 'site').trim();
 const sitePages = getSitePages(await getCollection('site'));
 const currentPage = getSitePage(entry);
 const siteContentLabel = entry.id.includes('-route-')
-	? `${siteDirectory || 'site'}/routes/${currentPage.routeDirectory}/route-content.md`
+	? `${siteDirectory || 'site'}/routes/${currentPage.routeDirectory}/content.md`
 	: `${siteDirectory || 'site'}/content.md`;
 const pageContentPath = currentPage.routeDirectory
-	? path.join(siteRoutesDir, currentPage.routeDirectory, 'route-content.md')
+	? path.join(siteRoutesDir, currentPage.routeDirectory, 'content.md')
 	: siteContentPath;
 const rawMarkdown = (await readSiteFile(pageContentPath, siteContentLabel)).body;
 const [siteTheme] = await getCollection('theme');
 if (!siteTheme) {
-	throw new Error('site/theme.md is required. Add a root theme before building the site.');
+	throw new Error('site/theme.yaml is required. Add a root theme before building the site.');
 }
 const [sitewide] = await getCollection('sitewide');
 const sitewideData = sitewide?.data ?? {};
@@ -46,15 +46,15 @@ const routeTheme = await getRouteTheme(currentPage.routeDirectory);
 const themeData = routeTheme?.data ?? siteThemeData;
 const themeLabel = routeTheme
 	? `${siteDirectory || 'site'}/${routeTheme.id}`
-	: `${siteDirectory || 'site'}/theme.md`;
+	: `${siteDirectory || 'site'}/${siteTheme.id}`;
 const visualTheme = resolveThemeVisualConfig(themeData, themeLabel);
-const brandLabel = sitewideData.navigation?.brand ?? homePage.title;
+const navigationLabel = sitewideData.navigation?.label ?? homePage.title;
 const logoAsset = getLogoAsset();
 const logoSettings = sitewideData.navigation?.logo;
 const logo = logoAsset
 	? {
 		src: logoAsset.href,
-		alt: logoSettings?.alt ?? brandLabel,
+		alt: navigationLabel,
 		height: logoSettings?.height,
 	}
 	: undefined;
@@ -98,7 +98,7 @@ if (visibleSections.length === 0) {
 	footer={sitewideData.footer}
 >
 	<SiteNavigation
-		brandLabel={brandLabel}
+		navigationLabel={navigationLabel}
 		logo={logo}
 		currentPage={currentPage}
 		pageNavigation={pageNavigation}
@@ -114,7 +114,7 @@ if (visibleSections.length === 0) {
 				visualTheme={visualTheme}
 				sectionIndex={index}
 				headingLevel={index === 0 ? 1 : 2}
-				priorityGalleryImage={index === 0}
+				prioritizeFirstImage={index === 0}
 			/>
 		))}
 	</main>

package/src/components/SiteSection.astro

@@ -2,8 +2,8 @@
 import projectConfig from '../../scripts/lib/project-config.mjs';
 import { resolveSectionSurface } from '../../scripts/lib/presentation.mjs';
 import CardList from './CardList.astro';
-import GalleryGrid from './GalleryGrid.astro';
 import ImageCarousel from './ImageCarousel.astro';
+import ImageStack from './ImageStack.astro';
 import type { ResolvedSection } from '../lib/sectionContent';
 
 type ResponsiveValue<T> = { desktop: T; mobile: T };
@@ -15,17 +15,14 @@ type ResolvedPagePresentation = {
 	palette: {
 		surfaces: Record<'base' | 'soft' | 'emphasis', { backgroundColor: string; textColor: string }>;
 	};
-	sectionSurfaces: {
-		mode: 'none' | 'cycle';
-		sequence: Array<'base' | 'soft' | 'emphasis'>;
-	};
+	sectionSurfaces: Array<'base' | 'soft' | 'emphasis'>;
 	typography: {
-		preset: string;
+		profile: string;
 		values: any;
 	};
 };
 type VisualTheme = {
-	gallery: {
+	images: {
 		maxAvailableWidthPercent: {
 			desktop: number;
 			mobile: number;
@@ -39,10 +36,10 @@ interface Props {
 	visualTheme: VisualTheme;
 	sectionIndex: number;
 	headingLevel: 1 | 2;
-	priorityGalleryImage?: boolean;
+	prioritizeFirstImage?: boolean;
 }
 
-const { section, pagePresentation, visualTheme, sectionIndex, headingLevel, priorityGalleryImage = false } = Astro.props;
+const { section, pagePresentation, visualTheme, sectionIndex, headingLevel, prioritizeFirstImage = false } = Astro.props;
 const HeadingTag = headingLevel === 1 ? 'h1' : 'h2';
 // Sections are authored with Markdown ## headings even when the first one renders as HTML h1.
 const sectionHeadingVisualLevel = 'h2';
@@ -169,7 +166,7 @@ const getHeadingSizeValue = (level: HeadingLevel, size: TextSize) => (
 const textWidthValues: Record<TextWidth, string> = {
 	narrow: 'min(60ch, var(--text-width))',
 	normal: 'min(72ch, var(--text-width))',
-	wide: 'min(72ch, var(--gallery-layout-width))',
+	wide: 'min(72ch, var(--image-layout-width))',
 };
 const surface = resolveSectionSurface(pagePresentation, sectionIndex);
 const typography = pagePresentation.typography.values;
@@ -213,7 +210,7 @@ const bodyWidth = {
 	desktop: bodyWidthValue,
 	mobile: bodyWidthValue,
 };
-const isMediaBlock = (block: ResolvedSection['contentBlocks'][number]) => (
+const isStructuredBlock = (block: ResolvedSection['contentBlocks'][number]) => (
 	block.type === 'image-stack'
 	|| block.type === 'image-carousel'
 	|| block.type === 'card-list'
@@ -243,7 +240,7 @@ const flushReadingBlocks = () => {
 };
 
 for (const block of section.contentBlocks) {
-	if (isMediaBlock(block)) {
+	if (isStructuredBlock(block)) {
 		flushReadingBlocks();
 		contentGroups.push({ type: 'media', block });
 	} else {
@@ -301,7 +298,7 @@ const sectionStyle = [
 ---
 
 <section
-	id={section.id}
+	aria-labelledby={section.id}
 	class:list={[
 		'site-section',
 		{
@@ -314,10 +311,10 @@ const sectionStyle = [
 >
 	<div class="section-card">
 		<header class="section-header">
-			<HeadingTag set:html={section.titleHtml} />
+			<HeadingTag id={section.id} set:html={section.titleHtml} />
 		</header>
 
-		<div class:list={['section-body', { 'section-body-has-gallery': hasMedia, 'section-body-text-only': !hasMedia }]}>
+		<div class:list={['section-body', { 'section-body-has-media': hasMedia, 'section-body-text-only': !hasMedia }]}>
 			{contentGroups.map((group, groupIndex) => {
 				if (group.type === 'reading') {
 					if (hasMarginNotes && group.blocks.some((block) => block.type === 'note')) {
@@ -383,22 +380,22 @@ const sectionStyle = [
 						<ImageCarousel
 							title={section.title}
 							images={block.images}
-							maxAvailableWidthPercent={visualTheme.gallery.maxAvailableWidthPercent}
-							priorityFirstImage={priorityGalleryImage && groupIndex === 0}
+							maxAvailableWidthPercent={visualTheme.images.maxAvailableWidthPercent}
+							priorityFirstImage={prioritizeFirstImage && groupIndex === 0}
 						/>
 					);
 				}
 
 				if (block.type === 'card-list') {
-					return <CardList cards={block.cards} maxAvailableWidthPercent={visualTheme.gallery.maxAvailableWidthPercent} layout={block.layout} flow={block.flow} size={block.size} width={block.width} />;
+					return <CardList cards={block.cards} layout={block.layout} flow={block.flow} size={block.size} width={block.width} />;
 				}
 
 				return (
-					<GalleryGrid
+					<ImageStack
 						title={section.title}
 						images={block.images}
-						maxAvailableWidthPercent={visualTheme.gallery.maxAvailableWidthPercent}
-						priorityFirstImage={priorityGalleryImage && groupIndex === 0}
+						maxAvailableWidthPercent={visualTheme.images.maxAvailableWidthPercent}
+						priorityFirstImage={prioritizeFirstImage && groupIndex === 0}
 					/>
 				);
 			})}