Customizing Sass-based Skins
Support for templated skins
Some skins have a stylesheet generated from Sass templates
and compiled with compass
. Each such skin has a "template"
subdirectory containing various files, including those used to regenerate the skin's stylesheet
. The files of interest to a custom skin are in
the template/sass directory:
Files you can edit
- _userSettings.scss -
This file is initially empty and can be edited. It should contain Sass variables and font
declarations intended to override settings in the builtin skin (see
- _userStyles.scss - This file is initially empty and can be edited. It should contain
CSS intended to be incorporated after the styles in the builtin skin (see
_base.scss below), overriding both
Files that should not be edited
The other files in template/sass should not be edited
and can be largely ignored (see the discussion below on Keeping the skin you extended up to
) - but their purpose is listed here:
- skin_styles.scss - This is the
bootstrap file that lists the fragments to load and is executed by running 'compass compile' in
the parent folder. There shouldn't be any need to alter this file - but you can do so if you
want to add further custom fragments
- _base.scss - This file contains all the base CSS
and the defaults for the supported variables in the builtin skin that your custom skin is
based on. This file should not be edited
- _skinSettings.scss - This file contains
Sass variables and font-declarations for the builtin skin, intended to override the defaults
set up in _base.scss. This file should not be edited
- _skinStyles.scss - This file
contains custom CSS for the builtin skin, to be appended after that in _base.scss. This
file should not be edited
Creating a custom skin
A custom skin is created by
copying and extending an existing one.
You can start from whichever templated skin is
closest to your requirement. Variable values largely cascade from one another, allowing
simple, high-level changes to affect much of the skin.
To create a custom skin based on
- Copy the skins/Tahoe directory to skins/MySkin
skins/MySkin/load_skin.js, find and replace instances of "Tahoe" with "MySkin"
skins/MySkin/template/sass/_userSettings.scss, declare $theme_name: 'MySkin'
- Change to
skins/MySkin/template and run 'compass compile'
Customizing your skin
What to edit
As noted at the top of this discussion, the files you can edit are in
the template/sass directory - specifically,
customizing supported variable values and
_userStyles.scss, for overriding
You can see the CSS classes that can be overridden in
You can see the list of available variables in
_skinSettings.scss, grouped and named according to what effects they have.
You can copy the variables you want to override into your
file, change their values and run 'compass compile'.
By way of example
a generally green version of Tahoe, try adding these settings to
and running 'compass compile'
#40BF41; // generally green rather than blue
$standard_widget_border_color: #006400; // darkgreen borders for widgets
$standard_button_border_radius: 5px; // give all buttons rounded corners
When you make changes to
, you can compile them into your skin by running 'compass
compile' from the skins/MySkin/template directory. This compiles the various fragments from
the template/sass directory (listed in
) to produce the skin's
stylesheet, at skins/MySkin/skin_styles.css.
After making changes and running 'compass
compile', clear your browser cache before refreshing your test page, to ensure the old
skin_styles.css isn't cached.
Keeping the skin you extended up to date
earlier, some of the files in template/sass should not be edited. This is because, from time
to time, we may make fixes or improvements to our builtin skins - when this happens, you can
keep your custom skins up to date, without clobbering any of your customizations, by copying
from the skin you extended to your skin's template/sass
folder, replacing the existing copies. From there, running 'compass compile' will incorporate
the latest builtin skin changes into your custom skin, without affecting your existing