Working with staff client SCSS
From Koha Wiki
The staff client's default (prog) template uses Sass files in SCSS format to generate the CSS files used in the theme. Sass is a "CSS extension" (similar to LESS) which allows authors to use "variables, mixins, operations and functions." The staff client's Sass files contain some use of variables and mixins, but their primary difference from standard CSS is the logical grouping of style rules through nested rules.
When making CSS changes to the staff client, changes should be made to the .scss files, not the .css files.
As of 2018-01-30 the only Sass file in the staff client is
Setting up your development environment
sudo apt-get install nodejs npm [not necessary in kohadevbox] sudo npm install -g yarn yarn install yarn build
Compiling Sass files
After you have made changes to staff-global.scss, compile your changes by running
yarn build again.
yarn build process automatically compiles SCSS to CSS, adds automatic vendor prefixing, and minifies the CSS.
There is also a
yarn css command available which might be used by
developers who are making changes to Sass. This command does two things
- Adds .css.map files which aid CSS debugging using in-browser inspector tools.
- Compiles staff-global.css without minification. It can be useful to see unminified CSS during development, especially to see how SCSS compiles.
The build process includes a tool called autoprefixer, used to "parse CSS and add vendor prefixes to CSS rules using values from Can I Use." autoprefixer is run without any explicit options. The default configuration adds automatic vendor prefixes in order to provide coverage for:
- Browsers with greater than 1% global usage
- The last 2 versions of browsers
- Firefox ESR.
This tool eliminates the necessity of adding vendor prefixes to SCSS code.
Guidelines for editing Sass files
staff-global.scss differs from the old staff-global.css primarily in that it uses nested syntax. There are two other Sass-specific features to note:
- Some variables are defined near the top of the file. These variables can be used in place of the strings which define them.
- Some mixins are defined.
When adding style rules to Sass files please look for existing rules in which your additions might be logically nested. Remember that nesting adds specificity to your CSS, which may not be necessary for the style you want to achieve. The minimum required specificity is recommended.
Adding Sass files
To add a new CSS file to the staff client, simply create the corresponding .scss file in the
css/src directory. Each
.scss file in the staff client's
css/src directory is automatically compiled, minified, and saved to the
.sass-lint.yml is a set of rules for writing consistent SCSS. It is a configuration file for linting SCSS with sass-lint. Various code editors can be set up to do inline SCSS linting, or it can be done on the command line. Currently staff-global.scss does not pass all sass-lint tests. New additions should.
See Sass lint rules for information about some notable rules.