@janga/norna 0.7.2 → 0.7.3

package/docs/theme.md

@@ -13,12 +13,51 @@ on top of the resolved page presentation.
 ```yaml
 ---
 navigation:
-  brand: Example Gallery
+  brand: Example Site
+layout:
+  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(2.55rem, 4.2vw, 3.9rem)
+      mobile: 2.25rem
+    finalSectionBottom:
+      desktop: clamp(2.55rem, 4.2vw, 3.9rem)
+      mobile: 2.25rem
+    sectionHeadingToBody:
+      desktop: clamp(0.5625rem, 1.25vw, 0.75rem)
+      mobile: 0.4375rem
+    bodyToImages:
+      desktop: clamp(1.25rem, 2.5vw, 2rem)
+      mobile: 1.25rem
+    imageGap:
+      desktop: clamp(1.5rem, 3.5vw, 2.75rem)
+      mobile: 2.75rem
+    subheadingTop:
+      desktop: 2rem
+      mobile: 1.6rem
+    subheadingRuleTop:
+      desktop: 1rem
+      mobile: 0.8rem
+gallery:
+  width: 900px
+  maxAvailableWidthPercent:
+    desktop: 100
+    mobile: 100
+  maxAvailableHeightPercent:
+    desktop: 74
+    mobile: 68
+typography:
+  fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
+  preset: quiet-gallery
 presentation:
   backgroundColor: "#000000"
   textColor: "#f7f4ee"
-  typography:
-    preset: quiet-gallery
 frame:
   colors: presentation
 ---
@@ -47,6 +86,108 @@ 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.
+- `spacing`: vertical rhythm for sections, text, image rows, and Markdown
+  subheadings. Every spacing value accepts either one CSS length for all
+  viewports or `desktop` / `mobile` values.
+
+Example:
+
+```yaml
+layout:
+  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(2.55rem, 4.2vw, 3.9rem)
+      mobile: 2.25rem
+    subheadingTop:
+      desktop: 2rem
+      mobile: 1.6rem
+```
+
+If omitted, Norna uses `1180px` for `pageWidth`, desktop
+`clamp(1.25rem, 4vw, 3rem)` for `gutter`, mobile `1rem`, and the spacing
+defaults shown in the minimal theme example.
+
+Spacing keys:
+
+- `firstSectionTop`: space above the first section heading.
+- `sectionGap`: space above each following section.
+- `finalSectionBottom`: space below the final section.
+- `sectionHeadingToBody`: space from a section heading to its body text.
+- `bodyToImages`: space from section body text to image rows.
+- `imageGap`: space between image rows.
+- `subheadingTop`: space above Markdown `###` subheadings inside body text.
+- `subheadingRuleTop`: space between the rule above a Markdown `###`
+  subheading and the subheading text.
+
+## 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.
+- `overrides`: focused changes to preset values.
+
+Example:
+
+```yaml
+typography:
+  fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
+  preset: quiet-gallery
+  overrides:
+    headings:
+      h2:
+        size: medium
+      h3:
+        size: small
+    body:
+      lineHeight: 1.55
+```
+
+Use `norna typography presets` to inspect built-in preset 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 +197,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 +215,9 @@ page file is always an override on top of the theme:
 presentation:
   typography:
     overrides:
+      headings:
+        h2:
+          size: large
       body:
         paragraphSpacing: 1em
 ```
@@ -96,12 +238,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, 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 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,8 +12,8 @@ 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
@@ -23,23 +23,23 @@ Available presets:
 
 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 `headings.h1` through `headings.h4`, `body`, and `caption`.
+They differ primarily through heading scale, 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.
 
 Use this command to inspect the exact preset 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:
 
 ```sh
-npm run norna:typography:show
+norna typography show
 ```
 
 The output includes the site theme, every page route, and every section. Each
@@ -49,19 +49,28 @@ 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
+  overrides:
+    headings:
+      h2:
+        size: medium
+      h3:
+        size: small
+    body:
+      paragraphSpacing: 0.8em
 ```
 
 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:
@@ -76,14 +85,24 @@ 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.
+normal section heading size, not a hero size. 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`.
 
 Supported override fields:
 
-- `heading.align`, `heading.size`, `heading.lineHeight`, `heading.spacing`
+- `headings.h1.align`, `headings.h1.size`, `headings.h1.lineHeight`,
+  `headings.h1.spacing`
+- `headings.h2.align`, `headings.h2.size`, `headings.h2.lineHeight`,
+  `headings.h2.spacing`
+- `headings.h3.align`, `headings.h3.size`, `headings.h3.lineHeight`,
+  `headings.h3.spacing`
+- `headings.h4.align`, `headings.h4.size`, `headings.h4.lineHeight`,
+  `headings.h4.spacing`
 - `body.align`, `body.size`, `body.lineHeight`, `body.paragraphSpacing`
 - `caption.align`, `caption.size`, `caption.lineHeight`, `caption.spacing`
 
@@ -93,9 +112,9 @@ 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
 ```
 
 A page-level `presentation.typography.preset` changes the typographic base for
@@ -120,6 +139,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.