General GN Advanced Science styles package
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.
The official release can be installed by executing:
``bash`
npm install @gn-as/styles
To install the "cutting edge" release, execute:
`bash`
npm install @gn-as/styles@next
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:
`html`
If you have the ability to leverage NodeJS modules, you can get the current
version of the styes into your local codebase via:
`bash`
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:
`html`
You may want to integrate the @gn-as/styles library slowly to avoid a majorowlie
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 , allowing you to isolate the impact to specific elements or/styles/gn-as
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 directory, you would reference the top-level app.css file like
this:
`html`
...and the scoped version would be available like this:
`html`
Usage example:
`html
... This element would retain your application's styling rules.
Only this element would inherit the "gn-as/styles" styling rules.
`
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@next
"regular" dist-tag releasenpm install @gn-as/styles@next
(more info).
This would result in a package that you can install via , but it would not install on the "typical" npm install @gn-as/styles command. When the @next release is ready for an "official"@next
standard release, we would merge _into_ the release branch.@next
- _Note that in the event that we didn't need to "hide" a release under the
dist tag, you can just go directly from main into @release torelease
get a standard (visible) release._
- : The main (or next) branch is merged _into_ this branch whenmain
we are ready to cut a new release. Therefore, unless you are interested in
generating a new release (from the 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).
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:
`bash`
npm install
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).
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.
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:
`bash`
npm run check-css
If you'd like to both check and _write_ the fixes across all CSS files, you can
issue:
`bash``
npm run format-css
---
[husky]: https://typicode.github.io/husky
[semver.org]: https://semver.org/
[conventional commits]: https://www.conventionalcommits.org/
[webpack]: https://webpack.js.org/
[vite]: https://vitejs.dev/
[svelte]: http://svelte.dev/
[grunt]: https://gruntjs.com/
[releases page]: https://gitlab.com/gn-as/styles/-/releases
[unpkg]: https://unpkg.com