unholy-design-tokens 1.0.0

package/src/type-declarations/type-declarations.formatter.ts

@@ -0,0 +1,122 @@
+import StyleDictionary from 'style-dictionary'
+import type { Format } from 'style-dictionary/types'
+
+/**
+ * Generates a TypeScript interface declaration for all design tokens.
+ *
+ * @type {{ name: string; format: ({ dictionary }: FormatFnArguments) => string; }}
+ *
+ * Will return:
+ * export interface YThemeToken {
+ *   tokenName1: string;
+ *   tokenName2: string;
+ *   ...
+ * }
+ */
+StyleDictionary.registerFormat({
+  name: 'typescript/types-declaration',
+  format: function ({ dictionary }) {
+    const props = dictionary.tokens
+    console.log('📟 - props → ', props)
+    // const types = props.map((token) => `  '${token.name}': string;`).join("\n");
+
+    // return `export interface YThemeToken {\n${types}\n}\n`;
+  },
+})
+
+/**
+ * Generates a TypeScript interface declaration for all design tokens.
+ *
+ * Will return:
+ * export interface YThemeToken {
+ *   tokenName1: string;
+ *   tokenName2: string;
+ *   ...
+ * }
+ *
+ * where tokenName is the name of the token e.g. 'color-primary-100'
+ */
+export const tokensDeclarationFormatter: Format = {
+  name: 'typescript/tokens-declaration',
+  format: function ({ dictionary }) {
+    const myMap = dictionary.tokenMap
+    let types = ''
+    for (const value of myMap.values()) {
+      const name = value.name
+      types += `  '${name}': string;\n`
+    }
+
+    return `export interface YThemeToken {\n${types}\n}\n`
+  },
+}
+
+/**
+ * @type {{ name: string; format: ({ dictionary }: FormatFnArguments) => string; }}
+ *
+ * Will return:
+ * export interface DesignTokens {
+ *   border: {
+ *     width: {
+ *       base: string;
+ *       scale: string;
+ *     };
+ *   };
+ *   ...
+ * }
+ */
+export const typesDeclarationFormatter: Format = {
+  name: 'typescript/types-declaration',
+  format: function ({ dictionary }) {
+    const interfaceBody = generateNestedInterface(dictionary.tokens, 1)
+    return `/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+export interface DesignTokens {
+${interfaceBody}}
+`
+  },
+}
+
+/**
+ * Check if an object is a leaf token (has $value or value property)
+ */
+function isToken(obj: Record<string, unknown>): boolean {
+  return obj && typeof obj === 'object' && ('$value' in obj || 'value' in obj)
+}
+
+/**
+ * Escape property name if it contains special characters
+ */
+function formatKey(key: string): string {
+  // If key starts with a number or contains special chars, quote it
+  if (/^[0-9]/.test(key) || /[^a-zA-Z0-9_$]/.test(key)) {
+    return `'${key}'`
+  }
+  return key
+}
+
+/**
+ * Recursively generate nested interface from token tree
+ */
+function generateNestedInterface(obj: Record<string, unknown>, depth = 0): string {
+  const indent = '  '.repeat(depth)
+  let result = ''
+
+  for (const key of Object.keys(obj)) {
+    const value = obj[key]
+
+    if (isToken(value as Record<string, unknown>)) {
+      // Leaf token - output as string type
+      result += `${indent}${formatKey(key)}: string;\n`
+    } else if (typeof value === 'object' && value !== null) {
+      // Nested object - recurse
+      const nested = generateNestedInterface(value as Record<string, unknown>, depth + 1)
+      if (nested.trim()) {
+        result += `${indent}${formatKey(key)}: {\n${nested}${indent}};\n`
+      }
+    }
+  }
+
+  return result
+}

package/src/utils/helpers.ts

@@ -0,0 +1,11 @@
+export function capitalizeFirstLetter(string: string): string {
+  return string.charAt(0).toUpperCase() + string.slice(1);
+}
+
+export function toKebab(s: string | number): string {
+  return String(s)
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/[_.]/g, "-")
+
+    .toLowerCase();
+}

package/src/utils/index.ts

@@ -0,0 +1,4 @@
+export * from './helpers'
+export * from './template'
+export * from './tokens'
+export * from './utopia'

