styleguide: A SCSS repository from Fermyon

A live design reference manual for Fermyon-related materials.

Styleguides are real-life pattern libraries, code standards documents and content style guides — styleguides.io, a wonderful collection.

This styleguide is built as a living, working codebase rather than a simple reference document. It is published as an npm package, so it can be easily imported into other projects and applied as a baseline branded CSS layer.

The styleguide also contains a /docs page (visible here as a website), which contains our brand guidelines, logos, and design resources.

Using The Styleguide

1. Add the styleguide to your project:

npm install -D @fermyon/styleguide
npm install

2. Once installed, the core `.scss` file can be imported into your project stylesheet as a dependency:

@import "../../node_modules/@fermyon/styleguide/scss/fermyon";

You can see examples of the styleguide being imported into other projects here (fermyon.com site) and here (Spin docs).

3. Re-Compiling Sass to CSS

If your project requires the addition of special, localized styles (which is pretty common), they can be added to your stylesheet underneath the imports shown above. You'll need to re-compile the styles to generate your CSS.

This will likely require the addition of asset build configuration to your project — which depends on the particulars of which tools are being used to generate and run that site/app (for us, that usually means Bartholomew).

Example using vanilla Sass (see fermyon.com here):

sass --watch static/sass/styles.scss static/css/style.css --style compressed

Example using Parcel JS: (see Spin docs):

npx parcel build static/sass/styles.scss --dist-dir static/css --no-optimize

4. Alternatively, just use the CSS as-is:

You can avoid working with Sass/Scss and just use the styleguide as-is by importing the CSS version (along with Bulma) directly into your page. Copy the css/fermyon.css file from the styleguide into your project and include it in the head of the page:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bulma/0.9.3/css/bulma.min.css"
        integrity="sha512-IgmDkwzs96t4SrChW29No3NXBIBv8baW490zk5aXvhCD8vuZM3yUSkbyTBcXohkySecyzIrUwiF/qV0cuPcL3Q==" crossorigin="anonymous" referrerpolicy="no-referrer" />
<link href="https://fonts.googleapis.com/css2?family=Sen:wght@400;700&amp;display=swap" rel="stylesheet" />
<link rel="stylesheet" href="YOUR_PROJECT_FILEPATH/fermyon.css" />

Note: the CSS should be linked after (i) the bulma.min.css and (ii) Sen webfont CDN requests, as shown above.

Working on Styleguide

To build the styleguide assets, and open the docs/index.html page run:

cd docs
npm run dev

If you just want to rebuild CSS your edits, run:

npm run styles

Changes can be viewed and tested at http://localhost:1234/.

When you have made edits, please commit the updated CSS (css/fermyon.css) in addition to any .scss changes.

fermyon/styleguide