@casomoltd/tooling 0.32.1 → 0.33.1

package/README.md

@@ -15,7 +15,7 @@ Shared linting, formatting, commit config, and CLI tools for Casomo Ltd's repos.
 | `@casomoltd/tooling/knip` | Knip config for unused exports/dependencies |
 | `@casomoltd/tooling/jscpd` | Copy-paste detection config |
 | `@casomoltd/tooling/readability` | `scoreText()` — readability scoring for page content |
-| `@casomoltd/tooling/buttondown` | For a repo using the `buttondown` command: `tokenReader()` for its email templates, `loadSettings()` and `buildPayload()` for its tests, `EMAIL_CHROME_HIDES` for its config, and the `Check` type for its own gates |
+| `@casomoltd/tooling/buttondown` | For a repo using the `buttondown` command: the shared email blocks and skins (`createEmailBlocks`, `emailBaseCss`, `composeWebSkin`), `tokenReader()`, `loadSettings()` and `buildPayload()`, and `EMAIL_CHROME_HIDES` ([docs/buttondown.md](docs/buttondown.md)) |
 
 ### Bin commands
 
@@ -33,7 +33,7 @@ Shared linting, formatting, commit config, and CLI tools for Casomo Ltd's repos.
 | `spec-check` | Check a design spec's anchors, contents, figures and numbering |
 | `check-private-refs` | In a public repo, refuse a private tracker link or a name listed under `privateRefs` in `casomo.config.mjs` |
 | `check-personal-data` | Refuse an email, National Insurance number, UK mobile number, date of birth or locally denylisted name; per-repo allowances under `personalData` in `casomo.config.mjs` |
-| `buttondown` | Keep a Buttondown newsletter as code: `diff` and `apply` its fields (settings, skins and email templates) and tags, `check` the skins, sync their tokens, and create drafts. Settings under `buttondown` in `casomo.config.mjs`; the API key from the file `BUTTONDOWN_KEY_FILE` names |
+| `buttondown` | Keep a Buttondown newsletter as code: `diff` and `apply` its fields (settings, skins and email templates) and tags, `check` the skins, sync their tokens, and create drafts ([docs/buttondown.md](docs/buttondown.md)) |
 
 ## Install
 

package/buttondown/base-web.css

