@janga/norna 0.7.9 → 0.7.10

package/README.md

@@ -24,7 +24,7 @@ A `norna` site is file-driven:
 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`.
+   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`.

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,15 @@ 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.
+  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.
+  font, typography rhythm, presentation 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/configuration.md

@@ -72,7 +72,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 +141,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 +164,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:
 

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/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,22 @@ 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. 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.
+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
@@ -158,12 +160,12 @@ Read [Site Structure](site-structure.md), [Content](content.md),
 [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
+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 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 complete route-local
+`theme.md`. 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,15 @@
 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. 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>/
@@ -38,9 +39,10 @@ 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.
+  image sizing, font, typography defaults, palettes, and section surfaces.
   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.

package/docs/sitewide-content.md

@@ -0,0 +1,74 @@
+# Sitewide Content
+
+`site/sitewide-content.md` contains content and settings shared by the whole site. It
+is separate from `content.md`, which defines the homepage, and from
+`config.mjs`, which defines technical behaviour.
+
+## Site identity
+
+Use the optional `navigation` object for identity shared by all pages. `brand`
+is the text shown in the home link when no logo is present. A logo is discovered
+from one convention-based file in `site/public`: `logo.svg`, `logo.png`,
+`logo.jpg`, or `logo.jpeg`.
+
+```yaml
+navigation:
+  brand: Example Site
+  logo:
+    alt: Example Site
+    height: 2.6rem
+```
+
+If `navigation.brand` is omitted, Norna uses the homepage `title` from
+`site/content.md`. The logo's width is derived from its intrinsic aspect ratio.
+If both a logo and a brand are present, the logo is displayed and the brand is
+used as its text fallback and accessible default.
+
+## Banners
+
+Use `banners` for short notices shown above the page content on every route.
+The list order controls the presentation order. Each banner needs a unique
+`id`, a title and text:
+
+```yaml
+---
+banners:
+  - id: project-status
+    tone: warning
+    visible:
+      from: "2026-08-01"
+      until: "2026-09-01"
+    title: Experimental code
+    text: Not for production use.
+---
+```
+
+`visible` uses the same date-window rules as temporary sections. Visitors can
+dismiss individual active banners. The dismissal is stored locally in the
+browser and is tied to the banner content, so an edited banner can appear
+again.
+
+The first version supports the `warning` tone. Keep banner text short; banners
+are presented as compact single-line notices and may use an ellipsis when the
+text does not fit.
+
+## Footer
+
+The footer is also sitewide content. `copyrightMessage` adds a copyright or
+license sentence. `buildInfo` optionally adds a generated build timestamp:
+
+```yaml
+footer:
+  copyrightMessage: (c) Example Artist.
+  buildInfo:
+    enabled: true
+    text: Built
+    dateTimeFormat:
+      locale: en-GB
+      timeZone: UTC
+      dateStyle: short
+      timeStyle: short
+```
+
+If both the copyright message and enabled build information are absent, the
+footer is not rendered.

package/docs/theme.md

@@ -1,20 +1,19 @@
 # Theme
 
-`site/theme.md` defines optional site-wide visual defaults for a `norna` site.
-It uses YAML frontmatter and does not need a Markdown body. If the file is
-missing, built-in engine defaults are used.
+`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.
 
-Page-level presentation in `site/content.md` and route page files is always an
-override on top of `site/theme.md`. Section-level presentation is an override
-on top of the resolved page presentation. Use those overrides for focused
-exceptions; the normal place for shared visual choices is `site/theme.md`.
+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`.
 
 ## Minimal Theme
 
 ```yaml
 ---
-navigation:
-  brand: Example Site
 layout:
   density: normal
   pageWidth: 1180px
@@ -34,10 +33,10 @@ typography:
   preset: quiet-gallery
   rhythm: normal
 presentation:
-  backgroundColor: "#000000"
-  textColor: "#f7f4ee"
-frame:
-  colors: presentation
+  palette: dark  # Alternatives: light, paper
+  sectionSurfaces:
+    mode: cycle
+    sequence: [base, soft, emphasis]
 ---
 ```
 
@@ -46,23 +45,8 @@ Starter sites include a marked comment block such as
 explorable help text; YAML comments do not affect rendering. The active
 configuration is the uncommented YAML below it.
 
-## Navigation
-
-`navigation` is optional. It currently supports:
-
-- `brand`: optional site-wide brand or home-link text shown in the site
-  navigation.
-
-If `navigation.brand` is omitted, Norna uses the homepage `title` from
-`site/content.md`. Use `navigation.brand` when the homepage title is editorial
-or route-specific, but the navigation should keep a stable site name.
-
-Example:
-
-```yaml
-navigation:
-  brand: Norna
-```
+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).
 
 ## Layout
 
@@ -74,9 +58,9 @@ navigation:
   `desktop` / `mobile` values.
 - `density`: default structural spacing profile. Allowed values are `compact`,
   `normal`, and `airy`.
-- `spacing`: optional structural spacing overrides for sections and Norna
-  managed media blocks. Every spacing value accepts either one CSS length for all
-  viewports or `desktop` / `mobile` values.
+- `spacing`: optional spacing overrides for sections and content blocks. Every
+  spacing value accepts either one CSS length for all viewports or `desktop` /
+  `mobile` values.
 
 Example:
 
@@ -94,6 +78,12 @@ layout:
     sectionGap:
       desktop: clamp(1.4rem, 3vw, 2.75rem)
       mobile: 1.5rem
