@webitel/styleguide 26.8.3 → 26.8.5

package/src/lib/styleguide/token-generation/script/generate.ts

@@ -0,0 +1,200 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { red } from './console-colors';
+import {
+	buildCssFile,
+	buildIndex,
+	cleanOutputDir,
+	writeFile,
+} from './output/write-css';
+import {
+	collectVariables,
+	groupByFolder,
+	isColorsFolder,
+} from './transform/collect-variables';
+import { slugify } from './transform/slugify';
+import type {
+	Folder,
+	GenerateResult,
+	ThemeConfig,
+	TokenSource,
+	TokenTree,
+	Variable,
+} from './types';
+import { validateCssVarNames } from './validation/css-var-names';
+import { validateThemeParity } from './validation/parity';
+import { validateThemeFile } from './validation/theme-file';
+
+/** Read and JSON-parse a theme's input file, with a clear error if it's missing/invalid. */
+function readThemeRoot(inputDir: string, theme: ThemeConfig): TokenTree | null {
+	const inputPath = path.join(inputDir, theme.file);
+	if (!fs.existsSync(inputPath)) return null;
+
+	let raw: string;
+	try {
+		raw = fs.readFileSync(inputPath, 'utf8');
+	} catch (err) {
+		throw new Error(
+			`Не вдалося прочитати вхідний файл "${inputPath}": ${(err as Error).message}`,
+		);
+	}
+	try {
+		return JSON.parse(raw) as TokenTree;
+	} catch (err) {
+		throw new Error(
+			`Вхідний файл "${inputPath}" містить некоректний JSON: ${(err as Error).message}`,
+		);
+	}
+}
+
+/** Generate the CSS output tree for a single token source (an app or lib/). Reports
+ * validation errors to the console and returns wroteOutput=false if validation failed
+ * or the source produced no variables - the caller decides whether that should stop
+ * the whole run, and uses wroteOutput to know which sources to wire up in the glue
+ * CSS files that import each source's dist/index.css. */
+export function generate(
+	source: TokenSource,
+	themes: ThemeConfig[],
+): GenerateResult {
+	const fail = (): GenerateResult => ({
+		source,
+		succeeded: false,
+		wroteOutput: false,
+	});
+
+	const rootsByTheme: Record<string, TokenTree> = {};
+	for (const theme of themes) {
+		const root = readThemeRoot(source.inputDir, theme);
+		if (root) rootsByTheme[theme.name] = root;
+	}
+
+	const missingThemes = themes.filter((theme) => !(theme.name in rootsByTheme));
+	if (missingThemes.length > 0) {
+		console.error(
+			red(
+				`[${source.label}] Зупинено: відсутні файли тем: ${missingThemes.map((t) => t.file).join(', ')}.`,
+			),
+		);
+		return fail();
+	}
+
+	// Validate each theme file's structure/leaves/references, then cross-theme parity.
+	// Collect every failure across all checks before reporting, so a single run surfaces
+	// everything wrong instead of stopping at the first error.
+	const collectors = themes.map((theme) =>
+		validateThemeFile(
+			rootsByTheme[theme.name],
+			`${source.label}/${theme.file}`,
+		),
+	);
+	collectors.push(validateThemeParity(rootsByTheme));
+
+	const failedCollectors = collectors.filter((c) => c.hasErrors);
+	if (failedCollectors.length > 0) {
+		for (const collector of failedCollectors) collector.report();
+		const totalErrors = failedCollectors.reduce(
+			(sum, c) => sum + c.errors.length,
+			0,
+		);
+		console.error(
+			red(
+				`[${source.label}] Зупинено: знайдено помилок перевірки - ${totalErrors}. Жодного файлу не було записано.`,
+			),
+		);
+		return fail();
+	}
+
+	// theme.name -> Map<folderKey, Folder>
+	const foldersByTheme = new Map<string, Map<string, Folder>>();
+
+	for (const theme of themes) {
+		const root = rootsByTheme[theme.name];
+		const variables: Variable[] = [];
+		collectVariables(root, root, [], variables);
+
+		const varNameCollector = validateCssVarNames(
+			variables,
+			`${source.label}/${theme.file}`,
+		);
+		if (varNameCollector.hasErrors) {
+			varNameCollector.report();
+			console.error(
+				red(
+					`[${source.label}] Зупинено: перевірку назв CSS-змінних не пройдено. Жодного файлу не було записано.`,
+				),
+			);
+			return fail();
+		}
+
+		foldersByTheme.set(theme.name, groupByFolder(variables));
+		console.log(
+			`[${source.label}:${theme.name}] оброблено змінних: ${variables.length}`,
+		);
+	}
+
+	const allFolderKeys = new Set<string>();
+	for (const folders of foldersByTheme.values()) {
+		for (const key of folders.keys()) allFolderKeys.add(key);
+	}
+
+	// All validation passed - safe to wipe the previous output now, so tokens removed
+	// from Figma since the last generation don't linger as stale CSS variables.
+	cleanOutputDir(source.outputDir);
+
+	let flatFileCount = 0;
+	let themeFileCount = 0;
+
+	for (const folderKey of allFolderKeys) {
+		const folderSegments = themes
+			.map(
+				(theme) =>
+					foldersByTheme.get(theme.name)?.get(folderKey)?.folderSegments,
+			)
+			.find((segments): segments is string[] => segments != null);
+		if (!folderSegments) continue;
+		const dirPath = path.join(source.outputDir, ...folderSegments.map(slugify));
+
+		if (isColorsFolder(folderSegments)) {
+			// "Colors" folder: theme-aware, one file per theme.
+			for (const theme of themes) {
+				const folderVariables =
+					foldersByTheme.get(theme.name)?.get(folderKey)?.variables ?? [];
+				if (folderVariables.length === 0) continue;
+				const filePath = path.join(dirPath, theme.name, 'index.css');
+				writeFile(filePath, buildCssFile(theme.selector, folderVariables));
+				themeFileCount += 1;
+			}
+		} else {
+			// Any other folder: theme-invariant, take values from the first theme's export
+			// (arbitrary choice - values are expected to be identical across themes here).
+			const [primaryTheme] = themes;
+			const primaryVariables =
+				foldersByTheme.get(primaryTheme.name)?.get(folderKey)?.variables ?? [];
+			if (primaryVariables.length > 0) {
+				const filePath = path.join(dirPath, 'index.css');
+				writeFile(filePath, buildCssFile(':root', primaryVariables));
+				flatFileCount += 1;
+			}
+		}
+	}
+
+	console.log(
+		`[${source.label}] Записано звичайних файлів index.css: ${flatFileCount}, темозалежних файлів: ${themeFileCount}`,
+	);
+
+	let wroteOutput = false;
+	if (fs.existsSync(source.outputDir)) {
+		wroteOutput = buildIndex(source.outputDir);
+		if (wroteOutput) {
+			console.log(
+				`[${source.label}] Записано dist/index.css (кореневу точку входу)`,
+			);
+		}
+	}
+
+	return {
+		source,
+		succeeded: true,
+		wroteOutput,
+	};
+}

