@janga/norna 0.7.2 → 0.7.4

package/README.md

@@ -1,7 +1,7 @@
 # norna
 
-`norna` is a reusable command-line toolchain for small static gallery
-sites. It provides the CLI, Astro renderer, validation scripts, image pipeline,
+`norna` is a reusable command-line toolchain for small static websites.
+It provides the CLI, Astro renderer, validation scripts, image pipeline,
 starter project, fixtures, and deploy helpers used by site repositories such as
 `www.walde.se`.
 
@@ -21,11 +21,11 @@ belong in each site repository. For example, Karin Walde's site lives in
 A `norna` site is file-driven:
 
 1. A site repository depends on this package.
-2. The site keeps technical settings, including page width, gallery width, and
-   the global font family, public URL, and optional URL base path in
-   `site/config.mjs`.
-3. The site can keep site-wide visual theme defaults in `site/theme.md`.
-4. The site keeps homepage content, section order, gallery rows, alt text, and
+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`.
+4. The site keeps homepage content, section order, image rows, alt text, and
    captions in `site/content.md`.
 5. Optional route pages live under
    `site/routes/<route-folder>/route-content.md`.
@@ -56,10 +56,10 @@ For a new site repository:
 
 ```sh
 cd ../
-npx @janga/norna@latest init my-gallery
-cd my-gallery
+npx @janga/norna@latest init my-site
+cd my-site
 npm install
