@janga/norna 0.7.10 → 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, palettes, and section surfaces, 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

@@ -45,8 +45,9 @@ For a quick reference:
 - [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 palettes, and section surfaces.
+- [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`

package/docs/content.md

@@ -269,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
 
@@ -288,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/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

@@ -92,9 +92,8 @@ Relevant documentation: [Commands](commands.md), [Site Structure](site-structure
    repository, and deploy settings.
 2. Edit `site/sitewide-content.md` for the shared brand or logo, banners and
    footer content.
-3. Edit `site/theme.md` for site-wide layout, layout density, typography
-   rhythm, image sizing, font, typography preset, palettes, and section
-   surfaces, or omit it to use engine defaults.
+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>`
@@ -124,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:
@@ -159,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, palettes, 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 give a route a different visual expression, add a complete route-local
-`theme.md`. See [Theme](theme.md#route-themes) and [Typography](typography.md).
+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

@@ -10,7 +10,8 @@ for the page and section model.
 
 Route directories can contain route content, route-local images, and
 an optional route-local `theme.md`. The route theme replaces the root visual
-theme for that route. Route directories cannot contain technical site
+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`.
 

package/docs/site-structure.md

@@ -31,15 +31,16 @@ 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, palettes, and section surfaces.
+- `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).
@@ -90,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.

package/docs/theme.md

@@ -2,48 +2,90 @@
 
 `site/theme.md` defines the site-wide visual theme for a `norna` site. It uses
 YAML frontmatter and does not need a Markdown body. The root theme file is
-required, but every setting inside it is optional and falls back to an engine
-default.
+required. The normal setup selects one complete theme preset and adds only
+focused overrides when needed.
 
 An optional `theme.md` inside a route directory replaces the root visual theme
-for that route. Route themes do not merge with the root theme: omitted values
-use engine defaults. Shared identity such as brand and logo remains site-wide
-and belongs in `sitewide-content.md`.
+for that route. Shared identity such as brand and logo remains site-wide and
+belongs in `sitewide-content.md`.
 
-## Minimal Theme
+## Theme Presets
+
+Available complete theme presets are:
+
+- `portfolio`: restrained typography and a broad image area for image-led
+  presentation.
+- `documentation`: reading-focused typography, a paper palette, and compact
+  structural rhythm.
+- `project`: compact layout and a light presentation for project and product
+  sites.
+- `statement`: airy spacing and stronger typography for short editorial
+  content.
+
+A normal `theme.md` can be only:
+
+```yaml
+---
+preset: documentation
+---
+```
+
+Each preset supplies coordinated values for:
+
+- layout density, page width, and gutters
+- managed image sizing
+- font family, typography preset, and typography rhythm
+- palette and section-surface behaviour
+
+The nested `typography.preset` setting documented below is a lower-level
+typography choice. A top-level theme `preset` selects the complete visual
+system, including that typography choice.
+
+## Overrides
+
+Values written beside the top-level preset override only that part of the
+preset. Other preset values remain active:
 
 ```yaml
 ---
+preset: documentation
 layout:
-  density: normal
-  pageWidth: 1180px
-  gutter:
-    desktop: clamp(1.25rem, 4vw, 3rem)
-    mobile: 1rem
-gallery:
-  width: 900px
-  maxAvailableWidthPercent:
-    desktop: 100
-    mobile: 100
-  maxAvailableHeightPercent:
-    desktop: 74
-    mobile: 68
-typography:
-  fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
-  preset: quiet-gallery
-  rhythm: normal
+  pageWidth: 1320px
 presentation:
-  palette: dark  # Alternatives: light, paper
-  sectionSurfaces:
-    mode: cycle
-    sequence: [base, soft, emphasis]
+  palette: dark
 ---
 ```
 
-Starter sites include a marked comment block such as
-`norna:start theme-help` / `norna:end theme-help`. The block is only
-explorable help text; YAML comments do not affect rendering. The active
-configuration is the uncommented YAML below it.
+Nested objects are merged by key. Arrays such as
+`presentation.sectionSurfaces.sequence` replace the preset array when they are
+specified.
+
+It is still valid to omit the top-level preset and define the visual settings
+explicitly. Omitted explicit settings then use engine defaults. This is useful
+for focused testing, but selecting a complete preset is the simpler normal
+workflow.
+
+## Export A Preset
+
+Export the installed definition of a preset before choosing overrides:
+
+```sh
+norna theme:export documentation
+```
+
+In a generated site, the equivalent npm command is:
+
+```sh
+npm run norna:theme:export -- documentation
+```
+
+The command creates `site/orig-documentation-theme.md`, or the corresponding
+path under the selected site directory. The file contains the preset values,
+comments describing accepted alternatives, and an example of a fine-grained
+typography override.
+
+Norna never loads `orig-*-theme.md`; only `theme.md` is active. The export
+command refuses to overwrite an existing reference file.
 
 Site identity is not part of the visual theme. Define the optional navigation
 brand and logo settings in `site/sitewide-content.md`; see [Sitewide Content](sitewide-content.md).
@@ -203,9 +245,19 @@ visual expression:
 site/routes/010-guide/theme.md
 ```
 
-The route theme uses the same visual schema as the root theme. It completely
-replaces the root visual theme for that route, so include every non-default
-visual choice the route needs. It cannot define navigation, brand, logo, or
+The route theme uses the same visual schema and complete presets as the root
+theme. A route can therefore select a different expression without repeating a
+large configuration:
+
+```yaml
+---
+preset: statement
+---
+```
+
+It completely replaces the root visual theme for that route. If the route
+theme selects no top-level preset, omitted values use engine defaults rather
+than values from the root theme. It cannot define navigation, brand, logo, or
 technical configuration.
 
 Section surfaces render as full-width horizontal bands while the section

package/docs/typography.md

@@ -3,12 +3,20 @@
 `norna` typography is configured in `site/theme.md` through a site-wide font,
 presets, text rhythm, and optional overrides.
 
-The normal place to choose a site-wide typography preset and rhythm is the
-top-level `typography` block in `site/theme.md`.
-Page and section files may override the theme when a focused exception is
-needed, but the normal workflow is to keep typography in `theme.md`.
+The normal workflow is to select a complete top-level theme preset. It already
+chooses a coordinated font, typography preset, and rhythm:
 
-## Presets
+```yaml
+---
+preset: documentation
+---
+```
+
+Use the nested `typography` block only when those typographic choices need to
+differ from the selected theme preset. Typography is configured at root-theme
+or route-theme level, not in page or section content.
+
+## Typography Presets
 
 Available presets:
 
@@ -21,7 +29,9 @@ Available presets:
 - `statement`: tighter, more declarative line-height for short programmatic
   statements. Use it sparingly, usually as a page or section exception.
 
-If theme typography is omitted, `quiet-gallery` is used.
+If a complete top-level theme preset is selected, that preset supplies the
+typography choice. If both the top-level preset and nested typography are
+omitted, the engine default is `quiet-gallery`.
 
 Presets define alignment, size, weight, and line height for `headings.h1`
 through `headings.h4`, `body`, and `caption`. They also choose a readable body
@@ -142,30 +152,35 @@ Supported override fields:
 
 ## Route Themes
 
-Theme typography is the site-wide base:
+The simplest route-specific typography change is to select a complete theme
+preset:
 
 ```yaml
-# site/theme.md
-typography:
-  fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
-  preset: quiet-gallery
-  rhythm: normal
+# site/routes/010-introduction/theme.md
+---
+preset: statement
+---
 ```
 
-A route-local `theme.md` can give that route a different typographic character.
-The route theme replaces the root visual theme rather than inheriting from it,
-so repeat any non-default `fontFamily`, `rhythm`, or `overrides` that the route
-still needs.
+A route-local `theme.md` replaces the root visual theme rather than inheriting
+from it. The complete preset supplies a coherent route theme without repeating
+the root values.
 
-Example route theme:
+Use a nested typography choice when only the typographic character needs to be
+specified explicitly:
 
 ```yaml
 # site/routes/010-introduction/theme.md
+---
 typography:
   preset: statement
   rhythm: normal
+---
 ```
 
+Without a top-level theme preset, other omitted route-theme values use engine
+defaults rather than values from the root theme.
+
 The `body.width` value controls the prose column independently of the page and
 image widths. Captions are normally centered, but `text-forward` uses
 left-aligned captions to support longer explanatory text.