VCU Compass Web Framework

Guidelines

Compass brandmark

Compass v1.4.0

The university web framework. This repository holds the source files of core Compass assets.

Table of contents

  1. Install as an NPM dependency
    1. Install via VCU’s NPM registry
      1. Updating your default registry
      2. Install via default registry
    2. Install via Git
    3. Importing JS
    4. Using SCSS
  2. Clone the repo
    1. Requirements
    2. Development
    3. Browser support
  3. Guidelines
    1. Development and production modes
    2. JS
    3. SCSS
    4. Twig
    5. Linting and formatting
  4. Contributing

Install as an NPM dependency

You can include Compass as an NPM dependency in your next project, allowing you to pull in just the HTML, JS, or SCSS that you need.

Install via VCU’s NPM registry

The easiest way to include Compass as an NPM dependency in your next project is through VCU’s NPM registry. Compass is hosted on a private software distribution server, and installing it via this method requires you to be on VCU’s network.

npm install cwf --registry=https://nexus.ts.vcu.edu/repository/vcu-npm/

Updating your default registry

To avoid having to include the registry flag every time you install Compass, set your global or project’s NPM registry to VCU’s NPM registry. Our recommendation is to use VCU’s NPM registry globally, as it’s the simplest solution with little-to-no project maintenance.

# Global configuration
echo 'registry=https://nexus.ts.vcu.edu/repository/vcu-npm/' > ~/.npmrc

# Project configuration
cd my-project
echo 'registry=https://nexus.ts.vcu.edu/repository/vcu-npm/' > .npmrc

Install via default registry

With VCU’s NPM registry set as your default, you can now install Compass like any other package.

npm install cwf

Install via Git

If you don’t want to use VCU’s NPM registry, you can install Compass as an NPM dependency from our SCM repo via Git.

npm install git+ssh://git@scm.vcu.edu:7999/cwf/core.git

We don’t recommend this option, as installing via Git causes maintenance issues, such as no version tracking (so NPM will always say Compass is outdated).

Importing JS

If you’re using a build-system that uses something like Webpack with support for ES2015+ modules, you can import any Compass component JS as follows:

// Nav class (default)
import Nav from 'cwf/components/nav';

// Nav class (explicit)
import { Nav } from 'cwf/components/nav';

// Nav class (from all components)
import { Nav } from 'cwf/components';

You can also import all component JS classes as an array:

// All component classes (default)
import components from 'cwf/components';

// All component classes (explicit)
import { components } from 'cwf/components';

If you want to include and run all Compass JS (resets and components), just import the whole package:

// All Compass JS
import 'cwf';

Using SCSS

You can use any Compass SCSS files as follows:

// Nav styles
@use 'path/to/node_modules/cwf/components/nav';

Compass uses the sass compiler instead of the default but deprecated node-sass compiler for compiling SCSS to CSS. This allows us to use new, powerful syntax when writing SCSS. An example of such syntax is our use of the new @use module imports, which future-proofs the project and allows for better namespacing.

You can avoid having to type the full path to Compass within the node_modules directory by resolving its path within your build system. For Gulp (which is what Compass uses for converting SCSS to CSS), you can do the following within your SCSS task:

...
.pipe(gulpSass({
    includePaths: [ 'node_modules' ]
}))
...

This allows you to write the following, which is much simpler and easier to remember:

// Nav styles (with node_modules path resolved)
@use "cwf/components/nav";

You can also use all component SCSS as follows:

// Component styles (with node_modules path resolved)
@use "cwf/components";

If you want to use all Compass SCSS (resets, utilities, and components), just use the whole package:

// All Compass styles (with node_modules path resolved)
@use "cwf";

Clone the repo

To install the repo as an easy way to bootstrap your static Compass site development, clone the repo and install all the required dependencies.

git clone ssh://git@scm.vcu.edu:7999/cwf/core.git compass-web-framework
cd compass-web-framework
npm i

Requirements

This repo was setup using the long-term support release of Node, which at the time of writing is v14.16.1, and NPM v7.11.1. While you may have little to no issues setting up and running the repo with a newer version of Node, this has not been tested. To make this process easier, we recommend using nvm to manage Node versions, as this repo includes an .nvmrc to tell nvm which Node version to use when working within the project.

Development

# To develop assets and live-reload them locally
npm run develop
npm run dev
npm run start

