Tuleap uses Sass for its CSS generation.
SCSS files are just extended CSS files. It means you can use variables, functions, operations and more in CSS files very easily. It’s fully backward compatible with exiting CSS files (you can rename file.css to file.scss, compile file.scss and it’ll just work).
Please refer to the Sass documentation for more information.
SCSS files should always go in “themes” folders.
For the core, it should go in
For plugins, it should go in
Compile SCSS files
From the root directory of the Tuleap sources:
$ pnpm install $ pnpm run build
This command will compile all SCSS files present in
you have to run
pnpm run buildevery time you edit a SCSS file.
CSS files will be git-ignored. Don’t edit them manually.
If you are working in Tuleap “core”, change your current directory to
src/ to run the “pnpm” commands.
If you are working in a plugin for Tuleap, change your current directory to the “root” of that plugin in
plugins/<my-plugin>/ to run the “pnpm” commands.
While you are working, the following command should help you:
$ pnpm run watch
pnpm run watch will automatically rebuild CSS after changes.
Best practices for Tuleap
When you submit a patch for review, we may request changes to better match the following best practices. Please try to follow them.
Files best practices
Never use the
Always use a SCSS file. No
Split your SCSS files into multiple partials files. Smaller files are easier to understand and review. You can then
@usethem from your main SCSS file.
File names for partials should always start with an “underscore” character, for example:
When you prepend a Copyright block at the beginning of a SCSS file, never use the
/*!style of comments. Those comments are output in compressed CSS. This makes them a lot larger for no benefit, because all included files will each add 30 lines of copyright to the final CSS file. Always use
/**. See the Sass documentation on comments.
Rules best practices
Prefer class to ID as a selector. Classes have lower specificity, so when someone really needs to override the style you had set, they don’t have to create crazy rules or worse, use
For the same reason, don’t use
!important. It’s impossible to override.
Always prefix class names by the plugin (or the general view) you are in. For example, when working in the Git plugin, prefix all class names with
Use naming to indicate where the selector is. For example:
<div class="git-repository-list"> <section class="git-repository-card"> <div class="git-repository-card-header"> <!-- ... -->
The long names help us avoid name-clashing with another plugin and help get a sense of where the rule is applied when reading Sass files.
Don’t use the descendant combinator, for example
.class1 .class2. It hurts performances because when the browser gets to “class2”, it will have to recursively find all its ancestors to see if they are “class1”.
For the same performance reason, if possible avoid using the child combinator, for example
.class1 > .class2.
Instead, use a single specific class name that targets precisely what you want.