Design tokens and core theme config (GoogleChrome#5767)

* Add color tokens

* Text sizes

* Temp colors ref

* First pass at tokens data complete

* Basic scaffold of a token to Sass conversion setup

* Fix typo

* Add dev light task because the emulators weren't working very well on an m1 mac

* Create a new Sass task and a design token to Sass variable converter

* Switch to using hex because Sass is converting to those values anyway 😤

* Really basic gorko config and theme config

* Improve the fluid type generator

* Add a themes config, a gulp task and wire it all up to Gorko

* Tidy up and add some comments

* Add some notes to color

* Add modified version of the modern css reset

* Add some more tokens and theme values

* Linter

* Fix lockfile

* Linting

* Theme tweaks

* Merge Sass into one task

* Tweak naming

* Get a modified version of the d.c.c reset

* System fonts in place of Roboto

* Clean packages

* Adjust write-version

* Remove test build

* Make write-version verify or create the dist directory before it attempts to write.

Co-authored-by: Rob Dodson <[email protected]>

Author: Andy-set-studio

.gitignore

@@ -85,6 +85,8 @@ entrypoint.hashmanifest.json
 .tmp
 .firebase
 firebase.json
+src/scss/_tokens.scss
+src/scss/_themes.scss
 
 # Eleventy
 # We generate our own .eleventyignore file dynamically during builds

gulp-tasks/convert-design-themes.js

@@ -0,0 +1,71 @@
+const fs = require('fs');
+const prettier = require('prettier');
+const themes = require('../src/site/_data/design/themes.js');
+
+/*
+  Converts the theme config into Sass variables that can be used
+  by Gorko to generate both Custom Property groups and also utility
+  classes that have a direct relationship to in-context design tokens
+*/
+const convertDesignThemes = (cb) => {
+  let result = '';
+
+  // Add a note that this is auto generated
+  result += `
+    /// Sass THEMES GENERATED WITH CONFIG ON ${new Date().toLocaleDateString()}.
+    /// Config location: ../src/site/_data/design/themes.js
+  `;
+
+  result += `
+  
+    /// THEME KEYS 
+    /// These are used to generate utility classes for themeable properties like color and background
+  `;
+  result += '$gorko-theme-keys: (';
+
+  Object.keys(themes.colorKeys).forEach((colorKey) => {
+    result += `'${themes.colorKeys[colorKey]}': var(--color-${themes.colorKeys[colorKey]}),`;
+  });
+
+  result += ');';
+
+  result += `
+  
+    /// THEMES
+    /// The gorko config for the actual themes starts https://github.com/andy-piccalilli/gorko#using-themes
+  `;
+  result += '$gorko-themes: (';
+
+  themes.generate().forEach(({name, key, value, tokens}) => {
+    result += `'${name}': (`;
+
+    if (key) {
+      result += `'${key}': '${value}',`;
+    }
+
+    result += `'tokens': (`;
+
+    result += `'color': (`;
+
+    Object.keys(tokens).forEach((tokenKey) => {
+      result += `'${themes.colorKeys[tokenKey]}': var(--color-${tokens[tokenKey]}),`;
+    });
+
+    result += '),'; // end color
+
+    result += '),'; // end tokens
+
+    result += '),'; // end theme
+  });
+
+  result += ');'; // end $gorko-themes
+
+  // Make the Sass readable to help people with auto-complete in their editors
+  result = prettier.format(result, {parser: 'scss'});
+
+  // Push this file into the Sass dir, ready to go
+  fs.writeFileSync('./src/scss/_themes.scss', result);
+  cb();
+};
+
+module.exports = convertDesignThemes;

gulp-tasks/convert-design-tokens.js

@@ -0,0 +1,128 @@
+const fs = require('fs');
+const slugify = require('slugify');
+const prettier = require('prettier');
+const tokens = require('../src/site/_data/design/tokens.json');
+
+/*
+  Converts the design tokens into Sass variables so Gorko can use
+  them as the core of the CSS system.
+*/
+const convertDesignTokens = (cb) => {
+  let result = '';
+  const rootSize = 16;
+  const nameSlug = (text) => slugify(text, {lower: true});
+
+  // Generates a CSS clamp size with min and max values passed
+  const clampGenerator = (min, max) => {
+    if (min === max) {
+      return `${min / 16}rem`;
+    }
+
+    const minSize = min / rootSize;
+    const maxSize = max / rootSize;
+    const minViewport = 20; // rems
+    const maxViewport = 90; // rems
+
+    // Slope and intersection allow us to have a fluid value but also keep that sensible
+    const slope = (maxSize - minSize) / (maxViewport - minViewport);
+    const intersection = -1 * minViewport * slope + minSize;
+
+    return `clamp(${minSize}rem, ${intersection.toFixed(2)}rem + ${
+      slope.toFixed(2) * 100
+    }vw, ${maxSize}rem)`;
+  };
+
+  // Removes trailing commas and closes Sass map group
+  const cleanResult = () => {
+    result = result.replace(/,\s*$/, '');
+    result += ');';
+  };
+
+  // Add a note that this is auto generated
+  result += `
+    /// Sass VARIABLES GENERATED WITH DESIGN TOKENS ON ${new Date().toLocaleDateString()}.
+    /// Tokens location: ../src/site/_data/design/tokens.json
+  `;
+
+  // Start with colors
+  result += `
+
+    ///  COLORS
+  `;
+  result += '$gorko-colors: (';
+
+  tokens.colors.forEach((group) => {
+    group.items.forEach((color) => {
+      result += `'${nameSlug(group.group + '-' + color.name)}': ${color.hex},`;
+    });
+  });
+
+  cleanResult();
+
+  // Move on to text sizes
+  result += `
+
+    ///  TEXT SIZES
+  `;
+  result += '$gorko-size-scale: (';
+
+  tokens.textSizes.forEach((size) => {
+    result += `'${nameSlug(size.name)}': ${clampGenerator(
+      size.min,
+      size.max,
+    )},`;
+  });
+
+  cleanResult();
+
+  // Move on to spacing
+  result += `
+  
+    ///  SPACING SIZES
+  `;
+  result += '$gorko-space-scale: (';
+
+  tokens.spacing.forEach((size) => {
+    result += `'${nameSlug(size.name)}': ${clampGenerator(
+      size.min,
+      size.max,
+    )},`;
+  });
+
+  cleanResult();
+
+  // Move on to fonts
+  result += `
+  
+    ///  FONTS 
+  `;
+  result += '$gorko-fonts: (';
+
+  tokens.fonts.forEach((font) => {
+    result += `'${nameSlug(font.name)}': '${font.values.join(',')}',`;
+  });
+
+  cleanResult();
+
+  // Lastly, misc values like radius and transitions
+  result += `
+  
+    ///  MISC 
+  `;
+  tokens.radius.forEach((item) => {
+    result += `$global-radius-${nameSlug(item.name)}: ${item.value};`;
+  });
+
+  tokens.transitions.forEach((item) => {
+    result += `$global-transition-${nameSlug(item.name)}: ${item.value};`;
+  });
+
+  // Make the Sass readable to help people with auto-complete in their editors
+  result = prettier.format(result, {parser: 'scss'});
+
+  // Push this file into the Sass dir, ready to go
+  fs.writeFileSync('./src/scss/_tokens.scss', result);
+  cb();
+};
+
+module.exports = convertDesignTokens;

gulp-tasks/sass.js

@@ -1,36 +1,16 @@
-const {dirname} = require('path');
-const {mkdirSync, writeFileSync} = require('fs');
-const sassProcessor = require('sass');
+const {dest, src} = require('gulp');
+const sassProcessor = require('gulp-sass')(require('sass'));
 
-const src = './src/styles/main.scss';
-const dest = './dist/css/main.css';
+const sourceFiles = ['./src/scss/next.scss', './src/styles/main.scss'];
 
-// Flags whether we generate sourcemaps
-// TODO: d.c.c. uses NODE_ENV but we use ELEVENTY_ENV a lot in web.dev.
-const isProd = process.env.ELEVENTY_ENV === 'prod';
+// Flags wether we compress the output etc
+const isProduction = process.env.NODE_ENV === 'production';
 
-// Techincally we're rendering synchronously so we don't need an async function,
-// but gulp requires all tasks to return a promise.
-const sass = async () => {
-  // nb. No need to catch errors because gulp handles that for us and logs them.
-  const result = sassProcessor.renderSync({
-    file: src,
-    // nb. Sass doesn't actually write to this outFile, the caller must do that
-    // themselves.
-    // outFile is used to determine the URL used to link from the generated CSS
-    // to the source map, and from the source map to the Sass source files.
-    outFile: dest,
-    sourceMap: !isProd,
-  });
-
-  mkdirSync(dirname(dest), {recursive: true});
-  writeFileSync(dest, result.css.toString(), 'utf8');
-
-  // I'm not guarding for result.map here because if we're doing a dev build we
-  // expect it to be defined and if it isn't, we want it to blow up.
-  if (!isProd) {
-    writeFileSync(dest + '.map', result.map.toString(), 'utf8');
-  }
+const sass = (cb) => {
+  return src(sourceFiles, {sourcemaps: !isProduction})
+    .pipe(sassProcessor().on('error', sassProcessor.logError))
+    .pipe(dest('./dist/css', {sourcemaps: !isProduction}))
+    .on('done', cb);
 };
 
 module.exports = sass;

gulp-tasks/write-version.js

@@ -5,9 +5,12 @@
  *
  * @returns {Promise<void>}
  */
+const fs = require('fs');
 const writeVersion = async () => {
   if (process.env.ELEVENTY_ENV === 'prod') {
-    require('fs').writeFileSync('./dist/version', process.env.GITHUB_SHA);
+    // Verify dist directory exists
+    fs.mkdirSync('./dist', {recursive: true});
+    fs.writeFileSync('./dist/version', process.env.GITHUB_SHA || '');
   }
 };
 

gulpfile.js

@@ -15,24 +15,39 @@
  */
 
 const gulp = require('gulp');
+const convertDesignThemes = require('./gulp-tasks/convert-design-themes.js');
+const convertDesignTokens = require('./gulp-tasks/convert-design-tokens.js');
 const copyDefaultLocale = require('./gulp-tasks/copy-default-locale.js');
 const copyFonts = require('./gulp-tasks/copy-fonts.js');
 const copyGlobalImages = require('./gulp-tasks/copy-global-images.js');
 const copyMisc = require('./gulp-tasks/copy-misc.js');
 const sassTask = require('./gulp-tasks/sass.js');
 const writeVersion = require('./gulp-tasks/write-version.js');
 
-gulp.task('default-locale', copyDefaultLocale);
+gulp.task('convert-design-themes', convertDesignThemes);
+gulp.task('convert-design-tokens', convertDesignTokens);
 gulp.task('copy-misc', copyMisc);
+gulp.task('default-locale', copyDefaultLocale);
 gulp.task('sass', sassTask);
 
 gulp.task(
   'build',
-  gulp.parallel(copyGlobalImages, copyMisc, copyFonts, sassTask, writeVersion),
+  gulp.series(
+    convertDesignThemes,
+    convertDesignTokens,
+    gulp.parallel(
+      copyGlobalImages,
+      copyMisc,
+      copyFonts,
+      sassTask,
+      writeVersion,
+    ),
+  ),
 );
 
 gulp.task('watch', () => {
   gulp.watch('./src/images/**/*', {ignoreInitial: true}, copyGlobalImages);
   gulp.watch('./src/misc/**/*', {ignoreInitial: true}, copyMisc);
   gulp.watch('./src/styles/**/*.scss', {ignoreInitial: true}, sassTask);
+  gulp.watch('./src/scss/**/*.scss', {ignoreInitial: true}, sassTask);
 });