@021.is/brand-studio 0.3.0 → 0.6.1

package/AGENTS.md

@@ -46,16 +46,26 @@ src/
 - **Named exports only.** **No CSS framework lock-in** — inline `style` / `var(--md-*)`, accept `className`.
 - Sections theme from `var(--md-<role>)`, never from a hand-authored palette.
 
+## The downloads contract — MANDATORY (v0.4+)
+
+Every consumer ships icon + logo download URLs under `/brand/download`. Wire `BrandConfig.downloads = buildStandardDownloads({ basePath })` (or supply explicit `BrandDownload[]`). The lib renders the link grid; the host app serves each URL — one Next.js route handler that renders the SVG sized + recoloured per path params is the canonical pattern.
+
+- URL shape: `<basePath>/<kind>/<size>/<mode>.<format>` — `kind` ∈ {icon, logo} · `mode` ∈ {light, dark} · `format` defaults to `svg`.
+- Canonical sizes: icon 64/128/256/512/1024 (square edge); logo 32/48/64/96/128 (height).
+- Consumers that don't wire `downloads` fall back to the legacy on-click SVG-blob generator with a banner pointing at this contract. The fallback is for migration only — every published app must wire the matrix.
+- Enforce: `grep -L "buildStandardDownloads\|downloads:" brand.config.ts` in every consumer repo's CI = regression.
+
 ## Build + publish
 
-- `bun run build` (tsup + `scripts/add-use-client.mjs`) → `dist/`. `bun run typecheck` + `bun run lint` green before commit.
-- `npm pack` → tgz (consumers currently vendor the tgz under `<app>/vendor/`). To publish: `npm publish` to GitHub Packages needs `NODE_AUTH_TOKEN` with `write:packages` (same as `@021is/spine-*`). **Only publish on Edvard's explicit OK.**
-- Bump `version` on any change; consumers re-vendor the new tgz + `bun install`.
+- `bun run build` (tsup + `scripts/add-use-client.mjs`) → `dist/`. `bun run typecheck` + `bun run lint` + `bun run test` green before commit.
+- `npm pack` → tgz (`021is-brand-studio-<version>.tgz`). Publish destination is **`registry.npmjs.org`** as `@021.is/brand-studio` (verified live for 0.3.0 — earlier note about GitHub Packages is stale). `npm publish` needs Edvard's classic npm token + **his explicit OK** — never auto-publish.
+- Bump `version` on every change; consumers update via `bun add @021.is/brand-studio@<version>`.
 
 ## Active threads
 
-- **v0.3.0 (current) — generic + MD3.** ✅ Ripped out all zeropost/postal content (icons, mailbox marks, FlagDroop/Stamp motions, forest/cream defaults). Added the MD3 color engine + seed-based `defineBrand`. Sections render consumer content (Icons/Motion) + the full MD3 role set (Colors). `private:false`, publishable.
-- **v0.4.0 — export CLI.** `npx brand-studio export ./brand.config.ts` → icon.svg / apple-icon.png / og.png (satori/resvg).
+- **v0.4.0 (current) — downloads URL contract.** ✅ Added `BrandConfig.downloads` + `buildStandardDownloads()` helper + rewrote `<DownloadSection>` as a URL link grid (open · copy · save). Legacy on-click SVG generator kept as fallback for v0.3.x consumers. zeropost is the reference wiring.
+- **v0.3.0 — generic + MD3.** ✅ Ripped out all zeropost/postal content (icons, mailbox marks, FlagDroop/Stamp motions, forest/cream defaults). Added the MD3 color engine + seed-based `defineBrand`. `private:false`, publishable. Live on npm 2026-06-03.
+- **v0.5.0 — export CLI.** `npx brand-studio export ./brand.config.ts` → icon.svg / apple-icon.png / og.png (satori/resvg). Complements the runtime URL contract for static-export use cases.
 - **v1.0.0 — visual editor + plugin API.**
 
 ## See

package/README.md