-npm run norna:dev
+npm run dev
 ```
 
 Run `init` before `npm install`. A new site directory is not a Node project
@@ -75,18 +75,18 @@ Actions use the same engine version.
 
 - Create a site: [Getting Started](docs/getting-started.md)
 - Understand required site files: [Site Structure](docs/site-structure.md)
-- Edit sections and galleries: [Content](docs/content.md)
+- Edit sections and image rows: [Content](docs/content.md)
 - Configure a site: [Configuration](docs/configuration.md)
 - Publish under a GitHub Pages project path:
   [`site.basePath`](docs/configuration.md#sitebasepath)
 - Configure site-wide theme: [Theme](docs/theme.md)
 - Add route pages: [Routes](docs/routes.md)
-- Set page width: [`layout.pageWidth`](docs/configuration.md#layoutpagewidth)
-- Set side gutters: [`layout.gutter`](docs/configuration.md#layoutgutter)
-- Set gallery width: [`gallery.width`](docs/configuration.md#gallerywidth)
+- Set page width: [`layout.pageWidth`](docs/theme.md#layout)
+- Set side gutters: [`layout.gutter`](docs/theme.md#layout)
+- Set image area width: [`gallery.width`](docs/theme.md#image-sizing)
 - Keep images within viewport height:
-  [`gallery.maxAvailableHeightPercent`](docs/configuration.md#gallerymaxavailableheightpercent)
-- Set the site font: [`typography.fontFamily`](docs/configuration.md#typographyfontfamily)
+  [`gallery.maxAvailableHeightPercent`](docs/theme.md#image-sizing)
+- Set the site font: [`typography.fontFamily`](docs/theme.md#typography)
 - Choose typography presets and overrides: [Typography](docs/typography.md)
 - Look up CLI and npm scripts: [Commands](docs/commands.md)
 - Understand generated images: [Images And Metadata](docs/images-and-metadata.md)

package/bin/norna-cli.mjs

@@ -15,10 +15,10 @@ Commands:
   dev:logs               Show local dev server logs
   dev:stop               Stop local dev server
   config:check           Validate site/config.mjs
-  content:check          Validate site/content.md and gallery references
+  content:check          Validate site/content.md and image references
   content:sync           Rewrite section order and move misplaced images
-  typography:presets     Show built-in typography preset values
-  typography:show        Show resolved typography for the selected site
+  typography presets     Show built-in typography preset values
+  typography show        Show resolved typography for the selected site
   site:public            Sync site/public/ to public/
   images                 Generate optimized image variants
   engine:update          Update @janga/norna in a site repository
@@ -86,6 +86,7 @@ if (siteDir) {
 }
 
 const [command = 'help', ...rest] = commandArgs;
+const [subcommand, ...subcommandRest] = rest;
 
 if (command === '-h' || command === '--help' || command === 'help') {
 	console.log(usage);
@@ -130,10 +131,14 @@ try {
 		await runAstroInherit(['sync']);
 	} else if (command === 'content:sync') {
 		await runScript('scripts/sync-content-sections.mjs', ['--write', ...rest]);
-	} else if (command === 'typography:presets') {
-		await runScript('scripts/show-typography.mjs', ['presets', ...rest]);
-	} else if (command === 'typography:show') {
-		await runScript('scripts/show-typography.mjs', ['show', ...rest]);
+	} else if (command === 'typography:presets' || (command === 'typography' && subcommand === 'presets')) {
+		const scriptArgs = command === 'typography' ? subcommandRest : rest;
+		await runScript('scripts/show-typography.mjs', ['presets', ...scriptArgs]);
+	} else if (command === 'typography:show' || (command === 'typography' && subcommand === 'show')) {
+		const scriptArgs = command === 'typography' ? subcommandRest : rest;
+		await runScript('scripts/show-typography.mjs', ['show', ...scriptArgs]);
+	} else if (command === 'typography') {
+		throw new Error(`Unknown typography command: ${subcommand ?? ''}\n${usage}`);
 	} else if (command === 'site:public') {
 		await runScript('scripts/sync-site-public.mjs', rest);
 	} else if (command === 'images') {

package/docs/README.md

@@ -9,9 +9,9 @@ For a site maintainer:
 
 1. [Getting Started](getting-started.md)
 2. [Site Structure](site-structure.md)
-3. [Configuration](configuration.md)
-4. [Content](content.md)
-5. [Theme](theme.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)
@@ -35,16 +35,15 @@ For design and naming principles:
 
 For a quick reference:
 
-- [Configuration](configuration.md) describes every supported
-  `site/config.mjs` field, including `layout.pageWidth`, `layout.gutter`,
-  gallery viewport limits, `typography.fontFamily`, validation rule, and
-  default.
+- [Configuration](configuration.md) describes technical `site/config.mjs`
+  fields such as URL, base path, locale labels, footer, GitHub, and deploy
+  settings.
 - [Content](content.md) describes page frontmatter, section frontmatter,
-  galleries, carousels, temporary sections, Markdown section matching, and
+  image rows, carousels, temporary sections, Markdown section matching, and
   content validation.
-- [Theme](theme.md) describes site-wide presentation, page and section
-  presentation overrides, frame colors, and inline styles.
-- [Typography](typography.md) describes presets, roles, overrides,
+- [Theme](theme.md) describes site-wide layout, layout density, image sizing,
+  font, typography rhythm, presentation colors, frame colors, and inline styles.
+- [Typography](typography.md) describes presets, rhythms, roles, overrides,
   inheritance, and inspection commands.
 - [Routes](routes.md) describes route files, slugs, route navigation, and
   route image directories.
@@ -55,7 +54,7 @@ For a quick reference:
 Design documents are intentionally separate from the user reference:
 
 - [Command Organization](design/command-organization.md) defines command
-  namespaces for pure gallery projects, mixed projects, and engine development.
+  namespaces for standalone sites, mixed projects, and engine development.
 - [Site Examples Structure](design/site-examples-structure.md) defines the
   intended vocabulary for starters, examples, documentation sites, reference
   docs, and fixtures.

package/docs/commands.md

@@ -25,8 +25,8 @@ norna dev:stop
 norna config:check
 norna content:check
 norna content:sync
-norna typography:presets
-norna typography:show
+norna typography presets
+norna typography show
 norna site:public
 norna images
 norna engine:update [version|latest]
@@ -55,7 +55,7 @@ norna --help
 ## Starter npm Scripts
 
 The starter uses `norna:*` for norna-specific work. This avoids collisions
-when a `norna` presentation is embedded inside a larger GitHub project
+when a Norna site is embedded inside a larger GitHub project
 whose own `build`, `test`, or deploy scripts mean something different.
 
 The starter defines:
@@ -90,7 +90,7 @@ npm run build
 
 `npm run dev` calls `npm run norna:dev`. In the pure starter,
 `npm run build` aliases `npm run norna:build`. In mixed repositories, such as
-a GitHub project that embeds a gallery presentation next to an app, `build`
+a GitHub project that embeds a Norna site next to an app, `build`
 should normally mean the repository's complete publishable artifact, while
 `norna:build` builds only the `norna` part.
 
@@ -101,13 +101,13 @@ should normally mean the repository's complete publishable artifact, while
   cache path.
 - `config:check`: validates `site/config.mjs` against the runtime config
   reader.
-- `content:check`: validates section structure and gallery references, then
+- `content:check`: validates section structure and image references, then
   runs `astro sync`.
 - `content:sync` / `norna:sync`: rewrites Markdown section order and moves misplaced referenced
   image files after confirmation.
-- `typography:presets`: prints the exact built-in values for every typography
-  preset.
-- `typography:show`: prints the selected site's resolved typography for the
+- `typography presets`: prints the exact built-in values for typography
+  presets and rhythms.
+- `typography show`: prints the selected site's resolved typography for the
   theme, every page route, and every section. Each value includes its source,
   and inherited page or section values are marked with `inherited: true`.
 - `site:public`: copies `site/public/` into `site/.norna/public/` and
@@ -125,7 +125,7 @@ should normally mean the repository's complete publishable artifact, while
   engine version, engine root, Astro dependency, and installed Astro version.
   With `--latest`, it also asks npm for the latest published engine version.
 - `init <target-dir> [--type pure|embedded] [--site-dir <path>]`: creates a
-  pure gallery project from the packaged starter, or adds a gallery source
+  standalone site project from the packaged starter, or adds a Norna site
   directory plus `norna:*` scripts to an existing project in embedded mode.
   Pure setup pins `@janga/norna` to the version that created it.
 - `build`: runs config check, content check, public sync, image generation, and

package/docs/configuration.md

@@ -58,152 +58,21 @@ site: {
 }
 ```
 
