Kinderopvang Brussel Styleguide
This is the styleguide for Kinderopvang Brussel.
Setup
Installation
- Clone the repo.
- Install nvm https://jamesauble.medium.com/install-nvm-on-mac-with-brew-adb921fb92cc
- Install correct node version
15 - Swith to correct node version
nvm use 15 - Install node modules
npm install - Make sure node-sass bindings are build
npm rebuild node-sass
Run
To start the styleguide just run node_modules/.bin/gulp dev. This will compile the styleguide and start a local server on http://localhost:8090.
Build
If you only want to compile/build the css you can run node_modules/.bin/gulp dist. This will only compile all of the sass and copies the images/fonts to the dist folder without starting the local server and generating the styleguide.
Deploy
Deploying a new release is fully automated via Github Actions.
Deployment flow
These are steps you need to do to start up a release deploy.
- Update the version in
package.json. The version should be identical as the tag you are going to use for the release in github. Just so the release numbers stay in sync. - Add a new tag ex:
git tag v1.0.1. - Push out the new tag ex.:
git push origin --tags.
That's all there is to it. This will trigger a github action that will create a release in github for the pushed tag. When the release is published then this will in turn trigger an action that will compile the styleguide, update the gh-pages and publish this to NPM.
Code structure
Basic structure
After you npm install and run node_modules/.bin/gulp dev for the first time, you'll have a folder structure like this.
-
root
- node_modules
- dist - where your compiled and autoprefixed styles will go.
- images - Contains all of our images/icons we use. These get copied to the dist folder when compiling the css.
- fonts - Contains all of our custom fonts. These get copied to the dist folder when compiling the css.
- sass - where your style files go.
- styleguide - where your style library is generated.
BEM notation
We use the BEM notation in our stylefiles. This has a few advantages:
- Avoids inheritance and provides some sort of scope by using unique CSS classes per element (like
.my-component__list-item). - Reduces style conflicts by keeping CSS specificity to a minimum level.
For more information about BEM you can get out their documentation
SASS Structure
To seperate the styles in a logical way, we use the atomic design system. Just a quick overview of atomic design:
Atomic design is a methodology composed of five distinct stages working together to create interface design systems in a more deliberate and hierarchical manner. The five stages of atomic design are:
- Atoms
- Atoms of our interfaces serve as the foundational building blocks that comprise all our user interfaces. These atoms include basic HTML elements like form labels, inputs, buttons, and others that can’t be broken down any further without ceasing to be functional.
- Molecules
- Molecules are relatively simple groups of UI elements functioning together as a unit. For example, a form label, search input, and button can join together to create a search form molecule.
- Organisms
- Organisms are relatively complex UI components composed of groups of molecules and/or atoms and/or other organisms. These organisms form distinct sections of an interface. (example: header containing search form)
- Templates
- Templates are page-level objects that place components into a layout and articulate the design’s underlying content structure. To build on our previous example, we can take the header organism and apply it to a homepage template.
- Pages
- Pages are specific instances of templates that show what a UI looks like with real representative content in place. Building on our previous example, we can take the homepage template and pour representative text, images, and media into the template to show real content in action.
Dependencies
We use the following dependencies:
- Normalize.css To set up the same starting environment cross-browser.
- jQuery We use this as our javascript platform.