W3C Syntax refactor to allow value & type token names/groups (#1100)

* feat: allow use of value/type/description as token names/groupnames in W3C syntax

* chore: rename from W3C to Dtcg

Author: jorenbroekema

.changeset/cuddly-cheetahs-drum.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': minor
+---
+
+Rename `typeW3CDelegate` utility function to `typeDtcgDelegate`, as using "W3C" is highly discouraged when the standard isn't a W3C standard yet.

.changeset/grumpy-peaches-flow.md

@@ -2,4 +2,4 @@
 'style-dictionary': patch
 ---
 
-Fix small issue in type w3c delegate utility type tracking.
+Fix small issue in type DTCG delegate utility type tracking.

.changeset/neat-zoos-reflect.md

@@ -0,0 +1,5 @@
+---
+'style-dictionary': minor
+---
+
+Support the use of "value"/"type"/"description" as token names or token group names, at the sacrifice of now no longer being able to combine non-DTCG and DTCG syntax within the same token dictionary.

.changeset/ninety-geckos-build.md

@@ -2,4 +2,4 @@
 'style-dictionary': patch
 ---
 
-Expose typeW3CDelegate utility. Don't take "value" into account anymore to determine that it's a design token, use $value.
+Expose `typeDtcgDelegate` utility. Don't take `value` into account anymore to determine that it's a design token, use `$value`.

.changeset/rich-pianos-walk.md

@@ -2,4 +2,4 @@
 'style-dictionary': minor
 ---
 
-Support W3C Draft specification for Design Tokens, by adding support for $value, $type and $description properties.
+Support Design Token Community Group Draft specification for Design Tokens, by adding support for $value, $type and $description properties.

CHANGELOG.md

@@ -22,14 +22,14 @@
 
 ### Patch Changes
 
-- 0c1a36f: Fix small issue in type w3c delegate utility type tracking.
-- 0c1a36f: Expose typeW3CDelegate utility. Don't take "value" into account anymore to determine that it's a design token, use $value.
+- 0c1a36f: Fix small issue in type DTCG delegate utility type tracking.
+- 0c1a36f: Expose `typeDtcgDelegate` utility. Don't take `value` into account anymore to determine that it's a design token, use `$value`.
 
 ## 4.0.0-prerelease.9
 
 ### Minor Changes
 
-- 294fd0e: Support W3C Draft specification for Design Tokens, by adding support for $value, $type and $description properties.
+- 294fd0e: Support Design Token Community Group Draft specification for Design Tokens, by adding support for $value, $type and $description properties.
 
 ### Patch Changes
 

__integration__/__snapshots__/customFormats.test.snap.js

@@ -962,7 +962,8 @@ snapshots["inline custom with new args should match snapshot"] =
   },
   "options": {
     "otherOption": "Test",
-    "showFileHeader": true
+    "showFileHeader": true,
+    "usesDtcg": false
   }
 }`;
 /* end snapshot inline custom with new args should match snapshot */
@@ -1893,7 +1894,8 @@ snapshots["register custom format with new args should match snapshot"] =
   },
   "options": {
     "otherOption": "Test",
-    "showFileHeader": true
+    "showFileHeader": true,
+    "usesDtcg": false
   }
 }`;
 /* end snapshot register custom format with new args should match snapshot */

__integration__/w3c-forward-compat.test.js

