@pantoken/swatches 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# @pantoken/swatches
+
+Export Instructure colours as designer swatch palettes — files a designer imports directly into
+their tool — plus a viewable SVG specimen sheet. These are terminal outputs, not an interchange
+format: for token interchange use `@pantoken/dtcg` or `@pantoken/figma`.
+
+| Format                                   | Tools                                                              |
+| ---------------------------------------- | ------------------------------------------------------------------ |
+| **ASE** (`toAse`)                        | Photoshop, Illustrator, InDesign (and Affinity, which imports ASE) |
+| **`.gpl`** (`toGpl`)                     | GIMP, Inkscape, Krita, Blender, and Aseprite                       |
+| **`.sketchpalette`** (`toSketchPalette`) | Sketch (Sketch Palettes plugin) and Lunacy                         |
+| **`.svg`** (`toSvg`)                     | A grouped specimen sheet for a README, docs page, PR, or Figma     |
+
+## Install
+
+```sh
+npm i @pantoken/swatches
+```
+
+Also available as `pantoken/swatches`.
+
+## Usage
+
+```ts
+import { swatches, toAse, toGpl, toSketchPalette, toSvg } from "@pantoken/swatches";
+
+writeFileSync("instructure.ase", toAse(swatches));
+writeFileSync("instructure.gpl", toGpl(swatches));
+writeFileSync("instructure.sketchpalette", JSON.stringify(toSketchPalette(swatches)));
+writeFileSync("instructure.svg", toSvg(swatches));
+```
+
+Or via the CLI:
+
+```sh
+pantoken generate swatches --format ase --out instructure.ase
+pantoken generate swatches --format gpl --out instructure.gpl
+pantoken generate swatches --format sketch --out instructure.sketchpalette
+pantoken generate swatches --format svg --out instructure.svg
+```
+
+Swatches are colours only — a flat reduction of the token set. Build the list from any IR with
+`toSwatches(tokens, mode)`.
+
+## API
+
+- **`swatches: Swatch[]`** — the `rebrand` colour swatches (the default palette).
+- **`toSwatches(tokens, mode?): Swatch[]`** — reduce a token IR to a flat list of colour swatches:
+  resolve references, pick a `mode` (`"light"` default or `"dark"`), and keep only tokens whose value
+  is a hex colour. Names drop the `--instui-` prefix.
+- **`toAse(swatches): Uint8Array`** — encode swatches as Adobe Swatch Exchange (ASE) bytes.
+- **`toGpl(swatches, options?): string`** — encode swatches as a GIMP `.gpl` palette string.
+  `options.name` sets the palette name (default `"Instructure"`).
+- **`toSketchPalette(swatches): SketchPalette`** — encode swatches as a Sketch palette object
+  (serialize with `JSON.stringify`).
+- **`toSvg(swatches, options?): string`** — render a grouped SVG specimen sheet. Swatches are grouped
+  by name minus the leaf segment; `options.title` sets the heading and `options.columns` the chips
+  per row (default `6`).
+- **`hexToRgb(hex): Rgb | undefined`** — parse a hex colour to 0–255 channels, or `undefined`.
+- **`Swatch`, `Rgb`, `Mode`, `ToGplOptions`, `SketchPalette`, `ToSvgOptions`** — the model and option
+  types.
+
+## Related
+
+- Pairs with `@pantoken/tokens` for the token IR to reduce.
+- For token interchange (not terminal palettes), see `@pantoken/dtcg` and `@pantoken/figma`.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,177 @@
+import { Token } from "@pantoken/model";
+
+//#region src/model.d.ts
+/** A single palette entry. */
+interface Swatch {
+  name: string;
+  hex: string;
+}
+/** RGB channels, 0–255. */
+interface Rgb {
+  r: number;
+  g: number;
+  b: number;
+}
+/**
+ * Parse `#rgb`/`#rrggbb`/`#rrggbbaa` to 0–255 channels, or `undefined` if not a hex colour.
+ *
+ * @example
+ * ```ts
+ * import { hexToRgb } from "@pantoken/swatches";
+ *
+ * hexToRgb("#ff8800"); // { r: 255, g: 136, b: 0 }
+ * hexToRgb("nope"); // undefined
+ * ```
+ */
+declare function hexToRgb(hex: string): Rgb | undefined;
+/** The colour mode to resolve when flattening `light-dark()` values. */
+type Mode = "light" | "dark";
+/**
+ * Reduce a token IR to a flat list of colour swatches: resolve references, pick a mode, keep only
+ * tokens whose value is a hex colour (icons and non-colour tokens are dropped).
+ *
+ * @param tokens - The IR (e.g. from `@pantoken/tokens`).
+ * @param mode - Which colour mode to resolve (default `"light"`).
+ * @returns The swatch list, named by token (without the `--instui-` prefix).
+ *
+ * @example Reduce the token IR to light-mode swatches
+ * ```ts
+ * import { toSwatches } from "@pantoken/swatches";
+ * import { tokens } from "@pantoken/tokens";
+ *
+ * const swatches = toSwatches(tokens); // [{ name: "color-background-brand", hex: "#…" }, …]
+ * ```
+ *
+ * @example Dark mode
+ * ```ts
+ * import { toSwatches } from "@pantoken/swatches";
+ * import { byTheme } from "@pantoken/tokens";
+ *
+ * const swatches = toSwatches(byTheme("canvas"), "dark");
+ * ```
+ */
+declare function toSwatches(tokens: readonly Token[], mode?: Mode): Swatch[];
+//#endregion
+//#region src/ase.d.ts
+/**
+ * Encode swatches as ASE bytes. Non-hex swatches are skipped.
+ *
+ * @param swatches - The palette.
+ * @returns The ASE file as bytes.
+ *
+ * @example Write an Adobe .ase palette
+ * ```ts
+ * import { writeFileSync } from "node:fs";
+ * import { swatches, toAse } from "@pantoken/swatches";
+ *
+ * writeFileSync("instructure.ase", toAse(swatches));
+ * ```
+ */
+declare function toAse(swatches: readonly Swatch[]): Uint8Array;
+//#endregion
+//#region src/gpl.d.ts
+/** Options for {@link toGpl}. */
+interface ToGplOptions {
+  /** The palette name (default `"Instructure"`). */
+  name?: string;
+}
+/**
+ * Encode swatches as a GIMP `.gpl` palette string.
+ *
+ * @param swatches - The palette.
+ * @param options - {@link ToGplOptions}.
+ *
+ * @example Write a GIMP .gpl palette
+ * ```ts
+ * import { writeFileSync } from "node:fs";
+ * import { swatches, toGpl } from "@pantoken/swatches";
+ *
+ * writeFileSync("instructure.gpl", toGpl(swatches));
+ * ```
+ *
+ * @example With a custom palette name
+ * ```ts
+ * import { swatches, toGpl } from "@pantoken/swatches";
+ *
+ * const gpl = toGpl(swatches, { name: "Instructure Rebrand" });
+ * ```
+ */
+declare function toGpl(swatches: readonly Swatch[], options?: ToGplOptions): string;
+//#endregion
+//#region src/sketch.d.ts
+/** A `.sketchpalette` document. */
+interface SketchPalette {
+  compatibleVersion: string;
+  pluginVersion: string;
+  colors: {
+    name: string;
+    red: number;
+    green: number;
+    blue: number;
+    alpha: number;
+  }[];
+}
+/**
+ * Encode swatches as a Sketch palette object (serialize with `JSON.stringify`).
+ *
+ * @param swatches - The palette.
+ *
+ * @example Write a Sketch .sketchpalette
+ * ```ts
+ * import { writeFileSync } from "node:fs";
+ * import { swatches, toSketchPalette } from "@pantoken/swatches";
+ *
+ * writeFileSync("instructure.sketchpalette", JSON.stringify(toSketchPalette(swatches)));
+ * ```
+ */
+declare function toSketchPalette(swatches: readonly Swatch[]): SketchPalette;
+//#endregion
+//#region src/svg.d.ts
+/** Options for {@link toSvg}. */
+interface ToSvgOptions {
+  /** The sheet title (default `"Instructure color tokens"`). */
+  title?: string;
+  /** Chips per row within a section (default `6`). */
+  columns?: number;
+}
+/**
+ * Render swatches as a grouped SVG specimen sheet.
+ *
+ * @param swatches - The palette (e.g. from `toSwatches`).
+ * @param options - {@link ToSvgOptions}.
+ * @returns The SVG document as a string.
+ *
+ * @example Render a specimen sheet for a README
+ * ```ts
+ * import { writeFileSync } from "node:fs";
+ * import { swatches, toSvg } from "@pantoken/swatches";
+ *
+ * writeFileSync("palette.svg", toSvg(swatches));
+ * ```
+ *
+ * @example Specimen only the core palette, with a title and wider grid
+ * ```ts
+ * import { swatches, toSvg } from "@pantoken/swatches";
+ *
+ * const core = swatches.filter((s) => !s.name.startsWith("primitive-"));
+ * const svg = toSvg(core, { title: "Instructure core colors", columns: 8 });
+ * ```
+ */
+declare function toSvg(swatches: readonly Swatch[], options?: ToSvgOptions): string;
+//#endregion
+//#region src/index.d.ts
+/**
+ * The `rebrand` colour swatches (the default palette).
+ *
+ * @example Encode the ready-made palette to any format
+ * ```ts
+ * import { writeFileSync } from "node:fs";
+ * import { swatches, toAse, toGpl } from "@pantoken/swatches";
+ *
+ * writeFileSync("instructure.ase", toAse(swatches));
+ * writeFileSync("instructure.gpl", toGpl(swatches));
+ * ```
+ */
+declare const swatches: Swatch[];
+//#endregion
+export { type Mode, type Rgb, type SketchPalette, type Swatch, type ToGplOptions, type ToSvgOptions, hexToRgb, swatches, toAse, toGpl, toSketchPalette, toSvg, toSwatches };

