@janga/norna 0.7.2 → 0.7.4

package/docs/theme.md

@@ -13,12 +13,28 @@ on top of the resolved page presentation.
 ```yaml
 ---
 navigation:
-  brand: Example Gallery
+  brand: Example Site
+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
 presentation:
   backgroundColor: "#000000"
   textColor: "#f7f4ee"
-  typography:
-    preset: quiet-gallery
 frame:
   colors: presentation
 ---
@@ -47,6 +63,114 @@ navigation:
   brand: Norna
 ```
 
+## Layout
+
+`layout` is optional. It controls the outer page 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 structural spacing overrides for sections and image
+  rows. Every spacing value accepts either one CSS length for all viewports or
+  `desktop` / `mobile` values.
+
+Example:
+
+```yaml
+layout:
+  density: normal
+  pageWidth: 1180px
+  gutter:
+    desktop: clamp(1.25rem, 4vw, 3rem)
+    mobile: 1rem
+  spacing:
+    firstSectionTop:
+      desktop: clamp(1.875rem, 3vw, 2.75rem)
+      mobile: 1.375rem
+    sectionGap:
+      desktop: clamp(1.4rem, 3vw, 2.75rem)
+      mobile: 1.5rem
+```
+
+If omitted, Norna uses `1180px` for `pageWidth`, desktop
+`clamp(1.25rem, 4vw, 3rem)` for `gutter`, mobile `1rem`, and `normal` layout
+density.
+
+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 image rows.
+- `imageGap`: space between image rows.
+
+Text-near spacing, such as spacing after headings, spacing before Markdown
+subheadings, paragraph spacing, and caption spacing, belongs to
+`typography.rhythm` and typography overrides.
+
+## Image Sizing
+
+`gallery` is optional. It controls 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.
+
+Example:
+
+```yaml
+gallery:
+  width: 900px
+  maxAvailableWidthPercent:
+    desktop: 100
+    mobile: 100
+  maxAvailableHeightPercent:
+    desktop: 74
+    mobile: 68
+```
+
+If omitted, Norna uses `900px`, full available width, and image height limits of
+desktop `74` / mobile `68`.
+
+## Typography
+
+Top-level `typography` is the site-wide typographic base. It supports:
+
+- `fontFamily`: global CSS font-family stack.
+- `preset`: built-in typography preset.
+- `rhythm`: text-near spacing profile. Allowed values are `compact`,
+  `normal`, and `airy`.
+- `overrides`: focused changes to preset values.
+
+Example:
+
+```yaml
+typography:
+  fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
+  preset: quiet-gallery
+  rhythm: normal
+  overrides:
+    headings:
+      h2:
+        size: medium
+        spacingAfter: 0.55em
+      h3:
+        size: medium
+        spacingBefore: 1.5em
+        spacingAfter: 0.5em
+    body:
+      lineHeight: 1.55
+```
+
+Use `norna typography presets` to inspect built-in preset and rhythm values,
+and `norna typography show` to inspect the resolved typography for the
+selected site. See [Typography](typography.md).
+
 ## Presentation
 
 `presentation` is optional. It can contain:
@@ -56,8 +180,6 @@ navigation:
 - `textColor`: optional quoted hex color in `#rgb`, `#rrggbb`, or
   `#rrggbbaa` form.
 - `inlineStyles`: optional named inline text styles.
-- `typography`: optional typography preset and overrides. See
-  [Typography](typography.md).
 
 Example:
 
@@ -76,6 +198,10 @@ page file is always an override on top of the theme:
 presentation:
   typography:
     overrides:
+      headings:
+        h2:
+          size: large
+          spacingAfter: 0.6em
       body:
         paragraphSpacing: 1em
 ```
@@ -96,12 +222,12 @@ 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 gallery widths. The top spacing
+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 gallery captions. Links keep the global accent color.
+Markdown subheadings, and image captions. Links keep the global accent color.
 
 ## Frame Colors
 

package/docs/typography.md

@@ -1,10 +1,10 @@
 # Typography
 
-`norna` typography is configured through presets with optional overrides. The
-site font family itself is a technical setting in
-[`typography.fontFamily`](configuration.md#typographyfontfamily).
+`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 is `site/theme.md`.
+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 page or section needs a
 different presentation.
 
@@ -12,34 +12,40 @@ different presentation.
 
 Available presets:
 
-- `quiet-gallery`: the default for image-led art and portfolio sites. Text is
-  restrained and supports the images without dominating the page.
+- `quiet-gallery`: the default for image-led sites. Text is restrained and
+  supports the images without dominating the page.
 - `compact-gallery`: tighter typography for many sections, many images, or
   short information blocks.
 - `text-forward`: more generous body text for pages where longer text carries
   more of the experience.
