@caltho/site-kit 0.2.10 → 0.3.0

package/dist/content/look.js

@@ -1,10 +1,21 @@
-// A site's Look, chosen in CalOS: its fonts (from the ones the site carries), its brand and accent
-// colours, its corners and its buttons. The site says what may be chosen and its own defaults
-// (defineSite's `look`); what's chosen reaches its CSS as variables, which its design reads:
+// A site's Look (its theme), chosen in CalOS: its fonts (from the ones the site carries), its colours
+// (brand and accent, the page's roles, and colours of its own by name), its type scale, its corners
+// and buttons, its content width and the space between its sections. The site says what may be
+// chosen and its own defaults (defineSite's `look`, LookOptions: the site's design as it is); what's
+// chosen reaches its CSS as variables, which its design (and the kit's sections) read:
 //
 //   --look-heading-font, --look-body-font   font-family stacks
 //   --look-brand, --look-on-brand           the brand colour, and the text that reads on it
-//   --look-accent                           the accent colour
+//   --look-accent, --look-on-accent         the accent colour, and the text that reads on it
+//   --look-page, --look-ink                 the page's background and its main text
+//   --look-muted, --look-line, --look-soft  quieter text, lines and borders, a quiet section's background
+//   --look-light, --look-dark               the lighter and the darker of page and ink (words on a dark or light frame)
+//   --look-swatch-<slug>                    each of the site's own colours, by its name ("Dark sand" → dark-sand)
+//   --look-swatch-1 … --look-swatch-12      the same, by place in the list (for static CSS: .kit-bg-swatch-1)
+//   --look-type-<role>-size|weight|tracking|leading   role: display, h1, h2, h3, body, small
+//   --look-width                            the content's width
+//   --look-gutter                           the space each side of it on a narrower screen (half on a phone)
+//   --look-section-pad                      a section's space above and below
 //   --look-radius, --look-button-radius     corners: of cards and pictures, and of buttons
 //   --look-button-bg, --look-button-fg, --look-button-border
 //   --look-button-fill                      1 filled, 0 outlined
@@ -12,57 +23,324 @@
 // Published, they're a <style> in the page (LookStyle, allowed by its hash); in CalOS's preview they're
 // set on the page as the draft changes (allowed: a style set from script isn't a style attribute).
 import { z } from "zod";
+import { googleFamily, googleFont, isFontName } from "../fonts-google.js";
+export const TYPE_ROLES = ["display", "h1", "h2", "h3", "body", "small"];
+/** The phone's menu button: what it shows (its icon, the word, both); its look is a button style (menuStyle). */
+export const MENU_SHOWS = ["both", "icon", "word"];
+export const BUTTON_SIZES = ["small", "medium", "large"];
+/** How many styles of its own a site can have (the classes sections.css draws, kit-btn-1 to -8). */
+export const MAX_BUTTON_STYLES = 8;
+/** The theme's own, always there: a style of the business's can't take their names. */
+export const THEME_BUTTONS = ["main", "accent", "quiet"];
+export const HEADER_STYLES = ["line", "plain", "brand", "floating"];
+export const HEADER_LAYOUTS = ["spread", "centered", "left"];
+const HEADER_DEFAULT = { sticky: true, style: "line", layout: "spread", menuShows: "both" };
+/** The header as it's drawn: what the business chose, else the site's own, else the kit's. */
+export function headerOf(look, o) {
+    const h = { ...HEADER_DEFAULT, ...o.header, ...look?.header };
+    return {
+        sticky: typeof h.sticky === "boolean" ? h.sticky : HEADER_DEFAULT.sticky,
+        style: HEADER_STYLES.includes(h.style) ? h.style : HEADER_DEFAULT.style,
+        layout: HEADER_LAYOUTS.includes(h.layout) ? h.layout : HEADER_DEFAULT.layout,
+        menuShows: MENU_SHOWS.includes(h.menuShows) ? h.menuShows : HEADER_DEFAULT.menuShows,
+        ...(typeof h.menuStyle === "string" && h.menuStyle ? { menuStyle: h.menuStyle } : {}),
+    };
+}
 const CORNERS = ["square", "soft", "round"];
 const BUTTONS = ["solid", "outline"];