-## Layout
+## Visual Theme
 
-### `layout.pageWidth`
+Visual configuration lives in `site/theme.md`, not `site/config.mjs`.
 
-- Purpose: maximum width of the main page content area, including section
-  headings, section text, galleries, sticky-navigation alignment, and footer.
-- Type: string containing a simple positive CSS length.
-- Required: no.
-- Default: `1180px`.
-- Validation: if set, it must be a positive number followed by one of `px`,
-  `rem`, `em`, `vw`, `vh`, `vmin`, `vmax`, `ch`, or `%`.
-- Consequence: the value overrides the global `--page-width` CSS variable.
-  It is the outer width limit for content that is centered on the page.
-  `gallery.width` cannot render wider than this page width or the available
-  viewport width after responsive gutters.
-
-Example:
-
-```js
-layout: {
-	pageWidth: '1180px',
-}
-```
-
-### `layout.gutter`
-
-- Purpose: side margin removed from the viewport before the available content
-  width is calculated.
-- Type: either a CSS length string used on all viewports, or an object with
-  `desktop` and `mobile` CSS length strings.
-- Required: no.
-- Default: desktop `clamp(1.25rem, 4vw, 3rem)`, mobile `1rem`.
-- Validation: if set, each value must be a positive CSS length such as `16px`,
-  `3rem`, or `4vw`. `clamp()` with those simple lengths is also accepted.
-- Consequence: wider gutters leave more side margin and reduce the maximum
-  available width for galleries and aligned text.
-
-Example:
-
-```js
-layout: {
-	gutter: {
-		desktop: '48px',
-		mobile: '16px',
-	},
-}
-```
-
-## Gallery
-
-### `gallery.width`
-
-- Purpose: maximum rendered width for gallery images, gallery captions, and
-  left- or right-aligned section text that is intended to line up with gallery
-  edges.
-- Type: string containing a simple positive CSS length.
-- Required: no.
-- Default: `900px`.
-- Validation: if set, it must be a positive number followed by one of `px`,
-  `rem`, `em`, `vw`, `vh`, `vmin`, `vmax`, `ch`, or `%`.
-- Consequence: the value overrides the global `--gallery-width` CSS variable.
-  Images and aligned text cannot render wider than this value, but the
-  effective width is also limited by `layout.pageWidth`, `layout.gutter`, and
-  `gallery.maxAvailableWidthPercent`.
-
-Example:
-
-```js
-gallery: {
-	width: '900px',
-}
-```
-
-### `gallery.maxAvailableWidthPercent`
+Use [Theme](theme.md) for:
 