package/src/utils/template.ts

@@ -0,0 +1,110 @@
+/**
+ * Utility functions for template generation.
+ * https://styledictionary.com/reference/hooks/formats/#using-a-template--templating-engine-to-create-a-format
+ */
+import { capitalizeFirstLetter } from "./helpers.js";
+
+export {
+  generateHeader,
+  generateSubheader,
+  formatInLayer,
+  generateFigmaHeaderReference,
+};
+
+const startComment = "/* ";
+const endComment = " */";
+const headerLength = 60;
+const subheaderLength = 20;
+const separatorChar = "-";
+const headerSeparator = " ";
+
+function generateSeparator(length: number): string {
+  return `${startComment}${separatorChar.repeat(length)}${endComment}`;
+}
+
+/**
+ * Will generate a comment block like this:
+/* ------------------------------------------------------------ *\/
+/*                            Title                             *\/
+/* ------------------------------------------------------------ *\/
+ *
+ */
+function generateCommentBlock(title: string, totalLength: number, separatorChar: string, indent = ""): string {
+  let titleTotalLength = totalLength - title.length;
+  let halfLength = Math.floor(titleTotalLength / 2);
+  let titleSeparator = headerSeparator.repeat(halfLength);
+
+  if (totalLength % 2 !== 0) {
+    titleSeparator += separatorChar;
+  }
+
+  return (
+    `\n${indent}${generateSeparator(totalLength)}` +
+    `\n${indent}${startComment}${titleSeparator}${title}${titleSeparator}${endComment}` +
+    `\n${indent}${generateSeparator(totalLength)}\n`
+  );
+}
+
+/**
+ * Generates a header comment block for a given header string.
+ * /* ------------------------------------------------------------ *\/
+ * /*                            Header                            *\/
+ * /* ------------------------------------------------------------ *\/
+ */
+function generateHeader(header: string): string {
+  if (!header) return "";
+
+  return generateCommentBlock(
+    capitalizeFirstLetter(header),
+    headerLength,
+    separatorChar,
+    "",
+  );
+}
+
+/**
+ * Generates a subheader comment block for a given subheader string.
+ * /* ---------------------- \/*
+ * /*       Subheader        *\/
+ * /* ---------------------- *\/
+ */
+function generateSubheader(subheader: string): string {
+  if (!subheader) return "";
+
+  return generateCommentBlock(
+    capitalizeFirstLetter(subheader),
+    subheaderLength,
+    separatorChar,
+    "  ",
+  );
+}
+
+/**
+ * Formats content within a CSS layer block.
+ * @layer name {
+ *   :root {
+ *     --variable: value;
+ *   }
+ * }
+ */
+function formatInLayer(name: string, content: string): string {
+  let result = `@layer ${name} {`;
+  result += `\n`;
+  result += `  :root {`;
+  result += `\n`;
+  result += `${content}`;
+  result += `  }\n`;
+  result += `}\n`;
+  return result;
+}
+
+/**
+ * Generates a Figma header reference comment block
+ * /* Collection name: <collectionName> *\/
+ * /* Mode: <mode> *\/
+ *
+ * See https://www.figma.com/community/plugin/1470777269812001046/css-variables-import-export
+ */
+function generateFigmaHeaderReference(collectionName: string, mode = "Light"): string {
+  return `/* Collection name: ${collectionName} */\n/* Mode: ${mode} */`;
+}

package/src/utils/tokens.ts

