@janga/norna 0.7.16 → 0.7.18

package/docs/theme.md

@@ -1,16 +1,20 @@
 # Theme
 
-`site/theme.yaml` defines the site-wide visual theme for a Norna site. It is a
-required plain YAML file. The normal setup selects one complete theme preset
-and adds only focused overrides when needed.
+`site/theme.yaml` defines the visual identity and default presentation for the
+whole Norna site. It is a required plain YAML file. The normal setup selects one
+complete preset and adds only focused overrides when they are needed:
 
-An optional `theme.yaml` inside a route directory replaces the root visual
-theme for that route. Shared identity such as the navigation label and logo
-remains site-wide and belongs in `sitewide-content.yaml`.
+```yaml
+preset: documentation
+```
+
+The root theme owns site-wide colors, shapes, typography, page frame, and
+navigation presentation. An optional page-local `theme.yaml` has a deliberately
+smaller role described under [Page Themes](#page-themes).
 
 ## Theme Presets
 
-Available complete theme presets are:
+Available complete presets are:
 
 - `portfolio`: restrained typography and a broad image area for image-led
   presentation.
@@ -21,27 +25,21 @@ Available complete theme presets are:
 - `statement`: airy spacing and stronger typography for short editorial
   content.
 
-A normal `theme.yaml` can be only:
+Each preset coordinates:
 
-```yaml
-preset: documentation
-```
+- colors, shape, and typography
+- page width, gutters, text width, and content spacing
+- navigation spacing and visual treatment
+- managed-image sizing
+- section background sequence
 
-Each preset supplies coordinated values for:
-
-- layout density, page width, and gutters
-- managed image sizing
-- font family, typography profile, and typography rhythm
-- palette and section-surface behaviour
-
-The nested `typography.profile` setting documented below is a lower-level
-typography choice. A top-level theme `preset` selects the complete visual
-system, including that typography choice.
+These coordinated values keep the site's identity consistent. Page themes
+cannot select another preset.
 
 ## Overrides
 
-Values written beside the top-level preset override only that part of the
-preset. Other preset values remain active:
+Values beside the root preset override only that part of the preset. Other
+preset values remain active:
 
 ```yaml
 preset: documentation
@@ -50,112 +48,89 @@ layout:
 palette: dark
 ```
 
-Nested objects are merged by key. `sectionSurfaces` replaces the preset array
-when it is 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.
+Nested objects are merged by key. It is valid to omit `preset` and define root
+settings explicitly, but a complete preset is the simpler normal workflow.
 
 ## Export A Preset
 
-Export the installed definition of a preset before choosing overrides:
+Export the installed definition before choosing overrides:
 
 ```sh
 norna theme:export documentation
 ```
 
-In a generated site, the equivalent npm command is:
+In a generated site, use:
 
 ```sh
 npm run norna:theme:export -- documentation
 ```
 
-The command creates `site/orig-documentation-theme.yaml`, 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.
+The command creates `site/orig-documentation-theme.yaml`. The file contains the
+preset values, accepted alternatives, and example overrides. Norna never loads
+`orig-*-theme.yaml`; only `theme.yaml` is active. The command refuses to
+overwrite an existing reference file.
 
-Norna never loads `orig-*-theme.yaml`; only `theme.yaml` 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
-label and logo display settings in `site/sitewide-content.yaml`; see
-[Sitewide Content](sitewide-content.md).
+Page titles and site-wide editorial content are not part of the visual theme.
+Optional logo display settings, banners, and the footer belong in
+[`sitewide-content.yaml`](sitewide-content.md).
 
 ## Layout
 
-`layout` is optional. It controls the outer page geometry:
+Root `layout` settings control the site frame and default content geometry:
 
-- `pageWidth`: maximum width of the main page content area.
-- `gutter`: side margin removed from the viewport before available content
-  width is calculated. Use either one CSS length for all viewports or
-  `desktop` / `mobile` values.
-- `density`: default structural spacing profile. Allowed values are `compact`,
-  `normal`, and `airy`.
-- `spacing`: optional spacing overrides for sections and content blocks. Every
-  spacing value accepts either one CSS length for all viewports or `desktop` /
-  `mobile` values.
+- `pageWidth`: maximum width of the full site layout, including local tree
+  navigation where present.
+- `gutter`: horizontal viewport gutter, either one CSS length or separate
+  `desktop` and `mobile` values.
+- `textWidth`: body-text line length: `narrow`, `normal`, or `wide`.
+- `contentSpacing`: vertical spacing between sections and structured blocks:
+  `compact`, `normal`, or `spacious`.
+- `spacing`: fine-grained structural spacing overrides.
 
 Example:
 
 ```yaml
+preset: documentation
 layout:
-  density: normal
-  pageWidth: 1180px
+  pageWidth: 1320px
   gutter:
     desktop: clamp(1.25rem, 4vw, 3rem)
     mobile: 1rem
+  textWidth: narrow
+  contentSpacing: compact
   spacing:
-    firstSectionTop:
-      desktop: clamp(1.875rem, 3vw, 2.75rem)
-      mobile: 1.375rem
+    firstSectionTop: 1.5rem
     sectionGap:
-      desktop: clamp(1.4rem, 3vw, 2.75rem)
+      desktop: 2.5rem
       mobile: 1.5rem
-    headingToBlock:
-      desktop: 0.75em
-      mobile: 0.7em
-    blockGap:
-      desktop: 1.5em
-      mobile: 1.25em
+    headingToBlock: 0.75em
+    blockGap: 1.5em
 ```
 
-If omitted, Norna uses `1180px` for `pageWidth`, desktop
-`clamp(1.25rem, 4vw, 3rem)` for `gutter`, mobile `1rem`, and `normal` layout
-density.
-
-Spacing keys:
+Spacing keys are:
 
 - `firstSectionTop`: space above the first section heading.
 - `sectionGap`: space above each following section.
 - `finalSectionBottom`: space below the final section.
-- `headingToBlock`: space between a section heading and its first visual content
+- `headingToBlock`: space between a section heading and its first structured
   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.
+- `blockGap`: space between structured content blocks.
+- `imageGap`: space between images in an image stack.
 
-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.
+The `contentSpacing` profiles supply coordinated defaults for these values.
+Text-near spacing inside Markdown, including paragraph and subheading spacing,
+belongs to typography rhythm.
 
-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.
+The horizontal gap between tree navigation and page content is coordinated by
+the selected preset. It is intentionally not a separate public override.
 
 ## Image Sizing
 
-`images` is optional. It controls managed image sizing:
+`images` controls managed image sizing:
 
-- `width`: hard maximum rendered image area width for images, captions, and
-  aligned text.
-- `maxAvailableWidthPercent`: maximum share of available width after gutters.
-- `maxAvailableHeightPercent`: maximum share of viewport height used by
-  images.
+- `width`: maximum rendered image-area width.
+- `maxAvailableWidthPercent`: maximum share of available horizontal space.
+- `maxAvailableHeightPercent`: maximum share of viewport height.
 
 Example:
 
@@ -170,18 +145,16 @@ images:
     mobile: 68
 ```
 
-If omitted, Norna uses `900px`, full available width, and image height limits of
-desktop `74` / mobile `68`.
+Each responsive percentage may also be a single number.
 
 ## Typography
 
-Top-level `typography` is the site-wide typographic base. It supports:
+Root `typography` is site-wide. It supports:
 
 - `fontFamily`: global CSS font-family stack.
-- `profile`: built-in typography profile.
-- `rhythm`: text-near spacing profile. Allowed values are `compact`,
-  `normal`, and `airy`.
-- `overrides`: focused changes to preset values.
+- `profile`: `restrained`, `dense`, `reading`, or `statement`.
+- `rhythm`: `compact`, `normal`, or `airy`.
+- `overrides`: focused changes to headings, body text, and captions.
 
 Example:
 
@@ -196,76 +169,69 @@ typography:
         size: medium
         weight: 600
         spacingAfter: 0.55em
-      h3:
-        size: medium
-        spacingBefore: 1.5em
-        spacingAfter: 0.5em
     body:
-      width: narrow
+      size: medium
       lineHeight: 1.55
 ```
 
-Use `norna typography profiles` to inspect built-in profile and rhythm values,
-and `norna typography show` to inspect the resolved typography for the
-selected site. See [Typography](typography.md).
+Use `norna typography profiles` to inspect built-in values and
+`norna typography show` to inspect the resolved site typography. See
+[Typography](typography.md) for every override field.
 
 ## Palette And Section Surfaces
 
-`palette` and `sectionSurfaces` are optional top-level theme settings:
+These root settings are site-wide:
 
-- `palette`: `dark`, `light`, or `paper`. It coordinates page, navigation,
-  footer, and section colors.
-- `sectionSurfaces`: one to three unique values chosen from `base`, `soft`, and
-  `emphasis`. One value gives every section the same surface. Multiple values
-  cycle in the listed order.
+- `palette`: `dark`, `light`, or `paper`.
+- `shape`: `square` or `soft`.
+- `sections.backgroundPattern`: `uniform`, `alternating`, or `cycling`.
 
 Example:
 
 ```yaml
-palette: paper  # Alternatives: dark, light
-sectionSurfaces: [base, soft, emphasis]
+preset: project
+palette: paper
+shape: soft
+sections:
+  backgroundPattern: cycling
 ```
 
-## Route Themes
-
-Add `theme.yaml` to a route directory when that route should have a different
-visual expression:
+The background pattern uses coordinated surfaces from the active palette. It
+does not let individual sections select arbitrary colors.
 
-```text
-site/routes/010-guide/theme.yaml
-```
+## Page Themes
 
-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:
+Add `theme.yaml` to a non-home page directory only when that page or one of its
+descendants needs a narrower presentation adjustment:
 
-```yaml
-preset: statement
+```text
+site/pages/010-guide/theme.yaml
 ```
 
-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 identity or
-technical configuration.
-
-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.
+A page theme may set only:
 
-## Common Questions
+- `layout.textWidth`
+- `layout.contentSpacing`
+- managed-image sizing under `images`
+- `sections.backgroundPattern`
 
-### Should every route select its own preset?
+For example:
 
-No. A route without its own `theme.yaml` inherits the root theme, which is the
-normal choice when the site should keep one visual expression.
+```yaml
+layout:
+  textWidth: narrow
+  contentSpacing: compact
+images:
+  width: 760px
+sections:
+  backgroundPattern: uniform
+```
 
-Add a route theme only when the route should intentionally look different. If
-the route should keep the same preset but demonstrate a focused change, repeat
-the root preset in the route theme and override only that setting. This is
-necessary because a route theme replaces the root visual theme rather than
-merging with it.
+Page settings are merged with the root theme and inherited by descendant pages.
+A more local page theme may override the same limited fields. Site colors,
+shape, typography, page width, gutters, and navigation remain constant.
 
-For example, a route demonstrating section surfaces may keep `preset: project`
-and change only `sectionSurfaces`. A route demonstrating image or content
-blocks should normally inherit the root preset so that the blocks remain the
-only variable being compared.
+Page themes cannot define `preset`, `palette`, `shape`, `typography`,
+`navigation`, `config.yaml`, or site-wide content. This boundary keeps one
+recognisable site while still allowing a guide, gallery, or reference area to
+use an appropriate reading width and media presentation.

package/docs/typography.md

@@ -12,7 +12,7 @@ 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.
+or page-theme level, not in page or section content.
 
 ## Typography Profiles
 
@@ -25,7 +25,7 @@ Available profiles:
 - `reading`: more generous body text for pages where longer text carries
   more of the experience.
 - `statement`: tighter, more declarative line-height for short programmatic
-  statements. Use it sparingly, usually as a route-level exception.
+  statements. Use it sparingly, usually as a page-level exception.
 
 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
@@ -65,7 +65,7 @@ profiles, rhythms, and overrides have been applied:
 norna typography show
 ```
 
-The output includes the site theme, every page route, and every section. Each
+The output includes the site theme, every page, and every section. Each
 resolved value shows its `source`; values inherited by a page or section are
 also marked with `inherited: true`.
 
@@ -125,9 +125,9 @@ follows the Markdown level the user wrote: `##` uses `headings.h2`.
 `1rem`, or `12px`. Use `em` for spacing that should track the text size.
 
 `weight` is a controlled heading weight. Allowed values are `400`, `500`,
-`600`, and `700`. `body.width` is the readable text width and accepts
-`narrow`, `normal`, or `wide`. It controls the prose column, not the page's
-maximum width or the width of image blocks.
+`600`, and `700`. Configure readable line length with `layout.textWidth` in the
+root or page theme; it controls the prose column, not the page's maximum width
+or the width of image blocks.
 
 Supported override fields:
 
@@ -143,38 +143,26 @@ Supported override fields:
 - `headings.h4.align`, `headings.h4.size`, `headings.h4.weight`,
   `headings.h4.lineHeight`,
   `headings.h4.spacingBefore`, `headings.h4.spacingAfter`
-- `body.align`, `body.size`, `body.width`, `body.lineHeight`,
+- `body.align`, `body.size`, `body.lineHeight`,
   `body.paragraphSpacing`
 - `caption.align`, `caption.size`, `caption.lineHeight`,
   `caption.spacingBefore`
 
-## Route Themes
+## Page Text Width
 
-The simplest route-specific typography change is to select a complete theme
-preset:
+Typography itself remains site-wide so pages keep the same font, heading
+hierarchy, and typographic character. A page-local `theme.yaml` may adjust the
+body-text line length when a particular page or subtree needs a narrower or
+wider reading column:
 
 ```yaml
-# site/routes/010-introduction/theme.yaml
-preset: statement
+# site/pages/010-introduction/theme.yaml
+layout:
+  textWidth: narrow
 ```
 
-A route-local `theme.yaml` replaces the root visual theme rather than inheriting
-from it. The complete preset supplies a coherent route theme without repeating
-the root values.
+The page setting is inherited by descendant pages. Page themes cannot select a
+typography profile, rhythm, font family, or heading override.
 
-Use a nested typography choice when only the typographic character needs to be
-specified explicitly:
-
-```yaml
-# site/routes/010-introduction/theme.yaml
-typography:
-  profile: 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 `reading` uses
-left-aligned captions to support longer explanatory text.
+Captions are normally centered, but `reading` uses left-aligned captions to
+support longer explanatory text.

package/examples/README.md

@@ -7,10 +7,13 @@ documentation workflow.
 | Example | Purpose | Live demo | Source |
 | --- | --- | --- | --- |
 | Dog shelter, single page | A coherent homepage made from sections | [Open site](https://janga.github.io/norna/examples/complete-sites/dog-shelter-single-page/) | [View files](complete-sites/dog-shelter-single-page/) |
-| Dog shelter, multi-page | A coherent site with ordered routes and route-local images | [Open site](https://janga.github.io/norna/examples/complete-sites/dog-shelter-multi-page/) | [View files](complete-sites/dog-shelter-multi-page/) |
-| Theme presets | All complete presets without overrides | [Open site](https://janga.github.io/norna/examples/feature-demos/theme-presets/) | [View files](feature-demos/theme-presets/) |
+| Dog shelter, multi-page | A coherent site with ordered pages and page-local images | [Open site](https://janga.github.io/norna/examples/complete-sites/dog-shelter-multi-page/) | [View files](complete-sites/dog-shelter-multi-page/) |
+| Portfolio preset | Complete `portfolio` preset without overrides | [Open site](https://janga.github.io/norna/examples/feature-demos/theme-preset-portfolio/) | [View files](feature-demos/theme-preset-portfolio/) |
+| Documentation preset | Complete `documentation` preset without overrides | [Open site](https://janga.github.io/norna/examples/feature-demos/theme-preset-documentation/) | [View files](feature-demos/theme-preset-documentation/) |
+| Project preset | Complete `project` preset without overrides | [Open site](https://janga.github.io/norna/examples/feature-demos/theme-preset-project/) | [View files](feature-demos/theme-preset-project/) |
+| Statement preset | Complete `statement` preset without overrides | [Open site](https://janga.github.io/norna/examples/feature-demos/theme-preset-statement/) | [View files](feature-demos/theme-preset-statement/) |
 | Media and surfaces | Image blocks, cards, notes, palettes, and section surfaces | [Open site](https://janga.github.io/norna/examples/feature-demos/media-and-surfaces/) | [View files](feature-demos/media-and-surfaces/) |
-| Sitewide content | Shared identity, navigation, banners, and footer content | [Open site](https://janga.github.io/norna/examples/feature-demos/sitewide-content/) | [View files](feature-demos/sitewide-content/) |
+| Sitewide content | Shared logo settings, banners, and footer content | [Open site](https://janga.github.io/norna/examples/feature-demos/sitewide-content/) | [View files](feature-demos/sitewide-content/) |
 
 ## Directory Structure
 
@@ -20,7 +23,10 @@ examples/
 |   |-- dog-shelter-single-page/
 |   `-- dog-shelter-multi-page/
 `-- feature-demos/
-    |-- theme-presets/
+    |-- theme-preset-portfolio/
+    |-- theme-preset-documentation/
+    |-- theme-preset-project/
+    |-- theme-preset-statement/
     |-- media-and-surfaces/
     `-- sitewide-content/
 ```

package/examples/complete-sites/dog-shelter-multi-page/.astro/collections/site.schema.json

@@ -2,58 +2,34 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {
-    "title": {
-      "type": "string"
-    },
-    "description": {
-      "type": "string"
+    "page": {
+      "type": "object",
+      "properties": {
+        "description": {
+          "description": "Optional page-specific meta description.",
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false,
+      "description": "Optional metadata for this homepage or additional page. The Markdown H1 supplies the page title."
     },
     "navigation": {
+      "description": "Optional navigation metadata for this page.",
       "type": "object",
       "properties": {
-        "include": {
+        "listed": {
+          "default": true,
+          "description": "List this page in site navigation. The page remains public when false.",
           "type": "boolean"
-        },
-        "label": {
-          "type": "string"
         }
       },
       "additionalProperties": false
     },
-    "sections": {
-      "default": {},
-      "type": "object",
-      "propertyNames": {
-        "type": "string",
-        "pattern": "^[a-z0-9-]+$"
-      },
-      "additionalProperties": {
-        "type": "object",
-        "properties": {
-          "visible": {
-            "type": "object",
-            "properties": {
-              "from": {
-                "type": "string",
-                "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
-              },
-              "until": {
-                "type": "string",
-                "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
-              }
-            },
-            "additionalProperties": false
-          }
-        },
-        "additionalProperties": false
-      }
-    },
     "$schema": {
       "type": "string"
     }
   },
-  "required": [
-    "title",
-    "description"
-  ]
+  "additionalProperties": false,
+  "description": "Frontmatter for a homepage or additional page content.md file."
 }