-- `statement`: stronger type for introductions, first sections, and short
-  programmatic statements. Use it sparingly, usually as a section override.
+- `statement`: tighter, more declarative line-height for introductions, first
+  sections, and short programmatic statements. Use it sparingly, usually as a
+  section override.
 
 If theme typography is omitted, `quiet-gallery` is used.
 
-Presets normally keep `heading.size` and `body.size` at `medium`. They differ
-primarily through alignment, line height, paragraph spacing, caption treatment,
-and intended use. Choose larger or smaller type with focused overrides when a
-specific page or section needs it.
+Presets define alignment, size, and line height for `headings.h1` through
+`headings.h4`, `body`, and `caption`. Built-in presets use `medium` as the
+default size for every text role. Visual heading hierarchy comes from the
+Markdown heading level, so `h1` is larger than `h2`, `h2` is larger than `h3`,
+and so on.
 
-Use this command to inspect the exact preset values shipped with the installed
-engine:
+`rhythm` defines text-near spacing for headings, paragraphs, and captions.
+Available rhythms are `compact`, `normal`, and `airy`. Built-in rhythm values
+use `em` so spacing follows the rendered text size.
+
+Use this command to inspect the exact preset and rhythm values shipped with
+the installed engine:
 
 ```sh
-npm run norna:typography:presets
+norna typography presets
 ```
 
 Use this command to inspect the effective values for the selected site after
-presets and overrides have been applied:
+presets, rhythms, and overrides have been applied:
 
 ```sh
-npm run norna:typography:show
+norna typography show
 ```
 
 The output includes the site theme, every page route, and every section. Each
@@ -49,19 +55,34 @@ also marked with `inherited: true`.
 ## Configuration Shape
 
 ```yaml
-presentation:
-  typography:
-    preset: quiet-gallery
-    overrides:
-      body:
-        paragraphSpacing: 0.8em
+typography:
+  fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
+  preset: quiet-gallery
+  rhythm: normal
+  overrides:
+    headings:
+      h2:
+        size: medium
+        spacingAfter: 0.55em
+      h3:
+        size: medium
+        spacingBefore: 1.5em
+        spacingAfter: 0.5em
+    body:
+      paragraphSpacing: 0.8em
+    caption:
+      spacingBefore: 0.5em
 ```
 
 The typographic roles are:
 
-- `heading`: section headings.
+- `headings.h1`: reserved for page-level Markdown `#` headings if the content
+  model starts supporting them.
+- `headings.h2`: Markdown `##` section headings.
+- `headings.h3`: Markdown `###` subheadings inside section body text.
+- `headings.h4`: Markdown `####` subheadings inside section body text.
 - `body`: Markdown body text inside sections.
-- `caption`: gallery captions.
+- `caption`: image captions.
 
 Allowed alignment values are `left`, `center`, and `right`. Alignment can be
 responsive:
@@ -75,17 +96,28 @@ align:
 Allowed size values are `small`, `medium`, `large`, and `xlarge`. `medium` is
 the normal reading size. Use `small` for quieter supporting text, and use
 `large` or `xlarge` only when a page or section needs stronger emphasis.
-Headings use their own scale, but follow the same principle: `medium` is the
-normal section heading size, not a hero size.
+Each heading level uses its own scale, but follows the same principle:
+`medium` is the normal size for that level. Norna may render the first section
+heading as an HTML `h1` for document structure, but its visual typography still
+follows the Markdown level the user wrote: `##` uses `headings.h2`.
 
-`lineHeight` is a unitless number from `1` through `3`. `spacing` and
-`paragraphSpacing` are CSS lengths such as `0`, `0.8em`, `1rem`, or `12px`.
+`lineHeight` is a unitless number from `1` through `3`. `spacingBefore`,
+`spacingAfter`, and `paragraphSpacing` are CSS lengths such as `0`, `0.8em`,
+`1rem`, or `12px`. Use `em` for spacing that should track the text size.
 
 Supported override fields:
 
-- `heading.align`, `heading.size`, `heading.lineHeight`, `heading.spacing`
+- `headings.h1.align`, `headings.h1.size`, `headings.h1.lineHeight`,
+  `headings.h1.spacingBefore`, `headings.h1.spacingAfter`
+- `headings.h2.align`, `headings.h2.size`, `headings.h2.lineHeight`,
+  `headings.h2.spacingBefore`, `headings.h2.spacingAfter`
+- `headings.h3.align`, `headings.h3.size`, `headings.h3.lineHeight`,
+  `headings.h3.spacingBefore`, `headings.h3.spacingAfter`
+- `headings.h4.align`, `headings.h4.size`, `headings.h4.lineHeight`,
+  `headings.h4.spacingBefore`, `headings.h4.spacingAfter`
 - `body.align`, `body.size`, `body.lineHeight`, `body.paragraphSpacing`