@@ -0,0 +1,135 @@
+/* The rules every site's blog skin shares, inserted ahead of the site's own
+   rules by composeWebSkin. They restyle Buttondown's markup by role and set
+   no value of their own: each comes from a variable the site's TOKENS block
+   defines, Buttondown's theme variables where the theme has the role and
+   --bd-* where it has not:
+
+     --bd-font-heading   headings and the archive entry's title
+     --bd-heading        their colour
+     --bd-action-bg      the one action's ground
+     --bd-action-ink     its label
+     --bd-action-weight  its label's weight
+     --bd-dialog-bg      a dialog's ground
+     --bd-focus          the focus ring
+     --bd-leading        an archive entry's line height */
+
+body,
+.subscribe,
+.manage-subscription {
+  background: var(--color-background);
+  color: var(--color-foreground);
+  font-family: var(--font-family-sans);
+}
+
+/* Square and flat everywhere, whatever class Buttondown gives an element,
+   its dialogs and their buttons included. A tag switch keeps its round
+   track. Removing every shadow removes any focus ring drawn as one, so
+   focus is an outline below. */
+*:not(.checkbox-field),
+*::before,
+*::after {
+  border-radius: var(--radius) !important;
+  box-shadow: none !important;
+}
+
+/* Important, so a theme utility that removes outlines cannot leave a
+   control with no focus indicator. */
+:focus-visible {
+  outline: 2px solid var(--bd-focus) !important;
+  outline-offset: 2px;
+}
+
+h1, h2, h3,
+.newsletter-name,
+.section-title,
+.modal-title,
+.login-modal-title {
+  font-family: var(--bd-font-heading);
+  color: var(--bd-heading);
+  letter-spacing: -0.01em;
+}
+
+/* The one action. `.archive__button` is every action button on the
+   archive, the subscribe form's and a signed-in reader's "Manage
+   subscription" alike; the theme sets it pill-shaped, white and upper
+   case with `!important`, so these name the element too to outrank it. */
+a.archive__button,
+button.archive__button,
+button.button.tinted,
+.portal-btn--primary,
+.subscription-success-button {
+  background-color: var(--bd-action-bg) !important;
+  color: var(--bd-action-ink) !important;
+  font-family: var(--font-family-sans) !important;
+  font-weight: var(--bd-action-weight) !important;
+  text-transform: none !important;
+  border-radius: var(--radius) !important;
+}
+
+/* 16px, because iOS zooms a focused field below it and the page jumps.
+   Buttondown's own rule is `input[type=email].input-field`, so the
+   portal's field is named with its type to outrank it. */
+.archive__subscribe-form-input,
+#subscribe-form input[type="email"],
+.subscribe-modal-content input[type="email"],
+.login-modal-content .magic-link-input,
+.manage-subscription input[type="email"].input-field,
+.manage-subscription input[type="text"].input-field {
+  font-family: var(--font-family-sans);
+  font-size: 16px;
+}
+
+.modal-content,
+.buttondown-dialog-root .bg-background {
+  background: var(--bd-dialog-bg) !important;
+}
+
+/* The log-in dialog renders outside the page body, so it does not
+   inherit the page's type. */
+.login-modal-content,
+.login-modal-content * {
+  font-family: var(--font-family-sans);
+}
+
+/* The line after a log-in request: body text, not Buttondown's green. */
+.magic-link-success-message {
+  color: var(--color-foreground) !important;
+}
+
+/* The theme centres the description, and lines of centred body text are
+   harder to read, since each starts in a different place. */
+.newsletter-description,
+.newsletter-description p {
+  text-align: left;
+}
+
+/* An archive entry, set as an article is: a large left-aligned title and
+   justified, hyphenated prose. */
+.email-body .subject {
+  font-family: var(--bd-font-heading);
+  font-size: 36px;
+  font-weight: 700;
+  line-height: 1.1;
+  color: var(--bd-heading);
+  text-align: left;
+}
+
+.email-body .description {
+  text-align: left;
+}
+
+.email-body-content {
+  margin-top: 1.5rem;
+}
+
+.email-body-content p,
+.email-body-content li {
+  font-size: 16px;
+  line-height: var(--bd-leading);
+}
+
+.email-body-content p {
+  text-align: justify;
+  hyphens: auto;
+  -webkit-hyphens: auto;
+}

package/buttondown/email-blocks.mjs