+const SPACES = ["compact", "normal", "roomy"];
+/** The colours of the page any section's background may be, beside the site's own (by their slug). */
+/**
+ * The kit's fonts (fonts.css, imported once in the site's layout): variable, every weight, by the
+ * name CalOS shows and the family it's drawn with. A site's look.ts lists them as its fonts (with
+ * any of its own), so the business picks any of them for its headings and text.
+ */
+export const KIT_FONTS = {
+    Fraunces: '"Fraunces Variable", Georgia, serif',
+    Newsreader: '"Newsreader Variable", Georgia, serif',
+    "Source Serif 4": '"Source Serif 4 Variable", Georgia, serif',
+    "Playfair Display": '"Playfair Display Variable", Georgia, serif',
+    Lora: '"Lora Variable", Georgia, serif',
+    Inter: '"Inter Variable", system-ui, Arial, sans-serif',
+    "DM Sans": '"DM Sans Variable", system-ui, Arial, sans-serif',
+    Manrope: '"Manrope Variable", system-ui, Arial, sans-serif',
+    "Work Sans": '"Work Sans Variable", system-ui, Arial, sans-serif',
+    Outfit: '"Outfit Variable", system-ui, Arial, sans-serif',
+};
+export const COLOUR_ROLES = ["page", "soft", "brand", "accent", "ink"];
 const HEX = /^#[0-9a-f]{6}$/i;
+const hex = (v) => typeof v === "string" && HEX.test(v);
 const color = z.string().regex(HEX, { error: "A colour like #2b5f8a" }).meta({ "x-ui": "color", "x-error": "A colour like #2b5f8a" });
