Spruce tries to be customizable and straightforward. On this page, you can find some core principles and the structure.
Coding Style Guide and Practices
- Where it is possible, we use elements and/or attributes to style elements, but it is still a class-based framework.
- We use Stylelint with a modified configuration with stylelint-config-sass-guidelines preset to quality control.
- We alphabetize the property declaration order. It is practical, no joke.
- We use mostly BEM when a more complicated structure is necessary.
- We try not to use px as units. Right now, it is only present at border values.
- We use modern Sass with
@use
and@forward
.
BEM (Block Element Modifier)
For writing complex components, we use BEM, a simple naming convention that helps to create manageable code. A simple example looks like this:
- Block: a component element, like
.btn
. - Element: a child element of the component like
.btn__icon
. - Modifier: a flag that someway modifies the component like
.btn--primary
.
Class vs. Classless Frameworks
A classless framework doesnβt specify classes and special markup for your elements. You use regular HTML elements. The advantage is that you only need to load a CSS file and get many styling right away.
We think this approach has more problems in the long run, so we use classes. Of course, we also style just elements where it is convenient (like text-related elements).
The Source Code of Spruce
Spruce uses npm scripts to compile Sass and to do other tasks. You can see all of the scripts in the package.json file.
Our two main scripts are:
npm run dev
is for development purposes. It will fire up the development preview (which is a sandbox for us), a pug-based, simple HTML page where you can see all the styled elements.npm run prod
is for production. It will create the right compiled CSS files.
The Structure of the Project
You can find the main code under the scss
folder at the root. The .vscode
folder contains a VS Code configuration file. The preview
folder is a developer helper where we can see the effect of the modification right away.
scsssprucecss/ββ .vscode/ββ css/ // Compiled CSS folderβ ββ spruce.cssβ ββ spruce.min.cssββ js/| |- cookie.jsββ preview/ // Spruce preview for developmentβ ββ ...ββ scss/ // Source .scss files, Spruce CSS itselfβ ββ config/ // Variablesβ ββ element/β ββ form/β ββ function/β ββ mixin/β ββ plugin/β ββ ...β ββ spruce.scssββ .gitignoreββ package.jsonββ README.mdββ ...
If you plan to contribute first, please visit our contributon. Thank you!
Browser Support
Spruce uses Autoprefixer with the default configurations.
The browser support is not set in stone, but one of the goals of this framework is to be a modern one. We will plan to support new features early, but we understand the browser landscape is not so simple. Please open an issue if you have any questions or ideas regarding this topic.