package/dist/index.mjs

@@ -0,0 +1,340 @@
+import { tokens } from "@pantoken/tokens";
+import { makeResolver, parseHexColor } from "@pantoken/utils";
+//#region src/model.ts
+/**
+* The shared swatch model and colour helpers. A {@link Swatch} is just a name + hex colour — the
+* flat reduction of the token set that every designer swatch format consumes.
+*
+* @module
+*/
+/**
+* Parse `#rgb`/`#rrggbb`/`#rrggbbaa` to 0–255 channels, or `undefined` if not a hex colour.
+*
+* @example
+* ```ts
+* import { hexToRgb } from "@pantoken/swatches";
+*
+* hexToRgb("#ff8800"); // { r: 255, g: 136, b: 0 }
+* hexToRgb("nope"); // undefined
+* ```
+*/
+function hexToRgb(hex) {
+	const c = parseHexColor(hex);
+	return c ? {
+		r: c.r,
+		g: c.g,
+		b: c.b
+	} : void 0;
+}
+/**
+* Reduce a token IR to a flat list of colour swatches: resolve references, pick a mode, keep only
+* tokens whose value is a hex colour (icons and non-colour tokens are dropped).
+*
+* @param tokens - The IR (e.g. from `@pantoken/tokens`).
+* @param mode - Which colour mode to resolve (default `"light"`).
+* @returns The swatch list, named by token (without the `--instui-` prefix).
+*
+* @example Reduce the token IR to light-mode swatches
+* ```ts
+* import { toSwatches } from "@pantoken/swatches";
+* import { tokens } from "@pantoken/tokens";
+*
+* const swatches = toSwatches(tokens); // [{ name: "color-background-brand", hex: "#…" }, …]
+* ```
+*
+* @example Dark mode
+* ```ts
+* import { toSwatches } from "@pantoken/swatches";
+* import { byTheme } from "@pantoken/tokens";
+*
+* const swatches = toSwatches(byTheme("canvas"), "dark");
+* ```
+*/
+function toSwatches(tokens, mode = "light") {
+	const resolve = makeResolver(tokens, { mode });
+	const out = [];
+	for (const token of tokens) {
+		if (token.meta?.kind === "icon") continue;
+		const hex = resolve(token.value).trim();
+		if (hexToRgb(hex)) out.push({
+			name: token.name.replace(/^--instui-/, ""),
+			hex
+		});
+	}
+	return out;
+}
+//#endregion
+//#region src/ase.ts
+/**
+* Encode swatches as an Adobe Swatch Exchange (ASE) file — the palette format Photoshop,
+* Illustrator, and InDesign import. Binary layout (big-endian):
+*
+* ```
+* "ASEF"  u16 major=1  u16 minor=0  u32 blockCount
+* per colour block:
+*   u16 type=0x0001  u32 dataLength
+*   u16 nameLen(incl. NUL)  UTF-16BE name + NUL  "RGB "  f32 r,g,b (0–1)  u16 colorType=2
+* ```
+*
+* @module
+*/
+/**
+* Encode swatches as ASE bytes. Non-hex swatches are skipped.
+*
+* @param swatches - The palette.
+* @returns The ASE file as bytes.
+*
+* @example Write an Adobe .ase palette
+* ```ts
+* import { writeFileSync } from "node:fs";
+* import { swatches, toAse } from "@pantoken/swatches";
+*
+* writeFileSync("instructure.ase", toAse(swatches));
+* ```
+*/
+function toAse(swatches) {
+	const entries = swatches.map((s) => ({
+		name: s.name,
+		rgb: hexToRgb(s.hex)
+	})).filter((e) => Boolean(e.rgb));
+	const header = Buffer.alloc(12);
+	header.write("ASEF", 0, "ascii");
+	header.writeUInt16BE(1, 4);
+	header.writeUInt16BE(0, 6);
+	header.writeUInt32BE(entries.length, 8);
+	const chunks = [header];
+	for (const { name, rgb } of entries) {
+		const nameLen = name.length + 1;
+		const nameBuf = Buffer.alloc(nameLen * 2);
+		for (let i = 0; i < name.length; i++) nameBuf.writeUInt16BE(name.charCodeAt(i), i * 2);
+		const color = Buffer.alloc(12);
+		color.writeFloatBE(rgb.r / 255, 0);
+		color.writeFloatBE(rgb.g / 255, 4);
+		color.writeFloatBE(rgb.b / 255, 8);
+		const nameLenBuf = Buffer.alloc(2);
+		nameLenBuf.writeUInt16BE(nameLen, 0);
+		const colorType = Buffer.alloc(2);
+		colorType.writeUInt16BE(2, 0);
+		const data = Buffer.concat([
+			nameLenBuf,
+			nameBuf,
+			Buffer.from("RGB ", "ascii"),
+			color,
+			colorType
+		]);
+		const blockHeader = Buffer.alloc(6);
+		blockHeader.writeUInt16BE(1, 0);
+		blockHeader.writeUInt32BE(data.length, 2);
+		chunks.push(blockHeader, data);
+	}
+	return new Uint8Array(Buffer.concat(chunks));
+}
+//#endregion
+//#region src/gpl.ts
+/**
+* Encode swatches as a GIMP palette (`.gpl`) — imported by GIMP, Inkscape, Krita, Blender, and
+* Aseprite. Plain text: a header, then `R G B name` lines (0–255).
+*
+* @module
+*/
+/**
+* Encode swatches as a GIMP `.gpl` palette string.
+*
+* @param swatches - The palette.
+* @param options - {@link ToGplOptions}.
+*
+* @example Write a GIMP .gpl palette
+* ```ts
+* import { writeFileSync } from "node:fs";
+* import { swatches, toGpl } from "@pantoken/swatches";
+*
+* writeFileSync("instructure.gpl", toGpl(swatches));
+* ```
+*
+* @example With a custom palette name
+* ```ts
+* import { swatches, toGpl } from "@pantoken/swatches";
+*
+* const gpl = toGpl(swatches, { name: "Instructure Rebrand" });
+* ```
+*/
+function toGpl(swatches, options = {}) {
+	const lines = [
+		"GIMP Palette",
+		`Name: ${options.name ?? "Instructure"}`,
+		"Columns: 0",
+		"#"
+	];
+	for (const swatch of swatches) {
+		const rgb = hexToRgb(swatch.hex);
+		if (!rgb) continue;
+		const col = (n) => String(n).padStart(3, " ");
+		lines.push(`${col(rgb.r)} ${col(rgb.g)} ${col(rgb.b)}\t${swatch.name}`);
+	}
+	return `${lines.join("\n")}\n`;
+}
+//#endregion
+//#region src/sketch.ts
+/**
+* Encode swatches as a Sketch `.sketchpalette` document (the Sketch Palettes plugin format). JSON
+* with colours as 0–1 RGBA.
+*
+* @module
+*/
+/**
+* Encode swatches as a Sketch palette object (serialize with `JSON.stringify`).
+*
+* @param swatches - The palette.
+*
+* @example Write a Sketch .sketchpalette
+* ```ts
+* import { writeFileSync } from "node:fs";
+* import { swatches, toSketchPalette } from "@pantoken/swatches";
+*
+* writeFileSync("instructure.sketchpalette", JSON.stringify(toSketchPalette(swatches)));
+* ```
+*/
+function toSketchPalette(swatches) {
+	const colors = [];
+	for (const swatch of swatches) {
+		const rgb = hexToRgb(swatch.hex);
+		if (!rgb) continue;
+		colors.push({
+			name: swatch.name,
+			red: rgb.r / 255,
+			green: rgb.g / 255,
+			blue: rgb.b / 255,
+			alpha: 1
+		});
+	}
+	return {
+		compatibleVersion: "2.0",
+		pluginVersion: "2.22",
+		colors
+	};
+}
+//#endregion
+//#region src/svg.ts
+const MARGIN = 32;
+const GROUP_HEAD_H = 26;
+const GROUP_GAP = 26;
+const CELL_W = 150;
+const SWATCH_H = 46;
+const CELL_H = 78;
+const GAP_X = 14;
+const GAP_Y = 16;
+const MAX_LABEL = 22;
+/** Escape the five XML text characters. */
+function esc(text) {
+	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+/** The category a swatch belongs to: first two name segments, or three for a primitive family. */
+function categoryOf(name) {
+	const parts = name.split("-");
+	const depth = parts[0] === "primitive" ? 3 : 2;
+	return parts.slice(0, depth).join("-");
+}
+/** Group swatches by category, preserving first-appearance order. */
+function group(swatches) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const swatch of swatches) {
+		const key = categoryOf(swatch.name);
+		const rest = swatch.name.length > key.length ? swatch.name.slice(key.length + 1) : swatch.name;
+		const label = rest.length > MAX_LABEL ? `${rest.slice(0, MAX_LABEL - 1)}…` : rest;
+		(groups.get(key) ?? groups.set(key, []).get(key)).push({
+			label,
+			swatch
+		});
+	}
+	return [...groups].map(([name, items]) => ({
+		name,
+		items
+	}));
+}
+/**
+* Render swatches as a grouped SVG specimen sheet.
+*
+* @param swatches - The palette (e.g. from `toSwatches`).
+* @param options - {@link ToSvgOptions}.
+* @returns The SVG document as a string.
+*
+* @example Render a specimen sheet for a README
+* ```ts
+* import { writeFileSync } from "node:fs";
+* import { swatches, toSvg } from "@pantoken/swatches";
+*
+* writeFileSync("palette.svg", toSvg(swatches));
+* ```
+*
+* @example Specimen only the core palette, with a title and wider grid
+* ```ts
+* import { swatches, toSvg } from "@pantoken/swatches";
+*
+* const core = swatches.filter((s) => !s.name.startsWith("primitive-"));
+* const svg = toSvg(core, { title: "Instructure core colors", columns: 8 });
+* ```
+*/
+function toSvg(swatches, options = {}) {
+	const title = options.title ?? "Instructure color tokens";
+	const columns = Math.max(1, options.columns ?? 6);
+	const width = MARGIN * 2 + columns * CELL_W + (columns - 1) * GAP_X;
+	const groups = group(swatches);
+	const body = [];
+	let y = 78;
+	for (const g of groups) {
+		body.push(`<text x="${MARGIN}" y="${y}" class="group">${esc(g.name)}</text>`);
+		const top = y + GROUP_HEAD_H;
+		const rows = Math.ceil(g.items.length / columns);
+		g.items.forEach(({ label, swatch }, i) => {
+			const x = MARGIN + i % columns * 164;
+			const cy = top + Math.floor(i / columns) * 94;
+			body.push(`<g transform="translate(${x},${cy})">`, `<rect width="${CELL_W}" height="${SWATCH_H}" rx="6" fill="${esc(swatch.hex)}" class="chip"/>`, `<text x="0" y="62" class="leaf">${esc(label)}</text>`, `<text x="0" y="75" class="hex">${esc(swatch.hex.toUpperCase())}</text>`, `</g>`);
+		});
+		y = top + rows * CELL_H + (rows - 1) * GAP_Y + GROUP_GAP;
+	}
+	const height = y + MARGIN - GROUP_GAP;
+	return [
+		`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" font-family="system-ui, sans-serif">`,
+		`<style>`,
+		`.bg { fill: #ffffff; }`,
+		`.title { fill: #111827; font-size: 20px; font-weight: 700; }`,
+		`.group { fill: #374151; font-size: 14px; font-weight: 600; }`,
+		`.chip { stroke: rgba(0,0,0,0.15); stroke-width: 1; }`,
+		`.leaf { fill: #374151; font-size: 11px; }`,
+		`.hex { fill: #9ca3af; font-size: 10px; font-family: ui-monospace, monospace; }`,
+		`</style>`,
+		`<rect class="bg" width="${width}" height="${height}"/>`,
+		`<text x="${MARGIN}" y="52" class="title">${esc(title)}</text>`,
+		...body,
+		`</svg>`,
+		``
+	].join("\n");
+}
+//#endregion
+//#region src/index.ts
+/**
+* `@pantoken/swatches` — export Instructure colours as designer swatch palettes.
+*
+* Swatches are a flat reduction of the tokens to named colours, delivered *directly to a designer*
+* to import into their tool. This is not an interchange format (use `@pantoken/dtcg` or
+* `@pantoken/figma` for that) — it's a terminal palette file: Adobe ASE, GIMP `.gpl`, or Sketch
+* `.sketchpalette`.
+*
+* @module
+* @experimental
+*/
+/**
+* The `rebrand` colour swatches (the default palette).
+*
+* @example Encode the ready-made palette to any format
+* ```ts
+* import { writeFileSync } from "node:fs";
+* import { swatches, toAse, toGpl } from "@pantoken/swatches";
+*
+* writeFileSync("instructure.ase", toAse(swatches));
+* writeFileSync("instructure.gpl", toGpl(swatches));
+* ```
+*/
+const swatches = toSwatches(tokens);
+//#endregion
+export { hexToRgb, swatches, toAse, toGpl, toSketchPalette, toSvg, toSwatches };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@pantoken/swatches",
+  "version": "0.1.0",
+  "description": "Export Instructure colours as designer swatch palettes: Adobe ASE, GIMP .gpl, and Sketch .sketchpalette.",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@pantoken/model": "0.1.0",
+    "@pantoken/tokens": "0.1.0",
+    "@pantoken/utils": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typescript": "^6.0.3",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.4",
+    "vite-plus": "0.2.4"
+  },
+  "pantoken": {
+    "key": "swatches",
+    "kind": "subpath"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check"
+  }
+}