+/** The kit's type scale, for what a site doesn't say. */
+export const KIT_TYPE = {
+    display: { size: 72, weight: 600, tracking: -0.03, leading: 1.05 },
+    h1: { size: 56, weight: 600, tracking: -0.02, leading: 1.1 },
+    h2: { size: 40, weight: 600, tracking: -0.02, leading: 1.15 },
+    h3: { size: 24, weight: 600, tracking: -0.01, leading: 1.25 },
+    body: { size: 17, weight: 400, tracking: 0, leading: 1.6 },
+    small: { size: 14, weight: 400, tracking: 0, leading: 1.5 },
+};
+const SECTION_PAD = {
+    compact: "clamp(40px, 6vw, 64px)",
+    normal: "clamp(56px, 8vw, 96px)",
+    roomy: "clamp(80px, 11vw, 144px)",
+};
+/** A colour of the site's own as a CSS name: "Dark sand" → "dark-sand" (runs of anything else one dash, none at the ends). */
+export function swatchSlug(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/** One colour part way to another: mix("#000000", "#ffffff", 0.5) is mid grey. */
+function mix(a, b, t) {
+    const ch = (h, i) => parseInt(h.slice(i, i + 2), 16);
+    return `#${[1, 3, 5].map((i) => Math.round(ch(a, i) + (ch(b, i) - ch(a, i)) * t).toString(16).padStart(2, "0")).join("")}`;
+}
+/** The site's own role colours: what it said, else worked out from its page and ink. */
+function ownRoles(o) {
+    const page = hex(o.page) ? o.page : hex(o.background) ? o.background : "#ffffff";
+    const ink = hex(o.ink) ? o.ink : "#111111";
+    return {
+        page,
+        ink,
+        muted: hex(o.muted) ? o.muted : mix(ink, page, 0.38),
+        line: hex(o.line) ? o.line : mix(page, ink, 0.15),
+        soft: hex(o.soft) ? o.soft : mix(page, ink, 0.05),
+    };
+}
+/** The site's own type scale: what it said of each role over the kit's. */
+function ownType(o) {
+    return Object.fromEntries(TYPE_ROLES.map((r) => [r, { ...KIT_TYPE[r], ...o.type?.[r] }]));
+}
+const typeStyle = z
+    .object({
+    size: z.number().min(10).max(200).optional().meta({ title: "Size" }),
+    weight: z.literal([300, 400, 500, 600, 700]).optional().meta({ title: "Weight" }),
+    tracking: z.number().min(-0.1).max(0.3).optional().meta({ title: "Letter spacing" }),
+    leading: z.number().min(0.8).max(2.5).optional().meta({ title: "Line height" }),
+})
+    .optional();
+const TYPE_TITLES = { display: "Display", h1: "Page heading", h2: "Section heading", h3: "Small heading", body: "Text", small: "Small text" };
 /** The Look's fields, for the site's content. */
 export function lookSchema(o) {
     const fonts = Object.keys(o.fonts ?? {});
     // Each starts as the site's own, so CalOS shows what the site looks like now.
-    const font = (title, own) => z.enum(fonts).default(own && fonts.includes(own) ? own : fonts[0]).meta({ title });
+    // One of the site's own fonts, or any Google font (its name): offered in CalOS as a search, its own first.
+    // Whether it's one is checked with the Look's own uploaded fonts in view (below).
+    const font = (title, own) => z
+        .string()
+        .trim()
+        .min(1)
+        .max(80)
+        .default(own && fonts.includes(own) ? own : fonts[0])
+        .meta({ title, "x-ui": "font", "x-fonts": fonts });
+    const roles = ownRoles(o);
     return z
         .object({
         ...(fonts.length ? { headingFont: font("Heading font", o.headingFont), bodyFont: font("Text font", o.bodyFont) } : {}),
         brand: color.default(o.brand).meta({ title: "Brand colour" }),
         accent: color.default(o.accent ?? o.brand).meta({ title: "Accent colour" }),
+        page: color.default(roles.page).meta({ title: "Page background" }),
+        ink: color.default(roles.ink).meta({ title: "Main text" }),
+        muted: color.default(roles.muted).meta({ title: "Quieter text" }),
+        line: color.default(roles.line).meta({ title: "Lines" }),
+        soft: color.default(roles.soft).meta({ title: "Quiet background" }),
+        palette: z
+            .array(z.object({ name: z.string().trim().min(1).max(30).meta({ title: "Name" }), color: color.meta({ title: "Colour" }) }))
+            .max(12)
+            .default(o.palette ?? [])
+            .meta({ title: "Your colours", "x-ui": "palette" }),
+        type: z
+            .object(Object.fromEntries(TYPE_ROLES.map((r) => [r, typeStyle.meta({ title: TYPE_TITLES[r] })])))
+            .default(ownType(o))
+            .meta({ title: "Type", "x-ui": "type-scale" }),
+        width: z.number().int().min(800).max(1600).default(o.width ?? 1200).meta({ title: "Content width" }),
+        space: z.enum(SPACES).default(o.space ?? "normal").meta({ title: "Space between sections" }),
         corners: z.enum(CORNERS).default(o.corners ?? "soft").meta({ title: "Corners" }),
         buttons: z.enum(BUTTONS).default(o.buttons ?? "solid").meta({ title: "Buttons" }),
+        // Exact corners, past the three presets: cards and pictures (px), and buttons (px, or 999 for a pill).
+        radius: z.number().int().min(0).max(40).optional().meta({ title: "Corner radius" }),
+        buttonRadius: z
+            .number()
+            .int()
+            .min(0)
+            .refine((n) => n <= 40 || n === 999, { error: "Up to 40px, or 999 for a pill" })
+            .optional()
+            .meta({ title: "Button corner radius" }),
+        buttonStyles: buttonStylesField.optional().meta({ title: "Button styles", "x-ui": "button-styles" }),
+        // A border round buttons: its width (0 for none) and colour (a role, a palette colour's slug, or the button's own).
+        buttonBorder: z
+            .object({ width: z.number().int().min(0).max(4).meta({ title: "Width" }), color: z.string().trim().max(40).optional().meta({ title: "Colour", "x-ui": "swatch" }) })
+            .optional()
+            .meta({ title: "Button border" }),
+        // Offered only to a site whose look.ts lists a header (the kit's KitHeader, or one of its own that
+        // follows headerOf): an older site, or one whose own header ignores these, never shows them.
+        ...(o.header ? { header: headerField(o) } : {}),
+        // The kit's footer's background: the site's dark (as it's always been), one of its colours by role, or one of its own by slug.
+        ...(o.header ? { footer: z.object({ background: z.string().trim().min(1).max(40).default("dark").meta({ title: "Background", "x-ui": "swatch" }) }).default({ background: "dark" }).meta({ title: "Footer" }) } : {}),
+        // Fonts the business uploaded (its own brand fonts): each family's files, kept with the site's pictures.
+        ...(fonts.length ? { uploadedFonts: uploadedFonts.optional().meta({ title: "Your fonts", "x-ui": "uploaded-fonts" }) } : {}),
+    })
+        .superRefine((l, c) => {
+        const uploaded = new Set((l.uploadedFonts ?? []).map((f) => f.family));
+        for (const k of ["headingFont", "bodyFont"]) {
+            const name = l[k];
+            if (name !== undefined && !isFontName(name, o.fonts ?? {}) && !uploaded.has(name))
+                c.addIssue({ code: "custom", path: [k], message: "A font the site has, one uploaded, or a Google font by its name" });
+        }
     })
         .optional()
         .meta({ title: "Look" });
 }
+/** A button style's name, by its slug where a button names it ("main", "accent", "quiet", or one of the business's). */
+export const buttonStyleName = z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, { error: "A button style's name" });
+const colourKey = z.string().trim().min(1).max(40);
+const buttonStylesField = z
+    .array(z.object({
+    name: z.string().trim().min(1).max(30).meta({ title: "Name" }),
+    fill: colourKey.optional().meta({ title: "Fill" }),
+    text: colourKey.optional().meta({ title: "Words" }),
+    border: z.object({ width: z.number().int().min(0).max(4).optional(), color: colourKey.optional() }).optional().meta({ title: "Border" }),
+    radius: z.number().int().min(0).refine((n) => n <= 40 || n === 999, { error: "Up to 40px, or 999 for round ends" }).optional().meta({ title: "Corners" }),
+    size: z.enum(BUTTON_SIZES).optional().meta({ title: "Size" }),
+    weight: z.number().int().min(300).max(900).optional().meta({ title: "Weight" }),
+    caps: z.boolean().optional().meta({ title: "Capitals" }),
+}))
+    .max(MAX_BUTTON_STYLES)
+    .superRefine((styles, c) => {
+    const seen = new Set();
+    styles.forEach((st, i) => {
+        const slug = swatchSlug(st.name);
+        if (!slug)
+            c.addIssue({ code: "custom", path: [i, "name"], message: "A style's name needs a letter or number" });
+        else if (THEME_BUTTONS.includes(slug))
+            c.addIssue({ code: "custom", path: [i, "name"], message: `"${st.name}" is one of the theme's: name it something else` });
+        else if (seen.has(slug))
+            c.addIssue({ code: "custom", path: [i, "name"], message: `Another style is already called "${st.name}"` });
+        seen.add(slug);
+    });
+});
+const BUTTON_SIZE = { small: ["0.45em 0.95em", "0.875em"], medium: ["0.7em 1.3em", "1em"], large: ["0.9em 1.7em", "1.125em"] };
+/** An uploaded font file's place among the site's files, and the font name a family can have (drawn in CSS as it is). */
+const FONT_FILE = /^fonts\/[a-z0-9._-]+\.(woff2|woff|ttf|otf)$/;
+const FAMILY = /^[A-Za-z0-9][A-Za-z0-9 ._-]{0,59}$/;
+const uploadedFonts = z
+    .array(z.object({
+    family: z.string().regex(FAMILY),
+    files: z
+        .array(z.object({ src: z.string().regex(FONT_FILE), weight: z.string().regex(/^\d{1,4}( \d{1,4})?$/), style: z.enum(["normal", "italic"]) }))
+        .min(1)
+        .max(24),
+}))
+    .max(8)
+    .refine((fs) => new Set(fs.map((f) => f.family.toLowerCase())).size === fs.length, { error: "Each uploaded font has its own name" });
+const FORMATS = { woff2: "woff2", woff: "woff", ttf: "truetype", otf: "opentype" };
+/** The @font-face rules for an uploaded font, each file at the address `at` gives its path. */
+export function uploadedFontCss(f, at) {
+    return f.files
+        .map((x) => `@font-face{font-family:"${f.family}";font-style:${x.style};font-display:swap;font-weight:${x.weight};src:url(${at(x.src)}) format("${FORMATS[x.src.split(".").pop()] ?? "woff2"}")}`)
+        .join("\n");
+}
+function headerField(o) {
+    return z
+        .object({
+        sticky: z.boolean().default(o.header?.sticky ?? HEADER_DEFAULT.sticky).meta({ title: "Stays at the top", description: "Stays in view as the page scrolls." }),
+        style: z
+            .enum(HEADER_STYLES)
+            .default(o.header?.style ?? HEADER_DEFAULT.style)
+            .meta({ title: "Style", "x-labels": { line: "Line under it", plain: "Plain", brand: "Brand colour", floating: "Floating bar" } }),
+        layout: z
+            .enum(HEADER_LAYOUTS)
+            .default(o.header?.layout ?? HEADER_DEFAULT.layout)
+            .meta({ title: "Layout", "x-labels": { spread: "Name left, menu right", centered: "Centred", left: "All on the left" } }),
+        menuShows: z
+            .enum(MENU_SHOWS)
+            .default(o.header?.menuShows ?? HEADER_DEFAULT.menuShows)
+            .meta({ title: "Phone menu button", "x-labels": { both: "Icon and word", icon: "Icon only", word: "Word only" } }),
+        // The phone's menu button in one of the site's button styles; left out, outlined in the header's line.
+        menuStyle: buttonStyleName.optional().meta({ title: "Phone menu button's style", "x-ui": "button-style" }),
+    })
+        .default({ ...HEADER_DEFAULT, ...o.header })
+        .meta({ title: "Header" });
+}
 /** How readable one colour is on another (WCAG): 1 to 21. */
 export function contrast(a, b) {
-    const lum = (hex) => {
-        const [r, g, bl] = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255).map((c) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4));
-        return 0.2126 * r + 0.7152 * g + 0.0722 * bl;
-    };
-    const [x, y] = [lum(a), lum(b)].sort((m, n) => n - m);
+    const [x, y] = [luminance(a), luminance(b)].sort((m, n) => n - m);
     return (x + 0.05) / (y + 0.05);
 }
