@dataimago/css 0.1.0-alpha.21 → 0.1.0-alpha.23

package/README.md

@@ -13,6 +13,8 @@ Depends on [`@dataimago/tokens`](../tokens) for the canonical house identity.
 - `dist/latex/dataimago-tokens.sty` + `dataimago.sty` — the generated `di-*` colour layer and the LaTeX macro layer.
 - `dist/dataviz/` — the Okabe-Ito data-viz palette as CSS, TeX (PSTricks/TikZ), JSON and R.
 - `dist/templates/` — the project templates (`KNOWLEDGE-*.md`, the Quarto website scaffold) as stamped copies, synced into a project with `dataimago-sync` like the other outputs (house only).
+- `dist/fonts/` — the token fonts as WOFF2 subsets with `fonts.css` per script, and `lang.css` (see Fonts).
+- `dist/quarto/_extensions/dataimago/monograph/`, `dist/figures/`, `dist/fonts/pkg/` — the PDF format, the figure toolkit and the package-name face, with the `dataimago-figures` bin (see PDF).
 - `dist/outputs.json` and the `dataimago-sync` bin — pinned sync for non-JS consumers (below).
 
 Use [`@dataimago/css-neutral`](../css-neutral) instead when an externally-owned Level-3 app or future third-party hub needs the neutral identity.
@@ -63,6 +65,245 @@ in CI: it fails on any drift. The shipped outputs are listed in `dist/outputs.js
 (e.g. `https://unpkg.com/@dataimago/css@<version>/dist/outputs.json`). See
 [`wiki/patterns/new-consumer-checklist.md`](../../wiki/patterns/new-consumer-checklist.md).
 