@@ -0,0 +1,191 @@
+/**
+ * The bands an email is built from, for a repo whose Buttondown emails
+ * draw their own header and footer: the title on a ground, white air,
+ * paragraphs, one action, a sign-off and the small print. The site
+ * supplies its tokens, its mark band and its colophon; this supplies the
+ * layout they share.
+ *
+ * Every rule is an inline `style` attribute, because inline is the only
+ * thing every mail client honours, and vertical rhythm is carried on
+ * table cell padding, because Outlook drops a margin on a table but
+ * always honours padding on a cell. Every block ends with its own
+ * trailing newlines, so a template is a plain concatenation.
+ */
+
+/** Buttondown re-emits these attributes in its own order when it inlines
+ *  an email, so the opening tag is written once. */
+export const TABLE =
+  '<table role="presentation"\n'
+  + '       cellpadding="0"\n'
+  + '       cellspacing="0"\n'
+  + '       border="0"\n'
+  + '       width="100%"';
+
+/** The body text size and a paragraph's spacing, the same in every band
+ *  and in the shared email stylesheet. */
+export const BODY_SIZE = "17px";
+export const PARAGRAPH_MARGIN = "0 0 16px 0";
+
+/** The template variables Buttondown fills with a subscriber's links. */
+const UNSUBSCRIBE = '{{ unsubscribe_url }}';
+const MANAGE = '{{ manage_subscription_url }}';
+
+/**
+ * The names an email theme must give, which `emailBaseCss` and
+ * `createEmailBlocks` both read: one value per site, so a font or colour
+ * has one producer.
+ */
+const THEME_PATHS = [
+  "fonts.body", "fonts.heading", "colours.page", "colours.ink",
+  "colours.heading", "leading.body", "leading.prose",
+];
+
+/** The paths in `paths` that `value` leaves undefined. */
+export function missingPaths(value, paths) {
+  return paths.filter((p) =>
+    p.split(".").reduce((v, key) => v?.[key], value) === undefined);
+}
+
+/** Throws, naming each path missing, so a site states its whole look
+ *  rather than rendering `undefined` into an email. */
+export function requirePaths(what, value, paths) {
+  const missing = missingPaths(value, paths);
+  if (missing.length) throw new Error(`${what} needs ${missing.join(", ")}`);
+}
+
+/** Checks an email theme: {fonts: {body, heading}, colours: {page, ink,
+ *  heading}, leading: {body, prose}}. */
+export function requireTheme(what, theme) {
+  requirePaths(what, {theme}, THEME_PATHS.map((p) => `theme.${p}`));
+}
+
+/**
+ * The blocks for one site. Every option is required:
+ *
+ *   theme:   the site's email theme (see requireTheme): the body and
+ *            heading fonts, the page, ink and heading colours, and the
+ *            prose line height
+ *   colours: {titleGround, action, actionInk, footerGround, footerRule}
+ *   rhythm:  {cardPadding, buttonCell, buttonSize, buttonPadding,
+ *             footerRuleWidth, footerCells: [top, bottom]}
+ *   small:   the small print's inline style
+ *   buttonClass: the class the email skin keys the button's rule on
+ *   smallLink(href, text): a link in the small print
+ *   colophon:  the small print's HTML, before the subscription sentence
+ *   copyright: the last line's HTML
+ *   sentenceBreak: what joins the colophon to the subscription sentence
+ *   signoff:   the name a message is signed with
+ */
+export function createEmailBlocks(options = {}) {
+  requireTheme("createEmailBlocks", options.theme);
+  requirePaths("createEmailBlocks", options, [
+    "colours.titleGround", "colours.action", "colours.actionInk",
+    "colours.footerGround", "colours.footerRule", "rhythm.cardPadding",
+    "rhythm.buttonCell", "rhythm.buttonSize", "rhythm.buttonPadding",
+    "rhythm.footerRuleWidth", "rhythm.footerCells.0", "rhythm.footerCells.1",
+    "small", "buttonClass", "smallLink", "colophon", "copyright",
+    "sentenceBreak", "signoff",
+  ]);
+  const {
+    theme, colours, rhythm, small, buttonClass, smallLink, colophon,
+    copyright, sentenceBreak, signoff: name,
+  } = options;
+
+  /** A link inside the message: body-coloured and underlined, which
+   *  leaves the action colour meaning "action". */
+  function bodyLink(href, text) {
+    return (
+      `<a href="${href}" style="color:${theme.colours.ink};`
+      + `text-decoration:underline;">${text}</a>`
+    );
+  }
+
+  /** What the message is, on its own ground. */
+  function card(title) {
+    return (
+      `${TABLE}\n`
+      + `       style="background-color:${colours.titleGround};"><tr><td`
+      + ` style="padding:${rhythm.cardPadding};"><div style="font-family:`
+      + `${theme.fonts.heading};color:${theme.colours.heading};font-size:22px;`
+      + "font-weight:700;line-height:28px;letter-spacing:-0.01em;\">"
+      + `${title}</div></td></tr></table>\n\n`
+    );
+  }
+
+  /** White air between bands: a cell with a height, because a margin on
+   *  the table above would be dropped by several clients. */
+  function spacer(height) {
+    return (
+      `${TABLE}\n`
+      + `       style="background-color:${theme.colours.page};"><tr><td`
+      + ` style="height:${height}px;line-height:${height}px;`
+      + "font-size:0;\">&nbsp;</td></tr></table>\n\n"
+    );
+  }
+
+  /** A paragraph of the message itself. */
+  function p(html, margin = PARAGRAPH_MARGIN) {
+    return (
+      `<p style="font-family:${theme.fonts.body};color:${theme.colours.ink};`
+      + `font-size:${BODY_SIZE};line-height:${theme.leading.prose};`
+      + "font-weight:400;"
+      + `margin:${margin};">${html}</p>\n\n`
+    );
+  }
+
+  /** The one action, in its own cell so the space around it does not
+   *  depend on the paragraph above collapsing its margin. */
+  function button(href, label) {
+    return (
+      `${TABLE}><tr><td style="padding:${rhythm.buttonCell};">`
+      + `<a class="${buttonClass}"\n`
+      + `   href="${href}"\n`
+      + `   style="font-family:${theme.fonts.body};display:inline-block;`
+      + `background-color:${colours.action};`
+      + `color:${colours.actionInk} !important;`
+      + `font-size:${rhythm.buttonSize};font-weight:600;line-height:1.2;`
+      + `padding:${rhythm.buttonPadding};text-decoration:none;">`
+      + `<span style="color:${colours.actionInk} !important;">`
+      + `${label}</span></a></td></tr></table>\n\n`
+    );
+  }
+
+  /** Signed off, with room above so it reads as the end of the message
+   *  rather than another paragraph of it. */
+  function signoff() {
+    return p(name, "24px 0 16px 0");
+  }
+
+  /**
+   * The small print: the colophon, how to leave, and the copyright line.
+   *
+   * `subscription` is false on the confirmation and its reminder, where
+   * there is no subscription yet to manage or leave. It has no default:
+   * a repo hiding Buttondown's own unsubscribe line relies on this one,
+   * so leaving it out by mistake would send an email with no way to
+   * leave.
+   */
+  function footer({subscription} = {}) {
+    if (typeof subscription !== "boolean") {
+      throw new Error("footer() needs subscription: true or false");
+    }
+    const [top, bottom] = rhythm.footerCells;
+    return (
+      `${TABLE}\n`
+      + "       style=\"margin-top:40px;"
+      + `background-color:${colours.footerGround};\n`
+      + `              border-top:${rhythm.footerRuleWidth} solid `
+      + `${colours.footerRule};"><tr><td style="padding:${top};">`
+      + `<div style="${small}">${colophon}`
+      + (subscription
+        ? `${sentenceBreak}You can ${smallLink(UNSUBSCRIBE, "unsubscribe")}`
+          + ` or ${smallLink(MANAGE, "manage your subscription")}.`
+        : "")
+      + `</div></td></tr><tr><td style="padding:${bottom};">`
+      + `<div style="${small}">${copyright}</div>`
+      + "</td></tr></table>\n"
+    );
+  }
+
+  return {bodyLink, button, card, footer, p, signoff, spacer};
+}

