dispersa 0.4.3 → 1.0.0

package/dist/index.js

@@ -3,6 +3,10 @@ import addFormats from 'ajv-formats';
 import { constants } from 'fs';
 import { mkdir, writeFile, access, readFile } from 'fs/promises';
 import * as path from 'path';
+import { isAbsolute, resolve } from 'path';
+import { createRequire } from 'module';
+import process2 from 'process';
+import { createJiti } from 'jiti';
 import { JsonPointer } from 'json-ptr';
 import { kebabCase } from 'change-case';
 import { converter, formatHex8, formatHex } from 'culori';
@@ -19,7 +23,7 @@ var __export = (target, all) => {
 };
 
 // src/shared/errors/index.ts
-var DispersaError, TokenReferenceError, CircularReferenceError, ValidationError, FileOperationError, ConfigurationError, BasePermutationError, ModifierError;
+var DispersaError, TokenReferenceError, CircularReferenceError, ValidationError, FileOperationError, ConfigurationError, BasePermutationError, ModifierError, LintError;
 var init_errors = __esm({
   "src/shared/errors/index.ts"() {
     DispersaError = class extends Error {
@@ -102,23 +106,19 @@ var init_errors = __esm({
         this.name = "ModifierError";
       }
     };
+    LintError = class extends DispersaError {
+      constructor(issues) {
+        const errorCount = issues.filter((i) => i.severity === "error").length;
+        const warningCount = issues.filter((i) => i.severity === "warn").length;
+        super(`Lint failed with ${errorCount} error(s) and ${warningCount} warning(s).`);
+        this.issues = issues;
+        this.name = "LintError";
+      }
+    };
   }
 });
 
 // src/shared/utils/token-utils.ts
-function formatDeprecationMessage(token, description = "", format = "bracket") {
-  if (token.$deprecated == null || token.$deprecated === false) {
-    return description;
-  }
-  const deprecationMsg = typeof token.$deprecated === "string" ? token.$deprecated : "";
-  if (format === "comment") {
-    const msg2 = deprecationMsg ? ` ${deprecationMsg}` : "";
-    return `DEPRECATED${msg2}`;
-  }
-  const msg = deprecationMsg ? `: ${deprecationMsg}` : "";
-  const prefix = `[DEPRECATED${msg}]`;
-  return description ? `${prefix} ${description}` : prefix;
-}
 function stripInternalTokenMetadata(tokens) {
   const cleaned = {};
   for (const [name, token] of Object.entries(tokens)) {
@@ -2472,7 +2472,7 @@ var init_schemas = __esm({
 });
 
 // src/validation/config-schemas.ts
-var resolverSchemaRef, basePluginProperties, commonRendererOptionsProperties, transformPluginSchema, rendererPluginSchema, filterPluginSchema, preprocessorPluginSchema, outputConfigSchema, dispersaOptionsSchema, buildConfigSchema;
+var resolverSchemaRef, basePluginProperties, commonRendererOptionsProperties, transformPluginSchema, rendererPluginSchema, filterPluginSchema, preprocessorPluginSchema, lintConfigSchema, outputConfigSchema, dispersaOptionsSchema, buildConfigSchema;
 var init_config_schemas = __esm({
   "src/validation/config-schemas.ts"() {
     init_schemas();
@@ -2623,6 +2623,42 @@ var init_config_schemas = __esm({
         }
       }
     };
+    lintConfigSchema = {
+      $schema: "http://json-schema.org/draft-07/schema#",
+      type: "object",
+      properties: {
+        enabled: {
+          type: "boolean",
+          description: "Enable linting (default: false, opt-in)"
+        },
+        failOnError: {
+          type: "boolean",
+          description: "Fail build on lint errors (default: true)"
+        },
+        plugins: {
+          type: "object",
+          description: "Plugins to load (by object or module path string)",
+          additionalProperties: {
+            oneOf: [{ type: "string" }, { type: "object" }]
+          }
+        },
+        rules: {
+          type: "object",
+          description: "Rule configurations",
+          additionalProperties: {
+            oneOf: [
+              { type: "string", enum: ["off", "warn", "error"] },
+              {
+                type: "array",
+                minItems: 2,
+                items: [{ type: "string", enum: ["off", "warn", "error"] }, { type: "object" }]
+              }
+            ]
+          }
+        }
+      },
+      additionalProperties: false
+    };
     outputConfigSchema = {
       $schema: "http://json-schema.org/draft-07/schema#",
       type: "object",
@@ -2740,10 +2776,20 @@ var init_config_schemas = __esm({
           description: "Resolver configuration - file path or ResolverDocument object"
         },
         buildPath: { type: "string" },
+        validation: {
+          type: "object",
+          properties: {
+            mode: { type: "string", enum: ["error", "warn", "off"] }
+          }
+        },
         hooks: {
           type: "object",
           description: "Global build lifecycle hooks (functions, validated at runtime)",
           additionalProperties: true
+        },
+        lint: {
+          ...lintConfigSchema,
+          description: "Linting configuration"
         }
       },
       additionalProperties: false
@@ -3503,6 +3549,94 @@ var init_utils = __esm({
   }
 });
 
+// src/renderers/metadata.ts
+function sanitizeText(text, format) {
+  switch (format) {
+    case "css":
+    case "tailwind":
+      return text.replace(/\*\//g, "*\\/").replace(/\r?\n/g, " ").trim();
+    case "kotlin":
+      return text.replace(/\*\//g, "* /").replace(/\r?\n/g, " ").trim();
+    case "js":
+    case "swift":
+      return text.replace(/\r?\n/g, " ").trim();
+    default:
+      return text.trim();
+  }
+}
+function buildDeprecationText(token) {
+  if (token.$deprecated == null || token.$deprecated === false) {
+    return "";
+  }
+  const msg = typeof token.$deprecated === "string" ? token.$deprecated : "";
+  return msg ? `DEPRECATED: ${msg}` : "DEPRECATED";
+}
+function buildTokenDescriptionComment(token, format) {
+  if (!token.$description || token.$description === "") {
+    return void 0;
+  }
+  const text = sanitizeText(token.$description, format);
+  switch (format) {
+    case "css":
+    case "tailwind":
+      return `/* ${text} */`;
+    case "js":
+      return `// ${text}`;
+    case "swift":
+      return `/// ${text}`;
+    case "kotlin":
+      return `/** ${text} */`;
+    default:
+      return void 0;
+  }
+}
+function buildTokenDeprecationComment(token, format) {
+  const text = buildDeprecationText(token);
+  if (!text) {
+    return void 0;
+  }
+  switch (format) {
+    case "css":
+    case "tailwind":
+      return `/* ${text} */`;
+    case "js":
+      return `// ${text}`;
+    case "swift":
+      return `/// ${text}`;
+    case "kotlin":
+      return `/** ${text} */`;
+    default:
+      return void 0;
+  }
+}
+function buildModifierComment(modifier, context) {
+  return `/* Modifier: ${modifier}=${context} */`;
+}
+function buildSwiftDeprecationAttribute(token) {
+  if (token.$deprecated == null || token.$deprecated === false) {
+    return void 0;
+  }
+  const msg = typeof token.$deprecated === "string" ? token.$deprecated : "";
+  if (msg) {
+    return `@available(*, deprecated, message: "${sanitizeText(msg, "swift")}")`;
+  }
+  return "@available(*, deprecated)";
+}
+function buildKotlinDeprecationAnnotation(token) {
+  if (token.$deprecated == null || token.$deprecated === false) {
+    return void 0;
+  }
+  const msg = typeof token.$deprecated === "string" ? token.$deprecated : "";
+  if (msg) {
+    return `@Deprecated(message = "${sanitizeText(msg, "kotlin")}")`;
+  }
+  return "@Deprecated";
+}
+var init_metadata = __esm({
+  "src/renderers/metadata.ts"() {
+  }
+});
+
 // src/renderers/bundlers/js.ts
 var js_exports = {};
 __export(js_exports, {
@@ -3607,7 +3741,7 @@ async function bundleAsJsModule(bundleData, resolver, options, formatTokens) {
   }
   const metadata = buildMetadata(resolver);
   const jsBlocks = [];
-  for (const { tokens, modifierInputs } of bundleData) {
+  for (const { tokens, modifierInputs, isBase } of bundleData) {
     const cleanTokens = stripInternalMetadata(tokens);
     const key = buildStableDashKey({
       modifierInputs,
@@ -3615,10 +3749,30 @@ async function bundleAsJsModule(bundleData, resolver, options, formatTokens) {
       defaults: metadata.defaults
     });
     const camelKey = toCamelKey(key);
+    const normalizedInputs = normalizeModifierInputs(modifierInputs);
+    const modifierParts = [];
+    for (const dim of metadata.dimensions) {
+      const value = normalizedInputs[dim.toLowerCase()];
+      if (value) {
+        modifierParts.push(`${dim}=${value}`);
+      }
+    }
     const formattedJs = await formatTokens(cleanTokens);
     const tokenObject = extractObjectFromJsModule(formattedJs);
     const indentedObject = tokenObject.replace(/\n/g, "\n  ");
-    jsBlocks.push(`  // ${key}
+    let comment;
+    if (modifierParts.length > 0) {
+      const modifierPart = modifierParts[0];
+      const eqIndex = modifierPart.indexOf("=");
+      const modifier = modifierPart.slice(0, eqIndex);
+      const context = modifierPart.slice(eqIndex + 1);
+      comment = buildModifierComment(modifier, context);
+    } else if (isBase) {
+      comment = "// Base permutation";
+    } else {
+      comment = `// ${key}`;
+    }
+    jsBlocks.push(`  ${comment}
   ${JSON.stringify(camelKey)}: ${indentedObject}`);
   }
   return assembleJsBundle(metadata, jsBlocks, options?.generateHelper ?? false);
@@ -3626,6 +3780,7 @@ async function bundleAsJsModule(bundleData, resolver, options, formatTokens) {
 var init_js = __esm({
   "src/renderers/bundlers/js.ts"() {
     init_errors();
+    init_metadata();
     init_utils();
   }
 });
@@ -3995,7 +4150,8 @@ var BuildOrchestrator = class {
         resolver,
         config.transforms,
         config.preprocessors,
-        config.filters
+        config.filters,
+        config.lint
       );
       return this.executeBuild(buildPath, config, permutations2, resolver);
     }
@@ -4006,7 +4162,8 @@ var BuildOrchestrator = class {
           modifierInputs,
           config.transforms,
           config.preprocessors,
-          config.filters
+          config.filters,
+          config.lint
         );
         return { tokens, modifierInputs: resolvedInputs };
       })
@@ -4267,7 +4424,358 @@ var OutputProcessor = class {
 
 // src/build/pipeline/token-pipeline.ts
 init_resolver_loader();
-init_validation_handler();
+
+// src/lint/plugin-loader.ts
+init_errors();
+var PluginLoader = class {
+  cwd;
+  jiti = null;
+  cache = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.cwd = options.cwd ?? process2.cwd();
+  }
+  /**
+   * Load a plugin from an inline object or module path
+   *
+   * @param source - Plugin object or module path string
+   * @returns Loaded plugin
+   * @throws {ConfigurationError} If plugin cannot be loaded or is invalid
+   */
+  async load(source) {
+    if (this.isPluginObject(source)) {
+      this.validatePlugin(source);
+      return source;
+    }
+    const modulePath = source;
+    const cached = this.cache.get(modulePath);
+    if (cached) {
+      return cached;
+    }
+    const plugin = await this.loadFromModule(modulePath);
+    this.validatePlugin(plugin);
+    this.cache.set(modulePath, plugin);
+    return plugin;
+  }
+  /**
+   * Load multiple plugins
+   *
+   * @param plugins - Record of namespace to plugin source
+   * @returns Record of namespace to loaded plugin
+   */
+  async loadAll(plugins) {
+    const entries = Object.entries(plugins);
+    const loaded = await Promise.all(
+      entries.map(async ([namespace, source]) => [namespace, await this.load(source)])
+    );
+    return Object.fromEntries(loaded);
+  }
+  /**
+   * Check if source is an inline plugin object
+   */
+  isPluginObject(source) {
+    return typeof source !== "string";
+  }
+  /**
+   * Load a plugin from a module path
+   */
+  async loadFromModule(modulePath) {
+    const resolvedPath = isAbsolute(modulePath) ? modulePath : resolve(this.cwd, modulePath);
+    const isFilePath = modulePath.startsWith("./") || modulePath.startsWith("../") || isAbsolute(modulePath);
+    try {
+      if (isFilePath) {
+        return await this.loadFromFile(resolvedPath);
+      }
+      return await this.loadFromPackage(modulePath);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ConfigurationError(`Failed to load lint plugin '${modulePath}': ${message}`);
+    }
+  }
+  /**
+   * Load a plugin from a file path using jiti (supports TypeScript)
+   */
+  async loadFromFile(filePath) {
+    this.jiti ??= createJiti(this.cwd, {
+      interopDefault: true
+    });
+    const loaded = await this.jiti(filePath);
+    const plugin = this.extractPlugin(loaded);
+    if (!plugin) {
+      throw new ConfigurationError(`Plugin file '${filePath}' does not export a valid LintPlugin`);
+    }
+    return plugin;
+  }
+  /**
+   * Load a plugin from a package name
+   */
+  async loadFromPackage(packageName) {
+    const require2 = createRequire(this.cwd);
+    let resolvedPath;
+    try {
+      resolvedPath = require2.resolve(packageName, { paths: [this.cwd] });
+    } catch {
+      try {
+        resolvedPath = require2.resolve(packageName);
+      } catch {
+        throw new ConfigurationError(
+          `Cannot find package '${packageName}'. Make sure it is installed.`
+        );
+      }
+    }
+    this.jiti ??= createJiti(this.cwd, {
+      interopDefault: true
+    });
+    const loaded = await this.jiti(resolvedPath);
+    const plugin = this.extractPlugin(loaded);
+    if (!plugin) {
+      throw new ConfigurationError(`Package '${packageName}' does not export a valid LintPlugin`);
+    }
+    return plugin;
+  }
+  /**
+   * Extract plugin from loaded module
+   *
+   * Supports multiple export patterns:
+   * - export default plugin
+   * - export const plugin = {...}
+   * - module.exports = plugin (CJS)
+   */
+  extractPlugin(loaded) {
+    if (!loaded || typeof loaded !== "object") {
+      return null;
+    }
+    const module = loaded;
+    if (module.default && this.isValidPluginStructure(module.default)) {
+      return module.default;
+    }
+    if (module.plugin && this.isValidPluginStructure(module.plugin)) {
+      return module.plugin;
+    }
+    if (this.isValidPluginStructure(loaded)) {
+      return loaded;
+    }
+    return null;
+  }
+  /**
+   * Check if object has required plugin structure
+   */
+  isValidPluginStructure(obj) {
+    if (!obj || typeof obj !== "object") {
+      return false;
+    }
+    const plugin = obj;
+    const rules = plugin.rules;
+    if (plugin.meta === void 0 || typeof plugin.meta !== "object" || !plugin.meta.name || rules === void 0 || Object.keys(rules).length === 0) {
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Validate a loaded plugin
+   */
+  validatePlugin(plugin) {
+    if (!plugin.meta) {
+      throw new ConfigurationError("Lint plugin must have a meta property with name");
+    }
+    if (!plugin.meta.name) {
+      throw new ConfigurationError("Lint plugin meta.name is required");
+    }
+    if (!plugin.rules || typeof plugin.rules !== "object" || Object.keys(plugin.rules).length === 0) {
+      throw new ConfigurationError(
+        `Lint plugin '${plugin.meta.name}' must have a non-empty rules object`
+      );
+    }
+    for (const [ruleName, rule] of Object.entries(plugin.rules)) {
+      if (!rule.meta) {
+        throw new ConfigurationError(
+          `Rule '${ruleName}' in plugin '${plugin.meta.name}' is missing meta property`
+        );
+      }
+      if (!rule.meta.messages || typeof rule.meta.messages !== "object") {
+        throw new ConfigurationError(
+          `Rule '${ruleName}' in plugin '${plugin.meta.name}' is missing meta.messages`
+        );
+      }
+      if (typeof rule.create !== "function") {
+        throw new ConfigurationError(
+          `Rule '${ruleName}' in plugin '${plugin.meta.name}' is missing create function`
+        );
+      }
+    }
+  }
+  /**
+   * Clear the plugin cache
+   */
+  clearCache() {
+    this.cache.clear();
+  }
+};
+
+// src/lint/lint-runner.ts
+var LintRunner = class {
+  config;
+  pluginLoader;
+  resolvedConfig = null;
+  warn;
+  constructor(config) {
+    this.config = config;
+    this.pluginLoader = new PluginLoader();
+    this.warn = config.onWarn ?? console.warn;
+  }
+  /**
+   * Run all configured rules against the provided tokens
+   *
+   * Rules are executed in parallel for performance. Issues are collected
+   * and returned with counts by severity.
+   *
+   * @param tokens - Resolved tokens to lint
+   * @returns Lint result with issues and counts
+   */
+  async run(tokens) {
+    this.resolvedConfig ??= await this.resolveConfig();
+    const { rules, plugins } = this.resolvedConfig;
+    const issues = [];
+    if (Object.keys(rules).length === 0) {
+      return { issues: [], errorCount: 0, warningCount: 0 };
+    }
+    const rulePromises = Object.entries(rules).map(async ([ruleId, ruleConfig]) => {
+      const { severity, options } = ruleConfig;
+      const rule = this.resolveRule(ruleId, plugins);
+      if (!rule) {
+        this.warn(`[lint] Unknown rule '${ruleId}' - no plugin provides this rule`);
+        return [];
+      }
+      const reports = [];
+      const applicableTokens = this.filterTokensByAppliesTo(tokens, rule.meta.appliesTo);
+      const mergedOptions = rule.defaultOptions ? { ...rule.defaultOptions, ...options } : options;
+      const context = {
+        id: ruleId,
+        options: mergedOptions,
+        tokens: applicableTokens,
+        report: (descriptor) => {
+          reports.push(descriptor);
+        }
+      };
+      try {
+        await rule.create(context);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return [
+          {
+            ruleId: "lint/rule-error",
+            severity: "error",
+            message: `Rule '${ruleId}' failed: ${message}`,
+            tokenName: "(rule execution)",
+            tokenPath: []
+          }
+        ];
+      }
+      return reports.map((report) => {
+        const messageTemplate = rule.meta.messages[report.messageId];
+        const message = messageTemplate ? this.interpolateMessage(messageTemplate, report.data) : report.messageId;
+        return {
+          ruleId,
+          severity,
+          message,
+          tokenName: report.token.name,
+          tokenPath: report.token.path
+        };
+      });
+    });
+    const allIssues = await Promise.all(rulePromises);
+    issues.push(...allIssues.flat());
+    const errorCount = issues.filter((i) => i.severity === "error").length;
+    const warningCount = issues.filter((i) => i.severity === "warn").length;
+    return { issues, errorCount, warningCount };
+  }
+  /**
+   * Resolve configuration: load plugins, parse rule configs
+   */
+  async resolveConfig() {
+    const { plugins: pluginSources = {}, rules: ruleConfigs = {} } = this.config;
+    const plugins = await this.pluginLoader.loadAll(pluginSources);
+    const rules = {};
+    for (const [ruleId, config] of Object.entries(ruleConfigs)) {
+      const resolved = this.resolveRuleConfig(config);
+      if (resolved) {
+        rules[ruleId] = resolved;
+      }
+    }
+    return {
+      enabled: true,
+      failOnError: this.config.failOnError ?? true,
+      plugins,
+      rules
+    };
+  }
+  filterTokensByAppliesTo(tokens, appliesTo) {
+    if (!appliesTo || appliesTo === "all") {
+      return tokens;
+    }
+    const filtered = {};
+    for (const [name, token] of Object.entries(tokens)) {
+      if (token.$type && appliesTo.includes(token.$type)) {
+        filtered[name] = token;
+      }
+    }
+    return filtered;
+  }
+  /**
+   * Parse rule configuration into resolved format
+   */
+  resolveRuleConfig(config) {
+    if (typeof config === "string") {
+      if (config === "off") {
+        return null;
+      }
+      return { severity: config, options: {} };
+    }
+    const [severity, options = {}] = config;
+    if (severity === "off") {
+      return null;
+    }
+    return { severity, options };
+  }
+  /**
+   * Resolve a rule from plugins by rule ID
+   *
+   * Rule IDs are formatted as 'namespace/rule-name'
+   */
+  resolveRule(ruleId, plugins) {
+    const separatorIndex = ruleId.indexOf("/");
+    if (separatorIndex === -1) {
+      return null;
+    }
+    const namespace = ruleId.slice(0, separatorIndex);
+    const ruleName = ruleId.slice(separatorIndex + 1);
+    const plugin = plugins[namespace];
+    if (!plugin) {
+      return null;
+    }
+    return plugin.rules[ruleName] ?? null;
+  }
+  /**
+   * Interpolate message template with data
+   *
+   * Replaces {{key}} placeholders with values from data
+   */
+  interpolateMessage(template, data) {
+    if (!data) {
+      return template;
+    }
+    return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+      const value = data[key];
+      return value !== void 0 ? String(value) : `{{${key}}}`;
+    });
+  }
+  /**
+   * Clear the plugin cache
+   */
+  clearCache() {
+    this.pluginLoader.clearCache();
+    this.resolvedConfig = null;
+  }
+};
 
 // src/shared/constants.ts
 var DEFAULT_MAX_ALIAS_DEPTH = 10;
@@ -5462,6 +5970,10 @@ var ResolutionEngine = class {
     return typeof obj === "object" && obj !== null && "contexts" in obj && typeof obj.contexts === "object";
   }
 };
+
+// src/build/pipeline/token-pipeline.ts
+init_errors();
+init_validation_handler();
 init_errors();
 
 // src/shared/utils/path-utils.ts
@@ -5954,6 +6466,8 @@ var TokenPipeline = class {
   resolverLoader;
   tokenParser;
   aliasResolver;
+  lintRunner = null;
+  lintConfigCache = null;
   constructor(options = {}) {
     this.options = options;
     this.validationHandler = new ValidationHandler(options.validation);
@@ -5973,8 +6487,9 @@ var TokenPipeline = class {
    * 6. Parse and flatten token structure
    * 7. Resolve alias references
    * 8. Strip $root from token names/paths (DTCG structural mechanism, transparent in output)
-   * 9. Apply filters (if provided) — runs first to remove tokens before transforms
-   * 10. Apply transforms (if provided) — runs on the already-filtered token set
+   * 9. Run lint rules (if enabled)
+   * 10. Apply filters (if provided) — runs first to remove tokens before transforms
+   * 11. Apply transforms (if provided) — runs on the already-filtered token set
    *
    * Each stage is explicitly typed to ensure correct order and prevent temporal coupling.
    *
@@ -5983,9 +6498,11 @@ var TokenPipeline = class {
    * @param transformList - Optional transforms to apply
    * @param preprocessorList - Optional preprocessors to apply
    * @param filterList - Optional filters to apply before transforms
-   * @returns Final tokens and resolution engine
+   * @param lintConfig - Optional lint configuration for this run
+   * @returns Final tokens, resolution engine, and lint result
    */
-  async resolve(resolver, modifierInputs, transformList, preprocessorList, filterList) {
+  async resolve(resolver, modifierInputs, transformList, preprocessorList, filterList, lintConfig) {
+    const effectiveLintConfig = lintConfig ?? this.options.lint;
     const stage1 = await this.loadResolver(resolver);
     const engine = this.createEngine(stage1);
     const result = await this.runPipelineStages(
@@ -5993,29 +6510,32 @@ var TokenPipeline = class {
       modifierInputs,
       preprocessorList,
       filterList,
-      transformList
+      transformList,
+      effectiveLintConfig
     );
     return {
       tokens: result.tokens,
       resolutionEngine: result.resolutionEngine,
-      modifierInputs: result.modifierInputs
+      modifierInputs: result.modifierInputs,
+      lintResult: result.lintResult
     };
   }
   /**
-   * Run pipeline stages 3-9 on a pre-created engine
+   * Run pipeline stages 3-11 on a pre-created engine
    *
    * Shared by both `resolve()` (single permutation) and
    * `resolveAllPermutations()` (parallel permutations) to keep the
    * stage sequence defined in exactly one place.
    */
-  async runPipelineStages(engine, modifierInputs, preprocessorList, filterList, transformList) {
+  async runPipelineStages(engine, modifierInputs, preprocessorList, filterList, transformList, lintConfig) {
     const rawTokens = await this.resolveTokens(engine, modifierInputs);
     const preprocessed = await this.preprocessTokens(rawTokens, preprocessorList);
     const refResolved = await this.resolveReferences(preprocessed);
     const flattened = this.flattenTokens(refResolved);
     const aliasResolved = this.resolveAliases(flattened);
     const rootStripped = this.stripRootTokenNames(aliasResolved);
-    const filtered = this.applyFilterStage(rootStripped, filterList);
+    const linted = await this.runLintStage(rootStripped, lintConfig);
+    const filtered = this.applyFilterStage(linted, filterList);
     return this.applyTransformStage(filtered, transformList);
   }
   /**
@@ -6128,6 +6648,47 @@ var TokenPipeline = class {
     }
     return { ...stage, aliasResolvedTokens: result };
   }
+  /**
+   * Stage 9: Run lint rules against tokens
+   *
+   * Linting runs after alias resolution and $root stripping but before
+   * filters and transforms. This ensures rules see the full token set
+   * with resolved values.
+   */
+  async runLintStage(stage, lintConfig) {
+    if (!lintConfig?.enabled) {
+      return stage;
+    }
+    if (!this.lintRunner || !this.isLintConfigEqual(this.lintConfigCache, lintConfig)) {
+      this.lintRunner = new LintRunner({
+        plugins: lintConfig.plugins,
+        rules: lintConfig.rules,
+        onWarn: (msg) => this.validationHandler.warn(msg)
+      });
+      this.lintConfigCache = lintConfig;
+    }
+    const lintResult = await this.lintRunner.run(stage.aliasResolvedTokens);
+    if (lintResult.errorCount > 0 && lintConfig.failOnError !== false) {
+      throw new LintError(lintResult.issues);
+    }
+    for (const issue of lintResult.issues.filter((i) => i.severity === "warn")) {
+      this.validationHandler.warn(
+        `[${issue.ruleId}] ${issue.message} (token: ${issue.tokenName})`
+      );
+    }
+    return { ...stage, lintResult };
+  }
+  isLintConfigEqual(a, b) {
+    if (!a || !b) return false;
+    if (a.enabled !== b.enabled) return false;
+    if (a.failOnError !== b.failOnError) return false;
+    if (a.plugins !== b.plugins) return false;
+    if (a.rules !== b.rules) return false;
+    return true;
+  }
+  /**
+   * Stage 10: Apply filters to the linted token set
+   */
   applyFilterStage(stage, filterList) {
     let tokens = stage.aliasResolvedTokens;
     if (filterList !== void 0 && filterList.length > 0) {
@@ -6136,7 +6697,7 @@ var TokenPipeline = class {
     return { ...stage, aliasResolvedTokens: tokens };
   }
   /**
-   * Stage 9: Apply transforms to the filtered token set
+   * Stage 11: Apply transforms to the filtered token set
    */
   applyTransformStage(stage, transformList) {
     let tokens = stage.aliasResolvedTokens;
@@ -6170,8 +6731,10 @@ var TokenPipeline = class {
    * @param transformList - Optional transforms to apply
    * @param preprocessorList - Optional preprocessors to apply
    * @param filterList - Optional filters to apply before transforms
+   * @param lintConfig - Optional lint configuration for this run
    */
-  async resolveAllPermutations(resolver, transformList, preprocessorList, filterList) {
+  async resolveAllPermutations(resolver, transformList, preprocessorList, filterList, lintConfig) {
+    const effectiveLintConfig = lintConfig ?? this.options.lint;
     const stage1 = await this.loadResolver(resolver);
     const discoveryEngine = this.createEngine(stage1);
     const permutationInputs = discoveryEngine.resolutionEngine.generatePermutations();
@@ -6184,11 +6747,13 @@ var TokenPipeline = class {
           modifierInputs,
           preprocessorList,
           filterList,
-          transformList
+          transformList,
+          effectiveLintConfig
         );
         return {
           tokens: result.tokens,
-          modifierInputs: result.modifierInputs
+          modifierInputs: result.modifierInputs,
+          lintResult: result.lintResult
         };
       })
     );
@@ -6209,286 +6774,106 @@ var TokenPipeline = class {
 init_errors();
 init_token_utils();
 init_validator();
-var Dispersa = class {
-  validator;
-  pipeline;
-  outputProcessor;
-  orchestrator;
-  options;
-  /**
-   * Creates a new Dispersa instance
-   *
-   * @param options - Configuration options (optional, can be empty object)
-   * @param options.resolver - Default resolver (file path or inline object, optional if provided at build time)
-   * @param options.buildPath - Default output directory for generated files (omit for in-memory mode)
-   * @throws {ConfigurationError} If options are invalid and validation is enabled
-   */
-  constructor(options = {}) {
-    this.options = options;
-    this.validator = new SchemaValidator();
-    const errors = this.validator.validateDispersaOptions(options);
-    if (errors.length > 0) {
-      throw new ConfigurationError(
-        `Invalid Dispersa options: ${this.validator.getErrorMessage(errors)}`
-      );
-    }
-    this.pipeline = new TokenPipeline({ validation: options.validation });
-    this.outputProcessor = new OutputProcessor();
-    this.orchestrator = new BuildOrchestrator(this.pipeline, this.outputProcessor);
-  }
-  /**
-   * Builds design tokens from a resolver configuration
-   *
-   * Processes tokens through the resolution pipeline, applies preprocessors,
-   * transforms, and filters, then generates output files in multiple formats
-   * for specified outputs.
-   *
-   * **Runtime Validation:**
-   * This method validates the build configuration
-   * and all output configurations before processing, throwing helpful errors for
-   * invalid inputs.
-   *
-   * **Permutation Handling:**
-   * - If `config.permutations` is provided and non-empty, builds those specific permutations
-   * - If `config.permutations` is undefined or empty, auto-discovers all permutations from resolver
-   *
-   * @param config - Build configuration
-   * @param config.resolver - Resolver configuration (file path or inline object, optional if set in constructor)
-   * @param config.outputs - Array of output configurations (renderers, transforms, filters)
-   * @param config.buildPath - Output directory for generated files (omit for in-memory mode, optional if set in constructor)
-   * @param config.transforms - Global transforms to apply to all tokens
-   * @param config.preprocessors - Global preprocessors to apply before parsing
-   * @param config.permutations - Array of modifier inputs for generating variations
-   * @returns Build result with success status and generated output files
-   * @throws {ConfigurationError} If configuration is invalid
-   * @throws {FileOperationError} If file operations fail
-   *
-   * @example Basic build
-   * ```typescript
-   * const dispersa = new Dispersa({
-   *   resolver: './tokens.resolver.json',
-   *   buildPath: './output'
-   * })
-   *
-   * const result = await dispersa.build({
-   *   outputs: [
-   *     css({
-   *       name: 'css',
-   *       file: 'tokens.css',
-   *       preset: 'bundle',
-   *       selector: ':root',
-   *       transforms: [nameKebabCase()]
-   *     })
-   *   ]
-   * })
-   * ```
-   *
-   * @example With filters and multiple presets
-   * ```typescript
-   * const result = await dispersa.build({
-   *   resolver: './tokens.resolver.json',
-   *   outputs: [
-   *     css({
-   *       name: 'css',
-   *       file: 'tokens.css',
-   *       preset: 'bundle',
-   *       selector: ':root',  // All themes in one file
-   *       transforms: [nameKebabCase()]
-   *     }),
-   *     json({
-   *       name: 'json',
-   *       file: 'tokens-{theme}.json',  // Separate file per theme
-   *       preset: 'standalone',
-   *       structure: 'flat'
-   *     })
-   *   ],
-   *   buildPath: './output',
-   *   permutations: [
-   *     { theme: 'light' },
-   *     { theme: 'dark' }
-   *   ]
-   * })
-   * ```
-   */
-  async build(config) {
-    try {
-      return await this.buildOrThrow(config);
-    } catch (error) {
-      return {
-        success: false,
-        outputs: [],
-        errors: [toBuildError(error)]
-      };
-    }
-  }
-  /**
-   * Builds design tokens and throws on any failure.
-   *
-   * Unlike {@link build}, which catches errors and returns them inside
-   * `BuildResult.errors`, this method propagates the first error as an
-   * exception. Use it when you want fail-fast behavior in CLI or CI workflows.
-   *
-   * @param config - Build configuration specifying resolver, outputs, transforms, etc.
-   * @returns A successful `BuildResult` (never contains errors)
-   * @throws {ConfigurationError} When the build config or resolver is invalid
-   * @throws {DispersaError} When token resolution, transforms, or rendering fails
-   *
-   * @example
-   * ```typescript
-   * try {
-   *   const result = await dispersa.buildOrThrow({
-   *     resolver: './tokens.resolver.json',
-   *     outputs: [css({ name: 'css', file: 'tokens.css' })],
-   *     buildPath: './output',
-   *   })
-   * } catch (error) {
-   *   process.exit(1)
-   * }
-   * ```
-   */
-  async buildOrThrow(config) {
-    const configErrors = this.validator.validateBuildConfig(config);
-    if (configErrors.length > 0) {
-      throw new ConfigurationError(
-        `Invalid build configuration: ${this.validator.getErrorMessage(configErrors)}`
-      );
-    }
-    for (const output of config.outputs) {
-      const outputErrors = this.validator.validateOutputConfig(output);
-      if (outputErrors.length > 0) {
-        throw new ConfigurationError(
-          `Invalid output '${output.name}': ${this.validator.getErrorMessage(outputErrors)}`
-        );
-      }
-    }
-    const { resolver, buildPath } = this.resolveConfig(config);
-    return this.orchestrator.build(resolver, buildPath, config);
+function createValidator() {
+  return new SchemaValidator();
+}
+function createPipeline(options) {
+  return new TokenPipeline({ validation: options?.validation });
+}
+function createOutputProcessor() {
+  return new OutputProcessor();
+}
+function createOrchestrator(pipeline, outputProcessor) {
+  return new BuildOrchestrator(pipeline, outputProcessor);
+}
+function resolveConfig(config, options) {
+  const resolver = config.resolver ?? options?.resolver;
+  const buildPath = config.buildPath ?? options?.buildPath ?? "";
+  if (!resolver) {
+    throw new ConfigurationError("resolver is required in build config");
   }
-  /**
-   * Builds tokens for a single permutation with all configured outputs
-   *
-   * Convenience wrapper around `build()` that forces a single permutation.
-   * This means it has the same runtime validation and error semantics as `build()`:
-   * it returns a `BuildResult` object rather than throwing (use `buildOrThrow()` if you
-   * want fail-fast behavior).
-   *
-   * @param config - Build configuration
-   * @param modifierInputs - Modifier values (e.g., `{ theme: 'dark' }`)
-   * @returns Build result (success, outputs, optional errors)
-   */
-  async buildPermutation(config, modifierInputs = {}) {
-    return await this.build({
-      ...config,
-      permutations: [modifierInputs]
-    });
+  return { resolver, buildPath };
+}
+function validateBuildConfig(validator, config) {
+  const configErrors = validator.validateBuildConfig(config);
+  if (configErrors.length > 0) {
+    throw new ConfigurationError(
+      `Invalid build configuration: ${validator.getErrorMessage(configErrors)}`
+    );
   }
-  /**
-   * Resolve configuration with constructor defaults
-   */
-  resolveConfig(config) {
-    const resolver = config.resolver ?? this.options.resolver;
-    const buildPath = config.buildPath ?? this.options.buildPath ?? "";
-    if (!resolver) {
+  for (const output of config.outputs) {
+    const outputErrors = validator.validateOutputConfig(output);
+    if (outputErrors.length > 0) {
       throw new ConfigurationError(
-        "resolver must be provided either in constructor options or build config"
+        `Invalid output '${output.name}': ${validator.getErrorMessage(outputErrors)}`
       );
     }
-    return { resolver, buildPath };
   }
-  /**
-   * Resolves tokens for a specific permutation without generating output files
-   *
-   * Useful for programmatic access to resolved token values, testing,
-   * or implementing custom output logic. Returns fully resolved tokens
-   * with all references and aliases resolved.
-   *
-   * @param resolver - Resolver configuration (file path or inline object)
-   * @param modifierInputs - Modifier values for this permutation (e.g., `{ theme: 'dark' }`)
-   * @returns Object mapping token names to resolved token objects
-   * @throws {FileOperationError} If resolver file cannot be read
-   * @throws {TokenReferenceError} If token references cannot be resolved (when validate is enabled)
-   *
-   * @example
-   * ```typescript
-   * const tokens = await dispersa.resolveTokens(
-   *   './tokens.resolver.json',
-   *   { theme: 'dark' }
-   * )
-   *
-   * console.log(tokens['color.background'].$value) // '#1a1a1a'
-   * ```
-   */
-  async resolveTokens(resolver, modifierInputs = {}) {
-    const { tokens } = await this.pipeline.resolve(resolver, modifierInputs);
-    return stripInternalTokenMetadata(tokens);
-  }
-  /**
-   * Resolves tokens for all permutations defined in the resolver
-   *
-   * Auto-discovers all possible permutations from the resolver's modifier
-   * definitions and resolves tokens for each one. Useful for generating
-   * comprehensive token sets or validating all theme variations.
-   *
-   * @param resolver - Resolver configuration (file path or inline object)
-   * @returns Array of resolved token sets with their modifier inputs
-   * @throws {FileOperationError} If resolver file cannot be read
-   * @throws {TokenReferenceError} If token references cannot be resolved (when validate is enabled)
-   *
-   * @example
-   * ```typescript
-   * const permutations = await dispersa.resolveAllPermutations(
-   *   './tokens.resolver.json'
-   * )
-   *
-   * permutations.forEach(({ tokens, modifierInputs }) => {
-   *   console.log(`Theme: ${modifierInputs.theme}`)
-   *   console.log(`Tokens: ${Object.keys(tokens).length}`)
-   * })
-   * ```
-   */
-  async resolveAllPermutations(resolver) {
-    const permutations = await this.pipeline.resolveAllPermutations(resolver);
-    return permutations.map(({ tokens, modifierInputs }) => ({
-      tokens: stripInternalTokenMetadata(tokens),
-      modifierInputs
-    }));
+}
+async function resolvePipeline(pipeline, resolver, modifierInputs) {
+  const { tokens } = await pipeline.resolve(resolver, modifierInputs);
+  return stripInternalTokenMetadata(tokens);
+}
+async function build(config) {
+  try {
+    return await buildOrThrow(config);
+  } catch (error) {
+    return {
+      success: false,
+      outputs: [],
+      errors: [toBuildError(error)]
+    };
   }
-  /**
-   * Generates TypeScript type definitions from resolved tokens
-   *
-   * Creates a `.d.ts` file with type-safe token definitions including:
-   * - Token name union type for autocomplete
-   * - Token value types
-   * - Nested structure types matching token organization
-   *
-   * @param tokens - Resolved tokens object
-   * @param fileName - Path for the generated `.d.ts` file
-   * @param options - Generation options
-   * @param options.moduleName - Name for the exported types (default: 'Tokens')
-   * @returns Promise that resolves when file is written
-   * @throws {FileOperationError} If file cannot be written
-   *
-   * @example
-   * ```typescript
-   * const tokens = await dispersa.resolveTokens('./tokens.resolver.json')
-   * await dispersa.generateTypes(tokens, './src/tokens.d.ts', {
-   *   moduleName: 'DesignTokens'
-   * })
-   *
-   * // Generated types can be used like:
-   * // const tokenName: TokenName = 'color.background'
-   * // const tokens: DesignTokens = { ... }
-   * ```
-   */
-  async generateTypes(tokens, fileName, options) {
-    const typeWriter = new TypeWriter();
-    await typeWriter.write(tokens, {
-      fileName,
-      moduleName: options?.moduleName ?? "Tokens",
-      includeValues: true
-    });
+}
+async function buildOrThrow(config) {
+  const validator = createValidator();
+  validateBuildConfig(validator, config);
+  const { resolver, buildPath } = resolveConfig(config);
+  const pipeline = createPipeline({ validation: config.validation });
+  const outputProcessor = createOutputProcessor();
+  const orchestrator = createOrchestrator(pipeline, outputProcessor);
+  return orchestrator.build(resolver, buildPath, config);
+}
+async function buildPermutation(config, modifierInputs = {}) {
+  return build({
+    ...config,
+    permutations: [modifierInputs]
+  });
+}
+async function resolveTokens(resolver, modifierInputs = {}, validation) {
+  const pipeline = createPipeline({ validation });
+  return resolvePipeline(pipeline, resolver, modifierInputs);
+}
+async function lint(options) {
+  const { resolver, modifierInputs = {}, validation, ...lintConfig } = options;
+  const pipeline = createPipeline({ validation });
+  const tokens = await resolvePipeline(pipeline, resolver, modifierInputs);
+  const runner = new LintRunner({
+    ...lintConfig,
+    failOnError: lintConfig.failOnError ?? true
+  });
+  const result = await runner.run(tokens);
+  if (result.errorCount > 0 && lintConfig.failOnError !== false) {
+    throw new LintError(result.issues);
   }
-};
+  return result;
+}
+async function resolveAllPermutations(resolver) {
+  const pipeline = createPipeline();
+  const permutations = await pipeline.resolveAllPermutations(resolver);
+  return permutations.map(({ tokens, modifierInputs }) => ({
+    tokens: stripInternalTokenMetadata(tokens),
+    modifierInputs
+  }));
+}
+async function generateTypes(tokens, fileName, options) {
+  const typeWriter = new TypeWriter();
+  await typeWriter.write(tokens, {
+    fileName,
+    moduleName: options?.moduleName ?? "Tokens",
+    includeValues: true
+  });
+}
 
 // src/tokens/types.ts
 function isColorToken(token) {
@@ -6603,6 +6988,7 @@ function durationObjectToString(duration) {
 init_errors();
 init_token_utils();
 init_utils();
+init_metadata();
 var toSRGB = converter("rgb");
 var toP3 = converter("p3");
 var KOTLIN_KEYWORDS = /* @__PURE__ */ new Set([
@@ -6653,9 +7039,6 @@ function resolveColorFormat(format) {
 function escapeKotlinString(str) {
   return str.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\$/g, "\\$");
 }
-function escapeKDoc(str) {
-  return str.replace(/\*\//g, "* /").replace(/\r?\n/g, " ").trim();
-}
 function formatKotlinNumber(value) {
   return Number.isInteger(value) ? `${value}.0` : String(value);
 }
@@ -6787,8 +7170,13 @@ var AndroidRenderer = class {
         const kotlinName = this.buildFlatKotlinName(token);
         const kotlinValue = this.formatKotlinValue(token, options, baseDepth + 1);
         const annotation = this.typeAnnotationSuffix(token);
-        if (token.$description) {
-          lines.push(`${valIndent}/** ${escapeKDoc(token.$description)} */`);
+        const descriptionComment = buildTokenDescriptionComment(token, "kotlin");
+        if (descriptionComment) {
+          lines.push(`${valIndent}${descriptionComment}`);
+        }
+        const deprecation = buildKotlinDeprecationAnnotation(token);
+        if (deprecation) {
+          lines.push(`${valIndent}${deprecation}`);
         }
         lines.push(
           `${valIndent}${options.visPrefix}val ${kotlinName}${annotation} = ${kotlinValue}`
@@ -6824,8 +7212,13 @@ var AndroidRenderer = class {
     const kotlinName = toSafeIdentifier(key, KOTLIN_KEYWORDS, false);
     const kotlinValue = this.formatKotlinValue(token, options, depth);
     const annotation = this.typeAnnotationSuffix(token);
-    if (token.$description) {
-      lines.push(`${pad}/** ${escapeKDoc(token.$description)} */`);
+    const descriptionComment = buildTokenDescriptionComment(token, "kotlin");
+    if (descriptionComment) {
+      lines.push(`${pad}${descriptionComment}`);
+    }
+    const deprecation = buildKotlinDeprecationAnnotation(token);
+    if (deprecation) {
+      lines.push(`${pad}${deprecation}`);
     }
     lines.push(`${pad}${options.visPrefix}val ${kotlinName}${annotation} = ${kotlinValue}`);
   }
@@ -7602,10 +7995,8 @@ function stableInputsKey(modifierInputs) {
 
 // src/renderers/css.ts
 init_utils();
+init_metadata();
 var CssRenderer = class _CssRenderer {
-  sanitizeCssCommentText(text) {
-    return text.replace(/\*\//g, "*\\/").replace(/\r?\n/g, " ").trim();
-  }
   async format(context, options) {
     const opts = {
       preset: options?.preset ?? "bundle",
@@ -7685,12 +8076,13 @@ var CssRenderer = class _CssRenderer {
   }
   pushTokenLines(lines, token, tokens, referenceTokens, preserveReferences, indent, newline, space) {
     const entries = this.buildCssEntries(token, tokens, referenceTokens, preserveReferences);
-    if (token.$deprecated != null && token.$deprecated !== false) {
-      const deprecationMsg = formatDeprecationMessage(token, "", "comment");
-      lines.push(`${indent}/* ${this.sanitizeCssCommentText(deprecationMsg)} */${newline}`);
+    const deprecationComment = buildTokenDeprecationComment(token, "css");
+    if (deprecationComment) {
+      lines.push(`${indent}${deprecationComment}${newline}`);
     }
-    if (token.$description && token.$description !== "") {
-      lines.push(`${indent}/* ${this.sanitizeCssCommentText(token.$description)} */${newline}`);
+    const descriptionComment = buildTokenDescriptionComment(token, "css");
+    if (descriptionComment) {
+      lines.push(`${indent}${descriptionComment}${newline}`);
     }
     for (const entry of entries) {
       lines.push(`${indent}--${entry.name}:${space}${entry.value};${newline}`);
@@ -8330,6 +8722,7 @@ function cssRenderer() {
 
 // src/renderers/ios.ts
 init_utils();
+init_metadata();
 var toSRGB2 = converter("rgb");
 var toP32 = converter("p3");
 var SWIFT_TYPE_GROUP_MAP = {
@@ -8473,9 +8866,13 @@ var IosRenderer = class {
       const swiftValue = this.formatSwiftValue(token, options);
       const typeAnnotation = this.getTypeAnnotation(token);
       const annotation = typeAnnotation ? `: ${typeAnnotation}` : "";
-      const docComment = this.buildDocComment(token, indent);
+      const docComment = buildTokenDescriptionComment(token, "swift");
       if (docComment) {
-        lines.push(docComment);
+        lines.push(`${indent}${docComment}`);
+      }
+      const deprecationAttr = buildSwiftDeprecationAttribute(token);
+      if (deprecationAttr) {
+        lines.push(`${indent}${deprecationAttr}`);
       }
       lines.push(`${indent}${access3} ${staticPrefix}${swiftName}${annotation} = ${swiftValue}`);
     }
@@ -8490,15 +8887,6 @@ var IosRenderer = class {
     }
     return Array.from(imports).sort();
   }
-  /**
-   * Builds a `///` doc comment from a token's `$description`, if present.
-   */
-  buildDocComment(token, indent) {
-    if (!token.$description) {
-      return void 0;
-    }
-    return `${indent}/// ${token.$description}`;
-  }
   /**
    * Builds a qualified Swift name from a token's path, preserving parent
    * hierarchy segments to avoid duplicate identifiers.
@@ -8889,6 +9277,7 @@ function iosRenderer() {
 // src/renderers/js-module.ts
 init_utils();
 init_token_utils();
+init_metadata();
 var JsModuleRenderer = class {
   async format(context, options) {
     const opts = {
@@ -8926,17 +9315,10 @@ var JsModuleRenderer = class {
     return outputTree(files);
   }
   async formatTokens(tokens, options) {
-    const opts = {
-      preset: options.preset ?? "standalone",
-      structure: options.structure ?? "nested",
-      minify: options.minify ?? false,
-      moduleName: options.moduleName ?? "tokens",
-      generateHelper: options.generateHelper ?? false
-    };
     const lines = [];
-    lines.push(...this.formatAsObject(tokens, opts));
+    lines.push(...this.formatAsObject(tokens, options));
     const code = lines.join("\n");
-    if (opts.minify) {
+    if (options.minify) {
       return code;
     }
     return await prettier.format(code, {
@@ -8949,20 +9331,53 @@ var JsModuleRenderer = class {
       trailingComma: "es5"
     });
   }
-  /**
-   * Format as default export object
-   */
   formatAsObject(tokens, options) {
     const lines = [];
-    const tokenObj = this.tokensToPlainObject(tokens, options.structure);
+    const tokenMap = this.buildTokenMap(tokens);
     const varName = options.moduleName !== "" ? options.moduleName : "tokens";
-    lines.push(`const ${varName} = {`);
-    this.addObjectProperties(lines, tokenObj, 1);
-    lines.push("}");
+    if (options.structure === "flat") {
+      lines.push(`const ${varName} = {`);
+      this.addFlatProperties(lines, tokens, 1);
+      lines.push("}");
+    } else {
+      lines.push(`const ${varName} = {`);
+      const tokenObj = this.tokensToPlainObject(tokens, "nested");
+      this.addNestedProperties(lines, tokenObj, tokenMap, 1);
+      lines.push("}");
+    }
     lines.push("");
     lines.push(`export default ${varName}`);
     return lines;
   }
+  buildTokenMap(tokens) {
+    const map = /* @__PURE__ */ new Map();
+    for (const [name, token] of Object.entries(tokens)) {
+      map.set(name, token);
+    }
+    return map;
+  }
+  addFlatProperties(lines, tokens, indent) {
+    const indentStr2 = "  ".repeat(indent);
+    const sortedEntries = getSortedTokenEntries(tokens);
+    for (let i = 0; i < sortedEntries.length; i++) {
+      const [name, token] = sortedEntries[i];
+      const isLast = i === sortedEntries.length - 1;
+      this.pushTokenComments(lines, token, indentStr2);
+      lines.push(
+        `${indentStr2}${this.quoteKey(name)}: ${JSON.stringify(token.$value)}${isLast ? "" : ","}`
+      );
+    }
+  }
+  pushTokenComments(lines, token, indent) {
+    const deprecationComment = buildTokenDeprecationComment(token, "js");
+    if (deprecationComment) {
+      lines.push(`${indent}${deprecationComment}`);
+    }
+    const descriptionComment = buildTokenDescriptionComment(token, "js");
+    if (descriptionComment) {
+      lines.push(`${indent}${descriptionComment}`);
+    }
+  }
   tokensToPlainObject(tokens, structure) {
     if (structure === "nested") {
       return buildNestedTokenObject(tokens, (token) => token.$value);
@@ -8973,7 +9388,7 @@ var JsModuleRenderer = class {
     }
     return result;
   }
-  addObjectProperties(lines, obj, indent) {
+  addNestedProperties(lines, obj, tokenMap, indent) {
     const indentStr2 = "  ".repeat(indent);
     const entries = Object.entries(obj).sort(([keyA], [keyB]) => keyA.localeCompare(keyB));
     for (let i = 0; i < entries.length; i++) {
@@ -8985,19 +9400,20 @@ var JsModuleRenderer = class {
       const isLast = i === entries.length - 1;
       const isNestedObject = typeof value === "object" && value !== null && !Array.isArray(value);
       if (!isNestedObject) {
+        const token = tokenMap.get(key);
+        if (token) {
+          this.pushTokenComments(lines, token, indentStr2);
+        }
         lines.push(
           `${indentStr2}${this.quoteKey(key)}: ${JSON.stringify(value)}${isLast ? "" : ","}`
         );
         continue;
       }
       lines.push(`${indentStr2}${this.quoteKey(key)}: {`);
-      this.addObjectProperties(lines, value, indent + 1);
+      this.addNestedProperties(lines, value, tokenMap, indent + 1);
       lines.push(`${indentStr2}}${isLast ? "" : ","}`);
     }
   }
-  /**
-   * Quote key if necessary
-   */
   quoteKey(key) {
     if (/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key)) {
       return key;
@@ -9233,6 +9649,7 @@ function resolveOptions(options) {
 
 // src/renderers/tailwind.ts
 init_utils();
+init_metadata();
 var TAILWIND_NAMESPACE_MAP = {
   color: "color",
   dimension: "spacing",
@@ -9286,6 +9703,14 @@ var TailwindRenderer = class {
     for (const [, token] of getSortedTokenEntries(tokens)) {
       const varName = this.buildVariableName(token);
       const varValue = this.formatValue(token);
+      const deprecationComment = buildTokenDeprecationComment(token, "tailwind");
+      if (deprecationComment) {
+        lines.push(`${indent}${deprecationComment}${newline}`);
+      }
+      const descriptionComment = buildTokenDescriptionComment(token, "tailwind");
+      if (descriptionComment) {
+        lines.push(`${indent}${descriptionComment}${newline}`);
+      }
       lines.push(`${indent}--${varName}:${space}${varValue};${newline}`);
     }
     lines.push(`}${newline}`);
@@ -9312,6 +9737,14 @@ var TailwindRenderer = class {
     for (const [, token] of getSortedTokenEntries(tokens)) {
       const varName = this.buildVariableName(token);
       const varValue = this.formatValue(token);
+      const deprecationComment = buildTokenDeprecationComment(token, "tailwind");
+      if (deprecationComment) {
+        lines.push(`${tokenIndent}${deprecationComment}${newline}`);
+      }
+      const descriptionComment = buildTokenDescriptionComment(token, "tailwind");
+      if (descriptionComment) {
+        lines.push(`${tokenIndent}${descriptionComment}${newline}`);
+      }
       lines.push(`${tokenIndent}--${varName}:${space}${varValue};${newline}`);
     }
     if (hasMediaQuery) {
@@ -9584,12 +10017,19 @@ init_errors();
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/**
+ * @license MIT
+ * Copyright (c) 2025-present Dispersa
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 /**
  * @license
  * Copyright (c) 2025 Dispersa Contributors
  * SPDX-License-Identifier: MIT
  */
 
-export { BasePermutationError, CircularReferenceError, ConfigurationError, Dispersa, DispersaError, FileOperationError, ModifierError, TokenReferenceError, ValidationError, android, css, defineRenderer, ios, isBorderToken, isColorToken, isDimensionToken, isDurationToken, isGradientToken, isOutputTree, isShadowToken, isTransitionToken, isTypographyToken, js, json, outputTree, tailwind };
+export { BasePermutationError, CircularReferenceError, ConfigurationError, DispersaError, FileOperationError, LintError, ModifierError, TokenReferenceError, ValidationError, android, build, buildOrThrow, buildPermutation, css, defineRenderer, generateTypes, ios, isBorderToken, isColorToken, isDimensionToken, isDurationToken, isGradientToken, isOutputTree, isShadowToken, isTransitionToken, isTypographyToken, js, json, lint, outputTree, resolveAllPermutations, resolveTokens, tailwind };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map