@@ -29,7 +29,7 @@ describe('integration', () => {
    * - $type special property & inherits from ancestors
    * - $description special property
    */
-  describe('W3C DTCG draft spec forward compatibility', async () => {
+  describe('DTCG draft spec forward compatibility', async () => {
     const sd = new StyleDictionary({
       tokens: {
         colors: {
@@ -58,14 +58,14 @@ describe('integration', () => {
           type: 'value',
           matcher: (token) => token.$type === 'color',
           transformer: (token) => {
-            return Color(token.$value).toRgbString();
+            return Color(sd.options.usesDtcg ? token.$value : token.value).toRgbString();
           },
         },
         'custom/add/px': {
           type: 'value',
           matcher: (token) => token.$type === 'dimension',
           transformer: (token) => {
-            return `${token.$value}px`;
+            return `${sd.options.usesDtcg ? token.$value : token.value}px`;
           },
         },
       },

__tests__/StyleDictionary.test.js

@@ -326,4 +326,17 @@ describe('StyleDictionary class + extend method', () => {
     expect(sd.tokens.dimensions.nested.deep.lg.$type).to.equal('dimension');
     expect(sd.tokens.dimensions.nope.$type).to.equal('spacing');
   });
+
+  it('should detect usage of DTCG draft spec tokens', async () => {
+    const sd = new StyleDictionary({
+      tokens: {
+        datalist: {
+          key: { color: { $value: '#222' } },
+          value: { color: { $value: '#000' } },
+        },
+      },
+    });
+    await sd.hasInitialized;
+    expect(sd.options.usesDtcg).to.be.true;
+  });
 });

__tests__/buildFile.test.js

@@ -39,23 +39,25 @@ describe('buildFile', () => {
   });
 
   it('should error if format doesnt exist or isnt a function', () => {
-    expect(buildFile.bind(null, { destination: '__tests__output/test.txt' }, {}, {})).to.throw(
+    expect(buildFile.bind(null, { destination: '__tests__output/test.txt' }, {}, {}, {})).to.throw(
       'Please enter a valid file format',
     );
     expect(
-      buildFile.bind(null, { destination: '__tests__output/test.txt', format: {} }, {}, {}),
+      buildFile.bind(null, { destination: '__tests__output/test.txt', format: {} }, {}, {}, {}),
     ).to.throw('Please enter a valid file format');
     expect(
-      buildFile.bind(null, { destination: '__tests__/__output/test.txt', format: [] }, {}, {}),
+      buildFile.bind(null, { destination: '__tests__/__output/test.txt', format: [] }, {}, {}, {}),
     ).to.throw('Please enter a valid file format');
   });
 
   it('should error if destination doesnt exist or isnt a string', () => {
-    expect(buildFile.bind(null, { format }, {}, {})).to.throw('Please enter a valid destination');
-    expect(buildFile.bind(null, { format, destination: [] }, {}, {})).to.throw(
+    expect(buildFile.bind(null, { format }, {}, {}, {})).to.throw(
       'Please enter a valid destination',
     );
-    expect(buildFile.bind(null, { format, destination: {} }, {}, {})).to.throw(
+    expect(buildFile.bind(null, { format, destination: [] }, {}, {}, {})).to.throw(
+      'Please enter a valid destination',
+    );
+    expect(buildFile.bind(null, { format, destination: {} }, {}, {}, {})).to.throw(
       'Please enter a valid destination',
     );
   });
@@ -81,7 +83,7 @@ describe('buildFile', () => {
 
     it('should generate warning messages for output name collisions', () => {
       GroupMessages.clear(PROPERTY_NAME_COLLISION_WARNINGS);
-      buildFile({ destination, format }, {}, dictionary);
+      buildFile({ destination, format }, {}, dictionary, {});
 
       const collisions = dictionary.allTokens
         .map(
@@ -107,7 +109,7 @@ describe('buildFile', () => {
 
     it('should not warn users if the format is a nested format', () => {
       const consoleStub = stubMethod(console, 'log');
-      buildFile({ destination, format: nestedFormat }, {}, dictionary);
+      buildFile({ destination, format: nestedFormat }, {}, dictionary, {});
       expect(consoleStub.calledWith(chalk.bold.green(`✔︎ ${destination}`))).to.be.true;
     });
   });
@@ -137,6 +139,7 @@ describe('buildFile', () => {
       },
       {},
       dictionary,
+      {},
     );
     expect(fileExists('__tests__/__output/test.emptyTokens')).to.be.false;
   });
@@ -151,6 +154,7 @@ describe('buildFile', () => {
         buildPath: '__tests__/__output/',
       },
       {},
+      {},
     );
     expect(fileExists('__tests__/__output/test.txt')).to.be.true;
   });

__tests__/buildFiles.test.js

@@ -104,17 +104,17 @@ describe('buildFiles', () => {
   });
 
   it('should work without buildPath', () => {
-    buildFiles(dictionary, platform);
+    buildFiles(dictionary, platform, {});
     expect(fileExists('__tests__/__output/test.json')).to.be.true;
   });
 
   it('should work with buildPath', () => {
-    buildFiles(dictionary, platformWithBuildPath);
+    buildFiles(dictionary, platformWithBuildPath, {});
     expect(fileExists('__tests__/__output/test.json')).to.be.true;
   });
 
   it('should work with a filter', () => {
-    buildFiles(dictionary, platformWithFilter);
+    buildFiles(dictionary, platformWithFilter, {});
     expect(fileExists('__tests__/__output/test.json')).to.be.true;
     const output = JSON.parse(fs.readFileSync(resolve('__tests__/__output/test.json')));
     expect(output).to.have.property('bingo');

__tests__/cleanDir.test.js

@@ -34,6 +34,7 @@ describe('cleanDir', () => {
       { destination: 'test.txt', format },
       { buildPath: '__tests__/__output/extradir1/extradir2/' },
       {},
+      {},
     );
     cleanFile(
       { destination: 'test.txt', format },

__tests__/cleanDirs.test.js

@@ -55,15 +55,15 @@ describe('cleanDirs', () => {
   });
 
   it('should delete without buildPath', () => {
-    buildFiles(dictionary, platform);
+    buildFiles(dictionary, platform, {});
     cleanFiles(platform);
     cleanDirs(platform);
     expect(dirExists('__tests__/__output/extradir1/extradir2')).to.be.false;
     expect(dirExists('__tests__/__output/extradir1')).to.be.false;
   });
 
   it('should delete with buildPath', () => {
-    buildFiles(dictionary, platformWithBuildPath);
+    buildFiles(dictionary, platformWithBuildPath, {});
     cleanFiles(platformWithBuildPath);
     cleanDirs(platformWithBuildPath);
     expect(dirExists('__tests__/__output/extradir1/extradir2')).to.be.false;

__tests__/cleanFile.test.js

@@ -29,7 +29,7 @@ describe('cleanFile', () => {
   });
 
   it('should delete a file properly', () => {
-    buildFile({ destination: 'test.txt', format }, { buildPath: '__tests__/__output/' }, {});
+    buildFile({ destination: 'test.txt', format }, { buildPath: '__tests__/__output/' }, {}, {});
     cleanFile({ destination: 'test.txt', format }, { buildPath: '__tests__/__output/' }, {});
     expect(fileExists('__tests__/__output/test.txt')).to.be.false;
   });

__tests__/cleanFiles.test.js

@@ -54,13 +54,13 @@ describe('cleanFiles', () => {
   });
 
   it('should delete without buildPath', () => {
-    buildFiles(dictionary, platform);
+    buildFiles(dictionary, platform, {});
     cleanFiles(platform);
     expect(fileExists('__tests__/__output/test.json')).to.be.false;
   });
 
   it('should delete with buildPath', () => {
-    buildFiles(dictionary, platformWithBuildPath);
+    buildFiles(dictionary, platformWithBuildPath, {});
     cleanFiles(platformWithBuildPath);
     expect(fileExists('__tests__/t__/__output/test.json')).to.be.false;
   });

__tests__/common/formatHelpers/__snapshots__/createPropertyFormatter.test.snap.js

@@ -34,21 +34,21 @@ snapshots["common formatHelpers createPropertyFormatter commentStyle allows over
 $color-green: #00FF00;`;
 /* end snapshot common formatHelpers createPropertyFormatter commentStyle allows overriding formatting commentStyle 2 */
 
-snapshots["common formatHelpers createPropertyFormatter commentStyle supports W3C spec $description property for comments 1"] = 
+snapshots["common formatHelpers createPropertyFormatter commentStyle supports DTCG spec $description property for comments 1"] = 
 `  --color-red: #FF0000; /* Foo bar qux red */`;
-/* end snapshot common formatHelpers createPropertyFormatter commentStyle supports W3C spec $description property for comments 1 */
+/* end snapshot common formatHelpers createPropertyFormatter commentStyle supports DTCG spec $description property for comments 1 */
 
-snapshots["common formatHelpers createPropertyFormatter commentStyle supports W3C spec $description property for comments 2"] = 
+snapshots["common formatHelpers createPropertyFormatter commentStyle supports DTCG spec $description property for comments 2"] = 
 `  --color-green: #00FF00; /* Foo bar qux green */`;
-/* end snapshot common formatHelpers createPropertyFormatter commentStyle supports W3C spec $description property for comments 2 */
+/* end snapshot common formatHelpers createPropertyFormatter commentStyle supports DTCG spec $description property for comments 2 */
 
-snapshots["common formatHelpers createPropertyFormatter commentStyle supports W3C spec $description property for comments 3"] = 
+snapshots["common formatHelpers createPropertyFormatter commentStyle supports DTCG spec $description property for comments 3"] = 
 `  /**
    * Foo
    * bar
    * qux
    * blue
    */
   --color-blue: #0000FF;`;
-/* end snapshot common formatHelpers createPropertyFormatter commentStyle supports W3C spec $description property for comments 3 */
+/* end snapshot common formatHelpers createPropertyFormatter commentStyle supports DTCG spec $description property for comments 3 */
 

__tests__/common/formatHelpers/createPropertyFormatter.test.js

@@ -359,7 +359,7 @@ describe('common', () => {
           await expect(sassRed).to.matchSnapshot(2);
         });
 
-        it('supports W3C spec $description property for comments', async () => {
+        it('supports DTCG spec $description property for comments', async () => {
           const descriptionDictionary = {
             color: {
               red: {