-- `caption.align`, `caption.size`, `caption.lineHeight`, `caption.spacing`
+- `caption.align`, `caption.size`, `caption.lineHeight`,
+  `caption.spacingBefore`
 
 ## Inheritance
 
@@ -93,18 +125,21 @@ Theme typography is the site-wide base:
 
 ```yaml
 # site/theme.md
-presentation:
-  typography:
-    preset: quiet-gallery
+typography:
+  fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
+  preset: quiet-gallery
+  rhythm: normal
 ```
 
-A page-level `presentation.typography.preset` changes the typographic base for
-that page. A section-level `sections[].presentation.typography.preset` changes
-the typographic base for that section.
+A page-level `presentation.typography.preset` changes the typographic character
+for that page. A section-level `sections[].presentation.typography.preset`
+changes the typographic character for that section. `rhythm` is inherited
+separately, so changing preset does not change spacing unless `rhythm` is also
+set.
 
-If a section sets `typography.preset`, that section starts from that preset. If
-a section only sets `typography.overrides`, it keeps the resolved page preset
-and changes only the specified values.
+If a section sets `typography.rhythm`, that section changes text-near spacing.
+If a section only sets `typography.overrides`, it keeps the resolved page
+preset and rhythm and changes only the specified values.
 
 Example section override:
 
@@ -120,6 +155,6 @@ sections:
 ```
 
 Centered text uses narrower text widths. Left- or right-aligned heading and body
-text use the calculated gallery layout width so text edges line up with gallery
-images after layout gutters and gallery limits are applied. Gallery captions
-are normally centered.
+text use the calculated image layout width so text edges line up with images
+after layout gutters and image limits are applied. Captions are normally
+centered.

package/examples/dog-gallery/node_modules/.vite/deps/_metadata.json

@@ -0,0 +1,74 @@
+{
+  "hash": "18953098",
+  "configHash": "df6ba470",
+  "lockfileHash": "808f2e8e",
+  "browserHash": "54286dfc",
+  "optimized": {
+    "astro > aria-query": {
+      "src": "../../../../../node_modules/aria-query/lib/index.js",
+      "file": "astro_n_aria-query.js",
+      "fileHash": "dc2a8aee",
+      "needsInterop": true
+    },
+    "astro > axobject-query": {
+      "src": "../../../../../node_modules/axobject-query/lib/index.js",
+      "file": "astro_n_axobject-query.js",
+      "fileHash": "3acd67c7",
+      "needsInterop": true
+    },
+    "astro > html-escaper": {
+      "src": "../../../../../node_modules/html-escaper/esm/index.js",
+      "file": "astro_n_html-escaper.js",
+      "fileHash": "9967a3db",
+      "needsInterop": false
+    },
+    "astro/runtime/client/dev-toolbar/entrypoint.js": {
+      "src": "../../../../../node_modules/astro/dist/runtime/client/dev-toolbar/entrypoint.js",
+      "file": "astro_runtime_client_dev-toolbar_entrypoint__js.js",
+      "fileHash": "98dc9563",
+      "needsInterop": false
+    }
+  },
+  "chunks": {
+    "astro-D_GIpJIE": {
+      "file": "astro-D_GIpJIE.js",
+      "isDynamicEntry": true
+    },
+    "audit-DM9Hkl5B": {
+      "file": "audit-DM9Hkl5B.js",
+      "isDynamicEntry": true
+    },
+    "highlight-DnZ1ULOL": {
+      "file": "highlight-DnZ1ULOL.js",
+      "isDynamicEntry": false
+    },
+    "icons-RyebKi45": {
+      "file": "icons-RyebKi45.js",
+      "isDynamicEntry": false
+    },
+    "rolldown-runtime-BvCyGRYZ": {
+      "file": "rolldown-runtime-BvCyGRYZ.js",
+      "isDynamicEntry": false
+    },
+    "settings-DaU-gNnK": {
+      "file": "settings-DaU-gNnK.js",
+      "isDynamicEntry": true
+    },
+    "toolbar-63PA619H": {
+      "file": "toolbar-63PA619H.js",
+      "isDynamicEntry": true
+    },
+    "ui-library--bkcNSYz": {
+      "file": "ui-library--bkcNSYz.js",
+      "isDynamicEntry": true
+    },
+    "window-jPkpKVcy": {
+      "file": "window-jPkpKVcy.js",
+      "isDynamicEntry": false
+    },
+    "xray-BXCHpEJP": {
+      "file": "xray-BXCHpEJP.js",
+      "isDynamicEntry": true
+    }
+  }
+}