@janga/norna 0.7.8 → 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:
 
@@ -32,17 +33,20 @@ For design and naming principles:
 
 1. [Command Organization](design/command-organization.md)
 2. [Site Examples Structure](design/site-examples-structure.md)
+3. [Norna Diagram Design](design/norna-diagram-design.md)
 
 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
@@ -58,6 +62,9 @@ Design documents are intentionally separate from the user reference:
 - [Site Examples Structure](design/site-examples-structure.md) defines the
   intended vocabulary for starters, examples, documentation sites, reference
   docs, and fixtures.
+- [Norna Diagram Design](design/norna-diagram-design.md) defines the first
+  experiment for technical and pedagogical diagrams without adding external
+  diagram tooling to the build pipeline.
 
 Site repositories should document only their site-specific choices and link here
 for generic `norna` behavior.

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

@@ -0,0 +1,158 @@
+# Norna Diagram Design
+
+This document defines a repository-local workflow for creating technical and
+pedagogical diagrams for Norna.
+
+It is intentionally not a vendored copy of any external skill, MCP server, or
+diagram tool. The first experiment should use hand-authored SVG assets managed
+by Norna's existing image model.
+
+## Goal
+
+Norna diagrams should help a new reader understand the site model faster than
+text alone.
+
+A diagram should explain one idea clearly, not show every related feature. If a
+topic needs several ideas, split it into several diagrams.
+
+## Current Scope
+
+Use this workflow for diagrams in the Norna documentation site under `site/`.
+
+Do not add diagram generation to the Norna build pipeline yet. Diagram creation
+is an authoring workflow for now, not product functionality.
+
+Do not require Excalidraw, MCP servers, browser plugins, or external layout
+tools for the first experiment.
+
+## Diagram Brief
+
+Before creating or replacing a diagram, write a short brief:
+
+```md
+Purpose:
+Audience:
+Main message:
+Concepts to show:
+Concepts to avoid:
+Norna features that must not be implied:
+Suggested layout:
+Mobile/readability requirement:
+Where the SVG will live:
+Markdown block and alt text:
+```
+
+The brief can live in the discussion, in a source-only Markdown comment near
+the image, or in `docs/design/` when it is useful for future maintenance.
+
+## Design Principles
+
+- Show one primary flow or relationship.
+- Prefer two to five main objects.
+- Use short labels.
+- Use one clear visual hierarchy.
+- Keep arrows few and directional.
+- Avoid diagrams where every object connects to every other object.
+- Prefer multiple simple diagrams over one dense diagram.
+- Make route order, URL slugs, section ids, image folders, source files, and
+  generated output visually distinct when those ideas matter.
+- Do not show templates, components, custom rendering logic, route-level
+  technical configuration, or hosting integrations that Norna does not support.
+- Do not show page layouts that Norna cannot actually render unless the diagram
+  is clearly abstract and not a product capability example.
+
+## Norna-Specific Accuracy
+
+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.
+- Images belong under the image root for the page or route, usually grouped by
+  section id.
+- Markdown remains the primary writing format.
+- Norna managed media blocks cover fixed site patterns such as image stacks,
+  carousels, and card lists.
+- `theme.md` controls visual presentation.
+- `config.mjs` controls technical site configuration.
+- `dist/` is generated static output.
+- GitHub Pages is the integrated publishing target today.
+
+## SVG Requirements
+
+Use hand-authored SVG for the first experiment.
+
+SVG assets should:
+
+- have a `viewBox`;
+- include `<title>` and `<desc>`;
+- use real text, not outlined text;
+- avoid external fonts and external image files;
+- remain readable at the size used on the site;
+- work when scaled down on a phone;
+- use restrained colors that fit the surrounding page;
+- avoid decorative effects that compete with the explanation;
+- keep text inside boxes with visible margins;
+- be maintainable by editing the SVG source.
+
+If a diagram is too wide for mobile, prefer splitting it into smaller diagrams
+over relying on horizontal scrolling.
+
+## Source Placement
+
+Store diagram SVG files as normal Norna managed image assets:
+
+```text
+site/routes/<NNN-route-id>/images/<section-id>/<diagram-name>.svg
+```
+
+Reference them with a Norna managed media block:
+
+````md
+<!-- norna-image-provenance:
+image: diagram-name.svg
+source: hand-authored
+Short maintenance note explaining why the diagram exists.
+-->
+
+```norna-image-stack
+- image: diagram-name.svg
+  alt: Concise explanation of what the diagram shows.
+```
+````
+
+## Review Checklist
+
+Before accepting a diagram:
+
+- The main message is obvious without reading the surrounding section.
+- The diagram does not imply unsupported Norna functionality.
+- URL, route, section, image, theme, config, and output terminology is
+  consistent with documentation.
+- Text fits inside boxes at desktop and mobile widths.
+- Arrows clarify the relationship instead of adding noise.
+- The SVG has title, description, and useful alt text in Markdown.
+- `norna content:check` passes.
+- A desktop and mobile visual check has been done when layout changed.
+
+## Relationship To Excalidraw
+
+Excalidraw can be useful as a sketching style or inspiration for box-and-arrow
+clarity, but the first Norna experiment should not depend on Excalidraw files,
+exports, or MCP tooling.
+
+If future experiments show that diagram generation should be automated, evaluate
+that as a separate authoring tool or CLI. Do not make it part of the site build
+engine unless there is a clear product reason.
+
+## Future Questions
+
+- Should diagram briefs become tracked files next to SVG assets?
+- Should Norna have a separate authoring helper for diagrams?
+- Should generated diagrams store both a source format and exported SVG?
+- Should a later tool create Excalidraw-compatible files, plain SVG, or both?
+- What review rules are needed before diagrams are used in starters or examples?

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.