-- Purpose: maximum share of the available width, after gutters, that gallery
-  images, gallery captions, and aligned section text may use.
-- Type: either a number used on all viewports, or an object with `desktop` and
-  `mobile` numbers.
-- Required: no.
-- Default: desktop `100`, mobile `100`.
-- Validation: each value must be greater than `0` and less than or equal to
-  `100`.
-- Consequence: `100` allows the gallery to use the full available width. A
-  smaller value keeps galleries narrower without changing the page width or
-  gutters.
-
-Example:
-
-```js
-gallery: {
-	maxAvailableWidthPercent: {
-		desktop: 100,
-		mobile: 100,
-	},
-}
-```
-
-### `gallery.maxAvailableHeightPercent`
-
-- Purpose: maximum share of viewport height that gallery images may use.
-- Type: either a number used on all viewports, or an object with `desktop` and
-  `mobile` numbers.
-- Required: no.
-- Default: desktop `74`, mobile `68`.
-- Validation: each value must be greater than `0` and less than or equal to
-  `100`.
-- Consequence: images keep their proportions and are scaled down when filling
-  the available width would make them taller than this limit. This applies to
-  both landscape and portrait images.
-
-Example:
-
-```js
-gallery: {
-	maxAvailableHeightPercent: {
-		desktop: 74,
-		mobile: 68,
-	},
-}
-```
-
-## Typography
-
-### `typography.fontFamily`
-
-- Purpose: global CSS `font-family` stack used by site text and sticky
-  navigation.
-- Type: string containing a CSS font-family value.
-- Required: no.
-- Default: `Arial, 'Helvetica Neue', Helvetica, sans-serif`, matching the
-  engine's existing sticky-navigation font stack.
-- Validation: if set, it must be a non-empty string and must not contain
-  semicolons, braces, or line breaks.
-- Consequence: the value overrides the global `--font-sans` CSS variable for
-  the whole page. Section headings, body text, gallery captions, footer text,
-  and sticky navigation all inherit from that variable unless engine CSS gives a
-  more specific rule.
-
-Example:
-
-```js
-typography: {
-	fontFamily: "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
-}
-```
+- `layout.pageWidth`
+- `layout.gutter`
+- `layout.density`
+- `gallery.width`
+- `gallery.maxAvailableWidthPercent`
+- `gallery.maxAvailableHeightPercent`
+- `typography.fontFamily`
+- typography presets, rhythm, and overrides
+- presentation colors, inline styles, and frame colors
 
 ## Navigation
 
@@ -272,7 +141,7 @@ Fields:
   `Sections`.
 - `locale.labels.menu`: mobile menu summary text, default `Menu`.
 - `locale.labels.closeMenu`: reserved close-menu label, default `Close menu`.
-- `locale.labels.gallery`: gallery ARIA label prefix, default `Gallery`.
+- `locale.labels.gallery`: image row ARIA label prefix, default `Images`.
 
 Example:
 
@@ -285,7 +154,7 @@ locale: {
 		pageNavigation: 'På denna sida',
 		sectionNavigation: 'Sektioner',
 		menu: 'Meny',
-		gallery: 'Galleri',
+		gallery: 'Bilder',
 	},
 }
 ```

package/docs/content.md

@@ -1,7 +1,7 @@
 # Content
 
 `site/content.md` is the homepage page file for a `norna` site. It defines the
-page metadata, section order, section ids, gallery rows, and Markdown text for
+page metadata, section order, section ids, image rows, and Markdown text for
 the homepage.
 
 Route pages use the same page and section model in
@@ -25,14 +25,14 @@ The Astro content schema validates these top-level fields in page files:
   [Theme](theme.md) and [Typography](typography.md).
 - `frame`: optional page-level frame color source. See [Theme](theme.md).
 - `sections`: required non-empty array. Defines section order, ids,
-  presentation overrides, and gallery rows.
+  presentation overrides, and image rows.
 
 Minimal homepage:
 
 ```md
 ---
-title: My Gallery
-description: A small gallery site.
+title: My Site
+description: A small Norna site.
 sections:
   - id: intro
 ---
@@ -81,9 +81,9 @@ Keep these values aligned:
 The visible section navigation label comes from the Markdown heading text, not
 from the frontmatter id.
 
-## Galleries
+## Image Rows
 
-Each gallery row can contain a single image:
+Each image row can contain a single image:
 
 ```yaml
 gallery:
@@ -105,7 +105,7 @@ images from `site/routes/<route-folder>/images/<section-id>/`.
 
 ## Carousels
 
-A gallery row can contain a carousel instead of a single image:
+An image row can contain a carousel instead of a single image:
 
 ```yaml
 gallery:
@@ -147,7 +147,7 @@ Both `from` and `until` use `YYYY-MM-DD`. Either value may be omitted, but a
 
 Hidden sections are omitted from the rendered HTML and sticky navigation. They
 remain in the page file, and `content:check` still validates their matching
-Markdown headings and gallery image references.
+Markdown headings and image references.
 
 The current date is evaluated at dev/build time. Set `NORNA_TODAY` to preview
 or test a specific date:
@@ -187,21 +187,23 @@ npm run norna:content:check
 ```
 
 This checks section order and heading ids, duplicate image names, missing image
-files, misplaced referenced images, duplicate gallery references, invalid image
+files, misplaced referenced images, duplicate image references, invalid image
 references, unreferenced images, undefined inline styles, 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 `gallery` appears at the top level:
+known nested key such as `gallery` or section-specific `typography` appears at
+the top level:
 
 ```yaml
-typography:
-  preset: quiet-gallery
-  overrides:
-    body:
-      paragraphSpacing: 0.8em
+presentation:
+  typography:
+    preset: quiet-gallery
+    overrides:
+      body:
+        paragraphSpacing: 0.8em
 ```
 
 Top-level page frontmatter may contain only `title`, `description`, `slug`,