package/src/lib/styleguide/token-generation/script/index.ts

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+
+/**
+ * Converts Figma variable export files (Light.tokens.json / Dark.tokens.json)
+ * into a tree of CSS files mirroring the token folder structure.
+ *
+ * Usage:
+ *   npm run generate:design-tokens
+ *
+ * Input files are discovered under this directory's siblings:
+ *   ../apps/<app-name>/{Light,Dark}.tokens.json  - one source per app
+ *   ../lib/{Light,Dark}.tokens.json               - shared/library tokens
+ *
+ * Each source is generated independently into its own colocated dist/ folder:
+ *   ../apps/<app-name>/dist/...
+ *   ../lib/dist/...
+ *
+ * A folder is theme-aware if it or any ancestor folder is literally named "Colors"
+ * (case-insensitive) - its direct leaf variables are written to light/index.css and
+ * dark/index.css. Every other folder is treated as theme-invariant: its direct leaf
+ * variables are written to a single index.css with plain :root rules, resolved from
+ * the light export (values are expected to be identical across themes there).
+ *
+ * Output per token folder (relative to a source's dist/):
+ *   <Group>/<...path>/index.css              - folders outside any "Colors" ancestor
+ *   <Group>/<...path>/light/index.css         - folders under a "Colors" ancestor, light theme
+ *   <Group>/<...path>/dark/index.css          - "Colors" folders, dark theme
+ */
+
+import path from 'node:path';
+import { checkCssImports } from './check-css-imports';
+import { red } from './console-colors';
+import { discoverSources } from './discover-sources';
+import { generate } from './generate';
+import { writeGlueCss } from './output/write-glue-css';
+import type { GenerateResult, ThemeConfig } from './types';
+
+const TOKEN_GENERATION_ROOT = path.join(__dirname, '..');
+
+const THEMES: ThemeConfig[] = [
+	{
+		name: 'light',
+		file: 'Light.tokens.json',
+		selector: ':root',
+	},
+	{
+		name: 'dark',
+		file: 'Dark.tokens.json',
+		selector: ':root.theme--dark',
+	},
+];
+
+function run(): void {
+	const sources = discoverSources(TOKEN_GENERATION_ROOT, THEMES);
+
+	if (sources.length === 0) {
+		console.error(
+			red(
+				'Зупинено: не знайдено жодного джерела токенів (apps/* або lib/ з файлами тем).',
+			),
+		);
+		process.exit(1);
+	}
+
+	const results: GenerateResult[] = sources.map((source) =>
+		generate(source, THEMES),
+	);
+	const allSucceeded = results.every((r) => r.succeeded);
+
+	// Rewrite the glue CSS files (apps/index.css, lib/index.css, index.css) so they only
+	// ever import sources that actually produced output - even when some sources failed
+	// validation this run, so the ones that succeeded still wire up correctly.
+	writeGlueCss(TOKEN_GENERATION_ROOT, results);
+
+	const importsOk = checkCssImports(TOKEN_GENERATION_ROOT);
+
+	if (!allSucceeded || !importsOk) {
+		process.exit(1);
+	}
+}
+
+run();

