DP-18263: Adds new assets package. (#1037)

.circleci/config.yml

@@ -12,8 +12,7 @@ references:
 react_defaults: &react_defaults
   working_directory: ~/repo
   docker:
-    - image: circleci/node:10.15.1
-
+    - image: circleci/node:12.18.0
 patternlab_defaults: &patternlab_defaults
   working_directory: /var/www/code
   docker:
@@ -165,12 +164,12 @@ jobs:
       - checkout
       - restore_cache:
           keys:
-            - mfr-dependencies-{{ checksum "react/package.json" }}
+            - mfr-dependencies-{{ checksum "react/package.json" }}-0
       - run: cd react && npm install
       - save_cache:
           paths:
             - react/node_modules
-          key: mfr-dependencies-{{ checksum "react/package.json" }}
+          key: mfr-dependencies-{{ checksum "react/package.json" }}-0
       - run:
           name: Mayflower React Build
           command: cd react && npm run build
@@ -194,6 +193,7 @@ jobs:
           docker-compose up --no-start web backstop
           docker cp ./ $(docker-compose ps -q backstop):/src/
           docker cp ../assets $(docker-compose ps -q backstop):/src/assets
+          docker cp ../docs $(docker-compose ps -q backstop):/src/docs
           docker cp ./storybook-static/. $(docker-compose ps -q web):/usr/share/nginx/html
       - run: |
           cd react
@@ -288,9 +288,6 @@ jobs:
       - run:
           name: Mayflower Style Linter
           command: cd assets && npm run stylelint
-      - run:
-          name: Validate Package Build
-          command: cd assets && npm run build
 
   assets_deploy_tag:
     <<: *react_defaults
@@ -305,13 +302,12 @@ jobs:
           paths:
             - assets/node_modules
           key: assets-dependencies-{{ checksum "assets/package.json" }}
-      - run: cd assets && npm run build
       - run:
-          name: 'Publish mayflower-tokens NPM package'
+          name: 'Publish mayflower-assets NPM package'
           command: |
             cd assets
             npm version --no-git-tag-version "$CIRCLE_TAG"
-            if test -z "$(npm show @massds/mayflower-tokens@$CIRCLE_TAG)"; then
+            if test -z "$(npm show @massds/mayflower-assets@$CIRCLE_TAG)"; then
               npm publish
             else
               echo "Skipping NPM publish - $CIRCLE_TAG already exists"

.gitignore

@@ -5,6 +5,6 @@
 node_modules
 
 .env
-
+!react/.env
 # Distribution folder
 dist

assets/.nvmrc

@@ -0,0 +1 @@
+v12.16.0

assets/.stylelintignore

@@ -1 +1 @@
-node_modules
+node_modules

assets/README.md

@@ -1,58 +1,158 @@
-# Mayflower-Tokens
-[![npm package][npm-badge]][npm]
-
-Mayflower-tokens provides a bundled up library of design tokens and assets that you will need for theming your front end framework to look and feel like [Mass.gov](https://mass.gov) and other Commonwealth web properties that are in Mayflower ecosystem. Mayflower-tokens includes color token SCSS variables, fonts, icons and other imagery from Mayflower — the [enterprise design system for the Commonwealth of Massachusetts][mayflower-doc].
-```
-├── dist   
-    ├── fonts                 Texta web fonts      
-    ├── images             
-    │   ├── svg-icons         SVG icon files
-    │   ├── stateseal         stateseal png
-    │   ├── stateseal-color   stateseal png in color grayscale
-    ├── scss        
-    │   ├── _colors.scss      Color tokens
-    │   ├── _fonts.scss       Texta font imports (needs to set $assets-path)
-    │   ├── _index.scss       Default SCSS export
-```
-
-- **Codebase:** [Mayflower monorepo][mayflower-github] `assets` subdirectory
-  >[Mayflower monorepo][mayflower-github] comprised of [Mayflower documentation][mayflower-doc], two component libraries — [Mayflower React][react-storybook] and [Mayflower PatternLab][patternLab], and their [shared assets][shared-assets].
-  > Refer to [Mayflower PatternLab Static Site][patternlab] for the set of UI components consumed in Mass.gov.
-- **Live demo:** [mayflower-react storybook][react-storybook]
-
-## Using Mayflower-Tokens in Your Project
-1. Install mayflower-tokens into your project as a dependency.
-`npm i @massds/mayflower-tokens --save`
-2. Import color tokens into your SASS/SCSS file
-`@import '[path to node_modules]/@massds/mayflower-tokens/colors/mayflower-color_tokens';`
-3. Refer to variables in `@massds/mayflower-tokens/colors/_mayflower-color_tokens.scss` or a [live demo for the colors](https://mayflower.digital.mass.gov/react/?path=/story/brand-colors--colors) to map the Mayflower color tokens in your theming SCSS.
-4. You can also find the web fonts Texta that are used in Mayflower (please)
-To import into your styles, refer to [mayflower Texta font imports](https://github.com/massgov/mayflower/blob/develop/assets/scss/00-base/_fonts.scss).
+# Mayflower Assets
+The styles provided by this package require compiling with a tool that supports the [npm sass package](https://www.npmjs.com/package/sass). 
 
 ## License
 Please note that the fonts and the svg-icons are licensed only for the usage on websites that are **owned by the Commonwealth of Massachusetts**. Mayflower is currently using a licensed web font Texta and purchased [Smashing Icons](https://smashicons.com/) for some icons.
 
-### Texta License
+## Texta License
 Fontspring grants Licensee a perpetual, worldwide, non-exclusive and non-transferrable license to install the Texta as webfont on Websites that are owned by the Commonwealth of Massachusetts using the @font-face selector in CSS files. For other usage, you may have to acquire an additional license through Fontsprint.
 For more details about Texta's terms of use, please refer to our [web font license](https://www.fontspring.com/lic/htswufoczd).
 
-## Publish Package
+## Publishing Instructions
+>To publish the package, you will have to be a collaborator or have access to the [@massds/mayflower-assets npm package](https://www.npmjs.com/package/@massds/mayflower-assets).
 
-1. `npm login` — Login to the npm account.
->To publish the package, you will have to be a collaborator or have access to the [@massds/mayflower-tokens npm package](https://www.npmjs.com/package/@massds/mayflower-tokens).
+1. Once you're done making changes and ready to publish, run `npm login` to login to the npm account.
+2. Update `version` in package.json and run `npm publish`. Wait a few minutes and check [@massds/mayflower-assets](https://www.npmjs.com/package/@massds/mayflower-assets) on the npm registry.
 
-1. `npm run build` — Build the distribution folder `dist`.
 
-1. Update `version` in package.json.
-1. `npm publish` — Publish `@massds/mayflower-tokens` to npm registry.å
-1. Wait a few minutes and check [@massds/mayflower-tokens][npm] on the registry.
 
+## Setup and Usage (fonts/images)
+If you're using this package only for its fonts and images, you can skip installing bourbon and sass. Assets can be found under `fonts` and `images`.
 
-[npm-badge]: https://img.shields.io/npm/v/@massds/mayflower-react.png?style=flat-square
-[npm]: https://www.npmjs.com/package/@massds/mayflower-tokens
-[mayflower-github]: https://github.com/massgov/mayflower
-[mayflower-doc]: https://www.mass.gov/mayflower
-[react-storybook]: https://mayflower.digital.mass.gov/react
-[react-starter]: https://github.com/massgov/mayflower-react-starter
-[patternlab]: https://mayflower.digital.mass.gov/patternlab
-[shared-assets]: https://github.com/massgov/mayflower/tree/develop/assets
+## Setup and Usage (Sass)
+When using this package for the .scss files, you should set the sass package's include paths to include bourbon's include paths as well as this package's own. This package's include paths are:
+```
+scss
+scss/00-base
+scss/00-base/mixins
+scss/01-atoms
+scss/03-organisms
+scss/04-templates
+scss/05-dataviz
+scss/08-print
+```
+These include paths allow you to include files with paths like `00-base/name-of-file` in your code.
+
+You can also set up your include paths by using an `.env` file at the root of your project. Sass can use the node environment variable `SASS_PATH` for setting your include paths:
+```
+// .env file
+SASS_PATH=./node_modules/@massds/mayflower-assets/scss:./node_modules/@massds/mayflower-assets/scss/00-base:./node_modules/@massds/mayflower-assets/scss/00-base/mixins:./node_modules/@massds/mayflower-assets/scss/01-atoms:./node_modules/@massds/mayflower-assets/scss/02-molecules:./node_modules/@massds/mayflower-assets/scss/03-organisms:./node_modules/@massds/mayflower-assets/scss/04-templates/./node_modules/@massds/mayflower-assets/scss/05-dataviz:./node_modules/@massds/mayflower-assets/scss/08-print
+```
+
+Many of the components require the file `00-base/_layout.scss` to be included at least once before their use. It's recommended for your project to create a single .scss file that includes all the shared files for your needs. This file should use `@forward` to forward sass modules that your other files need:
+```
+// example.scss
+
+// Assuming 'node_modules' is your include paths here...
+// forwards the normalize-scss library's normalize styling.
+@forward "normalize-scss/sass/normalize";
+@forward "00-base/layout";
+// Let all your scss files have access to colors without having to remember that.
+@forward "00-base/colors";
+// Grab the fonts from this package for inclusion:
+@forward "00-base/fonts";
+```
+```
+// some-other-file.scss
+
+// This path depends on what's in your include paths...
+@use "path/to/example.scss" as *;
+// You can also scope it:
+@use "path/to/example.scss";
+.elementClass {
+  ... rules go here ...
+}
+```
+Creating a shared file is NOT required. You can also just ensure that you include the box-sizing styling:
+```
+// some-other-file.scss
+@use "00-base/layout";
+.elementClass {
+  ... rules go here ...
+}
+```
+## Including SCSS Files
+To include a `.scss` file, please do NOT use `@import`. All previous uses of `@import` have been replaced by `@use` for [Sass Modules](https://sass-lang.com/documentation/at-rules/use) support:
+```
+// Scoped inclusion of variables. All variables will now
+// be under the variables scope.
+@use "00-base/variables";
+$my-new-var: variables.$column;
+// Or you can do this to place all variables
+// in the global scope for the file:
+@use "00-base/variables" as *;
+$my-new-var: $column;
+```
+## Variable Overrides
+All provided variables of this package allow for overrides by the user:
+```
+// You can define your overrides before the @use call.
+// Doing so will ensure the file you're calling with @use uses the overrides.
+$column: 60px;
+@use "00-base/variables";
+// You can also just pass the override to the file you're calling @use on:
+@use "00-base/variables" with (
+  $column: 60px;
+);
+```
+## Recommended Fonts
+Some reccomended fonts you can use can be found under `00-base/fonts`.
+## Example Compilation of Styles
+
+The following example uses gulp to compile all .scss files under src (with exceptions to those .scss files under `00-base/`). The script will place the compiled files under `dist/` within the same directories they originated.
+```
+// gulpfile.js
+const { src, dest, series } = require('gulp');
+const sass = require('gulp-sass');
+const rename = require('gulp-rename');
+const flatmap = require('gulp-flatmap');
+const del = require('del');
+const bourbon = require('bourbon');
+const path = require('path');
+// Replaces node_sass with sass.
+sass.compiler = require('sass');
+
+const compileSass = () => {
+  return src([
+    // Compile all scss files
+    './src/scss/**/*.scss',
+    // But skip over base directory files.
+    '!./src/scss/00-base/**'
+  ])
+  .pipe(rename(function(assetPath) {
+    // Sass will not compile files that start with an underscore,
+    // so rename them to remove it.
+    assetPath.basename = assetPath.basename.replace('_', '');
+    return assetPath;
+  }))
+  // Loops over all files in the stream with flatmap.
+  .pipe(flatmap((stream, file) => {
+    // Normally you should require/import the index file
+    // to get the includePaths used but that points to 
+    // the dist/ directory. Here we mimic that by just replacing
+    // dist/ with src/.
+    return stream
+
+    .pipe(sass({
+      includePaths: [
+        path.join(__dirname, 'src'),
+        path.join(__dirname, 'src/scss'),
+        path.join(__dirname, 'src/scss/00-base'),
+        path.join(__dirname, 'src/scss/00-base/mixins'),
+        path.join(__dirname, 'src/scss/01-atoms'),
+        path.join(__dirname, 'src/scss/03-organisms'),
+        path.join(__dirname, 'src/scss/04-templates'),
+        path.join(__dirname, 'src/scss/05-dataviz'),
+        path.join(__dirname, 'src/scss/08-print'),
+        'node_modules',
+      ],
+    }).on('error', sass.logError))
+    .on('error', (err) => console.log(err))
+  }))
+  .pipe(dest('./dist/css'));
+};
+exports.default = series(compileSass);
+
+```
+## Development with Assets Package
+When working on changing styling, you can use `npm link` with another project so that changes made to `.scss` files show up live time. First, run `npm link` under the mayflower repo's assets directory. Next, in your other project's root directory run `npm link @massds/mayflower-assets`. This will make it so that under node_modules for your project, this package is symlinked (from @massds/mayflower-assets) to the mayflower repo's assets directory.

assets/index.js

@@ -0,0 +1,14 @@
+var path = require("path");
+
+module.exports = {
+  includePaths: [
+    path.join(__dirname, 'scss'),
+    path.join(__dirname, 'scss/00-base'),
+    path.join(__dirname, 'scss/00-base/mixins'),
+    path.join(__dirname, 'scss/01-atoms'),
+    path.join(__dirname, 'scss/03-organisms'),
+    path.join(__dirname, 'scss/04-templates'),
+    path.join(__dirname, 'scss/05-dataviz'),
+    path.join(__dirname, 'scss/08-print'),
+  ]
+};