GN Advanced Science Styles

The aim of this project is to enable the GN Advanced Science organization to have a single source of truth for GN Advanced Science-related 'styles'.

Specifically, those styles relating to websites and web applications.

Installation

The official release can be installed by executing:

npm install @gn-as/styles

To install the "cutting edge" release, execute:

npm install @gn-as/styles@next

Usage

Applications with asset bundlers (Vite, Grunt, etc)

More information on this coming soon. However, if you are using a modern application bundler like Vite, WebPack, or Grunt, you should be able to simply import the way you would CSS from any other NPM module that ships with CSS.

In the case of Vite (in a Svelte codebase), this amounts to:

<script>
  import '@gn-as/styles/color.css'
  ...
</script>

Static/Legacy web applications/sites

If you have the ability to leverage NodeJS modules, you can get the current version of the styes into your local codebase via:

npm install @gn-as/styles

If you don't have this option, you can download your preferred release from the releases page. Alternatively, you can use a hosted version from Unpkg if necessary (not suggested for production deployments).

After you have decided where you want to host the actual CSS files, using the library is just like using any other CSS file...just include a link tag as you normally would. For example:

<link rel="stylesheet" href="/styles/gn-as/styles/app.css" type="text/css" />

Note for legacy applications

You may want to integrate the @gn-as/styles library slowly to avoid a major rewrite of all your markup and CSS rules. To simplify this process and avoid rule/naming conflicts, we release a "scoped" version of all CSS files (other than the color variable definitions). The "scoped" rules are all nested under a class of owlie, allowing you to isolate the impact to specific elements or pages in your application. The directory structure and file names are identical with the exception that all "scoped" CSS files are located inside a "scoped" directory. Therefore, if you copied all the CSS files from package into a /styles/gn-as directory, you would reference the top-level app.css file like this:

<link rel="stylesheet" href="/styles/gn-as/app.css" type="text/css" />

...and the scoped version would be available like this:

<link rel="stylesheet" href="/styles/gn-as/scoped/app.css" type="text/css" />

Usage example:

<link rel="stylesheet" href="/styles/gn-as/styles/scoped/app.css" type="text/css" />

...
<main>
  <p>This element would retain your application's styling rules.</p>
</main>

<main class="owlie">
  <p>Only this element would inherit the "gn-as/styles" styling rules.</p>
</main>

Developer notes

Development/Release process

This project uses the RCE Release Assistant. This means:

1. Commits should follow Conventional Commits
2. Merges to main will trigger a standard release (if commit messages dictate doing so)
3. Merges to alpha will trigger a pre-release (if commit messages dictate doing so)

Please refer to the Release Assistant docs for more details.

Tooling

Although the repository is comprised of CSS files, there are a few development tools installed to ensure we maintain a consistent codebase. You will want to install NPM dependencies:

npm install

Versioning

We follow the Semantic Versioning software versioning specification (see semver.org).

All releases are automatically generated and version numbering are based on commit messages (see below).

Commit message formatting

We follow the Conventional Commits specification on commit messages. The tooling installed (Husky, et al) will verify the format of your commit message, so if you are not familiar with Conventional Commits...there are guard rails to help you out.

CSS formatting

We have common configuration files in place that most editors should automatically both recognize and honor (.prettierrc, etc) as you are editing. There is also a commit hook that will fix/lint all files being committed so again, there are guard rails.

If you'd like to run a format-check across all CSS files, you can run:

npm run check-css

If you'd like to both check and write the fixes across all CSS files, you can issue:

npm run format-css