@@ -54,6 +54,32 @@ export default defineBrand({
 
 `defineBrand` eagerly resolves `config.scheme` (the full `{ light, dark }` role set) so downstream consumers never wait on a derivation.
 
+## Expose the download matrix (mandatory, v0.4+)
+
+Every consumer ships a `/brand/download` link grid for the **app icon** and **logo** at **multiple sizes** in **both light and dark** variants. Wire `BrandConfig.downloads` with `buildStandardDownloads(basePath)` and serve the URLs from your host app:
+
+```ts
+// brand.config.ts
+import { defineBrand, buildStandardDownloads } from "@021.is/brand-studio/define";
+
+export default defineBrand({
+  name: "Acme",
+  // ... color, type, voice ...
+  downloads: buildStandardDownloads({ basePath: "/brand/download" }),
+});
+```
+
+Default URL shape: `<basePath>/<kind>/<size>/<mode>.<format>`
+Example: `/brand/download/icon/256/light.svg` · `/brand/download/logo/64/dark.svg`
+
+Canonical matrix:
+- **Icon** sizes: 64 / 128 / 256 / 512 / 1024 (square edge px)
+- **Logo** sizes: 32 / 48 / 64 / 96 / 128 (height px)
+- Each size in both `light` and `dark`
+- Format: `svg` by default (PNG opt-in via the `formats` option)
+
+The host app serves each URL — typically one Next.js route handler that renders the SVG mark sized + recoloured per the path params. Consumers that don't wire `downloads` keep working: the Download section falls back to the v0.3.x on-click SVG-blob generator, with a banner pointing at this section.
+
 ## Mount the brand page
 
 ```tsx

package/dist/{BrandStudio-D2DcT8Fu.d.ts → BrandStudio-D1QR4hIC.d.ts}

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { B as BrandConfig } from './types-PWNYyaBF.js';
+import { B as BrandConfig } from './types-BycZ2igw.js';
 
 type BrandIcon = {
     node: ReactNode;

package/dist/app/index.d.ts

@@ -1,7 +1,7 @@
-export { B as BrandIcon, a as BrandStudio, b as BrandStudioProps } from '../BrandStudio-D2DcT8Fu.js';
+export { B as BrandIcon, a as BrandStudio, b as BrandStudioProps } from '../BrandStudio-D1QR4hIC.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { a as BrandStudioSection } from '../types-PWNYyaBF.js';
+import { c as BrandStudioSection } from '../types-BycZ2igw.js';
 export { c as contrastBadge, a as contrastRatio, r as relativeLuminance } from '../contrast-TVW3pzdd.js';
 import '../generateScheme-BDDcIzA3.js';
 

package/dist/app/index.js

@@ -1,4 +1,5 @@
 "use client";
-export { BrandStudio, Navigation, buildNavigation } from '../chunk-Z2DJJJDC.js';
-import '../chunk-55AYEWNQ.js';
+export { BrandStudio, Navigation, buildNavigation } from '../chunk-L4FQAO3K.js';
+import '../chunk-YDZA26YU.js';
+import '../chunk-MDTU2JR5.js';
 export { contrastBadge, contrastRatio, relativeLuminance } from '../chunk-JQV3ASME.js';

package/dist/chunk-6J2NFZLN.js

@@ -0,0 +1,50 @@
+import { DownloadKind, DownloadFormat, DownloadMode } from './chunk-MDTU2JR5.js';
+import { generateScheme } from './chunk-JQV3ASME.js';
+
+// src/define/defineBrand.ts
+function defineBrand(config) {
+  return { ...config, scheme: config.scheme ?? generateScheme(config.color) };
+}
+
+// src/define/downloads.ts
+var STANDARD_ICON_SIZES = [64, 128, 256, 512, 1024];
+var STANDARD_LOGO_SIZES = [32, 48, 64, 96, 128];
+var KIND_PATH = {
+  [DownloadKind.Icon]: "app-icon",
+  [DownloadKind.Logo]: "logo"
+};
+function buildStandardDownloads(input) {
+  const brand = slugify(input.brand);
+  if (!brand) throw new Error("buildStandardDownloads: `brand` is required (non-empty after slug)");
+  const basePath = (input.basePath ?? "/brand").replace(/\/+$/, "");
+  const iconSizes = input.iconSizes ?? STANDARD_ICON_SIZES;
+  const logoSizes = input.logoSizes ?? STANDARD_LOGO_SIZES;
+  const formats = input.formats ?? [DownloadFormat.Svg];
+  const modes = [DownloadMode.Light, DownloadMode.Dark];
+  const items = [];
+  for (const kind of [DownloadKind.Icon, DownloadKind.Logo]) {
+    const sizes = kind === DownloadKind.Icon ? iconSizes : logoSizes;
+    const kindPath = KIND_PATH[kind];
+    for (const size of sizes) {
+      for (const mode of modes) {
+        for (const format of formats) {
+          const filename = `${brand}-${size}-${mode}.${format}`;
+          items.push({
+            kind,
+            mode,
+            size,
+            format,
+            url: `${basePath}/${kindPath}/${filename}`,
+            filename
+          });
+        }
+      }
+    }
+  }
+  return { items };
+}
+function slugify(input) {
+  return input.normalize("NFKD").replace(/\p{M}/gu, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+export { STANDARD_ICON_SIZES, STANDARD_LOGO_SIZES, buildStandardDownloads, defineBrand, slugify };

package/dist/{chunk-ZE5UZAY6.js → chunk-F4CFQDS7.js}

@@ -1,5 +1,6 @@
 "use client";
-import { LoadingVariant, SpinnerLoadingMark } from './chunk-55AYEWNQ.js';
+import { SpinnerLoadingMark } from './chunk-YDZA26YU.js';
+import { LoadingVariant } from './chunk-MDTU2JR5.js';
 import { motion } from 'framer-motion';
 import { jsxs, jsx } from 'react/jsx-runtime';
 

package/dist/{chunk-Z2DJJJDC.js → chunk-L4FQAO3K.js}

@@ -1,4 +1,5 @@
-import { BrandStudioSection, SpinnerLoadingMark } from './chunk-55AYEWNQ.js';
+import { SpinnerLoadingMark } from './chunk-YDZA26YU.js';
+import { BrandStudioSection, DownloadMode, DownloadKind, DownloadFormat } from './chunk-MDTU2JR5.js';
 import { generateScheme, schemeToCssText, ROLE_GROUPS, contrastBadge, contrastRatio } from './chunk-JQV3ASME.js';
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { useRef, useState } from 'react';
@@ -178,17 +179,6 @@ function ColorsSection({ scheme }) {
 }
 var ICON_SIZES = [64, 128, 256, 512, 1024];
 var WORDMARK_HEIGHTS = [32, 48, 64, 96, 128];
-function triggerDownload(svgString, filename) {
-  const blob = new Blob([svgString], { type: "image/svg+xml;charset=utf-8" });
-  const url = URL.createObjectURL(blob);
-  const a = document.createElement("a");
-  a.href = url;
-  a.download = filename;
-  document.body.appendChild(a);
-  a.click();
-  a.remove();
-  setTimeout(() => URL.revokeObjectURL(url), 1e3);
-}
 function DownloadSection({
   config,
   staticLogo,
@@ -209,7 +199,17 @@ function DownloadSection({
   const darkLabel = scheme.dark.onSurfaceVariant;
   const iconDarkNode = staticLogoDark ?? staticLogo;
   const hasDistinctDark = staticLogoDark !== void 0 && staticLogoDark !== null;
-  function downloadIcon(mode) {
+  const downloads = config.downloads?.items ?? [];
+  const iconLight = findEntry(downloads, DownloadKind.Icon, DownloadMode.Light, iconSize);
+  const iconDark = findEntry(downloads, DownloadKind.Icon, DownloadMode.Dark, iconSize);
+  const logoLight = findEntry(downloads, DownloadKind.Logo, DownloadMode.Light, wmHeight);
+  const logoDark = findEntry(downloads, DownloadKind.Logo, DownloadMode.Dark, wmHeight);
+  async function downloadIcon(mode) {
+    const entry = mode === "light" ? iconLight : iconDark;
+    if (entry) {
+      await fetchAndSave(entry.url, entry.filename ?? lastSegment(entry.url));
+      return;
+    }
     const ref = mode === "light" ? iconLightRef : iconDarkRef;
     const svg = ref.current?.querySelector("svg");
     if (!svg) return;
@@ -217,12 +217,17 @@ function DownloadSection({
     clone.setAttribute("xmlns", "http://www.w3.org/2000/svg");
     clone.setAttribute("width", String(iconSize));
     clone.setAttribute("height", String(iconSize));
-    triggerDownload(
+    triggerBlobDownload(
       new XMLSerializer().serializeToString(clone),
       `${config.name}-icon-${iconSize}-${mode}.svg`
     );
   }
   async function downloadWordmark(mode) {
+    const entry = mode === "light" ? logoLight : logoDark;
+    if (entry) {
+      await fetchAndSave(entry.url, entry.filename ?? lastSegment(entry.url));
+      return;
+    }
     await document.fonts?.ready;
     const text = measureRef.current?.querySelector("text");
     if (!text) return;
@@ -237,7 +242,7 @@ function DownloadSection({
       `<text x="${(pad - bbox.x).toFixed(1)}" y="${pad.toFixed(1)}" dominant-baseline="text-before-edge" font-family="${sans}, system-ui, sans-serif" font-weight="600" font-size="100" letter-spacing="-3" fill="${fill}">${config.name}</text>`,
       "</svg>"
     ].join("");
-    triggerDownload(out, `${config.name}-wordmark-${wmHeight}-${mode}.svg`);
+    triggerBlobDownload(out, `${config.name}-wordmark-${wmHeight}-${mode}.svg`);
   }
   return /* @__PURE__ */ jsxs("section", { children: [
     /* @__PURE__ */ jsx(
@@ -257,11 +262,11 @@ function DownloadSection({
       {
         style: {
           color: "var(--md-on-surface-variant)",
-          maxWidth: "40rem",
+          maxWidth: "44rem",
           margin: "0 0 2.5rem",
           lineHeight: 1.6
         },
-        children: "Export the app icon and wordmark as standalone SVGs in light and dark variants. Pick a size, download, drop into your console branding page."
+        children: "Export the app icon and wordmark as standalone SVGs in light and dark variants. Pick a size, download, or copy the stable URL beneath the buttons to embed or share."
       }
     ),
     /* @__PURE__ */ jsxs(
@@ -302,6 +307,7 @@ function DownloadSection({
                 }
               )
             ] }),
+            iconLight || iconDark ? /* @__PURE__ */ jsx(UrlPair, { light: iconLight, dark: iconDark }) : null,
             staticLogo && !hasDistinctDark ? /* @__PURE__ */ jsxs(Note, { children: [
               "No dark icon supplied \u2014 dark export reuses the light mark. Pass",
               " ",
@@ -343,7 +349,8 @@ function DownloadSection({
                   children: "Dark SVG"
                 }
               )
-            ] })
+            ] }),
+            logoLight || logoDark ? /* @__PURE__ */ jsx(UrlPair, { light: logoLight, dark: logoDark }) : null
           ] })
         ]
       }
@@ -390,6 +397,139 @@ function DownloadSection({
     )
   ] });
 }
+function findEntry(items, kind, mode, size) {
+  const entry = items.find(
+    (it) => it.kind === kind && it.mode === mode && it.size === size && it.format === DownloadFormat.Svg
+  );
+  return entry ?? null;
+}
+function triggerBlobDownload(svgString, filename) {
+  const blob = new Blob([svgString], { type: "image/svg+xml;charset=utf-8" });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+  window.setTimeout(() => URL.revokeObjectURL(url), 1e3);
+}
+async function fetchAndSave(url, filename) {
+  try {
+    const res = await fetch(url, { cache: "no-store" });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const blob = await res.blob();
+    const objectUrl = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = objectUrl;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    window.setTimeout(() => URL.revokeObjectURL(objectUrl), 1e3);
+  } catch {
+    window.open(url, "_blank", "noopener,noreferrer");
+  }
+}
+function UrlPair({ light, dark }) {
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      style: {
+        marginTop: "0.7rem",
+        display: "grid",
+        gap: "0.35rem"
+      },
+      children: [
+        /* @__PURE__ */ jsx(UrlRow, { label: "LIGHT", entry: light }),
+        /* @__PURE__ */ jsx(UrlRow, { label: "DARK", entry: dark })
+      ]
+    }
+  );
+}
+function UrlRow({ label, entry }) {
+  const [copied, setCopied] = useState(false);
+  const url = entry?.url ?? null;
+  function onCopy() {
+    if (!url || typeof navigator === "undefined" || !navigator.clipboard) return;
+    navigator.clipboard.writeText(toAbsolute(url)).then(() => {
+      setCopied(true);
+      window.setTimeout(() => setCopied(false), 1200);
+    });
+  }
+  const disabled = !url;
+  const downloadName = entry?.filename ?? lastSegment(url ?? "");
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      style: {
+        display: "flex",
+        alignItems: "center",
+        gap: "0.4rem",
+        padding: "0.4rem 0.6rem",
+        borderRadius: "0.45rem",
+        background: "var(--md-surface-container-low)",
+        border: "1px solid var(--md-outline-variant)",
+        opacity: disabled ? 0.55 : 1
+      },
+      children: [
+        /* @__PURE__ */ jsx("span", { style: urlLabelStyle, children: label }),
+        /* @__PURE__ */ jsx(
+          "a",
+          {
+            href: url ?? "#",
+            target: "_blank",
+            rel: "noreferrer",
+            download: downloadName || void 0,
+            style: {
+              flex: 1,
+              color: "var(--md-on-surface)",
+              textDecoration: "none",
+              fontFamily: "var(--bs-mono, ui-monospace, monospace)",
+              fontSize: "0.74rem",
+              letterSpacing: "0.01em",
+              minWidth: 0,
+              overflow: "hidden",
+              textOverflow: "ellipsis",
+              whiteSpace: "nowrap",
+              pointerEvents: disabled ? "none" : "auto"
+            },
+            title: url ?? "no URL configured for this size",
+            children: url ?? "\u2014"
+          }
+        ),
+        /* @__PURE__ */ jsx(
+          "button",
+          {
+            type: "button",
+            onClick: onCopy,
+            disabled,
+            title: "Copy URL",
+            style: {
+              ...copyButtonStyle,
+              cursor: disabled ? "not-allowed" : "pointer"
+            },
+            children: copied ? "Copied" : "Copy"
+          }
+        )
+      ]
+    }
+  );
+}
+function lastSegment(url) {
+  const noQuery = url.split("?")[0] ?? "";
+  const parts = noQuery.split("/");
+  return parts[parts.length - 1] ?? "";
+}
+function toAbsolute(url) {
+  if (/^https?:\/\//.test(url)) return url;
+  if (typeof window === "undefined") return url;
+  try {
+    return new URL(url, window.location.origin).toString();
+  } catch {
+    return url;
+  }
+}
 var mono = { fontFamily: "var(--bs-mono)" };
 function NoAsset() {
   return /* @__PURE__ */ jsx("span", { style: { color: "var(--md-on-surface-variant)", fontSize: "0.8rem" }, children: "no icon" });
@@ -518,6 +658,26 @@ var eyebrowStyle = {
   color: "var(--md-primary)",
   margin: 0
 };
+var urlLabelStyle = {
+  fontFamily: "var(--bs-mono, ui-monospace, monospace)",
+  fontSize: "0.62rem",
+  letterSpacing: "0.14em",
+  textTransform: "uppercase",
+  color: "var(--md-on-surface-variant)",
+  flexShrink: 0,
+  width: "3rem"
+};
+var copyButtonStyle = {
+  padding: "0.3rem 0.55rem",
+  borderRadius: "0.35rem",
+  border: "1px solid var(--md-outline-variant)",
+  background: "transparent",
+  color: "var(--md-primary)",
+  fontFamily: "var(--bs-mono, ui-monospace, monospace)",
+  fontSize: "0.68rem",
+  fontWeight: 600,
+  whiteSpace: "nowrap"
+};
 function buttonStyle(disabled, kind) {
   const isPrimary = kind === "primary";
   return {

package/dist/chunk-MDTU2JR5.js

@@ -0,0 +1,35 @@
+// src/types.ts
+var LoadingVariant = {
+  Spinner: "spinner",
+  Ring: "ring",
+  Pulse: "pulse"
+};
+var BrandStudioSection = {
+  Overview: "overview",
+  Logo: "logo",
+  Colors: "colors",
+  Typography: "typography",
+  Icons: "icons",
+  Motion: "motion",
+  Download: "download"
+};
+var MotionState = {
+  Idle: "idle",
+  Loading: "loading",
+  Success: "success",
+  Empty: "empty"
+};
+var DownloadKind = {
+  Icon: "icon",
+  Logo: "logo"
+};
+var DownloadMode = {
+  Light: "light",
+  Dark: "dark"
+};
+var DownloadFormat = {
+  Svg: "svg",
+  Png: "png"
+};
+
+export { BrandStudioSection, DownloadFormat, DownloadKind, DownloadMode, LoadingVariant, MotionState };

package/dist/{chunk-55AYEWNQ.js → chunk-YDZA26YU.js}

@@ -2,27 +2,6 @@
 import { motion } from 'framer-motion';
 import { jsxs, jsx } from 'react/jsx-runtime';
 
-// src/types.ts
-var LoadingVariant = {
-  Spinner: "spinner",
-  Ring: "ring",
-  Pulse: "pulse"
-};
-var BrandStudioSection = {
-  Overview: "overview",
-  Logo: "logo",
-  Colors: "colors",
-  Typography: "typography",
-  Icons: "icons",
-  Motion: "motion",
-  Download: "download"
-};
-var MotionState = {
-  Idle: "idle",
-  Loading: "loading",
-  Success: "success",
-  Empty: "empty"
-};
 function SpinnerLoadingMark({
   size = 200,
   background = "transparent",
@@ -81,4 +60,4 @@ function SpinnerLoadingMark({
   );
 }
 
-export { BrandStudioSection, LoadingVariant, MotionState, SpinnerLoadingMark };
+export { SpinnerLoadingMark };

package/dist/define/index.d.ts

@@ -1,5 +1,5 @@
-import { B as BrandConfig, R as ResolvedBrandConfig } from '../types-PWNYyaBF.js';
-export { b as BrandType } from '../types-PWNYyaBF.js';
+import { B as BrandConfig, R as ResolvedBrandConfig, D as DownloadFormat, b as BrandDownloads } from '../types-BycZ2igw.js';
+export { a as BrandDownload, d as BrandType, e as DownloadKind, f as DownloadMode } from '../types-BycZ2igw.js';
 export { B as BrandScheme, C as ColorScheme, a as ColorSpec, H as Hex, d as Role, S as SchemeVariant, g as generateScheme } from '../generateScheme-BDDcIzA3.js';
 
 /**
@@ -22,4 +22,46 @@ export { B as BrandScheme, C as ColorScheme, a as ColorSpec, H as Hex, d as Role
  */
 declare function defineBrand(config: BrandConfig): ResolvedBrandConfig;
 
-export { BrandConfig, ResolvedBrandConfig, defineBrand };
+/** Canonical icon export sizes — square pixel edges. */
+declare const STANDARD_ICON_SIZES: readonly [64, 128, 256, 512, 1024];
+/** Canonical logo export sizes — pixel heights. */
+declare const STANDARD_LOGO_SIZES: readonly [32, 48, 64, 96, 128];
+type StandardDownloadsInput = {
+    /**
+     * The brand slug embedded in every URL. Required — this is the SEO win;
+     * `/brand/app-icon/zeropost-256-light.svg` indexes far better than
+     * `/brand/light.svg`. Pass the lowercased brand name (e.g. `"zeropost"`)
+     * or any slug. Auto-slugified to lowercase ASCII + hyphens.
+     */
+    brand: string;
+    /**
+     * Mount path the host app serves the assets under, no trailing slash.
+     * Default `/brand`. Full URL shape:
+     *   `<basePath>/<kind-path>/<brand>-<size>-<mode>.<format>`
+     * Example: `/brand/app-icon/zeropost-256-light.svg`
+     * Kind paths: `app-icon` (square mark) · `logo` (wordmark).
+     *
+     * The kind segment never collides with brand-studio's own section routes
+     * (`/brand/logo`, `/brand/colors`, …) because assets are two-segment URLs
+     * (`/brand/logo/<slug>.svg`) while sections are one-segment (`/brand/logo`).
+     * The host route handler at `app/brand/[kind]/[slug]/route.ts` beats the
+     * brand-page catch-all for two-segment URLs.
+     */
+    basePath?: string;
+    /** Icon edges in px. Default `STANDARD_ICON_SIZES`. */
+    iconSizes?: readonly number[];
+    /** Logo heights in px. Default `STANDARD_LOGO_SIZES`. */
+    logoSizes?: readonly number[];
+    /** Formats to emit per (kind, size, mode). Default `["svg"]`. */
+    formats?: readonly (typeof DownloadFormat)[keyof typeof DownloadFormat][];
+};
+/**
+ * Build the canonical icon + logo × {light, dark} × sizes × formats matrix.
+ * Every brand-studio consumer ships this (or a superset) so users always have
+ * shareable, SEO-friendly URLs to the brand marks.
+ */
+declare function buildStandardDownloads(input: StandardDownloadsInput): BrandDownloads;
+/** Lowercase ASCII, replace non-alphanumeric with hyphens, collapse + trim. */
+declare function slugify(input: string): string;
+
+export { BrandConfig, BrandDownloads, DownloadFormat, ResolvedBrandConfig, STANDARD_ICON_SIZES, STANDARD_LOGO_SIZES, type StandardDownloadsInput, buildStandardDownloads, defineBrand, slugify };

package/dist/define/index.js

@@ -1,2 +1,3 @@
-export { defineBrand } from '../chunk-QT5N4K7D.js';
+export { STANDARD_ICON_SIZES, STANDARD_LOGO_SIZES, buildStandardDownloads, defineBrand, slugify } from '../chunk-6J2NFZLN.js';
+export { DownloadFormat, DownloadKind, DownloadMode } from '../chunk-MDTU2JR5.js';
 export { SchemeVariant, generateScheme } from '../chunk-JQV3ASME.js';

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 export { Disc, DiscProps, Ring, RingProps, Squircle, SquircleProps } from './shapes/index.js';
 export { AppearGrow, AppearGrowProps, Drift, DriftProps, PulseLoop, PulseLoopProps, RingDraw, RingDrawProps, Sequence, SequenceProps, SequenceStep, SequenceStepProps, Strikethrough, StrikethroughProps, Sweep, SweepDirection, SweepProps, Wobble, WobbleProps } from './motion/index.js';
 export { LoadingMark, LoadingMarkProps, PulseLoadingMark, PulseLoadingMarkProps, RingLoadingMark, RingLoadingMarkProps, SpinnerLoadingMark, SpinnerLoadingMarkProps } from './loading/index.js';
-export { B as BrandConfig, a as BrandStudioSection, b as BrandType, L as LoadingVariant, M as MotionState, R as ResolvedBrandConfig } from './types-PWNYyaBF.js';
+export { B as BrandConfig, a as BrandDownload, b as BrandDownloads, c as BrandStudioSection, d as BrandType, D as DownloadFormat, e as DownloadKind, f as DownloadMode, L as LoadingVariant, M as MotionState, R as ResolvedBrandConfig } from './types-BycZ2igw.js';
 export { B as BrandScheme, C as ColorScheme, a as ColorSpec, H as Hex, R as ROLE, b as ROLE_GROUPS, c as ROLE_ORDER, d as Role, S as SchemeVariant, g as generateScheme } from './generateScheme-BDDcIzA3.js';
 export { cssVarName, schemeToCssText, schemeVars } from './color/index.js';
 export { C as ContrastTier, c as contrastBadge, a as contrastRatio, r as relativeLuminance } from './contrast-TVW3pzdd.js';
-export { a as BrandStudio, b as BrandStudioProps } from './BrandStudio-D2DcT8Fu.js';
-export { defineBrand } from './define/index.js';
+export { a as BrandStudio, b as BrandStudioProps } from './BrandStudio-D1QR4hIC.js';
+export { STANDARD_ICON_SIZES, STANDARD_LOGO_SIZES, StandardDownloadsInput, buildStandardDownloads, defineBrand, slugify } from './define/index.js';
 import 'react/jsx-runtime';
 import 'react';

package/dist/index.js

@@ -1,8 +1,9 @@
 "use client";
 export { Disc, Ring, Squircle } from './chunk-LJ4HZCAP.js';
 export { AppearGrow, Drift, PulseLoop, RingDraw, Sequence, SequenceStep, Strikethrough, Sweep, Wobble } from './chunk-7325RQRP.js';
-export { LoadingMark, PulseLoadingMark, RingLoadingMark } from './chunk-ZE5UZAY6.js';
-export { BrandStudio } from './chunk-Z2DJJJDC.js';
-export { BrandStudioSection, LoadingVariant, MotionState, SpinnerLoadingMark } from './chunk-55AYEWNQ.js';
-export { defineBrand } from './chunk-QT5N4K7D.js';
+export { LoadingMark, PulseLoadingMark, RingLoadingMark } from './chunk-F4CFQDS7.js';
+export { BrandStudio } from './chunk-L4FQAO3K.js';
+export { SpinnerLoadingMark } from './chunk-YDZA26YU.js';
+export { STANDARD_ICON_SIZES, STANDARD_LOGO_SIZES, buildStandardDownloads, defineBrand, slugify } from './chunk-6J2NFZLN.js';
+export { BrandStudioSection, DownloadFormat, DownloadKind, DownloadMode, LoadingVariant, MotionState } from './chunk-MDTU2JR5.js';
 export { ContrastTier, ROLE, ROLE_GROUPS, ROLE_ORDER, SchemeVariant, contrastBadge, contrastRatio, cssVarName, generateScheme, relativeLuminance, schemeToCssText, schemeVars } from './chunk-JQV3ASME.js';

package/dist/loading/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, CSSProperties } from 'react';
-import { L as LoadingVariant } from '../types-PWNYyaBF.js';
+import { L as LoadingVariant } from '../types-BycZ2igw.js';
 import '../generateScheme-BDDcIzA3.js';
 
 type LoadingMarkProps = {

package/dist/loading/index.js

@@ -1,3 +1,4 @@
 "use client";
-export { LoadingMark, PulseLoadingMark, RingLoadingMark } from '../chunk-ZE5UZAY6.js';
-export { LoadingVariant, SpinnerLoadingMark } from '../chunk-55AYEWNQ.js';
+export { LoadingMark, PulseLoadingMark, RingLoadingMark } from '../chunk-F4CFQDS7.js';
+export { SpinnerLoadingMark } from '../chunk-YDZA26YU.js';
+export { LoadingVariant } from '../chunk-MDTU2JR5.js';

package/dist/types-BycZ2igw.d.ts

@@ -0,0 +1,119 @@
+import { a as ColorSpec, B as BrandScheme } from './generateScheme-BDDcIzA3.js';
+
+/**
+ * Shared types for @021.is/brand-studio.
+ *
+ * Const-as-object enums (no inline string-literal unions in public signatures).
+ */
+
+/** Generic loading-mark variants. No brand-coded marks live in the lib. */
+declare const LoadingVariant: {
+    readonly Spinner: "spinner";
+    readonly Ring: "ring";
+    readonly Pulse: "pulse";
+};
+type LoadingVariant = (typeof LoadingVariant)[keyof typeof LoadingVariant];
+declare const BrandStudioSection: {
+    readonly Overview: "overview";
+    readonly Logo: "logo";
+    readonly Colors: "colors";
+    readonly Typography: "typography";
+    readonly Icons: "icons";
+    readonly Motion: "motion";
+    readonly Download: "download";
+};
+type BrandStudioSection = (typeof BrandStudioSection)[keyof typeof BrandStudioSection];
+declare const MotionState: {
+    readonly Idle: "idle";
+    readonly Loading: "loading";
+    readonly Success: "success";
+    readonly Empty: "empty";
+};
+type MotionState = (typeof MotionState)[keyof typeof MotionState];
+/**
+ * Mandatory download contract — every brand-studio consumer SHOULD expose its
+ * app icon + logo at multiple sizes, in both light- and dark-surface variants,
+ * as shareable URLs. The lib renders them as a link grid on `/brand/download`.
+ *
+ * Host apps wire `BrandConfig.downloads` to a route handler (or static files)
+ * that returns the asset. Use `buildStandardDownloads(basePath)` for the
+ * canonical 5×2×2 matrix.
+ */
+declare const DownloadKind: {
+    readonly Icon: "icon";
+    readonly Logo: "logo";
+};
+type DownloadKind = (typeof DownloadKind)[keyof typeof DownloadKind];
+declare const DownloadMode: {
+    readonly Light: "light";
+    readonly Dark: "dark";
+};
+type DownloadMode = (typeof DownloadMode)[keyof typeof DownloadMode];
+declare const DownloadFormat: {
+    readonly Svg: "svg";
+    readonly Png: "png";
+};
+type DownloadFormat = (typeof DownloadFormat)[keyof typeof DownloadFormat];
+type BrandDownload = {
+    kind: DownloadKind;
+    mode: DownloadMode;
+    /** Pixel size — square edge for icons, height for logos. */
+    size: number;
+    /** Asset format. SVG is the canonical export; PNG is optional raster. */
+    format: DownloadFormat;
+    /** Absolute or root-relative URL the host app serves. */
+    url: string;
+    /**
+     * Filename the user should see when downloading. Used as the
+     * `<a download="…">` attribute. Defaults to the URL's last segment.
+     */
+    filename?: string;
+    /** Optional override for the link label. */
+    label?: string;
+};
+type BrandDownloads = {
+    /** Linear list of download entries. Order is preserved for the link grid. */
+    items: readonly BrandDownload[];
+};
+type BrandType = {
+    sans: string;
+    mono?: string;
+    serif?: string;
+};
+type BrandConfig = {
+    /** Brand display name, shown on the overview + exports. */
+    name: string;
+    /** Short tagline shown on the brand-kit overview. */
+    tagline?: string;
+    /** Operator legal entity, shown in the brand-kit footer. */
+    operator?: string;
+    /** Domain (used for "view live" links). */
+    domain?: string;
+    /**
+     * Color spec — a seed (+ optional key colors / overrides) the MD3 engine
+     * derives a complete light + dark role set from. See `defineBrand`.
+     */
+    color: ColorSpec;
+    type: BrandType;
+    /** Voice rules, rendered as a bullet list. */
+    voice?: readonly string[];
+    /**
+     * Download URL contract — icon + logo at multiple sizes × {light, dark}.
+     * Rendered as a link grid under `/brand/download`. Use
+     * `buildStandardDownloads(basePath)` for the canonical matrix or supply
+     * explicit entries. When absent, the Download section falls back to
+     * on-click SVG-blob generation (legacy behaviour).
+     */
+    downloads?: BrandDownloads;
+    /**
+     * Resolved MD3 light + dark role sets. Populated by `defineBrand`; do not set
+     * by hand. Sections read it (and the injected `--md-*` CSS vars) for theming.
+     */
+    scheme?: BrandScheme;
+};
+/** A `BrandConfig` after `defineBrand` has resolved its `scheme`. */
+type ResolvedBrandConfig = BrandConfig & {
+    scheme: BrandScheme;
+};
+
+export { type BrandConfig as B, DownloadFormat as D, LoadingVariant as L, MotionState as M, type ResolvedBrandConfig as R, type BrandDownload as a, type BrandDownloads as b, BrandStudioSection as c, type BrandType as d, DownloadKind as e, DownloadMode as f };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@021.is/brand-studio",
-  "version": "0.3.0",
-  "description": "Generic MD3 brand-kit toolkit: seed → full light + dark role set, composable SVG shapes + motion + loading marks, and a mountable <BrandStudio> /brand page. Ships no brand content — every app supplies its own logo, icons, and seed colour.",
+  "version": "0.6.1",
+  "description": "Generic MD3 brand-kit toolkit: seed → full light + dark role set, composable SVG shapes + motion + loading marks, mountable <BrandStudio> /brand page, mandatory icon + logo download-URL contract. Ships no brand content — every app supplies its own logo, icons, and seed colour.",
   "license": "MIT",
   "author": {
     "name": "edvone",

package/dist/chunk-QT5N4K7D.js

@@ -1,8 +0,0 @@
-import { generateScheme } from './chunk-JQV3ASME.js';
-
-// src/define/defineBrand.ts
-function defineBrand(config) {
-  return { ...config, scheme: config.scheme ?? generateScheme(config.color) };
-}
-
-export { defineBrand };

package/dist/types-PWNYyaBF.d.ts

@@ -1,66 +0,0 @@
-import { a as ColorSpec, B as BrandScheme } from './generateScheme-BDDcIzA3.js';
-
-/**
- * Shared types for @021.is/brand-studio.
- *
- * Const-as-object enums (no inline string-literal unions in public signatures).
- */
-
-/** Generic loading-mark variants. No brand-coded marks live in the lib. */
-declare const LoadingVariant: {
-    readonly Spinner: "spinner";
-    readonly Ring: "ring";
-    readonly Pulse: "pulse";
-};
-type LoadingVariant = (typeof LoadingVariant)[keyof typeof LoadingVariant];
-declare const BrandStudioSection: {
-    readonly Overview: "overview";
-    readonly Logo: "logo";
-    readonly Colors: "colors";
-    readonly Typography: "typography";
-    readonly Icons: "icons";
-    readonly Motion: "motion";
-    readonly Download: "download";
-};
-type BrandStudioSection = (typeof BrandStudioSection)[keyof typeof BrandStudioSection];
-declare const MotionState: {
-    readonly Idle: "idle";
-    readonly Loading: "loading";
-    readonly Success: "success";
-    readonly Empty: "empty";
-};
-type MotionState = (typeof MotionState)[keyof typeof MotionState];
-type BrandType = {
-    sans: string;
-    mono?: string;
-    serif?: string;
-};
-type BrandConfig = {
-    /** Brand display name, shown on the overview + exports. */
-    name: string;
-    /** Short tagline shown on the brand-kit overview. */
-    tagline?: string;
-    /** Operator legal entity, shown in the brand-kit footer. */
-    operator?: string;
-    /** Domain (used for "view live" links). */
-    domain?: string;
-    /**
-     * Color spec — a seed (+ optional key colors / overrides) the MD3 engine
-     * derives a complete light + dark role set from. See `defineBrand`.
-     */
-    color: ColorSpec;
-    type: BrandType;
-    /** Voice rules, rendered as a bullet list. */
-    voice?: readonly string[];
-    /**
-     * Resolved MD3 light + dark role sets. Populated by `defineBrand`; do not set
-     * by hand. Sections read it (and the injected `--md-*` CSS vars) for theming.
-     */
-    scheme?: BrandScheme;
-};
-/** A `BrandConfig` after `defineBrand` has resolved its `scheme`. */
-type ResolvedBrandConfig = BrandConfig & {
-    scheme: BrandScheme;
-};
-
-export { type BrandConfig as B, LoadingVariant as L, MotionState as M, type ResolvedBrandConfig as R, BrandStudioSection as a, type BrandType as b };