package/buttondown/engine.mjs

@@ -29,7 +29,7 @@
  * stylesheet is read verbatim, and an `.mjs` file's default export is the
  * field's value.
  */
-import {existsSync} from "node:fs";
+import {existsSync, readFileSync} from "node:fs";
 import {mkdir, readdir, readFile, writeFile} from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -64,8 +64,8 @@ const DRAFT = "draft";
 
 const FRONT_MATTER = /^---\n([\s\S]*?)\n---\n/;
 
-/** The two skins, by the Buttondown field each file fills. */
-const SKIN = {web: "web_css.css", email: "css.css"};
+/** The Buttondown fields holding the two skins. */
+const SKIN = {web: "web_css", email: "css"};
 
 /** Fields Buttondown stores behind its image proxy. */
 const IMAGE_FIELDS = new Set(["icon", "image"]);
@@ -77,6 +77,14 @@ const IDENTITY = ["id", "publicId", "username"];
 /** Hrefs Buttondown draws itself, which no socials entry names. */
 const BUTTONDOWN_LINKS = ["buttondown.com"];
 
+/** The shared web rules' opening line, which marks a composed skin, and
+ *  the variables those rules read, which such a skin must declare. */
+const BASE_WEB = readFileSync(new URL("./base-web.css", import.meta.url), "utf8");
+const BASE_MARK = BASE_WEB.slice(0, BASE_WEB.indexOf("\n"));
+const BASE_VARS = [...new Set(
+  [...BASE_WEB.matchAll(/var\((--[\w-]+)/g)].map((m) => m[1]),
+)];
+
 /** Values of `content:` that remove text rather than inject it. */
 const NO_CONTENT = new Set(["none", "normal", '""', "''"]);
 
@@ -101,10 +109,11 @@ export async function loadSettings(root = process.cwd()) {
       + "stylesheet the site's design tokens are declared in");
   }
   const at = (p) => path.resolve(root, p);
