unholy-design-tokens 1.0.0

package/src/style-dictionary.config.ts

@@ -0,0 +1,151 @@
+import StyleDictionary, { Token } from 'style-dictionary'
+import { formats, transformGroups } from 'style-dictionary/enums'
+// @ts-expect-error - JS module without type declarations
+import { themeConfig } from './theme/index.js'
+import typeDeclarationsConfig from './type-declarations/type-declarations.config.js'
+// import { cubeCssVariablesLayerFormatter } from './cube-css/formatters/cube-css.js';
+import cubeConfig from './cube-css/cube.config.js'
+// @ts-expect-error - JS module without type declarations
+import { spacingFluid } from './formatters/spacing.js'
+// import "./theme/formatters/theme.format.js"; // your file shown above (theme formats)
+
+import colorConfig from './colors/color.config.js'
+// import themeConfig from './theme/theme.config.js';
+
+StyleDictionary.registerFormat(spacingFluid)
+
+function generateThemeFiles(directories: string[]) {
+  const genericAttributes = {
+    format: formats.cssVariables,
+    options: {
+      // outputReferences: true,
+    },
+  }
+  return directories.map((dir) => {
+    return {
+      ...genericAttributes,
+      // output the dironent tokens in the right folder and file e.g. dironents/button/button-vars.css
+      destination: `${dir}/${dir}.css`,
+      format: formats.cssVariables,
+      // only include the tokens that are inside this dironent token group
+      filter: (token: Token) => {
+        return token.path[0] === dir || token.attributes?.type === dir
+      },
+    }
+  })
+}
+
+StyleDictionary.registerFormat({
+  name: 'conditional-css',
+  format: function ({ dictionary }) {
+    let output = `:root {\n`
+    output += dictionary.allTokens
+      .map((token) => {
+        const { type } = token.attributes || {}
+        return `  --${type}: ${token.value};`
+      })
+      .join('\n')
+    output += `\n}\n`
+    return output
+  },
+})
+
+export default {
+  // parser: 'initial-theme-parser',
+  source: ['src/tokens/**/*.json'],
+  // action: ['generate-utopia-typography'],
+  platforms: {
+    css: {
+      transformGroup: transformGroups.css,
+      transforms: [
+        'attribute/cti', // pick up category/type/item
+      ],
+      buildPath: 'css/',
+      clearBuildPath: true,
+      outputReferences: true,
+
+      files: [
+        {
+          destination: 'tokens.css',
+          format: 'css/variables',
+          filter: (token: Token) => {
+            return token.attributes?.category === 'typography'
+          },
+          actions: ['generate-utopia-typography'], // <- here
+          options: {
+            outputReferences: true,
+          },
+        },
+        {
+          destination: 'conditional.css',
+          filter: (token: Token) => token.attributes?.category === 'conditional',
+          format: 'conditional-css',
+          transformGroup: 'css',
+          options: {
+            outputReferences: true,
+          },
+        },
+        ...themeConfig,
+        {
+          destination: 'space.css',
+          // format: "css/spacing-fluid",
+          format: formats.cssVariables,
+          filter: (token: Token) => {
+            return token.attributes?.category === 'space' || token.attributes?.type === 'space'
+          },
+          options: {
+            outputReferences: true,
+          },
+        },
+        // -------------------------------------------------------
+        /**
+         * OKlch tokens
+         */
+        // {
+        //   destination: 'primitives.css',
+        //   format: formats.cssVariables,
+        //   filter: (token) => {
+        //     return token.attributes?.type === 'primitive'
+        //   },
+        // },
+        // {
+        //   destination: 'variant.css',
+        //   format: formats.cssVariables,
+        //   filter: (token) => {
+        //     return token.attributes?.category === 'variant'
+        //   },
+        //   options: {
+        //     fileHeader: (defaultMessage: string[]) => {
+        //       return [...defaultMessage, 'Variant tokens']
+        //     },
+        //   },
+        // },
+        {
+          destination: 'variants.css',
+          format: formats.cssVariables,
+          filter: (token: Token) => {
+            const variants = ['variant', 'state', 'color']
+            const category: string | undefined = token.attributes?.category as string
+            return (
+              variants.includes(category) &&
+              token.attributes?.tokenTier !== 'intent' &&
+              token.attributes?.tokenTier !== 'semantic' &&
+              token.attributes?.tokenTier !== 'primitive'
+            )
+          },
+          options: {
+            fileHeader: (defaultMessage: string[]) => {
+              return [...defaultMessage, 'Variant tokens']
+            },
+            outputReferences: true,
+          },
+        },
+        ...colorConfig,
+        ...cubeConfig,
+        ...generateThemeFiles(['components', 'font', 'bg', 'border', 'text', 'variant']),
+      ],
+    },
+    // Type declarations
+    ...typeDeclarationsConfig,
+  },
+}