package/src/lib/styleguide/token-generation/script/output/write-css.ts

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { Variable } from '../types';
+
+export function buildCssFile(selector: string, variables: Variable[]): string {
+	const lines = variables.map((v) => `  ${v.cssVarName}: ${v.cssValue};`);
+	return `${selector} {\n${lines.join('\n')}\n}\n`;
+}
+
+/** Remove a source's previous output directory (if any), so tokens that were removed
+ * from Figma don't linger as stale CSS variables from a prior generation. */
+export function cleanOutputDir(dirPath: string): void {
+	fs.rmSync(dirPath, {
+		recursive: true,
+		force: true,
+	});
+}
+
+export function writeFile(filePath: string, content: string): void {
+	fs.mkdirSync(path.dirname(filePath), {
+		recursive: true,
+	});
+	fs.writeFileSync(filePath, content, 'utf8');
+}
+
+/**
+ * Recursively builds/extends an index.css in every directory under dirPath so it
+ * imports each subdirectory's index.css. A directory may already have its own
+ * index.css with :root rules (written directly for sizes/light/dark leaf
+ * folders) - in that case, @import lines for its subfolders are prepended before the
+ * existing rules (CSS requires @import to precede other rules to be valid), so a
+ * folder can have both its own variables and nested subfolders (e.g. a "sizes"
+ * bucket for theme-invariant vars that also happens to contain a real "Sizes"
+ * token subgroup).
+ * Returns true if this directory ends up with an index.css.
+ */
+export function buildIndex(dirPath: string): boolean {
+	const entries = fs.readdirSync(dirPath, {
+		withFileTypes: true,
+	});
+	const subdirs = entries
+		.filter((e) => e.isDirectory())
+		.map((e) => e.name)
+		.sort();
+	const ownIndexPath = path.join(dirPath, 'index.css');
+	const ownIndexEntry = entries.find(
+		(e) => e.isFile() && e.name === 'index.css',
+	);
+
+	const childDirsWithIndex = subdirs.filter((name) =>
+		buildIndex(path.join(dirPath, name)),
+	);
+
+	const importLines = childDirsWithIndex.map(
+		(name) => `@import "./${name}/index.css";`,
+	);
+
+	if (ownIndexEntry) {
+		if (importLines.length > 0) {
+			const existing = fs.readFileSync(ownIndexPath, 'utf8');
+			fs.writeFileSync(
+				ownIndexPath,
+				`${importLines.join('\n')}\n${existing.trimStart()}`,
+				'utf8',
+			);
+		}
+		return true;
+	}
+
+	if (importLines.length === 0) return false;
+
+	fs.writeFileSync(ownIndexPath, `${importLines.join('\n')}\n`, 'utf8');
+	return true;
+}

