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

Branches

We follow the typical "branch, develop, submit merge request" flow of development. Here is an overview of our branch names:

• main: This is the default branch that you will see in the GitLab interface and what should be used when starting work on a new branch and what you should (typically) set as the "base" branch when creating a merge request. Your work must be integrated into this branch in order to be released.
• next: This branch is merged into from main when we want to push a "regular" @next dist-tag release (more info). This would result in a package that you can install via npm install @gn-as/styles@next, but it would not install on the "typical" npm install @gn-as/styles command. When the @next release is ready for an "official" standard release, we would merge @next into the release branch.
  • Note that in the event that we didn't need to "hide" a release under the @next dist tag, you can just go directly from main into @release to get a standard (visible) release.
• release: The main (or next) branch is merged into this branch when we are ready to cut a new release. Therefore, unless you are interested in generating a new release (from the main branch), this should not be set as the "destination" branch in a merge request and should be the parent of any branches you create. It should never be set as the "base" branch in a Merge Request either.
• other branches: Create forks or branches as you like. If you don't "own" the branch, don't rebase it. If you are collaborating with people on a branch, be a good citizen (don't rebase unless you've confirmed with them, etc).

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