package/src/theme/README.md

@@ -0,0 +1,256 @@
+# 🎚️ **Theme Tokens: Public vs Private Variables**
+
+This repo generates **two versions** of theme variables:
+
+- **Public Theme Tokens** → meant for _outside consumers_
+- **Private Theme Tokens** → meant for _internal component use_
+
+Understanding the difference keeps your design system:
+
+✔ safe
+
+✔ overridable
+
+✔ stable
+
+✔ predictable
+
+Let’s break it down.
+
+---
+
+## 🟣 **1. Public Theme Tokens (`-token`)**
+
+These are the **official, documented** variables that consumers _are allowed_ to override.
+
+Example:
+
+```css
+:root {
+  --space-md: 1rem;
+  --color-bg-default: #ffffff;
+  --text-body-size: 1rem;
+}
+```
+
+### ✔ Purpose
+
+- Provide a **stable API** for theming
+- Let applications or customer brands override design tokens
+- Expose “slot” variables, not internal details
+
+### ✔ Consumers can override:
+
+```css
+:root {
+  --color-bg-default: #fef7ff; /* custom brand color */
+}
+```
+
+### 🛑 Consumers _should not_ override:
+
+- component-specific tokens
+- conditional tokens
+- computed variables
+- values derived from multiple dependencies
+
+Public tokens are your **surface area**.
+
+---
+
+## 🔵 **2. Private Theme Tokens (`-_token`)**
+
+These exist **only inside the design system**.
+
+Generated like this:
+
+```css
+--_space-md: var(--space-md, 1rem);
+--_color-bg-default: var(--color-bg-default, #ffffff);
+--_text-body-size: var(--text-body-size, clamp(...));
+```
+
+This structure follows Lea Verou’s pattern:
+
+https://lea.verou.me/blog/2021/10/custom-properties-with-defaults/
+
+### ✔ Private variables are _always safe_
+
+Even if a consumer overrides a public variable incorrectly, components still resolve safely.
+
+Example:
+
+```css
+background: var(--_color-bg-default);
+```
+
+### ✔ Developers should **ONLY** use private tokens inside components
+
+Never use:
+
+```css
+background: var(--color-bg-default); /* ❌ no */
+```
+
+Always use:
+
+```css
+background: var(--_color-bg-default); /* ✔ correct */
+```
+
+### ✔ Why?
+
+Because private variables:
+
+- lock in fallback values
+- isolate component behavior from breaking changes
+- prevent invalid overrides from crashing styling
+- are stable even if public tokens change
+
+---
+
+## 🌀 **How Public → Private Works**
+
+Each public token:
+
+```css
+--text-body-size: 1rem;
+```
+
+Produces a private counterpart:
+
+```css
+--_text-body-size: var(--text-body-size, 1rem);
+```
+
+This means:
+
+- if a theme provides a custom `-text-body-size`, it’s used
+- otherwise, fallback = design system default
+
+Exactly what you want.
+
+---
+
+## 🧠 **Why Not Use Public Tokens Inside Components?**
+
+Because public tokens are:
+
+- overrideable
+- unstable
+- potentially missing
+- brand-controlled
+
+Private tokens are:
+
+- resolved
+- safe
+- internal
+- consistent
+
+### Components use internal safety
+
+### Apps override external knobs
+
+---
+
+## 🧩 **Example: Button Token Flow**
+
+**Public:**
+
+```css
+--button-primary-bg: var(--color-brand-primary);
+--button-primary-radius: 6px;
+```
+
+**Private:**
+
+```css
+--_button-primary-bg: var(--button-primary-bg, var(--_color-brand-primary));
+--_button-primary-radius: var(--button-primary-radius, 6px);
+```
+
+**Component:**
+
+```css
+button.primary {
+  background: var(--_button-primary-bg);
+  border-radius: var(--_button-primary-radius);
+}
+```
+
+### If a consumer overrides:
+
+```css
+:root {
+  --button-primary-bg: hotpink;
+}
+```
+
+→ component updates correctly
+
+→ fallback is preserved
+
+→ nothing breaks
+
+---
+
+## 🧩 **Why Two Levels Are Necessary**
+
+| Layer                    | Who uses it  | Purpose                     |
+| ------------------------ | ------------ | --------------------------- |
+| **Public (`--token`)**   | consumers    | override, theme, brand      |
+| **Private (`--_token`)** | components   | stable internal contract    |
+| **Component tokens**     | DS devs      | button/card/input internals |
+| **Semantic tokens**      | DS designers | meaning-based mapping       |
+| **Primitives**           | DS designers | raw values                  |
+
+This hierarchy ensures:
+
+- **external flexibility**
+- **internal stability**
+
+Exactly what a scalable design system needs.
+
+---
+
+## 🛠 Your Custom Formatters
+
+Your Style Dictionary setup generates:
+
+### **public-theme.css**
+
+```css
+:root {
+  --space-md: 1rem;
+  --text-body-size: 1rem;
+  --color-bg-default: #fff;
+}
+```
+
+### **private-theme.css**
+
+```css
+:root {
+  --_space-md: var(--space-md, 1rem);
+  --_text-body-size: var(--text-body-size, 1rem);
+  --_color-bg-default: var(--color-bg-default, #fff);
+}
+```
+
+Nothing else in your build system needs to know how public & private vars relate.
+
+Components only consume **private** vars.
+
+Component libraries only expose **public** vars.
+
+---
+
+## 🧪 TL;DR Cheat Sheet
+
+| Thing            | Use Public? | Use Private? | Notes                             |
+| ---------------- | ----------- | ------------ | --------------------------------- |
+| Apps / Consumers | ✔ yes       | ❌ no        | override `--token`                |
+| DS Components    | ❌ no       | ✔ yes        | use `--_token`                    |
+| Themes           | ✔ yes       | ❌ no        | theme overrides go to public vars |
+| Fallbacks        | automatic   | automatic    | thanks to var(--token, fallback)  |