+    headingToBlock:
+      desktop: 0.75em
+      mobile: 0.7em
+    blockGap:
+      desktop: 1.5em
+      mobile: 1.25em
 ```
 
 If omitted, Norna uses `1180px` for `pageWidth`, desktop
@@ -105,11 +95,20 @@ Spacing keys:
 - `firstSectionTop`: space above the first section heading.
 - `sectionGap`: space above each following section.
 - `finalSectionBottom`: space below the final section.
-- `bodyToImages`: space from section body text to Norna managed media blocks.
+- `headingToBlock`: space between a section heading and its first visual content
+  block, such as an image stack, carousel, or card list.
+- `blockGap`: space between content blocks in a section. It applies between
+  Markdown, image, carousel, and card-list blocks, but not after the final block.
 - `imageGap`: space between stacked images or carousel blocks.
 
-Text-near spacing, such as spacing after headings, spacing before Markdown
-subheadings, paragraph spacing, and caption spacing, belongs to
+The default `compact`, `normal`, and `airy` density profiles provide values for
+these spacing keys. The `em` values for `headingToBlock` and `blockGap` are
+relative to the relevant text size, so the rhythm follows typography changes.
+Use `sectionGap` and the other structural keys when the distance should describe
+the page layout rather than the size of nearby text.
+
+Text-near spacing inside Markdown, such as spacing after headings, spacing
+before Markdown subheadings, paragraph spacing, and caption spacing, belongs to
 `typography.rhythm` and typography overrides.
 
 ## Image Sizing
@@ -153,18 +152,20 @@ Example:
 ```yaml
 typography:
   fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
-  preset: quiet-gallery
+  preset: text-forward
   rhythm: normal
   overrides:
     headings:
       h2:
         size: medium
+        weight: 600
         spacingAfter: 0.55em
       h3:
         size: medium
         spacingBefore: 1.5em
         spacingAfter: 0.5em
     body:
+      width: narrow
       lineHeight: 1.55
 ```
 
@@ -174,107 +175,39 @@ selected site. See [Typography](typography.md).
 
 ## Presentation
 
-`presentation` is optional. It can contain:
+`presentation` is optional. It selects a small built-in visual palette for the
+page frame and defines how section surfaces are assigned:
 
-- `backgroundColor`: optional quoted hex color in `#rgb`, `#rrggbb`, or
-  `#rrggbbaa` form.
-- `textColor`: optional quoted hex color in `#rgb`, `#rrggbb`, or
-  `#rrggbbaa` form.
-- `inlineStyles`: optional named inline text styles.
+- `palette`: `dark`, `light`, or `paper`. The palette controls the page,
+  navigation, footer, and section colors.
+- `sectionSurfaces.mode`: `none` or `cycle`.
+- `sectionSurfaces.sequence`: optional sequence of `base`, `soft`, and
+  `emphasis`. Each surface may occur at most once.
 
 Example:
 
 ```yaml
 presentation:
-  backgroundColor: "#101418"
-  textColor: "#f4f1ea"
-```
-
-## Page And Section Overrides
-
-Site-wide presentation belongs in `site/theme.md`. Page-level presentation in a
-page file is always an override on top of the theme:
-
-```yaml
-presentation:
-  typography:
-    overrides:
-      headings:
-        h2:
-          size: large
-          spacingAfter: 0.6em
-      body:
-        paragraphSpacing: 1em
-```
-
-Section-specific presentation belongs under
-`sections.<section-id>.presentation`. Use it when one section genuinely needs
-different presentation; do not use `sections` to define section order or normal
-Markdown structure.
-
-```yaml
-sections:
-  intro:
-    presentation:
-      backgroundColor: "#161616"
-      textColor: "#ffffff"
-      typography:
-        preset: statement
-```
-
-If a page omits `presentation`, it uses the theme presentation unchanged. If a
-section omits `presentation`, it uses the resolved page presentation.
-
-Configured section backgrounds render as full-width horizontal bands while the
-section content keeps the normal page and image widths. The top spacing
-before the first heading, the spacing between sections, and the spacing after
-the final section are part of the section background.
-
-Configured section text colors apply to section headings, Markdown text,
-Markdown subheadings, and image captions. Links keep the global accent color.
-
-## Frame Colors
-
-`frame.colors` controls the sticky navigation and footer colors.
-
-Allowed values:
-
-- `presentation`: use the resolved presentation colors for this level.
-- `theme`: use the site theme frame colors. This is useful in page-level
-  frontmatter.
-- explicit colors:
-
-```yaml
-frame:
-  colors:
-    backgroundColor: "#111111"
-    textColor: "#eeeeee"
+  palette: paper  # Alternatives: dark, light
+  sectionSurfaces:
+    mode: cycle
+    sequence: [base, soft, emphasis]
 ```
 
-The sticky section navigation row and footer use the resolved frame colors, not
-section-specific presentation.
+## Route Themes
 
-## Inline Styles
+Add `theme.md` to a route directory when that route should have a different
+visual expression:
 
-`presentation.inlineStyles` defines named inline text styles that can be used
-from Markdown:
-
-```yaml
-presentation:
-  inlineStyles:
-    highlight:
-      color: "#ffd84d"
+```text
+site/routes/010-guide/theme.md
 ```
 
-Inline style names must match `^[a-z][a-z0-9-]*$`. Each style currently
-supports a required `color` field using the same quoted hex color format as
-`textColor`.
-
-Apply an inline style in Markdown with `[text]{.style-name}`:
-
-```md
-This sentence contains [highlighted text]{.highlight}.
-```
+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
+technical configuration.
 
-`content:check` fails if Markdown uses an inline style that is not defined in
-`site/theme.md` `presentation.inlineStyles`.
+Section surfaces render as full-width horizontal bands while the section
+content keeps the normal page and image widths. Links keep the palette's global
+accent color.