@ideare/kit 0.0.0-stage → 0.1.0-next.0

package/dist/files/docs.js

@@ -0,0 +1,392 @@
+import { COLOR_ROLES, LINK_KINDS } from "../brand/schema.js";
+import { contrast, formatRatio } from "../color/wcag.js";
+import { cleanMarkSvg } from "../marks/svg.js";
+import { cssString, fontStack } from "./tokens.js";
+/**
+ * The words around the brand: brand.md for outside agents (Google's design.md format), the
+ * public brand.json, the head tags, a prompt for AI site builders, the web manifest and the
+ * email signature.
+ */
+const ROLE_WORDS = {
+    ground: "the page behind everything",
+    surface: "cards, panels and fields",
+    ink: "text and icons",
+    muted: "quiet text: captions, hints, dates",
+    line: "field borders and dividers that must be seen",
+    primary: "the brand color: main buttons and key marks",
+    onPrimary: "text and icons on the brand color",
+    accent: "a second color for highlights and illustrations",
+    onAccent: "text on the accent",
+    focus: "the keyboard focus ring",
+    danger: "errors and destructive actions, always with an icon and a word",
+    success: "success, always with an icon and a word",
+    warning: "warnings, always with an icon and a word",
+};
+function kebab(role) {
+    return role.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+function yamlString(value) {
+    return JSON.stringify(value);
+}
+/** The brand's slug, or one made from its name for a draft. */
+export function slugOf(brand) {
+    return (brand.slug ??
+        brand.name
+            .toLowerCase()
+            .normalize("NFD")
+            .replace(/\p{M}/gu, "")
+            .replace(/[^a-z0-9]+/g, "-")
+            .replace(/^-|-$/g, ""));
+}
+/** The brand's copy in a language, falling back to the default language. */
+export function copyFor(brand, locale) {
+    const copy = brand.copy[locale ?? brand.defaultLocale] ?? brand.copy[brand.defaultLocale];
+    if (!copy)
+        throw new TypeError(`The brand has no copy for ${locale ?? brand.defaultLocale}`);
+    return copy;
+}
+/** brand.md: YAML tokens, then the design.md sections in their fixed order. */
+export function brandMd(brand) {
+    const light = brand.colors.light;
+    const dark = brand.colors.dark;
+    const copy = copyFor(brand);
+    const colorYaml = [
+        ...COLOR_ROLES.map((role) => `  ${kebab(role)}: ${yamlString(light[role])}`),
+        ...COLOR_ROLES.map((role) => `  dark-${kebab(role)}: ${yamlString(dark[role])}`),
+        ...Object.entries(brand.paints).map(([name, hex]) => `  paint-${name}: ${yamlString(hex)}`),
+    ];
+    const display = brand.fonts.display;
+    const text = brand.fonts.text;
+    const lines = [
+        "---",
+        'version: "alpha"',
+        `name: ${yamlString(brand.name)}`,
+        `description: ${yamlString(copy.tagline)}`,
+        "colors:",
+        ...colorYaml,
+        "typography:",
+        "  display-lg:",
+        `    fontFamily: ${yamlString(display.family)}`,
+        "    fontSize: 3rem",
+        `    fontWeight: ${brand.wordmark.font === "display" ? brand.wordmark.weight : display.weights[0]}`,
+        "    lineHeight: 1.1",
+        "  headline-md:",
+        `    fontFamily: ${yamlString(display.family)}`,
+        "    fontSize: 1.75rem",
+        "    lineHeight: 1.2",
+        "  body-md:",
+        `    fontFamily: ${yamlString(text.family)}`,
+        "    fontSize: 1rem",
+        "    fontWeight: 400",
+        "    lineHeight: 1.5",
+        "  label-md:",
+        `    fontFamily: ${yamlString(text.family)}`,
+        "    fontSize: 0.875rem",
+        `    fontWeight: ${text.weights.includes(600) ? 600 : (text.weights.at(-1) ?? 400)}`,
+        "    lineHeight: 1.3",
+        "rounded:",
+        `  control: ${brand.radii.control}px`,
+        `  card: ${brand.radii.card}px`,
+        "spacing:",
+        "  sm: 8px",
+        "  md: 16px",
+        "  lg: 24px",
+        "  xl: 40px",
+        "components:",
+        "  button-primary:",
+        '    backgroundColor: "{colors.primary}"',
+        '    textColor: "{colors.on-primary}"',
+        '    rounded: "{rounded.control}"',
+        "    padding: 12px",
+        "  card:",
+        '    backgroundColor: "{colors.surface}"',
+        '    textColor: "{colors.ink}"',
+        '    rounded: "{rounded.card}"',
+        "    padding: 24px",
+        "  input:",
+        '    backgroundColor: "{colors.ground}"',
+        '    textColor: "{colors.ink}"',
+        '    rounded: "{rounded.control}"',
+        "---",
+        "",
+        `# ${brand.name}`,
+        "",
+        "Made by ideare from brand.json. Do not edit this file: change the brand and make the files again.",
+        "",
+        "## Overview",
+        "",
+        `${copy.description}`,
+        "",
+        `Tagline: "${copy.tagline}". Voice: ${brand.voice.tone.join(", ") || "plain"}.`,
+        ...(brand.voice.notesPublic && brand.voice.notes ? ["", brand.voice.notes] : []),
+        "",
+        ...brand.locales.flatMap((lang) => {
+            const local = brand.copy[lang];
+            return local
+                ? [
+                    `- ${lang}: "${local.tagline}" ${local.card.subtitle ? `(${local.card.subtitle})` : ""}`.trimEnd(),
+                ]
+                : [];
+        }),
+        "",
+        "## Colors",
+        "",
+        "Each color has one job. Light theme first; the `dark-` tokens are the same jobs on a dark ground.",
+        "",
+        ...COLOR_ROLES.map((role) => `- **${kebab(role)}** (${light[role]}, dark ${dark[role]}): ${ROLE_WORDS[role]}.`),
+        "",
+        ...(Object.keys(brand.paints).length
+            ? [
+                "",
+                `Paints, for illustrations, bands and accents, never for text roles: ${Object.entries(brand.paints)
+                    .map(([name, hex]) => `${name} ${hex}`)
+                    .join(", ")}.`,
+                "",
+            ]
+            : []),
+        `Text on ground reads at ${formatRatio(contrast(light.ink, light.ground))} in light and ${formatRatio(contrast(dark.ink, dark.ground))} in dark. Keep every text pair at 4.5:1 or more and every border, icon and focus ring at 3:1 or more.`,
+        "",
+        "## Typography",
+        "",
+        `- ${display.family} for the name, headlines and big statements (\`${fontStack(brand, "display")}\`).`,
+        `- ${text.family} for everything else (\`${fontStack(brand, "text")}\`).`,
+        "- Sentence case everywhere. No exclamation marks.",
+        "",
+        "## Layout",
+        "",
+        "Generous space: 8 px steps, 24 px between groups, 40 px between sections.",
+        "",
+        "## Shapes",
+        "",
+        `Controls round at ${brand.radii.control} px and cards at ${brand.radii.card} px.`,
+        "",
+        "## Components",
+        "",
+        "- Main button: the brand color with its on-color text.",
+        "- Cards: the surface color on the ground, no border needed.",
+        "- Fields: the ground with a line-colored border (3:1).",
+        "",
+        "## Do's and Don'ts",
+        "",
+        "- Do use the logo files as they are: `logo.svg` on light grounds, `logo-dark.svg` on dark ones.",
+        "- Do put status colors next to an icon and a word, never alone.",
+        "- Don't stretch, recolor or redraw the logo.",
+        "- Don't write the em dash, and don't use exclamation marks.",
+        ...(brand.voice.neverSay.length
+            ? [`- Don't use these words: ${brand.voice.neverSay.join(", ")}.`]
+            : []),
+        ...(brand.art.avoid.length ? [`- In pictures, avoid: ${brand.art.avoid.join(", ")}.`] : []),
+        "",
+    ];
+    return lines.join("\n");
+}
+/**
+ * The public brand.json: what anyone may read from the CDN and the brand page (plan D5). Voice
+ * notes, art references and every link without a public tick are left out, and the marks are
+ * written again by the kit, so only clean SVG is ever published.
+ */
+export function publicBrand(brand) {
+    const links = Object.fromEntries(LINK_KINDS.flatMap((kind) => {
+        const link = brand.links[kind];
+        return link?.public ? [[kind, link]] : [];
+    }));
+    const { svg, small, dark, lockups } = brand.mark;
+    const clean = (value) => value === undefined ? undefined : cleanMarkSvg(value);
+    return {
+        ...brand,
+        mark: {
+            ...brand.mark,
+            svg: cleanMarkSvg(svg),
+            small: clean(small),
+            dark: clean(dark),
+            lockups: lockups && {
+                horizontal: clean(lockups.horizontal),
+                stacked: clean(lockups.stacked),
+                wordmark: clean(lockups.wordmark),
+            },
+        },
+        voice: {
+            ...brand.voice,
+            notes: brand.voice.notesPublic ? brand.voice.notes : undefined,
+        },
+        art: {
+            ...brand.art,
+            references: brand.art.referencesPublic ? brand.art.references : [],
+        },
+        links,
+    };
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll('"', """)
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;");
+}
+/** The head tags for the icons, the manifest, the theme colors and the share card. */
+export function headTags(brand, options = {}) {
+    const base = (options.base ?? "/").replace(/\/?$/, "/");
+    const copy = copyFor(brand, options.locale);
+    const title = options.title ?? brand.name;
+    // A light-only page under a dark system setting would get dark browser chrome around a
+    // white page, so it names one color with no media query.
+    const themeColors = options.dark === "none"
+        ? [`<meta name="theme-color" content="${brand.colors.light.ground}">`]
+        : [
+            `<meta name="theme-color" content="${brand.colors.light.ground}" media="(prefers-color-scheme: light)">`,
+            `<meta name="theme-color" content="${brand.colors.dark.ground}" media="(prefers-color-scheme: dark)">`,
+        ];
+    const tags = [
+        `<link rel="icon" href="${base}favicon.ico" sizes="32x32">`,
+        `<link rel="icon" href="${base}icon.svg" type="image/svg+xml">`,
+        `<link rel="apple-touch-icon" href="${base}apple-touch-icon.png">`,
+        `<link rel="manifest" href="${base}site.webmanifest">`,
+        ...themeColors,
+        `<meta property="og:site_name" content="${escapeHtml(brand.name)}">`,
+        `<meta property="og:title" content="${escapeHtml(title)}">`,
+        `<meta property="og:description" content="${escapeHtml(copy.description)}">`,
+    ];
+    if (options.ogImage) {
+        tags.push(`<meta property="og:image" content="${escapeHtml(options.ogImage)}">`, '<meta property="og:image:width" content="1200">', '<meta property="og:image:height" content="630">', `<meta property="og:image:alt" content="${escapeHtml(ogAlt(brand, options.locale))}">`, '<meta name="twitter:card" content="summary_large_image">');
+    }
+    return tags;
+}
+/** The share card's alt text, in the card's language. */
+export function ogAlt(brand, locale, title) {
+    const copy = copyFor(brand, locale);
+    return `${brand.name}: ${title ?? copy.card.title}`;
+}
+/** site.webmanifest, with the fleet's icon names so a sibling can switch with no head edits. */
+export function webManifest(brand, options = {}) {
+    const base = (options.base ?? "/").replace(/\/?$/, "/");
+    return {
+        name: brand.name,
+        short_name: brand.shortName,
+        description: copyFor(brand).description,
+        lang: brand.defaultLocale,
+        start_url: base,
+        scope: base,
+        display: "standalone",
+        background_color: brand.colors.light.ground,
+        theme_color: brand.colors.light.ground,
+        icons: [
+            {
+                src: `${base}web-app-manifest-192x192.png`,
+                sizes: "192x192",
+                type: "image/png",
+                purpose: "any",
+            },
+            {
+                src: `${base}web-app-manifest-512x512.png`,
+                sizes: "512x512",
+                type: "image/png",
+                purpose: "any",
+            },
+            {
+                src: `${base}web-app-manifest-maskable-512x512.png`,
+                sizes: "512x512",
+                type: "image/png",
+                purpose: "maskable",
+            },
+        ],
+    };
+}
+function paletteLines(name, palette) {
+    return [
+        `${name}:`,
+        ...COLOR_ROLES.map((role) => `- ${kebab(role)}: ${palette[role]} (${ROLE_WORDS[role]})`),
+    ];
+}
+/** prompt.md: one paste-ready prompt for an AI site builder (Lovable, v0, Bolt and the like). */
+export function promptMd(brand, options = {}) {
+    const copy = copyFor(brand);
+    const site = brand.links.site?.public
+        ? brand.links.site.value
+        : brand.domain
+            ? `https://${brand.domain}`
+            : undefined;
+    const files = options.filesUrl?.replace(/\/?$/, "/");
+    const lines = [
+        `Build the site for ${brand.name}${site ? ` (${site})` : ""}. Use this brand exactly.`,
+        "",
+        `What it is: ${copy.description}`,
+        `Tagline: ${copy.tagline}`,
+        `Languages: ${brand.locales.join(", ")} (default ${brand.defaultLocale}). Write each language natively, never as a translation.`,
+        "",
+        ...paletteLines("Colors, light theme", brand.colors.light),
+        "",
+        ...paletteLines("Colors, dark theme", brand.colors.dark),
+        "",
+        `Fonts: ${brand.fonts.display.family} for headings, ${brand.fonts.text.family} for text (both free on Google Fonts and Fontsource).`,
+        `Corners: ${brand.radii.control} px on buttons and fields, ${brand.radii.card} px on cards.`,
+        "",
+        ...(files
+            ? [
+                "Files (use them as they are):",
+                `- Logo: ${files}logo/logo.svg (dark grounds: ${files}logo/logo-dark.svg)`,
+                `- Icons: ${files}web/favicon.ico, ${files}web/icon.svg, ${files}web/apple-touch-icon.png, ${files}web/site.webmanifest`,
+                `- Share card: ${files}og/og.png`,
+                `- Tokens: ${files}tokens/tokens.css`,
+                "",
+            ]
+            : []),
+        `Voice: ${brand.voice.tone.join(", ") || "plain"}. Short sentences, everyday words, sentence case, no exclamation marks, no em dash.`,
+        ...(brand.voice.neverSay.length
+            ? [`Never use these words: ${brand.voice.neverSay.join(", ")}.`]
+            : []),
+        "Keep text at 4.5:1 contrast or more, and borders and icons at 3:1. Never recolor or redraw the logo.",
+        "",
+    ];
+    return lines.join("\n");
+}
+/** signature.html: a table-based email signature with the opaque logo bar (Gmail's dark mode). */
+export function signatureHtml(brand, options) {
+    const light = brand.colors.light;
+    const copy = copyFor(brand);
+    const links = LINK_KINDS.flatMap((kind) => {
+        const link = brand.links[kind];
+        if (!link?.public)
+            return [];
+        const value = link.value;
+        const href = kind === "site"
+            ? value
+            : kind === "email"
+                ? `mailto:${value}`
+                : kind === "phone"
+                    ? `tel:${value.replace(/[^\d+]/g, "")}`
+                    : kind === "whatsapp"
+                        ? `https://wa.me/${value.replace(/\D/g, "")}`
+                        : kind === "instagram"
+                            ? `https://instagram.com/${value.replace(/^@/, "")}`
+                            : kind === "x"
+                                ? `https://x.com/${value.replace(/^@/, "")}`
+                                : kind === "tiktok"
+                                    ? `https://tiktok.com/@${value.replace(/^@/, "")}`
+                                    : kind === "youtube"
+                                        ? `https://youtube.com/${value.startsWith("@") ? value : `@${value}`}`
+                                        : kind === "linkedin"
+                                            ? `https://linkedin.com/${value}`
+                                            : `https://facebook.com/${value}`;
+        const label = kind === "site" ? value.replace(/^https?:\/\//, "").replace(/\/$/, "") : value;
+        return [
+            `<a href="${escapeHtml(href)}" style="color:${light.primary};text-decoration:none">${escapeHtml(label)}</a>`,
+        ];
+    });
+    // Single quotes, the form every mail client reads inside a double-quoted style.
+    const font = escapeHtml(`${cssString(brand.fonts.text.family, "'")}, Arial, sans-serif`);
+    return [
+        `<table cellpadding="0" cellspacing="0" border="0" style="font-family:${font};color:${light.ink};font-size:14px;line-height:1.4">`,
+        '<tr><td style="padding-bottom:8px">',
+        `<img src="${escapeHtml(options.logoUrl)}" width="300" height="80" alt="${escapeHtml(brand.name)}" style="display:block;border:0">`,
+        "</td></tr>",
+        ...(options.person
+            ? [
+                `<tr><td style="font-weight:600">${escapeHtml(options.person)}${options.role ? `<span style="font-weight:400;color:${light.muted}"> · ${escapeHtml(options.role)}</span>` : ""}</td></tr>`,
+            ]
+            : []),
+        `<tr><td style="color:${light.muted}">${escapeHtml(copy.tagline)}</td></tr>`,
+        ...(links.length ? [`<tr><td style="padding-top:4px">${links.join(" · ")}</td></tr>`] : []),
+        "</table>",
+        "",
+    ].join("\n");
+}

package/dist/files/generate.d.ts

@@ -0,0 +1,47 @@
+import type { Brand, Locale } from "../brand/schema.ts";
+import { type SceneCheck } from "../scene/render.ts";
+import type { FontResolver } from "../text/fonts.ts";
+import type { Rasterizer } from "./raster.ts";
+import { type CardCopy } from "./templates.ts";
+/** The groups of files `generate()` can make. Each file's path starts with its group. */
+export declare const TARGETS: readonly ["web", "logo", "og", "social", "tokens", "registry", "docs", "email", "print"];
+export type TargetId = (typeof TARGETS)[number];
+export type DerivedFile = {
+    bytes: Uint8Array;
+    mime: string;
+    sha256: string;
+    width?: number;
+    height?: number;
+};
+/** A page listed in the repo's ideare.json, which gets its own share card per language. */
+export type CardPage = {
+    slug: string;
+    copy: Partial<Record<Locale, CardCopy>>;
+};
+export type GenerateOptions = {
+    targets?: readonly TargetId[];
+    fonts: FontResolver;
+    rasterize: Rasterizer;
+    pages?: CardPage[];
+    /** Where the files will be served from, for links inside signature.html and prompt.md. */
+    filesUrl?: string;
+    /** tokens.css dark blocks and head.html's theme colors: "auto" (default), "attribute" or "none". */
+    dark?: "auto" | "attribute" | "none";
+};
+/** A file that would cut or overflow text, or drop a character, is refused rather than made. */
+export declare class GenerateRefusal extends Error {
+    readonly problems: {
+        path: string;
+        check: SceneCheck;
+    }[];
+    constructor(problems: {
+        path: string;
+        check: SceneCheck;
+    }[]);
+}
+/**
+ * Every derived file of a brand, by path. Pure: nothing is written; the caller (the CLI, the
+ * worker, the browser zip) decides where bytes go. PNGs carry a tEXt provenance chunk; print
+ * files also say 300 dpi.
+ */
+export declare function generate(brand: Brand, options: GenerateOptions): Promise<Map<string, DerivedFile>>;