package/src/theme/cube-theme-addon.js

@@ -0,0 +1,44 @@
+// // cube-theme-addon.js
+// import { generateThemeCubeCSSVariables } from "../cube-css/formatters/cube-css.js";
+// import {
+//   shouldOutputReferences,
+//   rewriteOriginalRefs,
+// } from "./formatters/theme-core.js";
+
+// export function cubeThemeAddon({ dictionary, options, scope }) {
+//   const privateVar = scope === "private";
+
+//   return dictionary.allTokens
+//     .filter((t) => t.attributes?.category === "cube")
+//     .map((t) => {
+//       // start from your existing cube name rules
+//       const entry = generateThemeCubeCSSVariables(t);
+//       console.log(
+//         "📟 - shouldOutputReferences(t, options, dictionary) → ",
+//         shouldOutputReferences(t, options, dictionary),
+//       );
+//       console.log(
+//         "📟 - rewriteOriginalRefs(originalValue, dictionary.tokens, privateVar",
+//         rewriteOriginalRefs(t.original?.value, dictionary.tokens, privateVar),
+//       );
+//       // add refs (optional)
+//       const originalValue = t.original?.value;
+//       const original = shouldOutputReferences(t, options, dictionary)
+//         ? rewriteOriginalRefs(originalValue, dictionary.tokens, privateVar)
+//         : null;
+
+//       return {
+//         ...entry,
+//         original, // lets generateThemeContent prefer original.value
+//       };
+//     });
+// }
+
+// // cube-theme-addon.js
+import { generateThemeCubeCSSVariables } from "../cube-css/formatters/cube-css.js";
+
+export function cubeThemeAddon({ dictionary }) {
+  return dictionary.allTokens
+    .filter((t) => t.attributes?.category === "cube")
+    .map((t) => generateThemeCubeCSSVariables(t));
+}

package/src/theme/helper.js

@@ -0,0 +1,38 @@
+// helper.js
+import { generateHeader, generateSubheader } from '../utils/template.js'
+export { generateThemeContent }
+
+function generateThemeContent(tokens, scope = 'public') {
+  let content = ''
+
+  let currentCategory = null
+  let usedSubsections = new Set() // resets per category
+
+  for (const t of tokens) {
+    const category = t?.category ?? null
+
+    // New category → print header and reset subsection tracking
+    if (category && category !== currentCategory) {
+      currentCategory = category
+      usedSubsections = new Set()
+      content += generateHeader(category)
+    }
+
+    // Optional subsection (opt-in per token)
+    const subsection = t?.subsection
+    if (subsection && !usedSubsections.has(subsection)) {
+      usedSubsections.add(subsection)
+      content += generateSubheader(subsection)
+    }
+
+    const rawValue = t.value
+
+    if (scope === 'public') {
+      content += `  ${t.publicName}: ${rawValue};\n`
+    } else {
+      content += `  ${t.privateName}: var(${t.publicName}, ${rawValue});\n`
+    }
+  }
+
+  return content
+}

package/src/theme/index.js

@@ -0,0 +1,6 @@
+export { default as themeConfig } from './theme.config.js'
+export { filterThemeTokens } from './theme.filter.js'
+export {} from // privateThemeTemplate,
+
+// publicThemeTemplate,
+'./theme.formatter.js'

package/src/theme/theme.config.js

