I welcome pull requests from anyone. This guide will prepare you for making your first pull request, and will get you set up for making changes.
Knowledge of SCSS is required for changing styles. Reporting any issue is encouraged.
Changes should not be made directly to any file within the css directory since these are generated files.
Sections:
SassC is used for Sass compilation. It's much faster than alternatives (compiling all themes should take <0.5s) since it is written in C.
SCSS-Lint is used to ensure all SCSS follows the project's style preferences.
Depending on your OS (incl. most Linux distributions, Windows), SassC may need to be built from source.
- Arch:
sudo pacman -S sassc - Mac OS X:
brew install sassc
SCSS-Lint requires Ruby. If you don't use Ruby, this isn't entirely necessary to install. Hound already monitors pull requests for style errors, so changes can be made at a later stage.
Install SCSS-Lint by running gem install scss_lint.
Once the required dependencies are installed, run make to compile all the themes.
Lint the project by running scss-lint in the project root. I recommend using a plugin with your favorite editor (e.g. linter-scss-lint for Atom), so that this runs while you make changes.
- scss/
- helpers/ - SCSS functions, mixins, and variables
- layout/ - Styles that occur throughout the Slack layout (i.e. shared styles)
- modules/ - Styles for specific parts of Slack, organized in parent directories
- themes/ - Theme files that override the default theme's variables
- build-variants/ - Each file here is compiled as a theme, allowing for theme extensions
- theme--main.scss - Extension wrapped for use on slack.com; compiles to css/variants/
- theme--styles.scss - Extension; compiles to css/raw/variants/
- build-variants/ - Each file here is compiled as a theme, allowing for theme extensions
- main.scss - Includes all of the SCSS files, wrapped for use on slack.com; compiles to css/
- styles.scss - Includes all of the SCSS files; compiles to css/raw/
Changes require a bit of searching using your browser's developer tools. It's recommended that you base styles off of Slack's own styles, using their selectors. Find the original CSS declaration in their CSS files and proceed to the next section.
Note: Always check if a selector doesn't already exist in the project by recursively searching the scss folder.
Use a tool such as CSS 2 SCSS to easily convert the CSS to SCSS syntax. Strip all non-styling properties from the SCSS. Some extra organization may be needed, CSS 2 SCSS often doesn't understand how to properly nest/merge selectors.
Put the styles in the appropriate Slack night mode theme file. If an appropriate theme file does not exist (typically only necessary for new features or restructuring), create a new file and import it in main.scss.
Now it's just a matter of swapping out Slack's style definitions with theme variables.
You must manually copy and paste themes into the Stylish manager to test changes. To quickly test themes, I recommend running make, then using a command-line tool to copy the compiled CSS into your clipboard:
- X systems:
make && xclip -sel clip < css/black.css - Mac OS X:
make && pbcopy < css/black.css
On Chromium-based browsers, when editing a Stylish theme, you must import a compiled CSS file because of the Mozilla specific domain-restriction syntax. If xclip is available, use ./bin/copy_raw.sh css/black.css.
If you decide to make your own theme, make a fork and create a new theme file (under scss/themes/). Adding a screenshot and customizing the README to be specific to your theme helps others find and use your theme.
Slack night mode is frequently updated. Keeping a theme fork up-to-date is fairly trivial. Remove the css folder to prevent conflicts, then sync with upstream. Once you rebuild the theme using make, your theme is updated.