fix(scripts): add in checks for unknown types

- support better checks for unknown figma variable types
- update and fix handling for verbose output
- add documentation details for how to handle import files

Author: booc0mtaco

.storybook/components/Docs/Guidelines/Theming.mdx

@@ -145,6 +145,8 @@ npx eds-import-from-figma-api file <file_id> --token <personal_access_token>
 
 **NOTE**: when using this method, it requires both the figma file ID (e.g., `figma.com/design/<file_id>/`), and an API token. Instructions from Figma [are here][figma-access-token-docs].
 
+**NOTE**: the figma file ID should refer to the Foundations file which defines the core tokens used by EDS.
+
 [figma-enterprise]: https://www.figma.com/enterprise/
 [figma-api-docs]: https://www.figma.com/developers/api
 [figma-access-token-docs]: https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens

README.md

@@ -8,6 +8,13 @@ The Education Design System (EDS) is a repository of building blocks, implementi
 - [Presentational](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0) components implementing the common controls provided by the EDS toolkit
 - Guidelines for creating recipes using EDS, composing the above components
 
+## Prerequisites
+
+Currently, EDS supports the following:
+
+* React 18.x
+* Tailwind 3.x
+
 ## Installation
 
 First, install the package.

bin/_util.js

@@ -257,7 +257,10 @@ module.exports = {
           );
         default:
           throw new TypeError(
-            'unknown resolved type: ' + this._figmaVariableData.resolvedType,
+            'unknown resolved type for ' +
+              this._figmaVariableData.name +
+              ': ' +
+              this._figmaVariableData.resolvedType,
           );
       }
     }
@@ -442,7 +445,10 @@ module.exports = {
             : this.value;
         default:
           throw new TypeError(
-            'unknown resolved type: ' + this._figmaVariableData.resolvedType,
+            'unknown resolved type for ' +
+              this._figmaVariableData.name +
+              ': ' +
+              this._figmaVariableData.resolvedType,
           );
       }
     }

bin/eds-import-from-figma-api.js

@@ -48,7 +48,7 @@ const { identity } = require('lodash');
 
   // read in the config from config file, package json "eds", etc.
   const config = !args.local && (await getConfig());
-  const isVerbose = args.v;
+  const isVerbose = args.verbose;
   const canWrite = !args.dryRun;
 
   // Get the local variables from the defined file b/c published ones won't contain the modes
@@ -130,36 +130,44 @@ const { identity } = require('lodash');
           chalk.bold(variable.name) +
             ': Skipped with warning (orphaned): please remove usage in figma',
         );
+        isVerbose && console.warn('Variable details:', variable);
 
         return;
       }
 
       // mesh the token path to a matching path in the local theme file
-      let writePath = variable.getTokenPath();
-      const locationInLocal = at(localTheme, writePath).filter(
-        (entries) => typeof entries !== 'undefined',
-      );
+      // TODO-AH: this blows up when hitting STRING values
+      let writePath;
+      try {
+        writePath = variable.getTokenPath();
+        const locationInLocal = at(localTheme, writePath).filter(
+          (entries) => typeof entries !== 'undefined',
+        );
 
-      // Update the write path to conform to the format used in style-dictionary
-      if (locationInLocal.length) {
-        // handle case where we should look for @ in the file, then pluck the value object properly
-        if (locationInLocal[0]['@']?.value) {
-          // update the write path to mark the @ and value
-          writePath = writePath + '[email protected]';
-        }
+        // Update the write path to conform to the format used in style-dictionary
+        if (locationInLocal.length) {
+          // handle case where we should look for @ in the file, then pluck the value object properly
+          if (locationInLocal[0]['@']?.value) {
+            // update the write path to mark the @ and value
+            writePath = writePath + '[email protected]';
+          }
 
-        // handle case where it's just value
-        if (locationInLocal[0]?.value) {
-          // update the write path to mark the value
-          writePath = writePath + '.value';
+          // handle case where it's just value
+          if (locationInLocal[0]?.value) {
+            // update the write path to mark the value
+            writePath = writePath + '.value';
+          }
         }
+      } catch (e) {
+        // We couldn't parse the write path
+        isVerbose && spinner.fail(chalk.bold(variable.name) + ': ' + e);
+        isVerbose && console.error('Variable details:', variable);
       }
 
       if (writePath) {
         try {
           // error when path suffix is invalid (all should end with .value)
           if (!writePath.endsWith('value')) {
-            isVerbose && console.error(variable);
             throw new Error(
               `Name format violation. JSON path missing in local theme: ${writePath} (${figmaVariable.resolvedType})`,
             );
@@ -195,6 +203,7 @@ const { identity } = require('lodash');
         } catch (e) {
           // We couldn't parse the resolved value, so skip and add to errors
           spinner.fail(chalk.bold(variable.name) + ': ' + e);
+          isVerbose && console.error('Variable details:', variable);
           stats.errored.push(variable);
         }
       } else {
@@ -206,6 +215,7 @@ const { identity } = require('lodash');
               ': Skipped with warning (no write path)',
           );
         }
+        isVerbose && console.warn('Variable details:', variable);
         stats.skipped.push(variable);
       }
     });