@@ -0,0 +1,42 @@
+// theme.files.js
+import { filterThemeTokens } from "./theme.filter.js";
+
+export default [
+  // Base theme (no cube)
+  {
+    destination: "themes/private-theme.css",
+    format: "private-theme",
+    filter: filterThemeTokens,
+    options: {
+      // outputReferences: true,
+    },
+  },
+  {
+    destination: "themes/public-theme.css",
+    format: "public-theme",
+    filter: filterThemeTokens,
+    options: {
+      // outputReferences: true,
+    },
+  },
+
+  // // Optional theme + cube (appended)
+  // {
+  //   destination: "themes/private-theme+cube.css",
+  //   format: "private-theme+cube",
+  //   filter: (token) =>
+  //     filterThemeTokens(token) || token.attributes?.category === "cube",
+  //   options: {
+  //     outputReferences: true,
+  //   },
+  // },
+  // {
+  //   destination: "themes/public-theme+cube.css",
+  //   format: "public-theme+cube",
+  //   filter: (token) =>
+  //     filterThemeTokens(token) || token.attributes?.category === "cube",
+  //   options: {
+  //     outputReferences: true,
+  //   },
+  // },
+];

package/src/theme/theme.filter.js

@@ -0,0 +1,42 @@
+const themeCategories = [
+  'space',
+  'spacing',
+  'border',
+  'radius',
+  'shadow',
+  'breakpoint',
+  'font',
+  'text',
+  'component',
+  'cube',
+  'body',
+  'heading',
+  'layout',
+
+  // Components
+  'components',
+  'highlighted-text',
+]
+
+const excludeTypes = [
+  'utility',
+  'variants',
+  // add more types to exclude from theme if needed
+]
+/**
+ * List of categories part of the generated private and public theme
+ * See category: https://styledictionary.com/info/tokens/#category--type--item
+ *
+ * @param {*} token
+ * @returns {boolean}
+ */
+export function isPartOfTheme(token) {
+  return themeCategories.includes(token.attributes?.category) &&
+    !excludeTypes.includes(token.attributes?.type)
+    ? true
+    : false
+}
+
+export function filterThemeTokens(token) {
+  return isPartOfTheme(token)
+}

package/src/theme/theme.formatter.js

@@ -0,0 +1,71 @@
+// theme.js
+import StyleDictionary from 'style-dictionary'
+import { generateThemeCubeCSS } from '../cube-css/cube.formatter.js'
+import { toKebab } from '../utils/helpers.js'
+import { resolveTokenReferences, tokenName } from '../utils/tokens.js'
+import { generateThemeContent } from './helper.js'
+
+/**
+ * Takes a token and format it to be rendered in the theme files.
+ *
+ * Will return:
+ * - public name for build/css/themes/public-theme.css
+ * - private name for build/css/themes/private-theme.css
+ * - resolved value (with references rewritten) or raw value
+ * - category for sectioning (heading sections)
+ * - subsection for subheading sections
+ *
+ *
+ * @param {*} tokens
+ * @param {*} options
+ * @param {*} dictionary
+ * @param {*} scope
+ * @returns {{}}
+ */
+function formatToThemeToken(token, options, dictionary, scope) {
+  const privateVar = scope === 'private'
+
+  // const normal = tokens.map((t) => {
+  // const originalValue = t.original?.value;
+
+  return {
+    publicName: `--${toKebab(tokenName(token))}`,
+    privateName: `--_${toKebab(tokenName(token))}`,
+    value: resolveTokenReferences(token, options, dictionary, privateVar),
+    category: token.attributes?.category,
+    subsection: token.attributes?.subsection,
+  }
+}
+
+function buildTheme({ dictionary, options }, scope) {
+  const header =
+    scope === 'public'
+      ? `/**
+ * Theme Overrides
+ * List of CSS variables that can be used to override the default theme
+ * Simply uncomment the variables you want to use
+ */`
+      : `/**
+ * Internal default theme variables
+ * Using CSS pseudo-private custom properties
+ * https://lea.verou.me/blog/2021/10/custom-properties-with-defaults/
+ */`
+
+  //  We exclude cube tokens from the main theme output
+  const themeTokens = dictionary.allTokens.filter((t) => t.attributes?.category !== 'cube')
+  let toks = themeTokens.map((token) => formatToThemeToken(token, options, dictionary, scope))
+
+  toks = [...toks, ...generateThemeCubeCSS(dictionary.allTokens)]
+
+  return `${header}\n:root {${generateThemeContent(toks, scope)}\n}\n`
+}
+
+StyleDictionary.registerFormat({
+  name: 'public-theme',
+  format: (args) => buildTheme(args, 'public'),
+})
+
+StyleDictionary.registerFormat({
+  name: 'private-theme',
+  format: (args) => buildTheme(args, 'private'),
+})