-/** The colours chosen that won't read: the brand colour is used for text and buttons on the page, so it must stand out from it. */
+function luminance(hex) {
+    const [r, g, bl] = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255).map((c) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4));
+    return 0.2126 * r + 0.7152 * g + 0.0722 * bl;
+}
+/** Whether a colour is dark: white words read better on it than near-black ones. */
+export function isDark(color) {
+    return hex(color) && contrast(color, "#ffffff") >= contrast(color, "#111111");
+}
+/** The colours chosen that won't read: the brand colour is used for text and buttons on the page, so it must stand out from it; text must read on it; the site's own colours need names of their own. */
 export function lookProblems(look, o) {
-    const bg = o.background ?? "#ffffff";
-    if (look?.brand && HEX.test(look.brand) && HEX.test(bg) && contrast(look.brand, bg) < 3)
-        return [{ path: ["look", "brand"], message: "Too close to the page's background to read: choose a darker or stronger colour" }];
-    return [];
+    const out = [];
+    const page = hex(look?.page) ? look.page : ownRoles(o).page;
+    if (hex(look?.brand) && contrast(look.brand, page) < 3)
+        out.push({ path: ["look", "brand"], message: "Too close to the page's background to read: choose a darker or stronger colour" });
+    if (hex(look?.ink) && contrast(look.ink, page) < 4.5)
+        out.push({ path: ["look", "ink"], message: "Too close to the page's background to read: choose a colour further from it" });
+    if (hex(look?.muted) && contrast(look.muted, page) < 3)
+        out.push({ path: ["look", "muted"], message: "Too close to the page's background to read: choose a colour further from it" });
+    const seen = new Set();
+    (look?.palette ?? []).forEach((s, i) => {
+        const slug = swatchSlug(s.name ?? "");
+        if (!slug)
+            out.push({ path: ["look", "palette", i, "name"], message: "A name with a letter or number in it" });
+        else if (COLOUR_ROLES.includes(slug))
+            out.push({ path: ["look", "palette", i, "name"], message: `"${s.name}" is already one of the page's colours: choose another name` });
+        else if (seen.has(slug))
+            out.push({ path: ["look", "palette", i, "name"], message: `Another colour is already called "${s.name}"` });
+        seen.add(slug);
+    });
+    return out;
 }
 const RADIUS = { square: ["0", "0"], soft: ["8px", "8px"], round: ["16px", "999px"] };