package/src/lib/styleguide/token-generation/script/output/write-glue-css.ts

@@ -0,0 +1,70 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { GenerateResult } from '../types';
+
+/**
+ * (Re)writes the top-level "glue" CSS files that wire generated token output into the
+ * rest of the styleguide build - these are NOT hand-maintained: every run rewrites them
+ * from scratch based on which sources actually produced output, so they can never drift
+ * from what's on disk (e.g. importing a dist/index.css that doesn't exist because that
+ * app's tokens failed validation or were removed).
+ *
+ * Writes, relative to tokenGenerationRoot:
+ *   apps/index.css              - @import for each app that wrote output
+ *   lib/index.css               - @import for lib/dist/index.css, if lib wrote output
+ *   index.css                   - @import for apps/index.css and/or lib/index.css,
+ *                                  whichever actually have content
+ */
+export function writeGlueCss(
+	tokenGenerationRoot: string,
+	results: GenerateResult[],
+): void {
+	const appResults = results.filter(
+		(r) => r.source.kind === 'app' && r.wroteOutput,
+	);
+	const libResult = results.find(
+		(r) => r.source.kind === 'lib' && r.wroteOutput,
+	);
+
+	const appsIndexPath = path.join(tokenGenerationRoot, 'apps', 'index.css');
+	const libIndexPath = path.join(tokenGenerationRoot, 'lib', 'index.css');
+	const rootIndexPath = path.join(tokenGenerationRoot, 'index.css');
+
+	const rootImports: string[] = [];
+
+	if (appResults.length > 0) {
+		const appImportLines = appResults
+			.map((r) => `@import "./${r.source.appName}/dist/index.css";`)
+			.join('\n');
+		writeGlueFile(appsIndexPath, appImportLines);
+		rootImports.push('@import "./apps/index.css";');
+	} else {
+		removeGlueFile(appsIndexPath);
+	}
+
+	if (libResult) {
+		writeGlueFile(libIndexPath, '@import "./dist/index.css";');
+		rootImports.push('@import "./lib/index.css";');
+	} else {
+		removeGlueFile(libIndexPath);
+	}
+
+	if (rootImports.length > 0) {
+		writeGlueFile(rootIndexPath, rootImports.join('\n'));
+	} else {
+		removeGlueFile(rootIndexPath);
+	}
+}
+
+function writeGlueFile(filePath: string, content: string): void {
+	fs.mkdirSync(path.dirname(filePath), {
+		recursive: true,
+	});
+	fs.writeFileSync(filePath, `${content}\n`, 'utf8');
+}
+
+function removeGlueFile(filePath: string): void {
+	fs.rmSync(filePath, {
+		force: true,
+	});
+}

package/src/lib/styleguide/token-generation/script/transform/collect-variables.ts