@@ -0,0 +1,95 @@
+import { Dictionary, Token } from 'style-dictionary'
+import { LocalOptions, TransformedToken } from 'style-dictionary/types'
+import { getReferences, usesReferences } from 'style-dictionary/utils'
+import { toKebab } from './helpers.js'
+
+interface RefToken extends TransformedToken {
+  ref?: string[]
+}
+
+export function tokenName(token: Token) {
+  const attrs = token.attributes
+  const path = attrs?.item ? [attrs.category, attrs.type, attrs.item] : token.path
+  return path.join('-')
+}
+
+// TODO:
+export function resolveTokenReferences(
+  token: Token,
+  options: LocalOptions,
+  dictionary: Dictionary,
+  privateVar = false,
+) {
+  const originalValue = token.original?.value
+  // if (!shouldOutputReferences(token, options, dictionary)) {
+  //   return originalValue != null
+  //     ? cssValue(originalValue)
+  //     : cssValue(token.value);
+  // }
+
+  if (!originalValue) return cssValue(token.value)
+
+  // if (
+  //   (originalValueParsed && originalValueParsed.startsWith("var(--")) ||
+  //   originalValueParsed.startsWith("calc") ||
+  //   originalValueParsed.startsWith("clamp")
+  // ) {
+  //   ("📟 - cssValue(originalValue) → ", cssValue(originalValue));
+  //   return originalValue;
+  // }
+  if (!usesReferences(originalValue)) return cssValue(token.value)
+  if (!shouldOutputReferences(token, options, dictionary)) {
+    return rewriteOriginalRefs(originalValue, dictionary.tokens, privateVar)
+  } else {
+    return cssValue(originalValue)
+  }
+}
+export function refToTokenRefString(ref: RefToken) {
+  // Verify if the ref is a style-dictionary reference object pattern or a direct var(--...) string
+  const refPath = ref.ref ?? ref.path
+  return `{${refPath.join('.')}}`
+}
+
+export function refToCssVar(ref: RefToken, privateVar: boolean) {
+  return `var(--${privateVar ? '_' : ''}${toKebab(ref.name)})`
+}
+
+const cssValue = (v: unknown): string => {
+  if (v == null) return ''
+  if (typeof v === 'string') return v
+  if (typeof v === 'number') return String(v)
+  if (typeof v === 'boolean') return v ? 'true' : 'false'
+  if (Array.isArray(v)) return v.join(',')
+  return JSON.stringify(v)
+}
+
+export function rewriteOriginalRefs(originalValue: unknown, dictionaryTokens: Dictionary['tokens'], privateVar: boolean): string | null {
+  if (typeof originalValue !== 'string' || !usesReferences(originalValue)) return null
+
+  const refs = getReferences(originalValue, dictionaryTokens)
+  let out = originalValue
+
+  for (const ref of refs) {
+    out = out.replaceAll(refToTokenRefString(ref), refToCssVar(ref, privateVar))
+  }
+
+  return out
+}
+
+export function shouldOutputReferences(token: Token, options: LocalOptions, dictionary: Dictionary): boolean {
+  const originalValue = token.original?.value
+  if (!usesReferences(originalValue)) return false
+  const originalValueParsed = cssValue(originalValue)
+  if (
+    (originalValueParsed && originalValueParsed.startsWith('var(--')) ||
+    originalValueParsed.startsWith('calc') ||
+    originalValueParsed.startsWith('clamp')
+  ) {
+    return false
+  }
+
+  const { usesDtcg, outputReferences } = options ?? {}
+  return typeof outputReferences === 'function'
+    ? outputReferences(token as TransformedToken, { dictionary, usesDtcg })
+    : Boolean(outputReferences)
+}

package/src/utils/utopia.ts

@@ -0,0 +1,36 @@
+// src/utils/utopia.js
+
+/**
+ * Generate a Utopia fluid type scale.
+ *
+ * Based on https://utopia.fyi/type/calculator/
+ * by James Gilyead & Trys Mudford
+ */
+
+export function generateUtopiaScale({
+  minViewport = 360,
+  maxViewport = 1280,
+  minFont = 16,
+  maxFont = 20,
+  scaleMin = 1.2,
+  scaleMax = 1.25,
+  steps = [-2, -1, 0, 1, 2, 3, 4],
+} = {}) {
+  const results: Record<number, string> = {};
+
+  steps.forEach((step) => {
+    const minSize = minFont * scaleMin ** step;
+    const maxSize = maxFont * scaleMax ** step;
+
+    const slope = ((maxSize - minSize) / (maxViewport - minViewport)) * 100;
+    const intercept = minSize - (slope / 100) * minViewport;
+
+    const clampValue = `clamp(${minSize / 16}rem, ${
+      intercept / 16
+    }rem + ${slope}vw, ${maxSize / 16}rem)`;
+
+    results[step] = clampValue;
+  });
+
+  return results;
+}