TGAM Pattern Library Documentation

Importing pattern library SASS into your project

1. Install a SASS compiler

You’ll need to setup an asset pipeline in order to compile your SASS into CSS:

Install a SASS compiler, such as sass, gulp-sass, and configure it to compile your SASS files (refer to your chosen compiler’s documentation for details).

2. Install PostCSS

You may also need to install the postcss and postcss-url NPM packages, in order to process the asset file paths in the SASS files from the node_modules/tgam-patterns/patterns/stylesheets directory.

Alternatively, if you’re using Webpack to bundle your CSS, then you probably won’t need to install PostCSS for this purpose because Webpack is capable of resolving asset file paths in your SASS files.

Sample SASS compilation pipeline using ‘postcss-url’

Below is a basic example of how to configure postcss-url to transform the asset file paths in your CSS:

var sass = require("sass");
var postcss = require("postcss");
var postcssUrl = require("postcss-url");

sass.render(
  {
    file: "input.scss",
    outFile: "output.css"
  },
  function(error, result) {
    if (error) {
      console.error(error.message);
    } else {
      var compiledCSS = result.css.toString();
      postcss([
        postcssUrl({
          url: function(asset) {
            return asset.url
              .replace("~patterns/fonts", "/your-project-assets-path/fonts")
              .replace("~patterns/images", "/your-project-assets-path/images");
          }
        })
      ])
      .process(compiledCSS, {
        from: "output.css",
        to: "output-final.css"
      })
      .then(function(result) {
        // TODO: Save this CSS to a file and include it on your page
      })
      .catch(e) => {
        console.error(e);
      });
    }
  }
);

This pipeline makes it possible to process paths prefixed with the ~ character in your SASS files, and convert them into proper file paths. For example, using the above configuration, this:

background-image: url("~patterns/images/logo.png");

Would be transformed into this:

background-image: url("/your-project-assets-path/images/logo.png");

This ability to prepend base URLs to assets that are referenced from inside the pattern library CSS is vital because the pattern library has no knowledge of the directory structure of the projects that consume it, or the environment where the files have been deployed. Without this ability to specify different asset URLs for each product, then every product that consumes the pattern library CSS would be required to share the use directory structure.