@@ -0,0 +1,65 @@
+import type { Folder, TokenNode, TokenTree, Variable } from '../types';
+import { formatValue, resolveValue } from './format-value';
+import { slugify, toCssVarName } from './slugify';
+
+/**
+ * Walk the token tree, collecting leaf variables into `out`.
+ * Each top-level group is walked as part of the same tree - callers group the flat
+ * result by folder afterwards (see groupByFolder).
+ */
+export function collectVariables(
+	root: TokenTree,
+	node: TokenNode,
+	pathSegments: string[],
+	out: Variable[],
+): void {
+	if (node && typeof node === 'object' && '$type' in node) {
+		let resolved: ReturnType<typeof resolveValue>;
+		let cssValue: string;
+		try {
+			resolved = resolveValue(root, node);
+			cssValue = formatValue(resolved.type, resolved.value);
+		} catch (err) {
+			throw new Error(
+				`Не вдалося розв'язати токен "${pathSegments.join('.')}": ${(err as Error).message}`,
+			);
+		}
+		out.push({
+			pathSegments: pathSegments.slice(),
+			cssVarName: toCssVarName(pathSegments),
+			type: resolved.type,
+			cssValue,
+		});
+		return;
+	}
+	if (node && typeof node === 'object') {
+		for (const [key, child] of Object.entries(
+			node as Record<string, TokenNode>,
+		)) {
+			if (key.startsWith('$')) continue;
+			collectVariables(root, child, pathSegments.concat(key), out);
+		}
+	}
+}
+
+/** Whether a folder is theme-aware: itself or any ancestor is literally named "Colors". */
+export function isColorsFolder(folderSegments: string[]): boolean {
+	return folderSegments.some((segment) => segment.toLowerCase() === 'colors');
+}
+
+/** Group a flat variable list (single theme) by folder (all path segments except the last). */
+export function groupByFolder(variables: Variable[]): Map<string, Folder> {
+	const folders = new Map<string, Folder>();
+	for (const variable of variables) {
+		const folderSegments = variable.pathSegments.slice(0, -1);
+		const folderKey = folderSegments.map(slugify).join('/');
+		if (!folders.has(folderKey)) {
+			folders.set(folderKey, {
+				folderSegments,
+				variables: [],
+			});
+		}
+		folders.get(folderKey)?.variables.push(variable);
+	}
+	return folders;
+}

package/src/lib/styleguide/token-generation/script/transform/format-value.ts

@@ -0,0 +1,86 @@
+import type {
+	FigmaColorValue,
+	TokenLeaf,
+	TokenNode,
+	TokenTree,
+	TokenType,
+	TokenValue,
+} from '../types';
+import { getNodeByPath, parseRef } from './token-refs';
+
+/** Round a float to a sane precision and format as a px string. */
+export function toPx(value: number): string {
+	const rounded = Math.round(value * 1000) / 1000;
+	return `${rounded}px`;
+}
+
+/** Convert a Figma color object ({colorSpace, components, alpha, hex}) to a hex/hex-alpha string. */
+export function colorToHex(value: TokenValue): string {
+	if (typeof value === 'string') return value;
+	if (
+		value &&
+		typeof value === 'object' &&
+		typeof (value as FigmaColorValue).hex === 'string'
+	) {
+		const colorValue = value as FigmaColorValue;
+		const hex = colorValue.hex;
+		const alpha = typeof colorValue.alpha === 'number' ? colorValue.alpha : 1;
+		if (alpha >= 1) return hex;
+		const alphaHex = Math.round(alpha * 255)
+			.toString(16)
+			.padStart(2, '0');
+		return `${hex}${alphaHex}`;
+	}
+	throw new Error(`Нерозпізнане значення кольору: ${JSON.stringify(value)}`);
+}
+
+export interface ResolvedValue {
+	type: TokenType;
+	value: TokenValue;
+}
+
+/** Resolve a token's final value, following alias chains, and return { type, value }. */
+export function resolveValue(
+	root: TokenTree,
+	node: TokenNode,
+	seenRefs: string[] = [],
+): ResolvedValue {
+	const leaf = node as TokenLeaf;
+	const rawValue = leaf.$value;
+	if (typeof rawValue === 'string') {
+		const refPath = parseRef(rawValue);
+		if (refPath) {
+			const refKey = refPath.join('.');
+			if (seenRefs.includes(refKey)) {
+				throw new Error(
+					`Виявлено циклічне посилання: ${seenRefs.concat(refKey).join(' -> ')}`,
+				);
+			}
+			const target = getNodeByPath(root, refPath);
+			if (!target || typeof target !== 'object' || !('$value' in target)) {
+				throw new Error(
+					`Неможливо розв'язати посилання "${rawValue}" (шлях: ${refPath.join('.')})`,
+				);
+			}
+			return resolveValue(root, target, seenRefs.concat(refKey));
+		}
+	}
+	return {
+		type: leaf.$type as TokenType,
+		value: rawValue,
+	};
+}
+
+/** Format a resolved value according to its $type. */
+export function formatValue(type: TokenType, value: TokenValue): string {
+	switch (type) {
+		case 'color':
+			return colorToHex(value);
+		case 'number':
+			return toPx(value as number);
+		case 'string':
+			return String(value);
+		default:
+			throw new Error(`Непідтримуваний $type токена: ${type}`);
+	}
+}

