@terrazzo/cli 2.0.0-beta.2 → 2.0.0-beta.4

package/dist/index.js

@@ -1,7 +1,7 @@
 import { createRequire } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { build, defineConfig as defineConfig$1, parse } from "@terrazzo/parser";
-import fs, { createReadStream, createWriteStream } from "node:fs";
+import fs from "node:fs";
 import path from "node:path";
 import pc from "picocolors";
 import { createServer } from "vite";
@@ -9,13 +9,15 @@ import { ViteNodeRunner } from "vite-node/client";
 import { ViteNodeServer } from "vite-node/server";
 import chokidar from "chokidar";
 import yamlToMomoa from "yaml-to-momoa";
+import fs$1 from "node:fs/promises";
+import { isAlias, pluralize } from "@terrazzo/token-tools";
+import { merge } from "merge-anything";
+import { camelCase } from "scule";
 import { spawn } from "node:child_process";
 import { confirm, intro, multiselect, outro, select, spinner } from "@clack/prompts";
-import { isAlias, pluralize } from "@terrazzo/token-tools";
 import { detect } from "detect-package-manager";
 import { generate } from "escodegen";
 import { parseModule } from "meriyah";
-import { readdir } from "node:fs/promises";
 import { Readable, Writable } from "node:stream";
 import { serve } from "@hono/node-server";
 import mime from "mime";
