feat(examples): add tailwind preset example

examples/advanced/tailwind-preset/.gitignore

@@ -0,0 +1,4 @@
+demo/output.css
+build
+node_modules
+package-lock.json

examples/advanced/tailwind-preset/README.md

@@ -0,0 +1,85 @@
+# Tailwind preset
+
+Builds [Tailwind preset](https://tailwindcss.com/docs/presets#creating-a-preset) from tokens.
+
+## Building the preset
+
+Run `npm run build-tokens` to generate files in `build/tailwind/`.
+
+### cssVarPlugin.js
+
+A [Tailwind plugin](https://tailwindcss.com/docs/plugins) for registering new base styles.
+
+Token values are transformed into space-separated RGB channels for compatability with [Tailwind's opacity modifier syntax](https://tailwindcss.com/docs/customizing-colors#using-css-variables).
+
+```js
+import plugin from 'tailwindcss/plugin';
+
+export default plugin(function ({ addBase }) {
+  addBase({
+    ':root': {
+      '--sd-text-small': '0.75',
+      '--sd-text-base': '#2E2E46',
+      '--sd-text-secondary': '100 100 115',
+      '--sd-text-tertiary': '129 129 142',
+      '--sd-theme': '31 197 191',
+      '--sd-theme-light': '153 235 226',
+      '--sd-theme-dark': '0 179 172',
+      '--sd-theme-secondary': '106 80 150',
+      '--sd-theme-secondary-dark': '63 28 119',
+      '--sd-theme-secondary-light': '196 178 225',
+    },
+  });
+});
+```
+
+### themeColors.js
+
+Tailwind theme color values that reference the plugin css vars.
+
+```js
+export default {
+  'sd-text-secondary': 'rgb(var(--sd-text-secondary) / <alpha-value>)',
+  'sd-text-tertiary': 'rgb(var(--sd-text-tertiary) / <alpha-value>)',
+  'sd-theme': 'rgb(var(--sd-theme) / <alpha-value>)',
+  'sd-theme-light': 'rgb(var(--sd-theme-light) / <alpha-value>)',
+  'sd-theme-dark': 'rgb(var(--sd-theme-dark) / <alpha-value>)',
+  'sd-theme-secondary': 'rgb(var(--sd-theme-secondary) / <alpha-value>)',
+  'sd-theme-secondary-dark': 'rgb(var(--sd-theme-secondary-dark) / <alpha-value>)',
+  'sd-theme-secondary-light': 'rgb(var(--sd-theme-secondary-light) / <alpha-value>)',
+};
+```
+
+### preset.js
+
+[Tailwind preset](https://tailwindcss.com/docs/presets) file that imports the colors and plugin.
+
+```js
+import themeColors from './themeColors.js';
+import cssVarsPlugin from './cssVarsPlugin.js';
+
+export default {
+  theme: {
+    extend: {
+      colors: {
+        ...themeColors, // <-- theme colors
+      },
+    },
+  },
+  plugins: [cssVarsPlugin], // <-- plugin
+};
+```
+
+## Building the CSS
+
+The [Tailwind preset](https://tailwindcss.com/docs/presets#creating-a-preset) is imported from the build directory in `tailwind.config.js`.
+
+```js
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  presets: [require('./build/tailwind/preset')], // <-- preset imported here
+  content: ['./demo/**/*.{html,js}'], // <-- files to watch
+};
+```
+
+Run `npm run build-css` to watch the `demo/index.html` file for changes -- any Tailwind classes used will be compiled into `demo/output.css`.

examples/advanced/tailwind-preset/config.js

@@ -0,0 +1,56 @@
+import StyleDictionary from 'style-dictionary';
+import { isColor } from './config/filter.js';
+import { cssVarsPlugin, preset, themeColors } from './config/format.js';
+import { rgbChannels } from './config/transform.js';
+
+StyleDictionary.registerTransform({
+  name: 'color/rgb-channels',
+  type: 'value',
+  filter: isColor,
+  transform: rgbChannels,
+});
+
+StyleDictionary.registerTransformGroup({
+  name: 'color/tailwind',
+  transforms: ['name/kebab', 'color/rgb', 'color/rgb-channels'],
+});
+
+StyleDictionary.registerFormat({
+  name: 'tailwind/css-vars-plugin',
+  format: cssVarsPlugin,
+});
+
+StyleDictionary.registerFormat({
+  name: 'tailwind/theme-colors',
+  format: themeColors,
+});
+
+StyleDictionary.registerFormat({
+  name: 'tailwind/preset',
+  format: preset,
+});
+
+export default {
+  source: ['./tokens/**/*.json'],
+  platforms: {
+    tailwindPreset: {
+      buildPath: 'build/tailwind/',
+      transformGroup: 'color/tailwind',
+      usesDtcg: true,
+      files: [
+        {
+          destination: 'cssVarsPlugin.js',
+          format: 'tailwind/css-vars-plugin',
+        },
+        {
+          destination: 'themeColors.js',
+          format: 'tailwind/theme-colors',
+        },
+        {
+          destination: 'preset.js',
+          format: 'tailwind/preset',
+        },
+      ],
+    },
+  },
+};

examples/advanced/tailwind-preset/config/filter.js

@@ -0,0 +1,3 @@
+export const isColor = (token, options) => {
+  return (options?.usesDtcg ? token.$type : token.type) === 'color';
+};

examples/advanced/tailwind-preset/config/filter.test.js

@@ -0,0 +1,15 @@
+import { expect } from 'chai';
+import { describe, it } from 'mocha';
+import { isColor } from './filter.js';
+
+describe('isColor', () => {
+  it('should handle legacy and dtcg formats', () => {
+    expect(isColor({ type: 'color' }, { usesDtcg: false })).to.equal(true);
+    expect(isColor({ type: 'color' }, { usesDtcg: true })).to.equal(false);
+    expect(isColor({ type: 'fontSize' }, { usesDtcg: false })).to.equal(false);
+
+    expect(isColor({ $type: 'color' }, { usesDtcg: true })).to.equal(true);
+    expect(isColor({ $type: 'color' }, { usesDtcg: false })).to.equal(false);
+    expect(isColor({ $type: 'fontSize' }, { usesDtcg: true })).to.equal(false);
+  });
+});

examples/advanced/tailwind-preset/config/format.js

@@ -0,0 +1,56 @@
+import { isColor } from './filter.js';
+
+/**
+ * Exports tailwind plugin for declaring root CSS vars
+ * @see https://tailwindcss.com/docs/plugins#overview
+ */
+export const cssVarsPlugin = ({ dictionary, options }) => {
+  const vars = dictionary.allTokens
+    .map((token) => {
+      const value = options.usesDtcg ? token.$value : token.value;
+      return `'--${token.name}': '${value}'`;
+    })
+    .join(',\n      ');
+
+  return `import plugin from 'tailwindcss/plugin';
+
+export default plugin(function ({ addBase }) {
+  addBase({
+    ':root': {
+      ${vars},
+    },
+  });
+});\n`;
+};
+
+/**
+ * Exports colors as space-separated RGB channels
+ */
+export const themeColors = ({ dictionary, options }) => {
+  const tokens = dictionary.allTokens.filter((token) => isColor(token, options));
+
+  const theme = tokens
+    .map((token) => `  '${token.name}': 'rgb(var(--${token.name}) / <alpha-value>)'`)
+    .join(',\n');
+  return `export default {\n${theme},\n};\n`;
+};
+
+/**
+ * Exports tailwind preset
+ * @see https://tailwindcss.com/docs/presets
+ */
+export const preset = () => {
+  return `import themeColors from './themeColors.js';
+import cssVarsPlugin from './cssVarsPlugin.js';
+
+export default {
+  theme: {
+    extend: {
+      colors: {
+        ...themeColors, // <-- theme colors defined here
+      },
+    },
+  },
+  plugins: [cssVarsPlugin], // <-- plugin imported here
+};\n`;
+};

examples/advanced/tailwind-preset/config/transform.js

@@ -0,0 +1,10 @@
+export const rgbChannels = (token, options) => {
+  const regex = /rgb\((\d+),\s*(\d+),\s*(\d+)\)/;
+  const value = options.usesDtcg ? token.$value : token.value;
+
+  const matches = value.match(regex);
+  if (!matches) {
+    throw new Error(`Value '${value}' is not a valid rgb format.`);
+  }
+  return `${matches[1]} ${matches[2]} ${matches[3]}`;
+};

examples/advanced/tailwind-preset/config/transform.test.js

@@ -0,0 +1,23 @@
+import { expect } from 'chai';
+import { describe, it } from 'mocha';
+import { rgbChannels } from './transform.js';
+
+describe('rgbChannels', () => {
+  it('should extract RGB channels from valid RGB string', () => {
+    const token = { value: 'rgb(255, 255, 255)' };
+    expect(rgbChannels(token, { usesDtcg: false })).to.equal('255 255 255');
+
+    const dtcgToken = { $value: 'rgb(1, 2, 3)' };
+    expect(rgbChannels(dtcgToken, { usesDtcg: true })).to.equal('1 2 3');
+  });
+
+  it('should throw error for invalid RGB string', () => {
+    const expectedErr = "Value 'mock' is not a valid rgb format.";
+
+    const token = { value: 'mock' };
+    expect(() => rgbChannels(token, { usesDtcg: false })).to.throw(expectedErr);
+
+    const dtcgToken = { $value: 'mock' };
+    expect(() => rgbChannels(dtcgToken, { usesDtcg: true })).to.throw(expectedErr);
+  });
+});

examples/advanced/tailwind-preset/demo/index.html

@@ -0,0 +1,24 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <!--
+      Run `npm run build-tokens` to generate build/preset.js.
+      Then run `npm run build-css` to generate `output.css`.
+    -->
+    <link href="./output.css" rel="stylesheet" />
+  </head>
+  <body>
+    <div class="h-screen w-full bg-sd-theme-secondary/10">
+      <div class="p-4 grid grid-cols-1 gap-4 text-5xl">
+        <span class="text-sd-theme-dark">Hello tokens</span>
+        <span class="text-sd-theme">Hello tokens</span>
+        <span class="text-sd-theme-light">Hello tokens</span>
+        <span class="text-sd-theme-secondary-dark">Hello tokens</span>
+        <span class="text-sd-theme-secondary">Hello tokens</span>
+        <span class="text-sd-theme-secondary-light">Hello tokens</span>
+      </div>
+    </div>
+  </body>
+</html>

examples/advanced/tailwind-preset/demo/input.css

@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;

examples/advanced/tailwind-preset/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "tailwind-preset",
+  "version": "1.0.0",
+  "description": "Builds tailwind preset from tokens",
+  "type": "module",
+  "scripts": {
+    "build-tokens": "style-dictionary build --config ./config.js",
+    "build-css": "npx tailwindcss -i ./demo/input.css -o ./demo/output.css --watch",
+    "test": "mocha 'config/**/*test.js'"
+  },
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "style-dictionary": "^4.0.0",
+    "tailwindcss": "~3.4.12",
+    "mocha": "^10.2.0",
+    "chai": "^5.0.0-alpha.2"
+  }
+}

examples/advanced/tailwind-preset/tailwind.config.js

@@ -0,0 +1,5 @@
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  presets: [require('./build/tailwind/preset')],
+  content: ['./demo/**/*.{html,js}'],
+};

examples/advanced/tailwind-preset/tokens/tokens.json

@@ -0,0 +1,45 @@
+{
+  "sd": {
+    "text": {
+      "small": {
+        "$value": "0.75",
+        "$type": "fontSize"
+      },
+      "base": {
+        "type$": "color",
+        "$value": "#2E2E46"
+      },
+      "secondary": {
+        "$type": "color",
+        "$value": "#646473"
+      },
+      "tertiary": {
+        "$type": "color",
+        "$value": "#81818E"
+      }
+    },
+    "theme": {
+      "$type": "color",
+      "_": {
+        "$value": "#1FC5BF"
+      },
+      "light": {
+        "$value": "#99EBE2"
+      },
+      "dark": {
+        "$value": "#00B3AC"
+      },
+      "secondary": {
+        "_": {
+          "$value": "#6A5096"
+        },
+        "dark": {
+          "$value": "#3F1C77"
+        },
+        "light": {
+          "$value": "#C4B2E1"
+        }
+      }
+    }
+  }
+}