# To build production assets...
npm run build
# ... and then to see them locally
npm run serve

Browser support

At the time of writing, this project supports the last two major versions of Chrome, Edge, Firefox, Opera and Safari as noted in the project’s package.json:

defaults and last 2 versions, not Explorer <= 11, not ExplorerMobile 11

A full list of supported browsers can be visualized at browserl.ist.

The grid component utilizes features that will not work in Baidu/Opera Mini browsers.

Information regarding Compass’ lack of Internet Explorer support is documented on the FAQ page of our main site.

Guidelines

As the project progresses and grows, it’s important to ensure consistency in the way the code is written and structured. The following are guidelines on how best to do so.

Development and production modes

Compass’ build system has two distinct modes: development and production. Development mode will build out the assets unminified, and is useful for testing purposes. Production mode will build out the assets minified and altered (such as the removal of redundant code or the simplification of variable names), and is used for implementation in production. Commands such as develop, dev, or start are automatically ran in development mode, whereas build is automatically ran in production mode.

  • Assets built in development mode should never be used for production.
  • Development mode can be explicitly set by prefixing any command with NODE_ENV=development.
  • Production mode can be explicitly set by prefixing any command with NODE_ENV=production.

JS

Javascript is to be written in vanilla, ES2015+ syntax; This is to ensure the JS is future proof, clean, and compartmentalized. This is converted to JS targeted for the browsers found in the browsers list in the package.json using the Gulp build system.

When writing JS, try and make things reusable by bundling functional logic in a module to later be imported in. In addition, do not use JS frameworks and only use JS dependencies through NPM where absolutely necessary. In addition, please have an ESLint linter running to enforce code style.

JS can be transpiled separately by running npx gulp js.

SCSS

SCSS is to be written as opposed to SASS; This is to ensure it’s closer to vanilla CSS which helps with onboarding. This is converted to CSS using the Gulp build system, which does the following:

  1. Adds vendor prefixes to rules using the browsers list found in the package.json
  2. Minifies the CSS (on production builds only)

The SCSS should be divided up into partials associated with components, utilities, or resets, and follow a BEM structure. This BEM structure is to use double underscores/dashes and no block nesting (or grandchild selectors) when writing classes. Try to keep class nesting to a minimum. Compass-specific classes must be prefixed with cwf-. Media queries are to be written using the bubbling method, as it is considered industry standard when using SASS/SCSS. Finally, do not use SASS/SCSS frameworks. SCSS partials should include variables and mixins explicitly, as it allows users to pick and choose which partials to pull in without having to a). pull in all of Compass, or b). know what variables/mixins to pull in along with it (see the components/card/_index.scss partial as an example). All functions and mixins within an SCSS partial should have error handling where applicable.

SCSS can be transpiled separately by running npx gulp scss.

Twig

Twig is an HTML templating engine, and this repo uses a Twig.js implementation for Gulp. This allows for easy templating integration and seperating of data/structure. Components and layouts should be within different folders. It is encouraged to download syntax highlighting for Twig in your code editor of choice. It should be noted that at the time of writing, the Gulp implementation of Twig.js used (gulp-twig) hasn’t been regularly maintained; Should you run into any problems templating HTML assets, inform the Compass team of the problem.

HTML can be transpiled separately by running npx run twig.

Linting and formatting

JS linting is handled through ESLint. This can be utilized by your code editor of choice, or can be manually ran using the npm run lint script. The ESLint configuration includes but is not limited to:

  1. Expects import/export modules instead of CommonJS modules
  2. 4-space indents
  3. Unix line-breaks
  4. Single quotes instead of double quotes
  5. Semicolons required

There are pre-commit Git hooks that will lint your JS files (see above) and check to see if all source files are formatted correctly (see below) before committing.

Formatting of all source files is handled through Prettier. This can be manually checked using npm run check and ran using the npm run format script. The Prettier configuration includes, but is not limited to:

  1. Ensures a blank final line appears
  2. Ensures Twig syntax can be parsed and formatted
  3. Semicolons are required (JS)
  4. Single quotes are preferred over double quotes (JS)
  5. 4-space indents
  6. Removes trailing commas

Contributing

If you are contributing to this project, please be sure to follow the above guidelines. In addition, please add your name to the contributors array found within the package.json file, the format of which should be First Last <email>.