+  const dir = at(config.dir ?? "buttondown");
   return {
     root,
     newsletter: config.newsletter,
-    dir: at(config.dir ?? "buttondown"),
+    dir,
     globals: at(config.globals),
     tokens: config.tokens ?? [],
     extra: config.extra ?? [],
@@ -112,6 +121,10 @@ export async function loadSettings(root = process.cwd()) {
     allowedHides: config.allowedHides ?? {},
     linkClasses: Object.values(config.linkClasses ?? {}),
     ownLinks: [...BUTTONDOWN_LINKS, ...(config.ownLinks ?? [])],
+    // The file holding the web skin's TOKENS block, which `tokens`
+    // rewrites: the field file itself unless the field is composed.
+    webSkin: config.webSkin
+      ? at(config.webSkin) : path.join(dir, "fields", "web_css.css"),
     paletteFiles: (config.paletteFiles ?? []).map(at),
     checks: (config.checks ?? []).map(at),
   };
@@ -206,7 +219,7 @@ export function tokensBlock(settings, css) {
 /** Rewrites the web skin's TOKENS block from the site's tokens. */
 export async function writeTokens(settings) {
   const css = await readFile(settings.globals, "utf8");
-  const file = skinPath(settings, "web");
+  const file = settings.webSkin;
   const web = await readFile(file, "utf8");
   const {s, e} = markers(web);
   await writeFile(
@@ -217,11 +230,48 @@ export async function writeTokens(settings) {
 /** Every problem with the repo's skins and settings; empty when clean. */
 export async function runCheck(settings) {
   const css = await readFile(settings.globals, "utf8");
-  const web = await readIf(skinPath(settings, "web"));
-  const email = await readIf(skinPath(settings, "email"));
   const payload = await buildPayload(settings);
+  // The skins as sent, base rules and site rules together, so what is
+  // checked is what Buttondown receives. Absent, there is nothing to
+  // check, which is refused rather than passed.
+  for (const field of Object.values(SKIN)) {
+    if (typeof payload[field] !== "string") {
+      throw new Error(`the payload has no ${field} field to check`);
+    }
+  }
+  const web = payload[SKIN.web];
+  const email = payload[SKIN.email];
   const problems = [];
 
+  // An @import must be a whole statement before any rule: a browser
+  // ignores one after a rule, and one whose URL was cut short swallows
+  // what follows it. Read past the leading statements as the composer
+  // does; any @import left over, outside a string, is one of those.
+  const rest = stripComments(web.slice(preludeEnd(web)))
+    .replace(/"[^"]*"|'[^']*'/g, '""');
+  if (/@import/i.test(rest)) {
+    problems.push("the web skin has an @import that is not a complete "
+      + "statement before its first rule, which a browser ignores");
+  }
+
+  // Every variable the shared rules read, and every --bd-* role read
+  // anywhere, must be declared, or the declaration reading it is dropped
+  // without an error.
+  const plain = stripComments(web);
+  const declared = new Set(
+    [...plain.matchAll(/(--[\w-]+)\s*:/g)].map((m) => m[1]),
+  );
+  const read = new Set([
+    ...web.includes(BASE_MARK) ? BASE_VARS : [],
+    ...[...plain.matchAll(/var\((--bd-[\w-]+)/g)].map((m) => m[1]),
+  ]);
+  for (const name of read) {
+    if (!declared.has(name)) {
+      problems.push(`the web skin reads ${name}, which nothing declares: `
+        + "map it in the TOKENS block");
+    }
+  }
+
   if (settings.tokens.length || settings.extra.length) {
     const {s, e} = markers(web);
     if (web.slice(s, e) !== tokensBlock(settings, css)) {
@@ -574,6 +624,29 @@ export async function emit(settings, dir) {
   return written;
 }
 
+/**
+ * Where a stylesheet's leading statements end: its opening comments and its
+ * `@charset`, `@import` and `@layer` statements, which must come before any
+ * rule. An @import's URL may hold semicolons (a font request's weights), so
+ * it is read whole before its closing `;`; one that isn't a whole statement
+ * ends the leading statements there.
+ */
+export function preludeEnd(css) {
+  let at = 0;
+  for (;;) {
+    // A URL never holds a newline or a brace, so one that does is an
+    // import cut short, and ends the leading statements there.
+    const url = "(?:\"[^\"\\n{}]*\"|'[^'\\n{}]*')";
+    const lead = css.slice(at).match(new RegExp(
+      "^\\s*(\\/\\*[\\s\\S]*?\\*\\/|@charset\\s+\"[^\"]*\";"
+      + `|@import\\s+(?:url\\((?:${url}|[^)"'\\n{}]*)\\)|${url})[^;{]*;`
+      + "|@layer\\s+[^;{]*;)", "i",
+    ));
+    if (!lead) return at;
+    at += lead[0].length;
+  }
+}
+
 /** Comments removed by index rather than a lazy regex, which backtracks
  *  between its two literals. */
 export function stripComments(text) {
@@ -591,16 +664,13 @@ export function stripComments(text) {
 
 /** Why a call failed: Buttondown's `detail`, else its whole body, which
  *  names the fields it refused, else the status. */
-const detail = (res) =>
-  JSON.stringify(res.data?.detail ?? res.data ?? res.status);
-
-const newsletterPath = (newsletter) => `/newsletters/${newsletter.id}`;
-
-const skinPath = (settings, kind) =>
-  path.join(settings.dir, "fields", SKIN[kind]);
+function detail(res) {
+  return JSON.stringify(res.data?.detail ?? res.data ?? res.status);
+}
 
-const readIf = async (file) =>
-  existsSync(file) ? readFile(file, "utf8") : "";
+function newsletterPath(newsletter) {
+  return `/newsletters/${newsletter.id}`;
+}
 
 /** Whether `index` sits directly in a top-level `:root` or `@theme` block:
  *  `:root.dark`, `:root[data-theme]` and a `:root` nested in an at-rule are
@@ -675,12 +745,14 @@ function declarations(text) {
 
 /** Declaration values only, so a selector such as `a:not(#cafe)` is not
  *  read as a colour. */
-const cssValues = (text) =>
-  declarations(text).map(([, value]) => value).join(" ");
+function cssValues(text) {
+  return declarations(text).map(([, value]) => value).join(" ");
+}
 
 /** An SVG's attribute values. */
-const attributeValues = (text) =>
-  [...text.matchAll(/="([^"]*)"/g)].map((m) => m[1]).join(" ");
+function attributeValues(text) {
+  return [...text.matchAll(/="([^"]*)"/g)].map((m) => m[1]).join(" ");
+}
 
 function offPalette(values, palette) {
   return [...new Set(

package/buttondown/index.d.mts

@@ -26,6 +26,8 @@ export interface Settings {
   newsletter: Newsletter;
   dir: string;
   globals: string;
+  /** The file holding the web skin's TOKENS block. */
+  webSkin: string;
   tokens: [target: string, source: string][];
   extra: [target: string, value: string][];
   asserts: Record<string, string>;
@@ -44,7 +46,8 @@ export interface CheckContext {
   payload: Payload;
   /** The site's tokens stylesheet. */
   css: string;
-  /** The web skin and the email skin, as written. */
+  /** The web skin and the email skin as sent: composed, base rules and
+   *  site rules together. */
   web: string;
   email: string;
   readToken(css: string, name: string): string;
@@ -64,3 +67,59 @@ export function buildPayload(settings: Settings): Promise<Payload>;
 export function tokenReader(
   file: string | URL,
 ): Promise<(name: string) => string>;
+
+/** The opening tag every band's table shares. */
+export const TABLE: string;
+
+/** A site's email theme, read by both `emailBaseCss` and
+ *  `createEmailBlocks`, so each font and colour has one producer. */
+export interface EmailTheme {
+  fonts: {body: string; heading: string};
+  colours: {page: string; ink: string; heading: string};
+  /** Line heights: of the page, and of prose. */
+  leading: {body: string; prose: string};
+}
+
+export interface EmailBlockOptions {
+  theme: EmailTheme;
+  colours: {
+    titleGround: string; action: string; actionInk: string;
+    footerGround: string; footerRule: string;
+  };
+  rhythm: {
+    cardPadding: string; buttonCell: string; buttonSize: string;
+    buttonPadding: string; footerRuleWidth: string;
+    footerCells: [top: string, bottom: string];
+  };
+  /** The small print's inline style. */
+  small: string;
+  /** The class the email skin keys the button's rule on. */
+  buttonClass: string;
+  smallLink(href: string, text: string): string;
+  colophon: string;
+  copyright: string;
+  /** What joins the colophon to the subscription sentence. */
+  sentenceBreak: string;
+  signoff: string;
+}
+
+export interface EmailBlocks {
+  bodyLink(href: string, text: string): string;
+  button(href: string, label: string): string;
+  card(title: string): string;
+  footer(options: {subscription: boolean}): string;
+  p(html: string, margin?: string): string;
+  signoff(): string;
+  spacer(height: number): string;
+}
+
+/** The bands an email is built from, in one site's theme. */
+export function createEmailBlocks(options: EmailBlockOptions): EmailBlocks;
+
+/** The web skin: the shared rules inserted after the site stylesheet's
+ *  leading comments and @charset, @import and @layer statements, ahead of
+ *  its own rules. */
+export function composeWebSkin(site: string): string;
+
+/** The shared email rules, in the site's theme, with literal values. */
+export function emailBaseCss(theme: EmailTheme): string;

package/buttondown/index.mjs

@@ -5,3 +5,5 @@
 export {
   buildPayload, EMAIL_CHROME_HIDES, loadSettings, tokenReader,
 } from "./engine.mjs";
+export {createEmailBlocks, TABLE} from "./email-blocks.mjs";
+export {composeWebSkin, emailBaseCss} from "./skins.mjs";

package/buttondown/skins.mjs

@@ -0,0 +1,85 @@
+/**
+ * The rules every site's skins share, for a repo whose `fields/web_css.mjs`
+ * and `fields/css.mjs` compose a field from them and the site's own rules.
+ */
+import {readFileSync} from "node:fs";
+import {
+  BODY_SIZE, PARAGRAPH_MARGIN, requireTheme,
+} from "./email-blocks.mjs";
+import {EMAIL_CHROME_HIDES, preludeEnd} from "./engine.mjs";
+
+/** The shared web rules: base-web.css, which reads every value from the
+ *  variables the site's TOKENS block defines. */
+const WEB_BASE = readFileSync(
+  new URL("./base-web.css", import.meta.url), "utf8",
+);
+
+/**
+ * The web skin: the site's stylesheet with the shared rules inserted after
+ * its opening comments and `@import`s, which must come before any rule,
+ * and ahead of its own rules, so the site's win a tie.
+ */
+export function composeWebSkin(site) {
+  const at = preludeEnd(site);
+  const head = site.slice(0, at);
+  return `${head}${head ? "\n\n" : ""}${WEB_BASE}\n${site.slice(at)}`;
+}
+
+/**
+ * The shared email rules, in the site's email theme (see requireTheme), with
+ * literal values: a mail client cannot resolve a CSS custom property, and
+ * Buttondown inlines the stylesheet before sending. The site's own
+ * stylesheet follows it: fonts it loads, its link colour, its button, its
+ * quotations and its small print.
+ */
+export function emailBaseCss(theme) {
+  requireTheme("emailBaseCss", theme);
+  const {fonts, colours, leading} = theme;
+  const hides = Object.keys(EMAIL_CHROME_HIDES)
+    .map((selector) => `${selector} { display: none !important; }`);
+  return [
+    `body, td, div { font-family: ${fonts.body}; color: ${colours.ink}; `
+      + `font-size: ${BODY_SIZE}; line-height: ${leading.body}; }`,
+    // Buttondown inlines its own grey; important, so this is the last.
+    `body { background-color: ${colours.page} !important; }`,
+    // Unscoped, because the template rounds its card, its quotation and
+    // whatever it adds next under class names of its own.
+    "* { border-radius: 0 !important; }",
+    // Forced, because the template styles the paragraph it wraps around
+    // the content and wins on specificity.
+    `p, li { font-family: ${fonts.body} !important; `
+      + `color: ${colours.ink} !important; font-size: ${BODY_SIZE} !important; `
+      + `line-height: ${leading.prose} !important; `
+      + "font-weight: 400 !important; text-align: justify !important; "
+      + "hyphens: auto; -webkit-hyphens: auto; -ms-hyphens: auto; }",
+    `p { margin: ${PARAGRAPH_MARGIN}; }`,
+    `ul, ol { margin: ${PARAGRAPH_MARGIN}; padding-left: 24px; `
+      + `color: ${colours.ink}; font-size: ${BODY_SIZE} !important; }`,
+    "li { margin: 0 0 6px 0; }",
+    `h1, h2, h3, h4 { font-family: ${fonts.heading}; `
+      + `color: ${colours.heading}; line-height: 1.2; `
+      + "letter-spacing: -0.01em; margin: 32px 0 12px 0; }",
+    // Smaller than a page's: read in a narrow pane under a subject the
+    // reader has already seen.
+    "h1 { font-size: 26px; font-weight: 700; line-height: 32px; }",
+    "h2 { font-size: 20px; font-weight: 700; line-height: 28px; }",
+    "h3 { font-size: 18px; line-height: 26px; }",
+    // The template inlines a size and a heavier weight on the subject.
+    "h1.subject, .newsletter-masthead h1 { font-size: 26px !important; "
+      + "line-height: 32px !important; font-weight: 700 !important; }",
+    `strong, b { font-weight: 600; color: ${colours.ink}; }`,
+    "a { text-decoration: underline; text-decoration-thickness: 1px; "
+      + "text-underline-offset: 0.15em; }",
+    "hr { border: 0; margin: 32px 0; }",
+    "blockquote { background: transparent !important; margin: 24px 0; }",
+    // Longhands, because Buttondown emits its own border properties after
+    // these and would override the shorthand.
+    ".email-container { border-width: 0 !important; "
+      + "border-style: none !important; "
+      + `background-color: ${colours.page} !important; }`,
+    ".newsletter-footer { border: 0 !important; "
+      + "background: transparent !important; padding: 0 !important; "
+      + "margin: 0 !important; }",
+    ...hides,
+  ].join("\n") + "\n\n";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@casomoltd/tooling",
-  "version": "0.32.1",
+  "version": "0.33.1",
   "description": "Casomo's shared dev config: ESLint, Prettier, commitlint, knip & jscpd presets and dev CLIs (git hooks, readability, screenshots, design specs)",
   "license": "MIT",
   "repository": {