@janga/norna 0.7.9 → 0.7.11

package/README.md

@@ -23,8 +23,9 @@ A `norna` site is file-driven:
 1. A site repository depends on this package.
 2. The site keeps technical settings, including public URL and optional URL
    base path, in `site/config.mjs`.
-3. The site keeps site-wide visual theme defaults, including layout, image
-   sizing, font, typography, colors, and frame colors, in `site/theme.md`.
+3. The site selects a complete visual preset, with optional focused overrides
+   for layout, image sizing, font, typography, palettes, and section surfaces,
+   in `site/theme.md`.
 4. The site keeps homepage content, Markdown section order, managed media
    blocks, alt text, captions, and optional section metadata in
    `site/content.md`.
@@ -81,6 +82,7 @@ Actions use the same engine version.
 - Publish under a GitHub Pages project path:
   [`site.basePath`](docs/configuration.md#sitebasepath)
 - Configure site-wide theme: [Theme](docs/theme.md)
+- Export a theme preset for inspection: [`theme:export`](docs/commands.md#command-summary)
 - Add route pages: [Routes](docs/routes.md)
 - Set page width: [`layout.pageWidth`](docs/theme.md#layout)
 - Set side gutters: [`layout.gutter`](docs/theme.md#layout)

package/bin/norna-cli.mjs

@@ -17,6 +17,7 @@ Commands:
   config:check           Validate site/config.mjs
   content:check          Validate site/content.md and image references
   content:sync           Move misplaced Norna-managed images and refresh generated images
+  theme:export           Export a commented theme preset reference
   typography presets     Show built-in typography preset values
   typography show        Show resolved typography for the selected site
   site:public            Sync site/public/ to public/
@@ -131,6 +132,8 @@ try {
 	} else if (command === 'content:sync') {
 		await runScript('scripts/sync-content-sections.mjs', ['--write', ...rest]);
 		await runScript('scripts/generate-images.mjs', rest);
+	} else if (command === 'theme:export') {
+		await runScript('scripts/export-theme-preset.mjs', rest);
 	} else if (command === 'typography:presets' || (command === 'typography' && subcommand === 'presets')) {
 		const scriptArgs = command === 'typography' ? subcommandRest : rest;
 		await runScript('scripts/show-typography.mjs', ['presets', ...scriptArgs]);

package/docs/README.md

@@ -10,13 +10,14 @@ For a site maintainer:
 1. [Getting Started](getting-started.md)
 2. [Site Structure](site-structure.md)
 3. [Theme](theme.md)
-4. [Configuration](configuration.md)
-5. [Content](content.md)
-6. [Typography](typography.md)
-7. [Routes](routes.md)
-8. [Images And Metadata](images-and-metadata.md)
-9. [Local Development](local-development.md)
-10. [Publishing](publishing.md)
+4. [Sitewide Content](sitewide-content.md)
+5. [Configuration](configuration.md)
+6. [Content](content.md)
+7. [Typography](typography.md)
+8. [Routes](routes.md)
+9. [Images And Metadata](images-and-metadata.md)
+10. [Local Development](local-development.md)
+11. [Publishing](publishing.md)
 
 For a developer integrating or updating the engine:
 
@@ -37,13 +38,16 @@ For design and naming principles:
 For a quick reference:
 
 - [Configuration](configuration.md) describes technical `site/config.mjs`
-  fields such as URL, base path, locale labels, footer, GitHub, and deploy
+  fields such as URL, base path, locale labels, GitHub, and deploy
   settings.
+- [Sitewide Content](sitewide-content.md) describes shared site identity, banners
+  and footer content in `site/sitewide-content.md`.
 - [Content](content.md) describes page frontmatter, Markdown-authored
-  sections, optional section metadata, managed media blocks, temporary
-  sections, and content validation.
-- [Theme](theme.md) describes site-wide layout, layout density, image sizing,
-  font, typography rhythm, presentation colors, frame colors, and inline styles.
+  sections, optional section metadata, managed media blocks, temporary sections,
+  and content validation.
+- [Theme](theme.md) describes complete visual presets, focused overrides,
+  preset export, layout, image sizing, typography, palettes, and section
+  surfaces.
 - [Typography](typography.md) describes presets, rhythms, roles, overrides,
   inheritance, and inspection commands.
 - [Routes](routes.md) describes route files, slugs, route navigation, and

package/docs/commands.md

@@ -25,6 +25,7 @@ norna dev:stop
 norna config:check
 norna content:check
 norna content:sync
+norna theme:export <preset>
 norna typography presets
 norna typography show
 norna site:public
@@ -72,6 +73,7 @@ npm run norna:check
 npm run norna:config:check
 npm run norna:content:check
 npm run norna:sync
+npm run norna:theme:export -- <preset>
 npm run norna:typography:presets
 npm run norna:typography:show
 npm run norna:public
@@ -106,6 +108,10 @@ should normally mean the repository's complete publishable artifact, while
 - `content:sync` / `norna:sync`: moves misplaced referenced image files after
   confirmation when the intended move is unambiguous. Moving files between the
   homepage and routes, or between routes, requires a clean Git working tree.
+- `theme:export <preset>`: writes a protected, commented
+  `orig-<preset>-theme.md` reference under the selected site directory. The
+  available complete theme presets are `portfolio`, `documentation`,
+  `project`, and `statement`. Norna continues to load only `theme.md`.
 - `typography presets`: prints the exact built-in values for typography
   presets and rhythms.
 - `typography show`: prints the selected site's resolved typography for the

package/docs/configuration.md

@@ -64,6 +64,7 @@ Visual configuration lives in `site/theme.md`, not `site/config.mjs`.
 
 Use [Theme](theme.md) for:
 
+- complete theme presets and focused overrides
 - `layout.pageWidth`
 - `layout.gutter`
 - `layout.density`
@@ -72,7 +73,7 @@ Use [Theme](theme.md) for:
 - `gallery.maxAvailableHeightPercent`
 - `typography.fontFamily`
 - typography presets, rhythm, and overrides
-- presentation colors, inline styles, and frame colors
+- presentation palettes and section surfaces
 
 ## Navigation
 
@@ -141,6 +142,10 @@ Fields:
   `Sections`.
 - `locale.labels.menu`: mobile menu summary text, default `Menu`.
 - `locale.labels.closeMenu`: reserved close-menu label, default `Close menu`.
+- `locale.labels.dismissBanner`: banner dismissal button label, default
+  `Dismiss notice`.
+- `locale.labels.siteBanners`: ARIA label for the banner stack, default
+  `Site notices`.
 - `locale.labels.gallery`: Norna managed media ARIA label prefix, default
   `Images`.
 
@@ -160,60 +165,11 @@ locale: {
 }
 ```
 
-## Footer
+## Sitewide Content
 
-### `footer.copyrightMessage`
-
-- Purpose: optional footer sentence.
-- Type: string.
-- Required: no.
-- Default: hidden.
-- Validation: if set, it must be a non-empty string. `undefined`, `null`, and
-  `''` are treated as absent.
-- Consequence: footer rendering is enabled when this or enabled build info is
-  present.
-
-### `footer.buildInfo`
-
-- Purpose: optional footer build timestamp.
-- Type: object, `false`, `null`, or omitted.
-- Required: no.
-- Default: hidden.
-- Validation: object fields are validated when the object is present. `false`,
-  `null`, or omission hides build info.
-
-Fields:
-
-- `footer.buildInfo.enabled`: boolean, default `true`.
-- `footer.buildInfo.text`: required non-empty string.
-- `footer.buildInfo.dateTimeFormat`: required object.
-- `footer.buildInfo.dateTimeFormat.locale`: required string.
-- `footer.buildInfo.dateTimeFormat.timeZone`: required string.
-- `footer.buildInfo.dateTimeFormat.dateStyle`: required string.
-- `footer.buildInfo.dateTimeFormat.timeStyle`: required string.
-
-The date/time object must be accepted by `Intl.DateTimeFormat`.
-
-Example:
-
-```js
-footer: {
-	copyrightMessage: '(c) Example Artist.',
-	buildInfo: {
-		enabled: true,
-		text: 'Built',
-		dateTimeFormat: {
-			locale: 'en-GB',
-			timeZone: 'UTC',
-			dateStyle: 'short',
-			timeStyle: 'short',
-		},
-	},
-}
-```
-
-If both `footer.copyrightMessage` and enabled `footer.buildInfo` are absent, the
-footer is not rendered.
+Shared site identity, banners and footer content are defined in
+`site/sitewide-content.md`. See [Sitewide Content](sitewide-content.md) for the
+schema and examples.
 
 ## GitHub
 

package/docs/content.md

@@ -18,9 +18,6 @@ The Astro content schema validates these top-level fields in page files:
 - `title`: required string. Rendered as the document title.
 - `description`: required string. Rendered as the meta description.
 - `navigation`: optional page navigation metadata. See [Routes](routes.md).
-- `presentation`: optional page-level presentation overrides. See
-  [Theme](theme.md) and [Typography](typography.md).
-- `frame`: optional page-level frame color source. See [Theme](theme.md).
 - `sections`: optional section metadata keyed by section id.
 
 Minimal homepage:
@@ -71,16 +68,18 @@ current section, not new sections.
 ## Section Metadata
 
 Use `sections` only when a section needs structured metadata that is not
-naturally expressed by Markdown, such as visibility or presentation overrides.
+naturally expressed by Markdown. Currently this is date-based visibility.
 
 ```yaml
 sections:
   work:
-    presentation:
-      typography:
-        preset: statement
+    visible:
+      from: "2026-08-01"
+      until: "2026-09-16"
 ```
 
+See [Temporary Sections](#temporary-sections) for visibility semantics.
+
 Each `sections.<section-id>` key must match a Markdown heading id in the same
 page file:
 
@@ -270,14 +269,16 @@ NORNA_TODAY=2026-08-15 npm run norna:build
 
 ## Markdown Text
 
-Inline styles use this Markdown form:
+Use ordinary Markdown for emphasis and structure:
 
 ```md
-This sentence contains [highlighted text]{.highlight}.
+This sentence contains **important text** and *emphasised text*.
 ```
 
-Inline style definitions live in `site/theme.md`. See
-[Theme](theme.md#inline-styles).
+Norna intentionally does not support arbitrary inline color or style classes.
+Deprecated syntax such as `[highlighted text]{.yellow}` is rejected by
+`content:check`. Keep the route visually coherent through its `theme.md`
+instead of styling individual phrases.
 
 ## Validation And Sync
 
@@ -289,27 +290,25 @@ npm run norna:content:check
 
 This checks section heading ids, section metadata, duplicate image names,
 missing image files, misplaced referenced images, duplicate image references,
-invalid managed media blocks, unreferenced images, undefined inline styles,
+invalid managed media blocks, unreferenced images, removed inline style syntax,
 Markdown image references to unmanaged local files, and common frontmatter
 indentation and structure mistakes.
 
 Frontmatter uses YAML indentation. Use ordinary spaces, not tabs or
 non-breaking spaces. `content:check` reports a focused error when indentation is
 invalid, when a key is indented under a line that already has a value, or when a
-known nested key such as section-specific `typography` appears at the top
-level:
+known nested key appears at the top level:
 
 ```yaml
-presentation:
-  typography:
-    preset: quiet-gallery
-    overrides:
-      body:
-        paragraphSpacing: 0.8em
+sections:
+  intro:
+    visible:
+      from: "2026-08-01"
 ```
 
 Top-level page frontmatter may contain only `title`, `description`,
-`navigation`, `presentation`, `frame`, and `sections`.
+`navigation`, and `sections`. Visual settings belong in the root or route-local
+`theme.md`.
 
 Run:
 

package/docs/design/norna-diagram-design.md

@@ -67,6 +67,8 @@ Diagrams must match the current Norna model:
 
 - A Norna site is described with site files, not arbitrary project structure.
 - `content.md` is the homepage content file.
+- `sitewide-content.md` contains shared site identity, banners, and footer
+  content.
 - Additional pages are route directories with `route-content.md`.
 - Route folder prefixes control route presentation order.
 - Route ids become default URL slugs.

package/docs/design/site-examples-structure.md

@@ -10,7 +10,8 @@ files are product documentation, which files are examples, and which files are
 test fixtures.
 
 The repository grew from one local demo, one starter, and a set of tests. The
-current structure keeps those roles separate.
+current structure keeps those roles distinct while allowing runnable examples
+to serve as documentation and realistic integration tests.
 
 ## Terms
 
@@ -26,8 +27,8 @@ site repository. It should not be a showcase for every feature.
 An example site is a runnable site that demonstrates one or more features.
 
 Examples can be richer than the starter. They may show routes, navigation,
-typography presets, typography rhythms, image stacks, image carousels, inline
-styles, and site-specific configuration choices.
+complete theme presets, image stacks, image carousels, cards, notes, surfaces,
+and site-specific configuration choices.
 
 ### Documentation Site
 
@@ -54,26 +55,37 @@ A fixture is test data.
 It should be minimal, stable, and optimized for regression tests rather than
 for human reading or visual appeal.
 
-## Intended Direction
+## Repository Structure
 
 Runnable site examples are collected under `examples/`:
 
 ```text
 examples/
-  dog-gallery/
-  routes-demo/
-  typography-demo/
+  complete-sites/
+    dog-shelter-single-page/
+    dog-shelter-multi-page/
+  feature-demos/
+    theme-presets/
+    media-and-surfaces/
 ```
 
-Only `dog-gallery/` exists today. Additional examples should be added when
-they demonstrate a distinct feature or workflow.
+`complete-sites/` contains coherent sites that show how Norna files work
+together in a realistic project:
 
-- `dog-gallery/`: current local visual demo, manual inspection site, and
-  navigation diagnostic target.
-- `routes-demo/`: focused route/navigation example if the dog example becomes
-  too broad.
-- `typography-demo/`: focused typography preset, rhythm, and override example
-  if needed.
+- `dog-shelter-single-page/`: sections and managed images without routes.
+- `dog-shelter-multi-page/`: ordered routes with route-local content and
+  images.
+
+`feature-demos/` contains focused visual test benches:
+
+- `theme-presets/`: one route per complete built-in theme preset, without
+  overrides.
+- `media-and-surfaces/`: managed media blocks, notes, palettes and section
+  surfaces. This is also the broad demo-build and navigation-test target.
+
+The repository Pages workflow builds all four examples and publishes them
+under `/norna/examples/`. The HTML documentation links to those rendered sites
+from its Examples route.
 
 The repository-local `site/` directory is reserved for the documentation site.
 `docs/` should remain for reference documentation. It should link to the
@@ -82,8 +94,8 @@ documentation site when visual explanation is more useful than reference text.
 `starters/basic/` stays separate from examples because it is copied by
 `norna init`. It should stay small and conservative.
 
-Fixtures may either stay under `fixtures/` or move under a clearly named test
-area later. They should not be confused with examples.
+Fixtures stay under `fixtures/`. They are intentionally smaller and more stable
+than examples and should not be confused with user-facing sites.
 
 ## Constraints
 
@@ -91,11 +103,10 @@ area later. They should not be confused with examples.
 - Do not make the documentation site the only documentation.
 - Do not let examples become required input for production site repositories.
 - Keep `norna init` deterministic and easy to test.
-- Keep engine tests using stable fixtures, not visually evolving demo content.
-
-## Open Decisions
+- Use examples for build, navigation and visual integration tests where the
+  user-facing site is the behavior being protected.
+- Use fixtures for isolated edge cases, invalid input and narrowly scoped
+  engine regressions.
 
-- Whether the documentation site should be published anywhere, or exist only as
-  a local/example build.
-- How local example selection should work when there are multiple runnable
-  examples.
+The repository-local `site/` remains the product documentation site and is not
+an example or fixture.

package/docs/engine-development.md

@@ -19,8 +19,8 @@ This document is for work on the reusable `norna` package itself.
 - `tests/`: Playwright navigation diagnostics.
 - `fixtures/basic/site/`: minimal site used for engine checks.
 - `starters/basic/`: copyable site starter.
-- `examples/dog-gallery/site/`: visual dog example used by demo builds and
-  navigation diagnostics.
+- `examples/feature-demos/media-and-surfaces/site/`: broad visual example used
+  by demo builds and navigation diagnostics.
 
 The repository-local `site/` directory is reserved for a local documentation
 site. It is useful for dogfooding `norna` documentation, but it is not the
@@ -34,11 +34,18 @@ Run focused checks while developing:
 npm run test:content-check
 npm run test:site-public
 npm run test:fixture:build
+npm run test:examples
 npm run demo:build
 npm run package:check
 ```
 
-`npm run test` runs the standard non-demo check sequence.
+`npm run test:examples` builds every complete site and feature demo under
+`examples/`. `npm run test` includes those builds in the standard check
+sequence.
+
+`npm run build:pages` is specific to this repository. It builds the
+documentation site and assembles rendered examples under `dist/examples/` for
+the shared GitHub Pages artifact. It is not a generic Norna site command.
 
 The root `site/` directory is the documentation site. Use the ordinary local
 commands for it:
@@ -48,12 +55,11 @@ npm run dev:local
 npm run build
 ```
 
-The dog example remains the visual demo and navigation diagnostic target:
+The media-and-surfaces feature demo is the broad visual and navigation
+diagnostic target:
 
 ```sh
-cd examples/dog-gallery/site
-node ../../../bin/norna.mjs dev:local
-cd ../../..
+node bin/norna.mjs --site-dir examples/feature-demos/media-and-surfaces/site dev:local
 npm run demo:build
 ```
 

package/docs/getting-started.md

@@ -57,6 +57,7 @@ The starter contains:
 - `.github/workflows/deploy.yml` for GitHub Pages
 - `site/config.mjs`
 - `site/theme.md`
+- `site/sitewide-content.md`
 - `site/content.md`
 - `site/public/robots.txt`
 
@@ -88,21 +89,21 @@ Relevant documentation: [Commands](commands.md), [Site Structure](site-structure
 ## First Edits
 
 1. Edit `site/config.mjs` for the site's URL, language labels, GitHub
-   repository, footer, and deploy settings.
-2. Edit `site/theme.md` for site-wide layout, layout density, typography
-   rhythm, image sizing, font, typography preset, colors, inline styles, and
-   frame colors, or omit it to use engine defaults.
-3. Edit `site/content.md` for homepage title, description, Markdown sections,
-   text, Norna managed media blocks, page/section presentation overrides, alt
-   text, and captions.
-4. Put source images under `site/images/<section-id>/`, where `<section-id>`
+   repository, and deploy settings.
+2. Edit `site/sitewide-content.md` for the shared brand or logo, banners and
+   footer content.
+3. Keep `site/theme.md` and select a complete theme preset. Add focused visual
+   overrides only when the preset needs adjustment.
+4. Edit `site/content.md` for homepage title, description, Markdown sections,
+   text, Norna managed media blocks, alt text, and captions.
+5. Put source images under `site/images/<section-id>/`, where `<section-id>`
    matches a `## Section {#section-id}` heading in `site/content.md`.
-5. Add optional route pages under
+6. Add optional route pages under
    `site/routes/<NNN-route-id>/route-content.md`, for example
    `site/routes/010-about/route-content.md`.
-6. Put static files such as `robots.txt`, `CNAME`, and favicons under
+7. Put static files such as `robots.txt`, `CNAME`, and favicons under
    `site/public/`.
-7. Run:
+8. Run:
 
 ```sh
 npm run norna:config:check
@@ -122,6 +123,42 @@ publishing.
 Relevant documentation: [Content](content.md), [Theme](theme.md),
 [Typography](typography.md), [Routes](routes.md), [Images And Metadata](images-and-metadata.md).
 
+## Choose A Theme
+
+The required root `theme.md` can be deliberately short:
+
+```yaml
+---
+preset: project
+---
+```
+
+Available complete presets are `portfolio`, `documentation`, `project`, and
+`statement`. They coordinate layout, image sizing, font, typography, spacing,
+palette, and section surfaces.
+
+Override only what the site needs to change:
+
+```yaml
+---
+preset: project
+layout:
+  pageWidth: 1240px
+---
+```
+
+Export a commented reference for a preset with:
+
+```sh
+npm run norna:theme:export -- project
+```
+
+The generated `site/orig-project-theme.md` is reference material and is not
+loaded by Norna. The command does not overwrite an existing reference file.
+
+Relevant documentation: [Theme](theme.md), [Typography](typography.md),
+[Commands](commands.md).
+
 ## Configure The Public URL
 
 For a custom domain or any site published at the web root, use:
@@ -157,13 +194,13 @@ Read [Site Structure](site-structure.md), [Content](content.md),
 [Theme](theme.md), [Typography](typography.md), [Routes](routes.md), and
 [Configuration](configuration.md) before publishing a real site.
 
-To change the site's maximum page width, side gutters, layout density,
-typography rhythm, image width, image height limits, font, colors, or
-site-wide typography preset, edit `site/theme.md`. See [Theme](theme.md) for
-the accepted shape.
+To change the site's overall visual expression, select a top-level preset in
+`site/theme.md`. Override individual page-width, gutter, image, typography, or
+palette values only where needed. See [Theme](theme.md) for the accepted shape.
 
-To change one page or section, add a focused `presentation.typography`
-override in `site/content.md`. See [Typography](typography.md). Use
-`norna typography presets` to inspect the installed preset and rhythm values and
-`norna typography show` to inspect the resolved typography for the selected
+To give a route a different visual expression, add a route-local `theme.md`
+and normally select another complete top-level preset. See
+[Theme](theme.md#route-themes) and [Typography](typography.md).
+Use `norna typography presets` to inspect the installed preset and rhythm values
+and `norna typography show` to inspect the resolved typography for the selected
 site.

package/docs/routes.md

@@ -4,14 +4,16 @@
 under `site/routes/<NNN-route-id>/route-content.md` and build to first-level
 URLs.
 
-Routes use the same page frontmatter, optional section metadata, Norna managed
-media blocks, and Markdown section model as the homepage. See
-[Content](content.md) for the page and section model.
+Routes use the same page frontmatter, optional section metadata, Norna-managed
+media blocks, and Markdown section model as the homepage. See [Content](content.md)
+for the page and section model.
 
 Route directories can contain route content, route-local images, and
-route-local presentation overrides in `route-content.md`. They cannot contain
-technical site configuration; technical configuration stays at the selected
-site directory's top-level `config.mjs`.
+an optional route-local `theme.md`. The route theme replaces the root visual
+theme for that route and can select any complete top-level theme preset. Route
+directories cannot contain technical site
+configuration; technical configuration stays in the selected site directory's
+top-level `config.mjs`.
 
 ## Route Directory Format
 

package/docs/site-structure.md

@@ -11,6 +11,7 @@ The selected site directory defaults to `site/`:
 site/
 |-- config.mjs
 |-- theme.md
+|-- sitewide-content.md
 |-- content.md
 |-- images/
 |   `-- <section-id>/
@@ -30,17 +31,19 @@ site directory. Without an explicit site directory, commands first accept the
 current directory when it contains both `config.mjs` and `content.md`.
 Otherwise, commands started from a subdirectory walk upward until they find the
 default `site/` directory containing those files.
-`theme.md` is optional; omit it to use the engine's built-in visual defaults.
+`theme.md` is required. It can contain only a complete preset selection.
 
 ## Versioned Source Files
 
 Version these files in a site repository:
 
 - `site/config.mjs`: technical site configuration.
-- `site/theme.md`: optional site-wide visual theme, including layout, spacing,
-  image sizing, font, typography defaults, colors, inline styles, and frame
-  colors.
+- `site/theme.md`: required site-wide visual theme. It normally selects a
+  complete preset and may add focused layout, image, typography, palette, or
+  section-surface overrides.
   See [Theme](theme.md).
+- `site/sitewide-content.md`: shared site identity, banners and footer content.
+  See [Sitewide Content](sitewide-content.md).
 - `site/content.md`: homepage page file with editable content, Markdown
   sections, optional section metadata, managed media blocks, alt text, and
   captions.
@@ -88,6 +91,8 @@ In this repository:
 - `starters/project/` is a project-site starter used as a maintained example
   for small project and developer-tool sites.
 - `fixtures/basic/site/` is used by engine regression tests.
-- `examples/dog-gallery/site/` is the local visual dog example used by demo
-  builds and navigation diagnostics.
+- `examples/feature-demos/media-and-surfaces/site/` is the broad visual example
+  used by demo builds and navigation diagnostics.
+- `examples/complete-sites/` contains coherent sites, while
+  `examples/feature-demos/` contains focused visual test benches.
 - `site/` is reserved for the local documentation site.