+const num = (v) => String(Math.round(v * 1000) / 1000);
 /** The Look as CSS variables: what's chosen, else the site's own. */
 export function lookVars(look, o) {
     const l = look ?? {};
     const fonts = o.fonts ?? {};
     const first = Object.values(fonts)[0];
-    const own = (name) => (name && fonts[name]) || first;
-    const brand = l.brand && HEX.test(l.brand) ? l.brand : o.brand;
-    const onBrand = HEX.test(brand) && contrast(brand, "#ffffff") >= contrast(brand, "#111111") ? "#ffffff" : "#111111";
-    const [radius, buttonRadius] = RADIUS[l.corners ?? o.corners ?? "soft"];
+    // The site's own font by its name, else any Google font (fetched and served by the site when it's built), else its first.
+    const own = (name) => {
+        if (name && fonts[name])
+            return fonts[name];
+        const g = name ? googleFont(name) : null;
+        return g ? googleFamily(g) : first;
+    };
+    const roles = ownRoles(o);
+    const pick = (k) => (hex(l[k]) ? l[k] : roles[k]);
+    const page = pick("page");
+    const ink = pick("ink");
+    const brand = hex(l.brand) ? l.brand : o.brand;
+    const onBrand = hex(brand) && !isDark(brand) ? "#111111" : "#ffffff";
+    const accent = (hex(l.accent) ? l.accent : o.accent) ?? brand;
+    // The darker of page and ink on a light accent (sand reads in the site's own dark), else white.
+    const onAccent = hex(accent) && !isDark(accent) ? (luminance(pick("page")) < luminance(pick("ink")) ? pick("page") : pick("ink")) : "#ffffff";
+    const [presetRadius, presetButtonRadius] = RADIUS[l.corners ?? o.corners ?? "soft"];
+    const px = (n, max) => (typeof n === "number" && Number.isInteger(n) && n >= 0 && (n <= max || n === 999) ? `${n}px` : null);
+    const radius = px(l.radius, 40) ?? presetRadius;
+    const buttonRadius = px(l.buttonRadius, 40) ?? presetButtonRadius;
     const outline = (l.buttons ?? o.buttons ?? "solid") === "outline";
+    const [light, dark] = luminance(page) >= luminance(ink) ? [page, ink] : [ink, page];
     const vars = {
         "--look-brand": brand,
         "--look-on-brand": onBrand,
-        "--look-accent": (l.accent && HEX.test(l.accent) ? l.accent : o.accent) ?? brand,
+        "--look-page": page,
+        "--look-ink": ink,
+        "--look-muted": pick("muted"),
+        "--look-line": pick("line"),
+        "--look-soft": pick("soft"),
+        "--look-light": light,
+        "--look-dark": dark,
+        "--look-accent": accent,
+        "--look-on-accent": onAccent,
         "--look-radius": radius,
         "--look-button-radius": buttonRadius,
         "--look-button-bg": outline ? "transparent" : brand,
@@ -71,17 +349,103 @@ export function lookVars(look, o) {
         /** 1 for a filled button, 0 for an outlined one: for a design that mixes its own colours by it. */
         "--look-button-fill": outline ? "0" : "1",
     };
-    const heading = (l.headingFont && fonts[l.headingFont]) || own(o.headingFont);
-    const body = (l.bodyFont && fonts[l.bodyFont]) || own(o.bodyFont);
+    const palette = (Array.isArray(l.palette) ? l.palette : (o.palette ?? [])).slice(0, 12);
+    palette.forEach((s, i) => {
+        if (!hex(s?.color))
+            return;
+        const slug = swatchSlug(s.name ?? "");
+        if (slug)
+            vars[`--look-swatch-${slug}`] = s.color;
+        vars[`--look-swatch-${i + 1}`] = s.color;
+    });
+    // Buttons' border, where chosen: its width, and its colour by role or palette slug (else the button's own).
+    const bb = l.buttonBorder;
+    if (bb && typeof bb.width === "number" && bb.width >= 0 && bb.width <= 4)
+        vars["--look-button-border-width"] = `${Math.round(bb.width)}px`;
+    if (bb?.color) {
+        const c = bb.color === "dark" ? dark : bb.color === "light" ? light : colourOf(bb.color, vars);
+        if (c && hex(c))
+            vars["--look-button-border-colour"] = c;
+    }
+    // The business's own button styles: each one's values as --look-btn-<n>-*, and --look-btn-<slug> its number,
+    // so a button naming it finds its class (kit-btn-<n>, sections.css).
+    const named = (key) => (key === "dark" ? dark : key === "light" ? light : key ? colourOf(key, vars) : undefined);
+    (Array.isArray(l.buttonStyles) ? l.buttonStyles : []).slice(0, MAX_BUTTON_STYLES).forEach((st, i) => {
+        const slug = swatchSlug(st?.name ?? "");
+        if (!slug || THEME_BUTTONS.includes(slug))
+            return;
+        const n = i + 1;
+        const none = st.fill === "none";
+        const bg = none ? null : (named(st.fill) ?? brand);
+        const fg = named(st.text) ?? (bg && hex(bg) ? (isDark(bg) ? light : dark) : ink);
+        const [pad, size] = BUTTON_SIZE[st.size ?? "medium"];
+        vars[`--look-btn-${slug}`] = String(n);
+        vars[`--look-btn-${n}-bg`] = bg ?? "transparent";
+        vars[`--look-btn-${n}-fg`] = fg;
+        vars[`--look-btn-${n}-bw`] = `${typeof st.border?.width === "number" ? Math.min(4, Math.max(0, Math.round(st.border.width))) : 1}px`;
+        vars[`--look-btn-${n}-bc`] = named(st.border?.color) ?? (bg ?? fg);
+        vars[`--look-btn-${n}-radius`] = px(st.radius, 40) ?? buttonRadius;
+        vars[`--look-btn-${n}-pad`] = pad;
+        vars[`--look-btn-${n}-size`] = size;
+        vars[`--look-btn-${n}-weight`] = String(typeof st.weight === "number" ? st.weight : 600);
+        vars[`--look-btn-${n}-case`] = st.caps ? "uppercase" : "none";
+        vars[`--look-btn-${n}-track`] = st.caps ? "0.06em" : "0";
+    });
+    // The footer in another of the site's colours, its words in whichever of page and ink reads on it.
+    const fb = l.footer?.background;
+    if (fb && fb !== "dark") {
+        const c = fb === "light" ? light : colourOf(fb, vars);
+        if (c && hex(c)) {
+            vars["--kit-footer-bg"] = c;
+            vars["--kit-footer-fg"] = isDark(c) ? light : dark;
+        }
+    }
+    const scale = ownType(o);
+    for (const r of TYPE_ROLES) {
+        const t = { ...scale[r], ...definedOnly(l.type?.[r]) };
+        vars[`--look-type-${r}-size`] = `${num(t.size)}px`;
+        vars[`--look-type-${r}-weight`] = String(t.weight);
+        vars[`--look-type-${r}-tracking`] = `${num(t.tracking)}em`;
+        vars[`--look-type-${r}-leading`] = num(t.leading);
+    }
+    const width = typeof l.width === "number" && l.width >= 800 && l.width <= 1600 ? l.width : (o.width ?? 1200);
+    vars["--look-width"] = `${Math.round(width)}px`;
+    const gutter = typeof o.gutter === "number" && o.gutter >= 8 && o.gutter <= 96 ? Math.round(o.gutter) : 40;
+    vars["--look-gutter"] = `clamp(${Math.round(gutter / 2)}px, 4vw, ${gutter}px)`;
+    vars["--look-section-pad"] = SECTION_PAD[l.space && SECTION_PAD[l.space] ? l.space : (o.space ?? "normal")];
+    const uploaded = (name) => (l.uploadedFonts ?? []).find((f) => f.family === name);
+    const chosen = (name) => (name && uploaded(name) && !fonts[name] ? `"${name}", system-ui, sans-serif` : name && (fonts[name] || googleFont(name)) ? own(name) : undefined);
+    const heading = chosen(l.headingFont) || own(o.headingFont);
+    const body = chosen(l.bodyFont) || own(o.bodyFont);
     if (heading)
         vars["--look-heading-font"] = heading;
     if (body)
         vars["--look-body-font"] = body;
     return vars;
 }
+function definedOnly(t) {
+    return Object.fromEntries(Object.entries(t ?? {}).filter(([, v]) => typeof v === "number" && Number.isFinite(v)));
+}
 /** The Look as a stylesheet for the page's head: `:root { … }`. */
 export function lookCss(look, o) {
     return `:root{${Object.entries(lookVars(look, o))
         .map(([k, v]) => `${k}:${v.replace(/[<>{};]/g, "")}`)
         .join(";")}}`;
 }
+/**
+ * The colour a section's background names (a role, or one of the site's own by its slug), from the
+ * Look's variables; undefined when it names none.
+ */
+export function colourOf(name, vars) {
+    return COLOUR_ROLES.includes(name) ? vars[`--look-${name}`] : vars[`--look-swatch-${name}`];
+}
+/**
+ * The class that draws a button in one of the business's own styles (kit-btn-3), from the Look's
+ * values (lookVars): undefined for the theme's own (main, accent, quiet) or a style it doesn't have.
+ */
+export function buttonStyleClass(style, vars) {
+    if (!style || THEME_BUTTONS.includes(style))
+        return undefined;
+    const n = vars[`--look-btn-${style}`];
+    return n ? `kit-btn kit-btn-${n}` : undefined;
+}

package/dist/content-migrate.d.ts

@@ -0,0 +1,51 @@
+/** The format this kit's content is in. 0: before built sections; 1: built sections and components. */
+export declare const CONTENT_FORMAT = 1;
+export type Content = Record<string, unknown>;
+export type ContentMigration = {
+    /** Stable, unique, in order: "0001-built-sections". */
+    id: string;
+    from: number;
+    to: number;
+    /** What it changes, for whoever looks at a site's history. */
+    title: string;
+    /** The content in format `from`, moved to `to` (a copy: the content given is never changed). Throws a MigrationError for what it can't move. */
+    run(content: Content): Content;
+};
+/** What a migration can't move, and where: a fault for Caltho to fix in the migration, never a site's to fix by hand. */
+export declare class MigrationError extends Error {
+    readonly path: (string | number)[];
+    constructor(message: string, path?: (string | number)[]);
+}
+/** Every migration, in order: each one's `from` is the one before's `to`. */
+export declare const CONTENT_MIGRATIONS: readonly ContentMigration[];
+/** The format content is in: its `format`, or 0 for content from before formats were said. */
+export declare function formatOf(content: unknown): number;
+export type MigrateResult = {
+    ok: true;
+    content: Content;
+    from: number;
+    format: number;
+    applied: {
+        id: string;
+        title: string;
+    }[];
+} | {
+    ok: false;
+    content: Content;
+    from: number;
+    format: number;
+    error: {
+        id: string;
+        message: string;
+        path: (string | number)[];
+    };
+};
+/**
+ * Content moved to this kit's format (or `to`): each migration it hasn't had, in order, then its
+ * `format` set. Idempotent: content already there comes back as it was, with nothing applied. A
+ * migration that fails stops it: the content is returned as given, with the failure (`ok: false`).
+ * Content in a format newer than this kit knows is refused the same way (the site needs the newer kit).
+ */
+export declare function migrateContent(content: Content, o?: {
+    to?: number;
+}): MigrateResult;

package/dist/content-migrate.js

@@ -0,0 +1,69 @@
+// A site's content moved from one format to the next. Every client site is the starter plus its
+// configuration (its content: pages, Look, built sections, components), with no code of its own,
+// so the configuration's format is the kit's, and it changes only with the kit. The content says
+// which format it's in (`format`; none is 0, the format before built sections). When a newer kit
+// changes a shape, a migration here moves content from the format before to its own, as data:
+// pure, in order, each once (content already at or past its format is left alone), never needing a
+// person to edit a site by hand. One that can't move something says so (a MigrationError) for
+// Caltho to fix in the migration; the content is then left exactly as it was.
+//
+// Most changes need none: a new kind of block (built, use) or a new optional field leaves existing
+// content valid, and only the format number moves. CalOS runs these on a site's draft and published
+// content when the site moves to a newer kit (migrateContent); the build runs them too (prepare),
+// so content CalOS hasn't moved yet still builds. Code migrations (a site's files) are ./migrate.ts.
+/** The format this kit's content is in. 0: before built sections; 1: built sections and components. */
+export const CONTENT_FORMAT = 1;
+/** What a migration can't move, and where: a fault for Caltho to fix in the migration, never a site's to fix by hand. */
+export class MigrationError extends Error {
+    path;
+    constructor(message, path = []) {
+        super(message);
+        this.path = path;
+        this.name = "MigrationError";
+    }
+}
+/** Every migration, in order: each one's `from` is the one before's `to`. */
+export const CONTENT_MIGRATIONS = [
+    {
+        id: "0001-built-sections",
+        from: 0,
+        to: 1,
+        title: "Built sections, components and the cookie banner: new kinds of block (built, use), the site's components and its consent setting, none of which changes existing content",
+        run: (c) => c,
+    },
+];
+/** The format content is in: its `format`, or 0 for content from before formats were said. */
+export function formatOf(content) {
+    const f = content?.format;
+    return typeof f === "number" && Number.isInteger(f) && f >= 0 ? f : 0;
+}
+/**
+ * Content moved to this kit's format (or `to`): each migration it hasn't had, in order, then its
+ * `format` set. Idempotent: content already there comes back as it was, with nothing applied. A
+ * migration that fails stops it: the content is returned as given, with the failure (`ok: false`).
+ * Content in a format newer than this kit knows is refused the same way (the site needs the newer kit).
+ */
+export function migrateContent(content, o = {}) {
+    const to = o.to ?? CONTENT_FORMAT;
+    const from = formatOf(content);
+    if (from > CONTENT_FORMAT)
+        return { ok: false, content, from, format: from, error: { id: "format", message: `The content is in format ${from}, newer than this kit's (${CONTENT_FORMAT}): the site needs a newer @caltho/site-kit`, path: ["format"] } };
+    let at = structuredClone(content);
+    const applied = [];
+    for (const m of CONTENT_MIGRATIONS) {
+        if (m.from < from || m.to > to)
+            continue;
+        try {
+            at = m.run(structuredClone(at));
+        }
+        catch (err) {
+            const e = err;
+            return { ok: false, content, from, format: from, error: { id: m.id, message: e.message, path: e instanceof MigrationError ? e.path : [] } };
+        }
+        at.format = m.to;
+        applied.push({ id: m.id, title: m.title });
+    }
+    if (from < to && formatOf(at) !== to)
+        at.format = to;
+    return { ok: true, content: at, from, format: formatOf(at), applied };
+}

package/dist/finish.d.ts

@@ -6,5 +6,5 @@ export declare function finish(root: string, outDir: string, env?: Record<string
  * out, and what's marked to count), and each phone link and map link marked: a call or directions
  * tapped is what a business wants to know came from the site. No cookies: nothing to consent to.
  */
-export declare function counted(html: string, a: Analytics): string;
+export declare function counted(html: string, a: Analytics, asks?: boolean): string;
 export {};