+## PDF
+
+`@dataimago/css` (house only; `css-neutral` ships none of this) carries the PDF format: a Quarto extension, a figure toolkit and the package-name face. See `wiki/decisions/pdf-format.md` and `src/latex/README.md`.
+
+- `dist/quarto/_extensions/dataimago/monograph/`: the `dataimago/monograph-pdf` leaf (`_extension.yml`, filters, partials, `dataimago-base.sty`, `dataimago-monograph.sty`, `dataimago-tokens.sty`, `fonts/`).
+- `dist/figures/`: `dataimago-figure.sty`, the tokens, the static Noto fonts and licences, for the `dataimago-figures` bin.
+- `dist/fonts/pkg/`: Latin Modern Sans (WOFF2, `fonts.css`, `GFL.txt`, `README-lm.txt`) for the `.pkg` span in HTML.
+
+**design.json mappings** (directory keys end in `/`):
+
+```json
+{ "package": "@dataimago/css", "version": "<exact version>",
+  "outputs": { "quarto/_extensions/dataimago/monograph/": "_extensions/dataimago/monograph/",
+               "figures/": "figures/",
+               "fonts/pkg/": "assets/fonts/pkg/",
+               "quarto/dataimago-light.scss": "styles/", "quarto/dataimago-dark.scss": "styles/",
+               "quarto/components.scss": "styles/" } }
+```
+
+**The paired `_quarto.yml`.** The extension is PDF only; the work keeps its own HTML format with the synced theme pair:
+
+```yaml
+format:
+  html:
+    theme:
+      light: [cosmo, styles/dataimago-light.scss, styles/components.scss]
+      dark: [cosmo, styles/dataimago-dark.scss, styles/components.scss]
+    html-math-method: mathml
+    css: [assets/fonts/pkg/fonts.css]
+  dataimago/monograph-pdf: default
+```
+
+**Metadata.** `title`, `subtitle`, `author` (with `affiliations`), `version`, `date`, `license` (`text`, `url`), `epigraph` (`text`, `attribution`), `toc`, `abstract` (set as a front-matter chapter), `dataimago-logo` (reserved, default `false`; Quarto owns `logo`) and `license-badge` (reserved, default `false`; `true` warns and the licence prints as text).
+
+**Matter classes.** Put `{.frontmatter}`, `{.backmatter}` or `{.appendix}` on a level-1 heading. On a deeper heading the render stops and names it. In HTML these are ordinary sections. Write no raw LaTeX in the `.qmd`.
+
+**Figures.** `{.box}` images get the figure plate and frame (`#f7f7f6` plate, light frame, in both modes). Build PSTricks sources with `npx -p @dataimago/css@<version> dataimago-figures build <dir>`: each source compiles once into `.pdf`, `.svg` (fonts as paths) and RGBA `.png`. Run it from a checkout of the work with `figures/` synced.
+
+**TeX requirements.** LuaLaTeX (TeX Live 2026 or later) for documents, with memoir, fontspec, unicode-math, lua-ul and luacolor; XeLaTeX, PSTricks, `dvisvgm` and poppler's `pdftocairo` for figures. The fonts come with the extension, so nothing is installed system-wide. Quarto copies the leaf's `fonts/` (about 6 MB) next to each rendered `.tex`, so add a `.gitignore` rule for it. The repository checks the format with `pnpm run validate:pdf` and the `PDF` CI job.
+
+**Copies Quarto leaves behind.** Quarto copies the leaf's `fonts/` (about 6 MB) and the three `dataimago-*.sty` files beside the source directory of every document it renders (the project root, and each subdirectory that holds a rendered `.qmd`), and leaves them there. They are build output, so ignore them in the work's own repository, scoped to the directories that hold rendered documents:
+
+```gitignore
+/fonts/
+/chapters/fonts/
+dataimago-*.sty
+```
+
+Use `**/fonts/` only if no directory of the work has a `fonts/` of its own: a work that keeps its own fonts under `fonts/` must list the copies by directory as above, or ignore `dataimago-*.sty` and the leaf's font file names instead.
+
+## Package site
+
+`@dataimago/css` (house only; `css-neutral` ships none of this) carries the package-site leaf: the Quarto format `dataimago/pkgsite` (key `pkgsite-html`) that dresses an R package's GitHub Pages site with a landing stage, cards, reference pages and the AI-composed label. **The normal way to use it is `dataimago::create_package_site()`**, which writes everything below, syncs it and renders the pages; read on to do it by hand or to see what it writes. See `wiki/decisions/package-site-factory.md`.
+
+- `dist/quarto/_extensions/dataimago/pkgsite/`: `_extension.yml`, `pkgsite.scss`, `filters/landing.lua`, `filters/provenance.lua`, `pkgsite-hero.js` (JS heroes only) and `hero-fallback.svg`. The leaf ships no fonts.
+
+**design.json mapping** (directory keys end in `/`; the generator merges into an existing file by adding keys):
+
+```json
+{ "package": "@dataimago/css", "version": "<exact version>",
+  "outputs": {
+    "quarto/_extensions/dataimago/pkgsite/": "_extensions/dataimago/pkgsite/",
+    "fonts/latin/": "assets/fonts/latin/", "fonts/latin-ext/": "assets/fonts/latin-ext/",
+    "fonts/josefin/": "assets/fonts/josefin/", "fonts/math/": "assets/fonts/math/",
+    "fonts/lang.css": "assets/fonts/" } }
+```
+
+**The paired `_quarto.yml`.** List each mapped `fonts.css`, and `lang.css`, under the format. A JS hero is imported at run time, so Quarto does not publish it: `project.resources` always lists `assets/fonts/**` (the generator writes it unconditionally and its CI guard fails without it) and adds `assets/hero/**` only for a JS hero (an `svg` or `fallback` hero needs no entry).
+
+```yaml
+project:
+  type: website
+  resources:
+    - assets/fonts/**       # always listed
+    - assets/hero/**        # only for hero.kind: js
+format:
+  pkgsite-html:
+    css:
+      - assets/fonts/latin/fonts.css
+      - assets/fonts/latin-ext/fonts.css
+      - assets/fonts/josefin/fonts.css
+      - assets/fonts/math/fonts.css
+      - assets/fonts/lang.css
+```
+
+**The landing.** `index.qmd` uses `page-layout: custom` and loads `_landing.yml`; the `.di-landing` div is replaced by the stage (a page without it is left as written):
+
+```markdown
+---
+pagetitle: "<pkg>"
+page-layout: custom
+toc: false
+metadata-files: [_landing.yml]
+---
+::: {.di-landing}
+::: {.di-landing-overview}
+<README body, without badges or the first H1>
+:::
+:::
+```
+
+A README's own `##` and `###` headings, lists and code blocks are fine in the overview: the stage is built from Div nodes, so Quarto's section wrapping cannot swallow the hero or the cards. A page with a `.di-landing` stage never shows a table of contents, whatever the project sets (the generator writes `toc: false`; the leaf also sets it from the filter, with a CSS backstop). `hero.src` and `hero.poster` must be relative paths with no `..` segment, and an SVG hero is re-checked by the leaf before it is inlined; an unsafe one fails the render and names the file.
+
+```yaml
+pkgsite:
+  name: toOrdinal
+  title: "Cardinal to Ordinal Number & Date Conversion"
+  version: "1.5-0.0"
+  hero: { kind: svg, src: assets/hero/hero.svg, poster: assets/hero/poster.svg, alt: "One sentence." }  # svg | js | fallback
+  links: [ { text: GitHub, href: "…" } ]
+  cards:    # keys in order: overview, documentation, api, news, source; a card with no target is left out
+    - { key: overview, title: Overview, href: overview/index.qmd, desc: "…" }
+```
+
+**Hero inputs.** `ui/hero/hero.svg`: CSS animation only, inside `@media (prefers-reduced-motion: no-preference)`, `animation-iteration-count: 3`; no `<script>`, SMIL, `<?xml` declaration or external reference; styles scoped under the root class; a `viewBox`. Or `ui/hero/hero.js` with `ui/hero/poster.{svg,png}`: a default export `mount(el, {signal}) -> {pause(), play(), destroy()}` that stops after a finite run, served from the same origin and scheme as the site. Optional `ui/hero/hero.yml` with `alt:`. With neither, the brand fallback shows. A visible pause control is always present, and under reduced motion the poster shows and no module loads.
+
+**AI-composed pages.** A page whose front matter has a `knowledge:` block (`status: draft | approved`, `composer`, `source_sha`, `source_url`, and for approved pages `approved_by`, `approved_on`, `edited_by_author`) gets the "AI-composed" label. A malformed or inconsistent block fails the render and names the page.
+
+**Navbar.** Overview · Documentation · API · What's new, then a GitHub link. A pinned navbar is offset in CSS on landing pages at 1024 px and up; keep the navbar to one line (4rem), or it overlaps the pinned hero. The repository checks the leaf with `pnpm run validate:pkgsite` and `tools/motion-lint.mjs`.
+
+## Fonts
+
+The package ships the token fonts as WOFF2 files, so a site or document does not depend on Google's CDN. Everything is under `dist/fonts/`, one directory per script, each with a `fonts.css` of `@font-face` rules and the licence text:
+
+- Noto Sans, upright and italic, variable in weight (100 to 900), width pinned at 100.
+- Noto Sans Mono, upright only, variable in weight (100 to 900).
+- Noto Sans Math, one static weight (400), for equations.
+- Josefin Sans, upright only, variable in weight (100 to 700), for house headings. It is the upstream file wrapped as WOFF2, never subset (its licence reserves the font name).
+
+Directories: latin, latin-ext, greek, greek-ext, cyrillic, cyrillic-ext, vietnamese, josefin, math. Each `@font-face` uses `font-display: swap`, a weight range read from the font file, and a `unicode-range` on the subset files, so a browser downloads only the scripts a page renders. There is no `local()` source and no preload. Subsets keep every layout feature the kept text uses; `lnum` and `tnum` work in Noto Sans. Noto Sans Mono's digits are monospaced and lining by design, and it has no figure features. Josefin Sans has no `lnum` or `tnum` feature; its digits are lining and proportional. `dist/fonts/lang.css` holds the language rules (below). The licence is OFL-1.1; `dist/fonts/` carries each licence file.
+
+Combining marks: the `latin` and `latin-ext` files also carry the whole combining-diacritics block (U+0300-036F), a documented addition to Google's ranges, so decomposed accents (for example e + U+0301, or o + U+031B) draw from the same file as their base letter.
+
+### Using them
+
+`dist/fonts/**` is listed in `dist/outputs.json`, so `dataimago-sync` copies it. A key ending in `/` maps a whole directory to a destination ending in `/`.
+
+**A web page.** Map every script you ship and `fonts/lang.css`, then link the CSS files. The browser fetches only what the page renders.
+
+```json
+{ "package": "@dataimago/css", "version": "<exact version>",
+  "outputs": { "fonts/latin/": "assets/fonts/latin/", "fonts/latin-ext/": "assets/fonts/latin-ext/",
+               "fonts/greek/": "assets/fonts/greek/", "fonts/greek-ext/": "assets/fonts/greek-ext/",
+               "fonts/cyrillic/": "assets/fonts/cyrillic/", "fonts/cyrillic-ext/": "assets/fonts/cyrillic-ext/",
+               "fonts/vietnamese/": "assets/fonts/vietnamese/",
+               "fonts/josefin/": "assets/fonts/josefin/",
+               "fonts/math/": "assets/fonts/math/", "fonts/lang.css": "assets/fonts/" } }
+```
+
+**A self-contained Quarto output** (`embed-resources: true`). Map only the scripts the work's language needs, for example `fonts/latin/` and `fonts/latin-ext/` (add `fonts/vietnamese/` for Vietnamese text), plus `fonts/math/` if the work has equations and `fonts/lang.css`. Add `fonts/josefin/` for the house headings. List each CSS file under `css:` in `_quarto.yml` and set `html-math-method: mathml`. Quarto then embeds just the files those rules reach.
+
+```yaml
+format:
+  html:
+    embed-resources: true
+    html-math-method: mathml
+    css:
+      - assets/fonts/latin/fonts.css
+      - assets/fonts/latin-ext/fonts.css
+      - assets/fonts/vietnamese/fonts.css
+      - assets/fonts/josefin/fonts.css
+      - assets/fonts/math/fonts.css
+      - assets/fonts/lang.css
+```
+
+**A translated work in a script the package does not ship** (Arabic, Hebrew, Devanagari, and so on). `lang.css` already names the family. Load it from Google Fonts on the web, or make the files yourself (see "Making a script the package does not ship") and keep them in the work's own repository.
+
+### Numeric figures
+
+Josefin Sans has no figure features: its digits are lining and proportional, so they do not line up in columns.
+
+- `.di-numeric-display` keeps Josefin and the light weight, for hero numbers (a statistic callout, a year).
+- `.di-numeric-tabular` uses Noto Sans with tabular lining figures, for tables, ledgers and anything stacked that must align.
+
+```html
+<span class="di-numeric-display">2026</span>
+<td class="di-numeric-tabular">1,234.50</td>
+```
+
+### Other languages
+
+Text in another language must carry a `lang` attribute, or the browser applies its own fallback. In Quarto write `[text]{lang=ar}` for a span, a fenced div `::: {lang=ar}` for a block, or `lang: ar` in the front matter for a whole work. `lang.css` maps each language to a family by `:lang()` and rebinds the display variables on headings and navigation only; the brand mark, code and maths are left alone. The tags `zh-CN`, `zh-SG` and bare `zh` map to Noto Sans SC (bare `zh` is treated as Simplified); `zh-TW`, `zh-HK` and `zh-MO` map to Noto Sans TC. Tag Traditional text `zh-Hant` or a Traditional region.
+
+### Maths
+
+Equations use native MathML in `Noto Sans Math` (`font.family.math` is `Noto Sans Math, math`, so a reader without the font gets the browser's maths face). Set `html-math-method: mathml`. MathJax and KaTeX bring their own fonts, and with `embed-resources` Quarto fetches them from the network unless `self-contained-math` is set. A property that chooses one of them is outside this contract.
+
+### Synthesised oblique
+
+Noto Sans Mono and Josefin Sans ship upright only. Italic text in them is the browser's synthesised oblique. Noto Sans has a true italic.
+
+### Preloading
+
+Preloading is yours to opt into; the package does not. For the Latin body file, in the page head:
+
+```html
+<link rel="preload" as="font" type="font/woff2" href="/assets/fonts/latin/noto-sans.woff2" crossorigin>
+```
+
+`crossorigin` is required even for a same-origin font, or the browser fetches it twice.
+
+### Caching
+
+File names are stable and change only when a family changes, so serve them with revalidation. That is the default on the hosts these properties use (confirmed 2026-10-31): GitHub Pages sends `cache-control: max-age=600` with an ETag, and Vercel serves static files with `public, max-age=0, must-revalidate`. Do not set a long immutable lifetime.
+
+### The Google alternative
+
+A project that does not sync files can link Google's CDN instead. This is the query matching what the package ships:
+
+```
+https://fonts.googleapis.com/css2?family=Josefin+Sans:wght@100..700&family=Noto+Sans:ital,wdth,wght@0,100,100..900;1,100,100..900&family=Noto+Sans+Math&family=Noto+Sans+Mono:wght@100..900&display=swap
+```
+
+Add `lang.css` as well. This loads full variable files from Google rather than the subsets, so a self-contained Quarto output becomes much larger. The Google route serves Google's own ranges, so decomposed accents using U+0302, U+0306 or U+031B fall back there (and on sites built from the Quarto website template, which uses that route); the shipped files carry the combining marks in the Latin files.
+
+### Making a script the package does not ship
+
+`subset.mjs` in the dataimago-design repository has an out mode that fetches a pinned upstream file, checks its digest, subsets it and writes `<script>/<family>.woff2`, `<script>/fonts.css` and the licence into a directory outside `packages/`. It refuses a family whose licence reserves the font name.
+
+```bash
+node tools/fonts/subset.mjs --out ../my-work/fonts \
+  --upstream <url pinned to a tag or commit> --sha256 <hex> --script arabic \
+  [--unicode-range "U+0600-06FF, U+200C-200E"] [--style normal|italic] \
+  --licence-url <url> --licence-sha256 <hex> \
+  [--member <path in archive> --member-sha256 <hex>] \
+  [--licence-member <path> --licence-member-sha256 <hex>]
+```
+
+Without the tool, fontTools (the repository pins Python 3.13 and `tools/fonts/requirements.txt`) does the same in two steps. Pin the width axis if the font has one, then subset keeping every layout feature:
+
+```bash
+fonttools varLib.instancer NotoSansArabic[wdth,wght].ttf wdth=100 --no-recalc-timestamp -o instanced.ttf
+pyftsubset instanced.ttf --unicodes="U+0600-06FF,U+200C-200E" --layout-features='*' \
+  --name-IDs='*' --name-languages='*' --notdef-outline --no-recalc-timestamp \
+  --flavor=woff2 --output-file=noto-sans-arabic.woff2
+```
+
+To wrap a file as WOFF2 without subsetting: `fonttools ttLib.woff2 compress -o out.woff2 in.ttf`. (The repository's tool also turns off table transforms so the tables stay byte-identical; the command line does not, so the bytes can differ while the font is the same.) Write the `@font-face` rule with `font-display: swap`, the font's own weight range and `unicode-range`, and no `local()`.
+
 ## Building
 
 ```bash