package/src/lib/styleguide/token-generation/script/transform/slugify.ts

@@ -0,0 +1,16 @@
+/** Convert an arbitrary path segment (may contain spaces/mixed case) to kebab-case. */
+export function slugify(segment: string): string {
+	return String(segment)
+		.trim()
+		.replace(/([a-z0-9])([A-Z])/g, '$1-$2') // camelCase -> camel-Case
+		.replace(/[\s_]+/g, '-')
+		.toLowerCase()
+		.replace(/[^a-z0-9-]/g, '-')
+		.replace(/-+/g, '-')
+		.replace(/^-|-$/g, '');
+}
+
+/** Build the full CSS custom property name from a token path, e.g. ["WT","Buttons","Primary","background"] -> --wt-wt-buttons-primary-background */
+export function toCssVarName(pathSegments: string[]): string {
+	return `--wt-${pathSegments.map(slugify).join('-')}`;
+}

package/src/lib/styleguide/token-generation/script/transform/token-refs.ts

@@ -0,0 +1,21 @@
+import type { TokenNode, TokenTree } from '../types';
+
+/** Parse a Figma alias reference string like "{Border radius.lg}" into its dot-separated path segments. */
+export function parseRef(value: string): string[] | null {
+	const match = /^\{(.+)\}$/.exec(value);
+	if (!match) return null;
+	return match[1].split('.');
+}
+
+/** Look up a token node by its top-level-group path (as produced by parseRef). */
+export function getNodeByPath(
+	root: TokenTree,
+	segments: string[],
+): TokenNode | undefined {
+	let node: TokenNode | undefined = root;
+	for (const segment of segments) {
+		if (node == null || typeof node !== 'object') return undefined;
+		node = (node as Record<string, TokenNode>)[segment];
+	}
+	return node;
+}

package/src/lib/styleguide/token-generation/script/types.ts

@@ -0,0 +1,75 @@
+/** Raw Figma "Design Tokens" export shape (a recursive tree of groups and leaf tokens). */
+export type TokenType = 'color' | 'number' | 'string';
+
+export interface FigmaColorValue {
+	colorSpace?: string;
+	components?: number[];
+	alpha?: number;
+	hex: string;
+}
+
+export type TokenValue =
+	| string
+	| number
+	| FigmaColorValue
+	| Record<string, unknown>;
+
+export interface TokenLeaf {
+	$type: string;
+	$value: TokenValue;
+	$extensions?: Record<string, unknown>;
+}
+
+export type TokenNode =
+	| TokenLeaf
+	| {
+			[key: string]: TokenNode;
+	  }
+	| Record<string, unknown>;
+
+export type TokenTree = Record<string, TokenNode>;
+
+/** One theme variant to generate CSS for (e.g. light/dark). */
+export interface ThemeConfig {
+	name: string;
+	file: string;
+	selector: string;
+}
+
+/** A single source of token files: either an app under apps/<app-name>/ or the shared lib/. */
+export interface TokenSource {
+	/** Human-readable label used in log/error messages, e.g. "apps/agent-workspace-app" or "lib". */
+	label: string;
+	/** Absolute path to the directory containing the theme input files. */
+	inputDir: string;
+	/** Absolute path to the directory the generated CSS tree should be written to. */
+	outputDir: string;
+	/** Whether this source is an app under apps/<app-name>/ or the shared lib/. */
+	kind: 'app' | 'lib';
+	/** The app's directory name, e.g. "agent-workspace-app". Only set when kind is 'app'. */
+	appName?: string;
+}
+
+/** Outcome of generating a single token source. */
+export interface GenerateResult {
+	source: TokenSource;
+	/** Whether validation passed for this source. */
+	succeeded: boolean;
+	/** Whether a dist/index.css entry point was actually written (false if validation
+	 * failed, or if the source produced zero variables). */
+	wroteOutput: boolean;
+}
+
+/** A resolved leaf variable ready to be emitted as a CSS custom property. */
+export interface Variable {
+	pathSegments: string[];
+	cssVarName: string;
+	type: TokenType;
+	cssValue: string;
+}
+
+/** Variables grouped by their containing folder (all path segments except the last). */
+export interface Folder {
+	folderSegments: string[];
+	variables: Variable[];
+}