pageship 0.2.0 → 0.4.0

package/dist/skills/pageship-docs/references/design.md

@@ -2,45 +2,63 @@
 
 ## Who sets the look
 
-Take the look from the first source that has one:
+Settle the look and its colours yourself, from the first source that has one:
 
 1. The user's explicit visual instructions.
 2. The project's design system: its tokens, stylesheets or brand guide.
-3. An installed design skill: one in your list of available skills, not a skill file found elsewhere on disk. Prefer Anthropic's `frontend-design`, then the Taste Skill stack (`design-taste-frontend` and its companion skills). Follow its guidance on type, colour values and character. When it asks questions or offers options, take its default and keep going.
+3. An installed design skill: one in your list of available skills, not a skill file found elsewhere on disk. Prefer Anthropic's `frontend-design`, then the Taste Skill stack (`design-taste-frontend` and its companion skills). Follow its guidance on type and character. When it asks questions or offers options, take its default and keep going.
 4. Otherwise, copy [the plain default](plain-default.md).
 
-Whatever sets the look, these rules own structure, density, reading width, print, the colour count below and the [file rules](file.md). A design skill's one-accent or colour-lock rule shapes the values it picks, but the colour count here wins whatever a design skill says about accents: two accents, four series colours and three status colours. A document is for reading: leave out the landing-page parts a design skill may suggest, such as hero banners, decorative sections, marketing copy and entrance animations.
+Whatever sets the look, these rules own structure, density, reading width, print, the colours below and the [file rules](file.md). The colours here win whatever a design skill says about palettes or accents: two accents, four series colours and three status colours, from [the palette calculator](#the-palette-calculator). A document is for reading: leave out the landing-page parts a design skill may suggest, such as hero banners, decorative sections, marketing copy, and entrance animations on text and sections. Figures move only as `pageship-motion` says.
 
 ## The look's colour variables
 
-Every source file sets these fourteen variables in `:root`, once for light and once more under `@media (prefers-color-scheme: dark)`. The look's source fills their values: a design system from its tokens, a design skill from the palette it chooses, the plain default as written. Each takes a plain colour value: hex, `rgb()`, `hsl()`, `oklch()`, or `light-dark()` of those. Pattern skills colour their parts from these variables and no other colour.
+Every source file sets these fourteen variables in `:root`, once for light and once more under `@media (prefers-color-scheme: dark)`. [The palette calculator](#the-palette-calculator) fills their values, unless the user gives the colours or the project's design system has colour tokens: then those fill them. Each takes a plain colour value: hex, `rgb()`, `hsl()`, `oklch()`, or `light-dark()` of those. Pattern skills colour their parts from these variables and no other colour.
 
-| Variable                     | Colours                                                                                                                                                                     | Floor against `--bg` |
-| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
-| `--bg`                       | The page background.                                                                                                                                                        |                      |
-| `--fg`                       | Text.                                                                                                                                                                       | 4.5:1                |
-| `--muted`                    | Secondary text: meta lines, captions, axis labels, connector labels.                                                                                                        | 4.5:1                |
-| `--line`                     | Hairlines: rules, table borders, frames, gridlines.                                                                                                                         |                      |
-| `--surface`                  | Tinted panels: callouts, code blocks, caption strips, diagram nodes.                                                                                                        |                      |
-| `--accent`                   | The first accent: the title area, section headings, callout bars, focus outlines and the focus of each figure.                                                              | 3:1                  |
-| `--accent-2`                 | The second accent: links, the title rule and quote bars. In each theme, at least 60° from the first in OKLCH hue, so it stands out from the first accent and from the page. | 4.5:1                |
-| `--series-1` to `--series-4` | Chart series and diagram node categories, in this order. Four hues apart from each other and from the accents.                                                              | 3:1                  |
-| `--good`, `--warn`, `--bad`  | A status the source gives, such as on track, at risk and blocked: green, amber and red tuned to the look.                                                                   | 3:1                  |
+| Variable                     | Colours                                                                                                        | Floor against `--bg` |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------- |
+| `--bg`                       | The page background.                                                                                           |                      |
+| `--fg`                       | Text.                                                                                                          | 4.5:1                |
+| `--muted`                    | Secondary text: meta lines, captions, axis labels, connector labels.                                           | 4.5:1                |
+| `--line`                     | Hairlines: rules, table borders, frames, gridlines.                                                            |                      |
+| `--surface`                  | Tinted panels: callouts, code blocks, caption strips, diagram nodes.                                           |                      |
+| `--accent`                   | The first accent: the title area, section headings, callout bars, focus outlines and the focus of each figure. | 4.5:1                |
+| `--accent-2`                 | The second accent: links, the title rule and quote bars.                                                       | 4.5:1                |
+| `--series-1` to `--series-4` | Chart series and diagram node categories, in this order. Four hues apart from each other and from the accents. | 3:1                  |
+| `--good`, `--warn`, `--bad`  | A status the source gives, such as on track, at risk and blocked: green, amber and red tuned to the look.      | 3:1                  |
 
-Spend colour by the 60-30-10 rule: the neutrals fill most of the page, the first accent carries the look, and the second accent is the small share that stands out. Both accents colour something a reader sees in every source file, as the table places them. The first accent meets 4.5:1 where it colours text, such as headings.
+Spend colour by the 60-30-10 rule: the neutrals fill most of the page, the first accent carries the look, and the second accent is the small share that stands out. Both accents colour something a reader sees in every source file, as the table places them.
 
 A status the source gives shows in the source's words, in an element with `data-status="good"`, `"warn"` or `"bad"` that carries the matching colour on a dot, border or bar beside the words; the words stay `--fg`. The words are the element's own text, or a `.status` label inside it when the element holds more, such as a card. Rate it only as the source's word does: good for done or on track, warn for at risk, bad for blocked, late or missed. Any other status, such as in progress or not started, stays `--muted` with no `data-status`.
 
+## The palette calculator
+
+[palette.mjs](palette.mjs) writes all fourteen variables for light and dark, each at its floor. The accents are what it gives. Make each choice below yourself, from the topic and the source.
+
+- **Seed** (`--seed`): the project's brand colour when it has one, otherwise a colour you pick for the topic: hex, `rgb()`, `hsl()` or `oklch()`, with hues in degrees.
+- **Number of colours** (`--colours`, 1 to 5): the hues the colour system sets: 1 for a calm look of one hue, more for a livelier one. Hues 1 and 2 become the accents, hues 3 to 5 the first series colours, and the calculator picks the rest. With 1, the second accent is a shade of the first.
+- **Gap** (`--gap`): degrees between hues. Leave it out to space the hues evenly. A small gap, such as 30, gives neighbouring hues; a large one, contrasting hues.
+- **Preset** (`--preset`), in place of the number and the gap: `split-complementary` (three hues at 0°, 150° and 210°) or `rectangle` (four at 0°, 60°, 180° and 240°).
+- **Neutral tint** (`--tint`): how much of the seed's hue the background, text and lines carry: `none`, `subtle` (the default) or `strong`.
+
+```sh
+node <pageship-docs folder>/references/palette.mjs --seed '#0d9488' --colours 3 --gap 40
+node <pageship-docs folder>/references/palette.mjs --seed '#0d9488' --preset split-complementary --tint none
+```
+
+It prints the `:root` block for light and the one for dark. Put their declarations in the look's light and dark root rules, in place of any colour values there. Without Node, keep [the plain default](plain-default.md)'s colours.
+
 ## Base rules every file meets
 
 - **Light and dark.** Both themes follow the system setting through `prefers-color-scheme`.
 - **Contrast.** Text meets WCAG AA: 4.5:1 for body text, 3:1 for large text, icons and control borders. Each colour variable meets its floor in the table above, in light and in dark.
 - **Reading width.** Prose lines hold about 70 characters (`max-width: 70ch` on prose).
 - **Type size.** Body text is at least 16px. Nothing a reader needs is smaller than 13px, including captions, table text, labels and code.
+- **Height.** Content sets each part's height, or a length in `rem` or `px`. Previews frame the page at its full height, so a height that follows the window (`vh`, `svh`, `lvh`, `dvh`) grows with the frame.
 - **Phone width.** At 390px wide the page never scrolls sideways and keeps at least 12px of side padding, so no text or figure frame touches the screen's edge. Wide content scrolls inside its own box: a `<div class="scroll">` (`overflow-x: auto`) around a diagram or chart, the `.table-scroll` box `pageship-table` gives, or a code block's own `pre`.
 - **Print.** A print stylesheet shows all content, expands anything collapsed (`details::details-content { content-visibility: visible }`), hides controls, prints dark text on white, and avoids breaking inside figures, table rows and callouts.
 - **Links and controls.** Hovering a link or control changes how it looks, such as a thicker underline or a tinted background, and keyboard focus shows a visible outline. Every control is a native interactive element. Before adding one, load `pageship-interaction`.
-- **Motion.** Nothing moves until the reader acts. Under `prefers-reduced-motion: reduce`, nothing animates and every state shows in full. Before making anything move, load `pageship-motion`.
+- **Motion.** Every chart, graphic and sequence plays once when it scrolls into view and stops on its end state, which its markup holds; everything else holds still until the reader acts. Under `prefers-reduced-motion: reduce`, nothing plays on its own and every state shows in full. Before drawing a chart, a graphic or a sequence, or making anything else move, load `pageship-motion`.
 - **Headings.** One `h1`, then levels in order. The document has a `lang` attribute and a `title`.
 
 ## The form of each figure
@@ -57,4 +75,6 @@ Take each figure's form from what the reader wants of it. Before writing a form
 | The lines of code the text is about                                                                            | Code block                             | `pageship-code-block`  |
 | An image, video or audio the source gives                                                                      | Media                                  | `pageship-media`       |
 | Items with one attribute each, or steps in one line with no branch whose timing doesn't matter                 | List                                   |                        |
-| One or two relationships, or two or three numbers that aren't parts of a whole                                 | Sentence                               |                        |
+| A single relationship, or one or two numbers, that a figure would only repeat                                  | Sentence                               |                        |
+
+A point that fits a figure's row and the list or sentence row takes the figure, with the list or sentence as the prose beside it.

package/dist/skills/pageship-docs/references/html-validate-rules.mjs

@@ -0,0 +1,326 @@
+// Pageship's html-validate rules, loaded by html-validate.json beside this file.
+// Run: npx --yes html-validate@11.17.0 --config <this folder>/html-validate.json <file>
+
+import { readFileSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// `npx` installs html-validate where this file can't import it by name, so take its rule class
+// from the copy that is running, found through the command's path.
+async function loadHtmlValidate() {
+  const command = process.argv[1] ? realpathSync(process.argv[1]) : "";
+  if (/[/\\]html-validate[/\\]bin[/\\]html-validate\.m?js$/u.test(command)) {
+    return import(pathToFileURL(join(dirname(command), "../dist/esm/index.js")).href);
+  }
+  return import("html-validate");
+}
+
+const { Rule } = await loadHtmlValidate();
+
+const fileRules = new URL("./file.md", import.meta.url);
+
+/** The script and stylesheet tags the file rules give, with their exact attributes. */
+const trustedTags = [
+  ...readFileSync(fileRules, "utf8").matchAll(/^```html\n([\s\S]*?)^```/gmu),
+].flatMap(([, block]) =>
+  [...block.matchAll(/<(script|link)\b([^>]*)>/gu)].map(([, name, attributes]) => {
+    const values = new Map(
+      [...attributes.matchAll(/([\w-]+)="([^"]*)"/gu)].map(([, key, value]) => [key, value]),
+    );
+    return {
+      url: values.get(name === "script" ? "src" : "href"),
+      integrity: values.get("integrity"),
+      crossorigin: values.get("crossorigin"),
+    };
+  }),
+);
+
+const hasScheme = /^[a-z][a-z\d+.-]*:/iu;
+
+/** Hosted font CSS differs by browser, so it can't carry `integrity`. */
+const hostedFonts = /^https:\/\/fonts\.googleapis\.com\/css2?\?/u;
+
+const attributeValue = (element, name) => {
+  const value = element.getAttributeValue(name);
+  return typeof value === "string" ? value : null;
+};
+
+const linkTypes = (element) =>
+  (attributeValue(element, "rel") ?? "").toLowerCase().split(/\s+/u).filter(Boolean);
+
+/** The location of `text.slice(begin, end)`, for `text` that starts at `location`. */
+function locate(location, text, begin, end) {
+  const before = text.slice(0, begin);
+  const newline = before.lastIndexOf("\n");
+  return {
+    filename: location.filename,
+    offset: location.offset + begin,
+    line: location.line + before.split("\n").length - 1,
+    column: newline === -1 ? location.column + begin : begin - newline,
+    size: end - begin,
+  };
+}
+
+/** Spaces in place of each match, so offsets into the text stay the same. */
+const blank = (text, pattern) => text.replace(pattern, (match) => " ".repeat(match.length));
+const cssComments = /\/\*[\s\S]*?\*\//gu;
+const cssStrings = /"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'/gu;
+
+/**
+ * The markup inside each `<svg>`, which html-validate leaves unparsed, and the location in the
+ * file of an offset into that markup.
+ */
+function* svgContents(document, source) {
+  // Blanking comments keeps commented-out markup from counting.
+  const data = blank(source.data, /<!--[\s\S]*?-->/gu);
+  for (const element of document.querySelectorAll("svg")) {
+    // An svg tag, read past any ">" inside its quoted attribute values.
+    const tags = /<(\/?)svg\b(?:[^>"']|"[^"]*"|'[^']*')*?(\/?)>/giu;
+    tags.lastIndex = Math.max(0, element.location.offset - source.offset - 1);
+    const opening = tags.exec(data);
+    if (!opening) continue;
+    const start = opening.index + opening[0].length;
+    // The svg's own closing tag, past any svg nested inside it.
+    let depth = 1;
+    let end = -1;
+    for (let tag = tags.exec(data); tag; tag = tags.exec(data)) {
+      // A self-closing <svg/> opens nothing.
+      if (tag[2]) continue;
+      depth += tag[1] ? -1 : 1;
+      if (depth === 0) {
+        end = tag.index;
+        break;
+      }
+    }
+    if (end === -1) continue;
+    const at = (begin, length) =>
+      locate(source, source.data, start + begin, start + begin + length);
+    yield { element, markup: data.slice(start, end), at };
+  }
+}
+
+/** The CSS of every `<style>` element and `style` attribute, SVG's included, with where it starts. */
+function* stylesheets(document, source) {
+  for (const element of document.querySelectorAll("style")) {
+    const text = element.childNodes[0];
+    if (text) yield { element, css: element.textContent, location: text.location };
+  }
+  for (const element of document.querySelectorAll("[style]")) {
+    const attribute = element.getAttribute("style");
+    if (typeof attribute?.value === "string") {
+      yield { element, css: attribute.value, location: attribute.valueLocation };
+    }
+  }
+  for (const { element, markup, at } of svgContents(document, source)) {
+    const css = /<style\b[^>]*>([\s\S]*?)<\/style\s*>|\sstyle\s*=\s*(?:"([^"]*)"|'([^']*)')/giu;
+    for (const match of markup.matchAll(css)) {
+      const text = match[1] ?? match[2] ?? match[3];
+      const begin = match.index + match[0].indexOf(text, match[0].indexOf(match[1] ? ">" : "="));
+      yield { element, css: text, location: at(begin, text.length) };
+    }
+  }
+}
+
+class TrustedLibraries extends Rule {
+  documentation() {
+    return {
+      description:
+        "Load scripts and stylesheets only with a tag copied from the file rules (references/file.md): the same URL, `integrity` and `crossorigin`. A hosted Google Fonts stylesheet needs no `integrity`.",
+    };
+  }
+
+  setup() {
+    this.on("dom:ready", ({ document, source }) => {
+      for (const element of document.querySelectorAll("script[src]")) {
+        this.check(element, attributeValue(element, "src"));
+      }
+      for (const element of document.querySelectorAll("link")) {
+        const types = linkTypes(element);
+        const preloads = (attributeValue(element, "as") ?? "").toLowerCase();
+        const stylesheet =
+          types.includes("stylesheet") || (types.includes("preload") && preloads === "style");
+        const script =
+          types.includes("modulepreload") || (types.includes("preload") && preloads === "script");
+        if (stylesheet || script) {
+          this.check(element, attributeValue(element, "href"), { stylesheet });
+        }
+      }
+      for (const { element, css, location } of stylesheets(document, source)) {
+        const code = blank(css, cssComments);
+        for (const match of code.matchAll(/@import\s+(?:url\(\s*)?["']?([^"')\s;]+)/giu)) {
+          const url = match[1];
+          // A path beside the file is pageship/no-relative-paths' problem.
+          if (hostedFonts.test(url) || !hasScheme.test(url)) continue;
+          this.report(
+            element,
+            `The @import of ${url} is not a stylesheet the file rules give: load only the tags they give`,
+            locate(location, css, match.index, match.index + match[0].length),
+          );
+        }
+      }
+      for (const element of document.querySelectorAll("script")) {
+        if (element.hasAttribute("src")) continue;
+        const imported = /\bimport\b[^;]*?["'](https?:\/\/[^"']+)/u.exec(element.textContent)?.[1];
+        if (imported) {
+          this.report(
+            element,
+            `The module import of ${imported} can't be checked by integrity: load the library with a <script src> tag from the file rules`,
+          );
+        }
+      }
+    });
+  }
+
+  check(element, url, { stylesheet = false } = {}) {
+    if (url === null || (stylesheet && hostedFonts.test(url))) return;
+    const trusted = trustedTags.find((tag) => tag.url === url);
+    if (!trusted) {
+      this.report(element, `${url} is not a tag in the file rules: load only the tags they give`);
+      return;
+    }
+    for (const name of ["integrity", "crossorigin"]) {
+      if (attributeValue(element, name) !== trusted[name]) {
+        this.report(element, `${url} needs ${name}="${trusted[name]}", as the file rules give it`);
+      }
+    }
+  }
+}
+
+/** Attributes that load a resource, by the elements that carry them. */
+const loadingAttributes = {
+  script: ["src"],
+  img: ["src", "srcset"],
+  source: ["src", "srcset"],
+  video: ["src", "poster"],
+  audio: ["src"],
+  track: ["src"],
+  iframe: ["src"],
+  embed: ["src"],
+  object: ["data"],
+  input: ["src"],
+  link: ["href"],
+};
+/** The same inside an `<svg>`, read from its markup. */
+const svgLoads =
+  /<(?:image|use|feimage|script)\b[^>]*?\s(?:xlink:)?(?:href|src)\s*=\s*(?:"([^"]*)"|'([^']*)')/giu;
+/** The specifier of each static or dynamic module import in a script. */
+const imports = /\bimport\s*(?:\(\s*|[\w$*{}\s,]+?\s*from\s*)?["']([^"']+)["']/gu;
+
+const allowedUrl = /^(?:https:\/\/|data:|#)/iu;
+
+/** The URL of each candidate in a `srcset`, where a `data:` URL may hold commas of its own. */
+function srcsetUrls(srcset) {
+  const urls = [];
+  let rest = srcset;
+  for (;;) {
+    rest = rest.replace(/^[\s,]+/u, "");
+    if (!rest) return urls;
+    const url = /^\S+/u.exec(rest)[0];
+    rest = rest.slice(url.length);
+    if (url.endsWith(",")) {
+      urls.push(url.replace(/,+$/u, ""));
+    } else {
+      urls.push(url);
+      // Skip the descriptor, such as "2x" or "640w", up to the next candidate.
+      rest = rest.replace(/^[^,]*/u, "");
+    }
+  }
+}
+
+class NoRelativePaths extends Rule {
+  documentation() {
+    return {
+      description:
+        "A published file is the only file Pageship serves, so nothing loads from beside it. Use an `https://` or `data:` URL, or a `#fragment`.",
+    };
+  }
+
+  setup() {
+    this.on("dom:ready", ({ document, source }) => {
+      for (const [name, attributes] of Object.entries(loadingAttributes)) {
+        for (const element of document.querySelectorAll(name)) {
+          for (const attribute of attributes) {
+            const value = attributeValue(element, attribute);
+            if (value === null) continue;
+            const urls = attribute === "srcset" ? srcsetUrls(value) : [value.trim()];
+            for (const url of urls) this.check(element, url, element.location);
+          }
+        }
+      }
+      for (const { element, markup, at } of svgContents(document, source)) {
+        for (const match of markup.matchAll(svgLoads)) {
+          this.check(element, (match[1] ?? match[2]).trim(), at(match.index, match[0].length));
+        }
+      }
+      for (const element of document.querySelectorAll("script")) {
+        const text = element.childNodes[0];
+        if (element.hasAttribute("src") || !text) continue;
+        for (const match of element.textContent.matchAll(imports)) {
+          // An import from a URL is pageship/trusted-libraries' problem.
+          if (hasScheme.test(match[1])) continue;
+          const location = locate(
+            text.location,
+            element.textContent,
+            match.index,
+            match.index + match[0].length,
+          );
+          this.check(element, match[1], location);
+        }
+      }
+      for (const { element, css, location } of stylesheets(document, source)) {
+        const code = blank(css, cssComments);
+        for (const match of code.matchAll(/url\(\s*["']?([^"')]*)|@import\s+["']([^"']*)/giu)) {
+          const url = (match[1] ?? match[2]).trim();
+          this.check(
+            element,
+            url,
+            locate(location, css, match.index, match.index + match[0].length),
+          );
+        }
+      }
+    });
+  }
+
+  check(element, url, location) {
+    if (allowedUrl.test(url)) return;
+    this.report(
+      element,
+      `"${url}" loads from beside the file, which isn't published with it: use an https:// or data: URL`,
+      location,
+    );
+  }
+}
+
+const viewportHeight = /(?<![\w.-])-?(?:\d+\.?\d*|\.\d+)(?:vh|svh|lvh|dvh)\b/giu;
+
+class NoViewportHeight extends Rule {
+  documentation() {
+    return {
+      description:
+        "Size parts by their content, `rem` or `%`, not by the window's height: `vh`, `svh`, `lvh` and `dvh` are not allowed.",
+    };
+  }
+
+  setup() {
+    this.on("dom:ready", ({ document, source }) => {
+      for (const { element, css, location } of stylesheets(document, source)) {
+        for (const match of blank(blank(css, cssComments), cssStrings).matchAll(viewportHeight)) {
+          this.report(
+            element,
+            `${match[0]} sizes by the window's height: size by the content, rem or % instead`,
+            locate(location, css, match.index, match.index + match[0].length),
+          );
+        }
+      }
+    });
+  }
+}
+
+export default {
+  name: "pageship",
+  rules: {
+    "pageship/trusted-libraries": TrustedLibraries,
+    "pageship/no-relative-paths": NoRelativePaths,
+    "pageship/no-viewport-height": NoViewportHeight,
+  },
+};

package/dist/skills/pageship-docs/references/html-validate.json

@@ -0,0 +1,13 @@
+{
+  "plugins": ["./html-validate-rules.mjs"],
+  "extends": ["html-validate:recommended", "html-validate:document", "html-validate:prettier"],
+  "rules": {
+    "no-inline-style": "off",
+    "prefer-native-element": ["error", { "exclude": ["region"] }],
+    "require-sri": ["error", { "exclude": ["https://fonts.googleapis.com/"] }],
+    "heading-level": ["error", { "allowMultipleH1": false }],
+    "pageship/trusted-libraries": "error",
+    "pageship/no-relative-paths": "error",
+    "pageship/no-viewport-height": "error"
+  }
+}