@@ -377,21 +379,584 @@ async function checkCmd({ config, logger, positionals }) {
 function helpCmd() {
 	console.log(`tz
   [commands]
-    build           Build token artifacts from tokens.json
-      --watch, -w   Watch tokens.json for changes and recompile
-      --no-lint     Disable linters running on build
-    check [path]    Check tokens.json for errors and run linters
-    lint [path]     (alias of check)
-    init            Create a starter tokens.json file
-    lab             Manage your tokens with a web interface
+    build            Build token artifacts from tokens.json
+      --watch, -w    Watch tokens.json for changes and recompile
+      --no-lint      Disable linters running on build
+    check [path]     Check tokens.json for errors and run linters
+    lint [path]      (alias of check)
+    init             Create a starter tokens.json file
+    lab              Manage your tokens with a web interface
+    import [path]    Import from a Figma Design file
+      --o [file]     Save imported JSON
+      --unpublished  Include unpublished Variables
+      --skip-styles  Don’t import styles
+      --skip-variables
+                     Don’t import variables
 
   [options]
-    --help          Show this message
-    --config, -c    Path to config (default: ./terrazzo.config.ts)
-    --quiet         Suppress warnings
+    --help           Show this message
+    --config, -c     Path to config (default: ./terrazzo.config.ts)
+    --quiet          Suppress warnings
 `);
 }
 
+//#endregion
+//#region src/import/figma/lib.ts
+const KEY = ":key";
+const FILE_KEY = ":file_key";
+const API = {
+	file: `https://api.figma.com/v1/files/${FILE_KEY}`,
+	fileNodes: `https://api.figma.com/v1/files/${FILE_KEY}/nodes`,
+	fileStyles: `https://api.figma.com/v1/files/${FILE_KEY}/styles`,
+	localVariables: `https://api.figma.com/v1/files/${FILE_KEY}/variables/local`,
+	publishedVariables: `https://api.figma.com/v1/files/${FILE_KEY}/variables/published`,
+	styles: `https://api.figma.com/v1/styles/${KEY}`
+};
+/** Wrapper around camelCase to handle more cases */
+function formatName(name) {
+	return camelCase(name.replace(/\s+/g, "-"));
+}
+const nf = new Intl.NumberFormat("en-us");
+/** Wrapper around camelCase to handle more cases */
+function formatNumber(number) {
+	return nf.format(number);
+}
+/** Get File ID from design URL */
+function getFileID(url) {
+	return url.match(/^https:\/\/(www\.)?figma\.com\/design\/([^/]+)/)?.[2];
+}
+/** /v1/files/:file_key */
+async function getFile(fileKey, { logger }) {
+	const res = await fetch(API.file.replace(FILE_KEY, fileKey), {
+		method: "GET",
+		headers: { "X-Figma-Token": process.env.FIGMA_ACCESS_TOKEN }
+	});
+	if (!res.ok) logger.error({
+		group: "import",
+		message: `${res.status} ${await res.text()}`
+	});
+	return await res.json();
+}
+/** /v1/files/:file_key/nodes */
+async function getFileNodes(fileKey, { ids, logger }) {
+	let url = API.fileNodes.replace(FILE_KEY, fileKey);
+	if (ids?.length) url += `?ids=${ids.join(",")}`;
+	const res = await fetch(url, {
+		method: "GET",
+		headers: { "X-Figma-Token": process.env.FIGMA_ACCESS_TOKEN }
+	});
+	if (!res.ok) logger.error({
+		group: "import",
+		message: `${res.status} ${await res.text()}`
+	});
+	return await res.json();
+}
+/** /v1/files/:file_key/styles */
+async function getFileStyles(fileKey, { logger }) {
+	const res = await fetch(API.fileStyles.replace(FILE_KEY, fileKey), {
+		method: "GET",
+		headers: { "X-Figma-Token": process.env.FIGMA_ACCESS_TOKEN }
+	});
+	if (!res.ok) logger.error({
+		group: "import",
+		message: `${res.status} ${await res.text()}`
+	});
+	return await res.json();
+}
+/** /v1/files/:file_key/variables/local */
+async function getFileLocalVariables(fileKey, { logger }) {
+	const res = await fetch(API.localVariables.replace(FILE_KEY, fileKey), {
+		method: "GET",
+		headers: { "X-Figma-Token": process.env.FIGMA_ACCESS_TOKEN }
+	});
+	if (!res.ok) logger.error({
+		group: "import",
+		message: `${res.status} ${await res.text}`
+	});
+	return await res.json();
+}
+/** /v1/files/:file_key/variables/published */
+async function getFilePublishedVariables(fileKey, { logger }) {
+	const res = await fetch(API.publishedVariables.replace(FILE_KEY, fileKey), {
+		method: "GET",
+		headers: { "X-Figma-Token": process.env.FIGMA_ACCESS_TOKEN }
+	});
+	if (!res.ok) logger.error({
+		group: "import",
+		message: `${res.status} ${await res.text}`
+	});
+	return await res.json();
+}
+
+//#endregion
+//#region src/import/figma/styles.ts
+/** /v1/files/:file_key/styles */
+async function getStyles(fileKey, { logger, unpublished }) {
+	const result = {
+		count: 0,
+		code: { sets: { styles: { sources: [{}] } } }
+	};
+	const styleNodeIDs = /* @__PURE__ */ new Set();
+	const stylesByID = /* @__PURE__ */ new Map();
+	if (unpublished) {
+		const styles = await getFile(fileKey, { logger });
+		for (const [id, style] of Object.entries(styles.styles)) {
+			styleNodeIDs.add(id);
+			stylesByID.set(id, style);
+		}
+	} else {
+		const styles = await getFileStyles(fileKey, { logger });
+		for (const style of styles.meta.styles) {
+			styleNodeIDs.add(style.node_id);
+			stylesByID.set(style.node_id, style);
+		}
+	}
+	const fileNodes = await getFileNodes(fileKey, {
+		ids: [...styleNodeIDs],
+		logger
+	});
+	result.count += styleNodeIDs.size;
+	for (const [id, s] of stylesByID) {
+		const styleNode = fileNodes.nodes[id];
+		if (!styleNode) {
+			logger.warn({
+				group: "import",
+				message: `Style ${s.name} not found in file nodes. Does it need to be published?`
+			});
+			continue;
+		}
+		const styleType = "style_type" in s ? s.style_type : s.styleType;
+		const tokenBase = {
+			$type: void 0,
+			$description: s.description || void 0,
+			$value: void 0,
+			$extensions: { "figma.com": {
+				name: s.name,
+				node_id: id,
+				created_at: "created_at" in s ? s.created_at : void 0,
+				updated_at: "updated_at" in s ? s.updated_at : void 0
+			} }
+		};
+		switch (styleType) {
+			case "FILL": {
+				const $value = fillStyle(styleNode.document);
+				if (!$value) logger.error({
+					group: "import",
+					message: `Could not parse fill for ${s.name}`,
+					continueOnError: true
+				});
+				if (Array.isArray($value)) tokenBase.$type = "gradient";
+				else tokenBase.$type = "color";
+				tokenBase.$value = $value;
+				break;
+			}
+			case "TEXT": {
+				const $value = textStyle(styleNode.document);
+				if (!$value) logger.error({
+					group: "import",
+					message: `Could not parse text for ${s.name}`,
+					continueOnError: true
+				});
+				tokenBase.$type = "typography";
+				tokenBase.$value = $value;
+				break;
+			}
+			case "EFFECT": {
+				const $value = effectStyle(styleNode.document);
+				if (!$value) logger.error({
+					group: "import",
+					message: `Could not parse effect for ${s.name}`,
+					continueOnError: true
+				});
+				tokenBase.$type = "shadow";
+				tokenBase.$value = $value;
+				break;
+			}
+			case "GRID": {
+				const layoutGrids = gridStyles(styleNode.document);
+				if (!layoutGrids) logger.error({
+					group: "import",
+					message: `Could not parse grid for ${s.name}`,
+					continueOnError: true
+				});
+				let node = result.code.sets.styles.sources[0];
+				const path = s.name.split("/").map(formatName);
+				const name = path.pop();
+				for (const key of path) {
+					if (!(key in node)) node[key] = {};
+					node = node[key];
+				}
+				node[name] = layoutGrids;
+				break;
+			}
+		}
+		if (tokenBase.$type !== void 0) {
+			let node = result.code.sets.styles.sources[0];
+			const path = s.name.split("/").map(formatName);
+			const name = path.pop();
+			for (const key of path) {
+				if (!(key in node)) node[key] = {};
+				node = node[key];
+			}
+			node[name] = tokenBase;
+		}
+	}
+	return result;
+}
+/** Return a shadow token from an effect */
+function effectStyle(node) {
+	if ("effects" in node) {
+		const shadows = node.effects.filter((e) => e.type === "DROP_SHADOW" || e.type === "INNER_SHADOW");
+		if (shadows.length) return shadows.map((s) => ({
+			inset: s.type === "INNER_SHADOW",
+			offsetX: {
+				value: s.offset.x,
+				unit: "px"
+			},
+			offsetY: {
+				value: s.offset.y,
+				unit: "px"
+			},
+			blur: {
+				value: s.radius,
+				unit: "px"
+			},
+			spread: {
+				value: s.spread ?? 0,
+				unit: "px"
+			},
+			color: {
+				colorSpace: "srgb",
+				components: [
+					s.color.r,
+					s.color.g,
+					s.color.b
+				],
+				alpha: s.color.a
+			}
+		}));
+	}
+}
+/** Return a color or gradient token from a fill */
+function fillStyle(node) {
+	if ("fills" in node) for (const fill of node.fills) switch (fill.type) {
+		case "SOLID": return {
+			colorSpace: "srgb",
+			components: [
+				fill.color.r,
+				fill.color.g,
+				fill.color.b
+			],
+			alpha: fill.color.a
+		};
+		case "GRADIENT_LINEAR":
+		case "GRADIENT_RADIAL":
+		case "GRADIENT_ANGULAR":
+		case "GRADIENT_DIAMOND": return fill.gradientStops.map((stop) => ({
+			position: stop.position,
+			color: {
+				colorSpace: "srgb",
+				components: [
+					stop.color.r,
+					stop.color.g,
+					stop.color.b
+				],
+				alpha: stop.color.a
+			}
+		}));
+	}
+}
+/** Return a dimension token from grid */
+function gridStyles(node) {
+	if (!("layoutGrids" in node) || !node.layoutGrids?.length) return;
+	const values = {};
+	for (const grid of node.layoutGrids) {
+		const pattern = grid.pattern.toLowerCase();
+		if (values[pattern]) continue;
+		values[pattern] = {
+			sectionSize: {
+				$type: "dimension",
+				$value: {
+					value: grid.sectionSize,
+					unit: "px"
+				}
+			},
+			gutterSize: {
+				$type: "dimension",
+				$value: {
+					value: grid.sectionSize,
+					unit: "px"
+				}
+			}
+		};
+		if (grid.count > 0) values[pattern].count = {
+			$type: "number",
+			$value: grid.count
+		};
+	}
+	return values;
+}
+/** Return a typography token from text */
+function textStyle(node) {
+	if (!("style" in node)) return;
+	return {
+		fontFamily: [node.style.fontFamily],
+		fontWeight: node.style.fontWeight,
+		fontStyle: node.style.fontStyle,
+		fontSize: node.style.fontSize ? {
+			value: node.style.fontSize,
+			unit: "px"
+		} : {
+			value: 1,
+			unit: "em"
+		},
+		letterSpacing: {
+			value: node.style.letterSpacing ?? 0,
+			unit: "px"
+		},
+		lineHeight: "lineHeightPercentFontSize" in node.style ? node.style.lineHeightPercentFontSize : "lineHeightPx" in node.style ? {
+			value: node.style.lineHeightPx,
+			unit: "px"
+		} : 1
+	};
+}
+
+//#endregion
+//#region src/import/figma/variables.ts
+/** /v1/files/:file_key/variables/published | /v1/files/:file_key/variables/local */
+async function getVariables(fileKey, { logger, unpublished, matchers }) {
+	const result = {
+		count: 0,
+		remoteCount: 0,
+		code: {
+			sets: {},
+			modifiers: {}
+		}
+	};
+	const allVariables = {};
+	const variableCollections = {};
+	let finalVariables = {};
+	const modeIDToName = {};
+	const local = await getFileLocalVariables(fileKey, { logger });
+	for (const id of Object.keys(local.meta.variables)) {
+		if (local.meta.variables[id].hiddenFromPublishing) continue;
+		allVariables[id] = local.meta.variables[id];
+	}
+	for (const id of Object.keys(local.meta.variableCollections)) {
+		variableCollections[id] = local.meta.variableCollections[id];
+		for (const mode of local.meta.variableCollections[id].modes) modeIDToName[mode.modeId] = formatName(mode.name);
+	}
+	if (unpublished) finalVariables = allVariables;
+	else {
+		const published = await getFilePublishedVariables(fileKey, { logger });
+		for (const id of Object.keys(published.meta.variables)) finalVariables[id] = allVariables[id];
+	}
+	const remoteIDs = /* @__PURE__ */ new Set();
+	for (const id of Object.keys(finalVariables)) {
+		const variable = finalVariables[id];
+		const collection = variableCollections[variable.variableCollectionId];
+		const collectionName = formatName(collection.name);
+		const hasMultipleModes = collection.modes.length > 1;
+		if (hasMultipleModes) {
+			if (!(collectionName in result.code.modifiers)) result.code.modifiers[collectionName] = {
+				contexts: Object.fromEntries(collection.modes.map((m) => [formatName(m.name), [{}]])),
+				default: modeIDToName[collection.defaultModeId]
+			};
+		} else if (!(collectionName in result.code.sets)) result.code.sets[collectionName] = { sources: [{}] };
+		const matches = matchers.fontFamily?.test(variable.name) && "fontFamily" || matchers.fontWeight?.test(variable.name) && "fontWeight" || matchers.number?.test(variable.name) && "number" || void 0;
+		for (const [modeID, value] of Object.entries(variable.valuesByMode)) {
+			const modeName = modeIDToName[modeID];
+			let node = result.code;
+			if (hasMultipleModes) {
+				if (!(modeName in result.code.modifiers[collectionName].contexts)) result.code.modifiers[collectionName].contexts[modeName] = [{}];
+				node = result.code.modifiers[collectionName].contexts[modeName][0];
+			} else node = result.code.sets[collectionName].sources[0];
+			const tokenBase = {
+				$type: void 0,
+				$description: variable.description || void 0,
+				$value: void 0,
+				$extensions: { "figma.com": {
+					name: variable.name,
+					id: variable.id,
+					variableCollectionId: variable.variableCollectionId,
+					codeSyntax: Object.keys(variable.codeSyntax).length ? variable.codeSyntax : void 0
+				} }
+			};
+			const isAliasOfID = typeof value === "object" && "type" in value && value.type === "VARIABLE_ALIAS" && value.id || void 0;
+			if (isAliasOfID) if (allVariables[isAliasOfID]) {
+				tokenBase.$type = matches || {
+					COLOR: "color",
+					BOOLEAN: "boolean",
+					STRING: "string",
+					FLOAT: "dimension"
+				}[variable.resolvedType];
+				tokenBase.$value = `{${allVariables[isAliasOfID].name.split("/").map(formatName).join(".")}}`;
+			} else {
+				remoteIDs.add(isAliasOfID);
+				continue;
+			}
+			else if (matches === "fontFamily") {
+				tokenBase.$type = "fontFamily";
+				tokenBase.$value = String(value).split(",");
+			} else if (matches === "fontWeight") {
+				tokenBase.$type = "fontWeight";
+				tokenBase.$value = value;
+			} else if (matches === "number") {
+				if (typeof value === "object") throw new Error(`Can’t coerce ${variable.name} into number type.`);
+				tokenBase.$type = "number";
+				tokenBase.$value = Number(value);
+			} else switch (variable.resolvedType) {
+				case "BOOLEAN":
+				case "STRING":
+					tokenBase.$type = variable.resolvedType.toLowerCase();
+					tokenBase.$value = value;
+					break;
+				case "FLOAT":
+					tokenBase.$type = "dimension";
+					tokenBase.$value = {
+						value,
+						unit: "px"
+					};
+					break;
+				case "COLOR": {
+					const { r, g, b, a } = value;
+					tokenBase.$type = "color";
+					tokenBase.$value = {
+						colorSpace: "srgb",
+						components: [
+							r,
+							g,
+							b
+						],
+						alpha: a
+					};
+					break;
+				}
+			}
+			if (tokenBase.$value !== void 0) {
+				const path = variable.name.split("/").map(formatName);
+				const name = path.pop();
+				for (const key of path) {
+					if (!(key in node)) node[key] = {};
+					node = node[key];
+				}
+				node[name] = tokenBase;
+			}
+		}
+	}
+	result.count = Object.keys(finalVariables).length;
+	result.remoteCount = remoteIDs.size;
+	return result;
+}
+
+//#endregion
+//#region src/import/figma/index.ts
+async function importFromFigma({ url, logger, unpublished, skipStyles, skipVariables, fontFamilyNames, fontWeightNames, numberNames }) {
+	const fileKey = getFileID(url);
+	if (!fileKey) logger.error({
+		group: "import",
+		message: `Invalid Figma URL: ${url}`
+	});
+	const result = {
+		variableCount: 0,
+		styleCount: 0,
+		code: {
+			$schema: "https://www.designtokens.org/schemas/2025.10/resolver.json",
+			version: "2025.10",
+			resolutionOrder: [],
+			sets: {},
+			modifiers: {}
+		}
+	};
+	try {
+		const [styles, vars] = await Promise.all([!skipStyles ? getStyles(fileKey, { logger }) : null, !skipVariables ? getVariables(fileKey, {
+			logger,
+			unpublished,
+			matchers: {
+				fontFamily: new RegExp(fontFamilyNames || "/fontFamily$"),
+				fontWeight: new RegExp(fontWeightNames || "/fontWeight$"),
+				number: numberNames ? new RegExp(numberNames) : void 0
+			}
+		}) : null]);
+		if (styles) {
+			result.styleCount += styles.count;
+			result.code = merge(result.code, styles.code);
+		}
+		if (vars) {
+			result.variableCount += vars.count;
+			result.code = merge(result.code, vars.code);
+			if (vars.remoteCount) logger.warn({
+				group: "import",
+				message: `${formatNumber(vars.remoteCount)} ${pluralize(vars.remoteCount, "Variable", "Variables")} were remote and could not be accessed. Try importing from other files to grab them.`
+			});
+		}
+	} catch (err) {
+		logger.error({
+			group: "import",
+			message: err.message
+		});
+	}
+	for (const group of ["sets", "modifiers"]) for (const name of Object.keys(result.code[group])) result.code.resolutionOrder.push({ $ref: `#/${group}/${name}` });
+	return result;
+}
+/** Is this a valid URL, and one belonging to a Figma file? */
+function isFigmaPath(url) {
+	try {
+		new URL(url);
+		return /^https:\/\/(www\.)?figma\.com\/design\/[A-Za-z0-9]+/.test(url);
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+//#region src/import/index.ts
+async function importCmd({ flags, positionals, logger }) {
+	const [_cmd, url] = positionals;
+	if (!url) logger.error({
+		group: "import",
+		message: "Missing import path. Expected `tz import [file]`."
+	});
+	if (isFigmaPath(url)) {
+		const { FIGMA_ACCESS_TOKEN } = process.env;
+		if (!FIGMA_ACCESS_TOKEN) logger.error({
+			group: "import",
+			message: `FIGMA_ACCESS_TOKEN not set! See https://terrazzo.app/docs/guides/import-from-figma`
+		});
+		const start = performance.now();
+		const result = await importFromFigma({
+			url,
+			logger,
+			unpublished: flags.unpublished,
+			skipStyles: flags["skip-styles"],
+			skipVariables: flags["skip-variables"],
+			fontFamilyNames: flags["font-family-names"],
+			fontWeightNames: flags["font-weight-names"],
+			numberNames: flags["number-names"]
+		});
+		const end = performance.now() - start;
+		if (flags.output) {
+			const oldFile = fs.existsSync(flags.output) ? JSON.parse(await fs$1.readFile(flags.output, "utf8")) : {};
+			const code = {
+				$schema: result.code.$schema,
+				version: result.code.version,
+				resolutionOrder: oldFile.resolutionOrder?.length ? oldFile.resolutionOrder : result.code.resolutionOrder,
+				sets: result.code.sets,
+				modifiers: result.code.modifiers,
+				$defs: oldFile.$defs,
+				$extensions: oldFile.$extensions
+			};
+			await fs$1.writeFile(flags.output, `${JSON.stringify(code, void 0, 2)}\n`);
+			logger.info({
+				group: "import",
+				message: `Imported ${formatNumber(result.variableCount)} ${pluralize(result.variableCount, "Variable", "Variables")}, ${formatNumber(result.styleCount)} ${pluralize(result.styleCount, "Style", "Styles")} → ${flags.output}`,
+				timing: end
+			});
+		} else process.stdout.write(JSON.stringify(result.code));
+		return;
+	}
+}
+
 //#endregion
 //#region src/init.ts
 const INSTALL_COMMAND = {
@@ -400,6 +965,12 @@ const INSTALL_COMMAND = {
 	pnpm: "add -D --silent",
 	bun: "install -D --silent"
 };
+const SYNTAX_SETTINGS = { format: {
+	indent: { style: "  " },
+	quotes: "single",
+	semicolons: true
+} };
+const EXAMPLE_TOKENS_PATH = "my-tokens.tokens.json";
 const DESIGN_SYSTEMS = {
 	"adobe-spectrum": {
 		name: "Spectrum",
@@ -441,19 +1012,19 @@ async function initCmd({ logger }) {
 	try {
 		intro("⛋ Welcome to Terrazzo");
 		const packageManager = await detect({ cwd: fileURLToPath(cwd) });
-		const { config, configPath } = await loadConfig({
+		const { config, configPath = "terrazzo.config.ts" } = await loadConfig({
 			cmd: "init",
 			flags: {},
 			logger
 		});
-		const relConfigPath = configPath ? path.relative(fileURLToPath(cwd), fileURLToPath(new URL(configPath))) : void 0;
-		let tokensPath = config.tokens[0];
+		const tokensPath = config.tokens[0];
+		const hasExistingConfig = fs.existsSync(configPath);
 		let startFromDS = !(tokensPath && fs.existsSync(tokensPath));
 		if (tokensPath && fs.existsSync(tokensPath)) {
 			if (await confirm({ message: `Found tokens at ${path.relative(fileURLToPath(cwd), fileURLToPath(tokensPath))}. Overwrite with a new design system?` })) startFromDS = true;
-		} else tokensPath = DEFAULT_TOKENS_PATH;
+		}
 		if (startFromDS) {
-			if (DESIGN_SYSTEMS[await select({
+			const ds = DESIGN_SYSTEMS[await select({
 				message: "Start from existing design system?",
 				options: [...Object.entries(DESIGN_SYSTEMS).map(([id, { author, name }]) => ({
 					value: id,
@@ -462,7 +1033,8 @@ async function initCmd({ logger }) {
 					value: "none",
 					label: "None"
 				}]
-			})]) {
+			})];
+			if (ds) {
 				const s = spinner();
 				s.start("Downloading");
 				await new Promise((resolve, reject) => {
@@ -470,8 +1042,14 @@ async function initCmd({ logger }) {
 					subprocess.on("error", reject);
 					subprocess.on("exit", resolve);
 				});
-				await s.stop("Download complete");
-			}
+				s.stop("Download complete");
+				if (hasExistingConfig) await updateConfigTokens(configPath, ds.tokens);
+				else await newConfigFile(configPath, ds.tokens);
+			} else startFromDS = false;
+		}
+		if (!hasExistingConfig) {
+			await newConfigFile(configPath, [EXAMPLE_TOKENS_PATH]);
+			await fs$1.writeFile(EXAMPLE_TOKENS_PATH, JSON.stringify(EXAMPLE_TOKENS, void 0, 2));
 		}
 		const existingPlugins = config.plugins.map((p) => p.name);
 		const pluginSelection = await multiselect({
@@ -500,7 +1078,7 @@ async function initCmd({ logger }) {
 		if (newPlugins?.length) {
 			const plugins = newPlugins.map((p) => ({
 				specifier: p.replace("@terrazzo/plugin-", ""),
-				package: p
+				path: p
 			}));
 			const pluginCount = `${newPlugins.length} ${pluralize(newPlugins.length, "plugin", "plugins")}`;
 			const s = spinner();
@@ -511,77 +1089,27 @@ async function initCmd({ logger }) {
 				subprocess.on("exit", resolve);
 			});
 			s.message("Updating config");
-			if (configPath) {
-				const ast = parseModule(fs.readFileSync(configPath, "utf8"));
-				const astExport = ast.body.find((node) => node.type === "ExportDefaultDeclaration");
-				ast.body.push(...plugins.map((p) => ({
-					type: "ImportDeclaration",
-					source: {
-						type: "Literal",
-						value: p.package
-					},
-					specifiers: [{
-						type: "ImportDefaultSpecifier",
-						local: {
-							type: "Identifier",
-							name: p.specifier
-						}
-					}],
-					attributes: []
-				})));
-				if (!astExport) {
-					logger.error({
-						group: "config",
-						message: `SyntaxError: ${relConfigPath} does not have default export.`
-					});
-					return;
-				}
-				const astConfig = astExport.declaration.type === "CallExpression" ? astExport.declaration.arguments[0] : astExport.declaration;
-				if (astConfig.type !== "ObjectExpression") {
-					logger.error({
-						group: "config",
-						message: `Config: expected object default export, received ${astConfig.type}`
-					});
-					return;
-				}
-				const pluginsArray = astConfig.properties.find((property) => property.type === "Property" && property.key.type === "Identifier" && property.key.name === "plugins")?.value;
-				const pluginsAst = plugins.map((p) => ({
-					type: "CallExpression",
-					callee: {
-						type: "Identifier",
-						name: p.specifier
-					},
-					arguments: [],
-					optional: false
-				}));
-				if (pluginsArray) pluginsArray.elements.push(...pluginsAst);
-				else astConfig.properties.push({
-					type: "Property",
-					key: {
-						type: "Identifier",
-						name: "plugins"
-					},
-					value: {
-						type: "ArrayExpression",
-						elements: pluginsAst
-					},
-					kind: "init",
-					computed: false,
-					method: false,
-					shorthand: false
-				});
-				fs.writeFileSync(configPath, generate(ast, { format: {
-					indent: { style: "  " },
-					quotes: "single",
-					semicolons: true
-				} }));
-			} else fs.writeFileSync(DEFAULT_CONFIG_PATH, `import { defineConfig } from '@terrazzo/cli';
-${plugins.map((p) => `import ${p.specifier} from '${p.package}';`).join("\n")}
+			await updateConfigPlugins(configPath, plugins);
+			s.stop(`Installed ${pluginCount}`);
+		}
+		if (!startFromDS && !newPlugins?.length) {
+			outro("Nothing to do. Exiting.");
+			return;
+		}
+		outro("⛋ Done! 🎉");
+	} catch (err) {
+		printError(err.message);
+		process.exit(1);
+	}
+}
+async function newConfigFile(configPath, tokens, imports = []) {
+	await fs$1.writeFile(configPath, `import { defineConfig } from '@terrazzo/cli';
+${imports.map((p) => `import ${p.specifier} from '${p.path}';`).join("\n")}
 
 export default defineConfig({
-  tokens: ['./tokens.json'],
+  tokens: ['${tokens.join("', '")}'],
   plugins: [
-    ${plugins.map((p) => `${p.specifier}(),`).join("\n    ")}
+    ${imports.length ? imports.map((p) => `${p.specifier}(),`).join("\n    ") : "/** @see https://terrazzo.app/docs */"}
   ],
   outDir: './dist/',
   lint: {
@@ -610,14 +1138,279 @@ export default defineConfig({
     },
   },
 });`);
-			s.stop(`Installed ${pluginCount}`);
-		}
-		outro("⛋ Done! 🎉");
-	} catch (err) {
-		printError(err.message);
-		process.exit(1);
+}
+function getConfigObjFromAst(ast, configPath) {
+	const astExport = ast.body.find((node) => node.type === "ExportDefaultDeclaration");
+	if (!astExport) {
+		const relConfigPath = configPath ? path.relative(fileURLToPath(cwd), fileURLToPath(new URL(configPath))) : void 0;
+		throw new Error(`SyntaxError: ${relConfigPath} does not have default export.`);
 	}
+	const astConfig = astExport.declaration.type === "CallExpression" ? astExport.declaration.arguments[0] : astExport.declaration;
+	if (astConfig.type !== "ObjectExpression") throw new Error(`Config: expected object default export, received ${astConfig.type}.`);
+	return astConfig;
+}
+async function updateConfigTokens(configPath, tokens) {
+	const ast = parseModule(await fs$1.readFile(configPath, "utf8"));
+	const astConfig = getConfigObjFromAst(ast, configPath);
+	let tokensKey = astConfig.properties.find((p) => p.type === "Property" && p.key.type === "Identifier" && p.key.name === "tokens");
+	if (!tokensKey) {
+		tokensKey = {
+			type: "Property",
+			key: {
+				type: "Identifier",
+				name: "tokens"
+			},
+			method: false,
+			computed: false,
+			shorthand: false,
+			value: {
+				type: "ArrayExpression",
+				elements: tokens.map((value) => ({
+					type: "Literal",
+					value,
+					raw: `'${value}'`
+				}))
+			}
+		};
+		astConfig.properties.unshift(tokensKey);
+	}
+	await fs$1.writeFile(configPath, generate(ast, SYNTAX_SETTINGS));
+}
+/**
+* Add plugin imports
+* note: this has the potential to duplicate plugins, but we tried our
+* best to filter already, and this may be the user’s fault if they
+* selected to install a plugin already installed. But also, this is
+* easily-fixable, so let’s not waste too much time here (and possibly
+* introduce bugs).
+*/
+async function updateConfigPlugins(configPath, plugins) {
+	const ast = parseModule(await fs$1.readFile(configPath, "utf8"));
+	ast.body.push(...plugins.map((p) => ({
+		type: "ImportDeclaration",
+		source: {
+			type: "Literal",
+			value: p.path
+		},
+		specifiers: [{
+			type: "ImportDefaultSpecifier",
+			local: {
+				type: "Identifier",
+				name: p.specifier
+			}
+		}],
+		attributes: []
+	})));
+	const astConfig = getConfigObjFromAst(ast, configPath);
+	const pluginsArray = astConfig.properties.find((property) => property.type === "Property" && property.key.type === "Identifier" && property.key.name === "plugins")?.value;
+	const pluginsAst = plugins.map((p) => ({
+		type: "CallExpression",
+		callee: {
+			type: "Identifier",
+			name: p.specifier
+		},
+		arguments: [],
+		optional: false
+	}));
+	if (pluginsArray) pluginsArray.elements.push(...pluginsAst);
+	else astConfig.properties.push({
+		type: "Property",
+		key: {
+			type: "Identifier",
+			name: "plugins"
+		},
+		value: {
+			type: "ArrayExpression",
+			elements: pluginsAst
+		},
+		kind: "init",
+		computed: false,
+		method: false,
+		shorthand: false
+	});
+	await fs$1.writeFile(configPath, generate(ast, SYNTAX_SETTINGS));
 }
+const EXAMPLE_TOKENS = {
+	color: {
+		$description: "Color tokens",
+		black: {
+			"100": {
+				$type: "color",
+				$value: {
+					colorSpace: "srgb",
+					components: [
+						.047,
+						.047,
+						.047
+					],
+					alpha: .05,
+					hex: "#0c0c0d"
+				}
+			},
+			"200": {
+				$type: "color",
+				$value: {
+					colorSpace: "srgb",
+					components: [
+						.047,
+						.047,
+						.047
+					],
+					alpha: .1,
+					hex: "#0c0c0d"
+				}
+			},
+			"300": {
+				$type: "color",
+				$value: {
+					colorSpace: "srgb",
+					components: [
+						.047,
+						.047,
+						.047
+					],
+					alpha: .2,
+					hex: "#0c0c0d"
+				}
+			},
+			"400": {
+				$type: "color",
+				$value: {
+					colorSpace: "srgb",
+					components: [
+						.047,
+						.047,
+						.047
+					],
+					alpha: .34,
+					hex: "#0c0c04"
+				}
+			},
+			"500": {
+				$type: "color",
+				$value: {
+					colorSpace: "srgb",
+					components: [
+						.047,
+						.047,
+						.047
+					],
+					alpha: .7,
+					hex: "#0c0c0d"
+				}
+			},
+			"600": {
+				$type: "color",
+				$value: {
+					colorSpace: "srgb",
+					components: [
+						.047,
+						.047,
+						.047
+					],
+					alpha: .8,
+					hex: "#0c0c0d"
+				}
+			},
+			"700": {
+				$type: "color",
+				$value: {
+					colorSpace: "srgb",
+					components: [
+						.047,
+						.047,
+						.047
+					],
+					alpha: .85,
+					hex: "#0c0c0d"
+				}
+			},
+			"800": {
+				$type: "color",
+				$value: {
+					colorSpace: "srgb",
+					components: [
+						.047,
+						.047,
+						.047
+					],
+					alpha: .9,
+					hex: "#0c0c0d"
+				}
+			},
+			"900": {
+				$type: "color",
+				$value: {
+					colorSpace: "srgb",
+					components: [
+						.047,
+						.047,
+						.047
+					],
+					alpha: .95,
+					hex: "#0c0c0d"
+				}
+			},
+			"1000": {
+				$type: "color",
+				$value: {
+					colorSpace: "srgb",
+					components: [
+						.047,
+						.047,
+						.047
+					],
+					alpha: 0,
+					hex: "#0c0c0d"
+				}
+			}
+		}
+	},
+	border: {
+		$description: "Border tokens",
+		default: {
+			type: "border",
+			$value: {
+				color: "{color.black.900}",
+				style: "solid",
+				width: {
+					value: 1,
+					unit: "px"
+				}
+			}
+		}
+	},
+	radius: {
+		$description: "Corner radius tokens",
+		"100": { $value: {
+			value: .25,
+			unit: "rem"
+		} }
+	},
+	space: {
+		$description: "Dimension tokens",
+		"100": { $value: {
+			value: .25,
+			unit: "rem"
+		} }
+	},
+	typography: {
+		$description: "Typography tokens",
+		body: {
+			$type: "typography",
+			$value: {
+				fontFamily: "{typography.family.sans}",
+				fontSize: "{typography.scale.03}",
+				fontWeight: "{typography.weight.regular}",
+				letterSpacing: {
+					value: 0,
+					unit: "em"
+				},
+				lineHeight: 1
+			}
+		}
+	}
+};
 
 //#endregion
 //#region src/lab.ts
@@ -625,7 +1418,7 @@ async function labCmd({ config, logger }) {
 	/** TODO: handle multiple files */
 	const [tokenFileUrl] = config.tokens;
 	const staticFiles = /* @__PURE__ */ new Set();
-	const dirEntries = await readdir(fileURLToPath(import.meta.resolve("./lab")), {
+	const dirEntries = await fs$1.readdir(fileURLToPath(import.meta.resolve("./lab")), {
 		withFileTypes: true,
 		recursive: true
 	});
@@ -639,18 +1432,18 @@ async function labCmd({ config, logger }) {
 		overrideGlobalObjects: false,
 		async fetch(request) {
 			const pathname = new URL(request.url).pathname;
-			if (pathname === "/") return new Response(Readable.toWeb(createReadStream(fileURLToPath(import.meta.resolve("./lab/index.html")))), { headers: { "Content-Type": "text/html" } });
+			if (pathname === "/") return new Response(Readable.toWeb(fs.createReadStream(fileURLToPath(import.meta.resolve("./lab/index.html")))), { headers: { "Content-Type": "text/html" } });
 			if (pathname === "/api/tokens") {
-				if (request.method === "GET") return new Response(Readable.toWeb(createReadStream(tokenFileUrl)), { headers: {
+				if (request.method === "GET") return new Response(Readable.toWeb(fs.createReadStream(tokenFileUrl)), { headers: {
 					"Content-Type": "application/json",
 					"Cache-Control": "no-cache"
 				} });
 				else if (request.method === "POST" && request.body) {
-					await request.body.pipeTo(Writable.toWeb(createWriteStream(tokenFileUrl)));
+					await request.body.pipeTo(Writable.toWeb(fs.createWriteStream(tokenFileUrl)));
 					return new Response(JSON.stringify({ success: true }), { headers: { "Content-Type": "application/json" } });
 				}
 			}
-			if (staticFiles.has(pathname)) return new Response(Readable.toWeb(createReadStream(fileURLToPath(import.meta.resolve(`./lab${pathname}`)))), { headers: { "Content-Type": mime.getType(pathname) ?? "application/octet-stream" } });
+			if (staticFiles.has(pathname)) return new Response(Readable.toWeb(fs.createReadStream(fileURLToPath(import.meta.resolve(`./lab${pathname}`)))), { headers: { "Content-Type": mime.getType(pathname) ?? "application/octet-stream" } });
 			return new Response("Not found", { status: 404 });
 		}
 	}, (info) => {
@@ -807,5 +1600,5 @@ function defineConfig(config) {
 }
 
 //#endregion
-export { DEFAULT_CONFIG_PATH, DEFAULT_TOKENS_PATH, GREEN_CHECK, buildCmd, checkCmd, cwd, defineConfig, helpCmd, initCmd, labCmd, loadConfig, loadTokens, normalizeCmd, printError, printSuccess, resolveConfig, resolveTokenPath, time, versionCmd, writeFiles };
+export { DEFAULT_CONFIG_PATH, DEFAULT_TOKENS_PATH, GREEN_CHECK, buildCmd, checkCmd, cwd, defineConfig, helpCmd, importCmd, importFromFigma, initCmd, isFigmaPath, labCmd, loadConfig, loadTokens, normalizeCmd, printError, printSuccess, resolveConfig, resolveTokenPath, time, versionCmd, writeFiles };
 //# sourceMappingURL=index.js.map