ASCII text
Summary
To be able to use the latest/adequate version of Sass, install
dart-sass.meson installwill regenerate the CSS every time you modify the SCSS files.Note that Meson always builds out-of-tree, so the regenerated CSS files will appear in your builddir.
Do not edit the PNG directly, edit the source SVG files and run
./render-assets.sh.To be able to run
./render-assets.sh, installinkscapeandoptipng.To change the colors of SVG files, use a text editor instead of a image editor.
How to tweak the theme
SCSS
Materia is a complex theme, so to keep it maintainable it's written and processed in Sass, like the upstream Adwaita.
Here's a rundown of the "supporting" stylesheets, that are unlikely to be the right place for a drive by stylesheet fix:
File | Description
: | :
_theme.scss | Variables to allow easier definition of widget sizing/styling.
_color-palette.scss | Material Design colour palette definitions. We don't recommend editing this unless Google updates the colour scheme.
_theme-color.scss | Global colour definitions. We keep the number of defined colours to a necessary minimum. It covers both the light variant and the dark variant.
_public-colors.scss | SCSS colours exported through GTK to allow for 3rd party apps colour mixing.
_drawing.scss | Drawing helper mixings/functions to allow easier definition of widget drawing under specific context.
_common.scss | Actual definitions of style for each widget. This is where you are likely to add/remove your changes.
You can read about Sass on its web page.
Once you make your changes to the SCSS files, you can run meson install
to generate the final CSS files.
SVG
In Materia, to keep it maintainable, SVG files are edited as XML. So if you just want to change the colours of SVG files, it is recommended to use a text editor instead of a vector editor.
Several SVG files are used to render the PNG assets. Once you make your changes
to the SVG files, run the ./render-assets.sh script to render the PNG assets.
How to change the colour scheme
Script
To easily change the colour scheme, you can use the change_color.sh script (or
just use the oomox app).
Originally,
change_color.shandscripts/*.shwere implemented for oomox, but you can also run it on the command line without the app.
For example, to change the colour scheme to the previous Flat-Plat, run the script as follows:
For bash:
./change_color.sh -o Flat-Plat <(echo -e "BG=F5F5F5\nFG=212121\nMATERIA_VIEW=FFFFFF\nMATERIA_SURFACE=FAFAFA\nHDR_BG=455A64\nHDR_FG=FFFFFF\nSEL_BG=42A5F5\n")
For fish:
./change_color.sh -o Flat-Plat (echo -e "BG=F5F5F5\nFG=212121\nMATERIA_VIEW=FFFFFF\nMATERIA_SURFACE=FAFAFA\nHDR_BG=455A64\nHDR_FG=FFFFFF\nSEL_BG=42A5F5\n" | psub)
Manual
If you want to change the colour scheme in more detail, edit the files where colours are defined.
SCSS
src/_sass/_color-palette.scsssrc/_sass/_theme-color.scss
SVG
src/gtk-3.0/assets.svgsrc/gtk-2.0/assets{,-dark}.svgsrc/cinnamon/assets/*.svgsrc/gnome-shell/assets{,-dark}/*.svgsrc/unity/*/*.svgsrc/xfwm4/xfwm4{,-dark,-light}/*.svgsrc/chrome/chrome-scrollbar{,-dark}/icons/*.svg
Note: Do not forget to run
./render-assets.shafter changing the colours ofsrc/gtk-3.0/assets.svgandsrc/gtk-2.0/assets{,-dark}.svg.
Misc
src/gtk-2.0/gtkrc{,-dark,-light}src/metacity-1/metacity-theme-2{,-light}.xmlsrc/xfwm4/xfwm4{,-dark,-light}/themercsrc/chrome/chrome-theme{,-dark,-light}/manifest.json
Note: The colours of
manifest.jsonare defined in RGB format, so you need to convert your colours from HEX format to RGB format.
After all the steps, run meson install to rebuild the themes.
Useful Links
Upstream theme sources
Sass sources (legacy)
Metacity (legacy)
For other upstream theme sources of apps/DEs, see the comments in the source code.
Tips
1
## Summary
2
- To be able to use the latest/adequate version of Sass, install `dart-sass`.
4
- `meson install` will regenerate the CSS every time you modify the SCSS files.
5
- Note that Meson always builds out-of-tree, so the regenerated CSS files will
6
appear in your builddir.
7
- Do not edit the PNG directly, edit the source SVG files and run `./render-assets.sh`.
8
- To be able to run `./render-assets.sh`, install `inkscape` and `optipng`.
9
- To change the colors of SVG files, use a text editor instead of a image editor.
10
## How to tweak the theme
12
### SCSS
14
Materia is a complex theme, so to keep it maintainable it's written and
16
processed in Sass, like the upstream Adwaita.
17
Here's a rundown of the "supporting" stylesheets, that are unlikely to be the
19
right place for a drive by stylesheet fix:
20
File | Description
22
:-- | :--
23
`_theme.scss` | Variables to allow easier definition of widget sizing/styling.
24
`_color-palette.scss` | Material Design colour palette definitions. We don't recommend editing this unless Google updates the colour scheme.
25
`_theme-color.scss` | Global colour definitions. We keep the number of defined colours to a necessary minimum. It covers both the light variant and the dark variant.
26
`_public-colors.scss` | SCSS colours exported through GTK to allow for 3rd party apps colour mixing.
27
`_drawing.scss` | Drawing helper mixings/functions to allow easier definition of widget drawing under specific context.
28
`_common.scss` | Actual definitions of style for each widget. This is where you are likely to add/remove your changes.
29
You can read about Sass on its [web page](http://sass-lang.com/documentation/).
31
Once you make your changes to the SCSS files, you can run `meson install`
32
to generate the final CSS files.
33
### SVG
35
In Materia, to keep it maintainable, SVG files are edited as XML. So if
37
you just want to change the colours of SVG files, it is recommended to use a
38
**text editor** instead of a vector editor.
39
Several SVG files are used to render the PNG assets. Once you make your changes
41
to the SVG files, run the `./render-assets.sh` script to render the PNG assets.
42
## How to change the colour scheme
44
### Script
46
To easily change the colour scheme, you can use the `change_color.sh` script (or
48
just use the [oomox](https://github.com/themix-project/oomox) app).
49
> Originally, `change_color.sh` and `scripts/*.sh` were implemented for oomox,
51
but you can also run it on the command line without the app.
52
For example, to change the colour scheme to the previous Flat-Plat, run the
54
script as follows:
55
For `bash`:
57
```bash
59
./change_color.sh -o Flat-Plat <(echo -e "BG=F5F5F5\nFG=212121\nMATERIA_VIEW=FFFFFF\nMATERIA_SURFACE=FAFAFA\nHDR_BG=455A64\nHDR_FG=FFFFFF\nSEL_BG=42A5F5\n")
60
```
61
For `fish`:
63
```fish
65
./change_color.sh -o Flat-Plat (echo -e "BG=F5F5F5\nFG=212121\nMATERIA_VIEW=FFFFFF\nMATERIA_SURFACE=FAFAFA\nHDR_BG=455A64\nHDR_FG=FFFFFF\nSEL_BG=42A5F5\n" | psub)
66
```
67
### Manual
69
If you want to change the colour scheme in more detail, edit the files where
71
colours are defined.
72
#### SCSS
74
- `src/_sass/_color-palette.scss`
76
- `src/_sass/_theme-color.scss`
77
#### SVG
79
- `src/gtk-3.0/assets.svg`
81
- `src/gtk-2.0/assets{,-dark}.svg`
82
- `src/cinnamon/assets/*.svg`
83
- `src/gnome-shell/assets{,-dark}/*.svg`
84
- `src/unity/*/*.svg`
85
- `src/xfwm4/xfwm4{,-dark,-light}/*.svg`
86
- `src/chrome/chrome-scrollbar{,-dark}/icons/*.svg`
87
> Note: Do not forget to run `./render-assets.sh` after changing the colours of
89
`src/gtk-3.0/assets.svg` and `src/gtk-2.0/assets{,-dark}.svg`.
90
#### Misc
92
- `src/gtk-2.0/gtkrc{,-dark,-light}`
94
- `src/metacity-1/metacity-theme-2{,-light}.xml`
95
- `src/xfwm4/xfwm4{,-dark,-light}/themerc`
96
- `src/chrome/chrome-theme{,-dark,-light}/manifest.json`
97
> Note: The colours of `manifest.json` are defined in RGB format, so you need to
99
convert your colours from HEX format to RGB format.
100
After all the steps, run `meson install` to rebuild the themes.
102
## Useful Links
104
### Upstream theme sources
106
- [GTK 4](https://gitlab.gnome.org/GNOME/gtk/tree/master/gtk/theme/Adwaita)
108
- [GTK 3](https://gitlab.gnome.org/GNOME/gtk/tree/gtk-3-24/gtk/theme/Adwaita)
109
- [GTK 2](https://gitlab.gnome.org/GNOME/gnome-themes-extra/tree/master/themes/Adwaita/gtk-2.0)
110
- [GNOME Shell](https://gitlab.gnome.org/GNOME/gnome-shell/tree/master/data/theme)
111
- [Sass sources](https://gitlab.gnome.org/GNOME/gnome-shell-sass) (legacy)
112
- [Metacity](https://gitlab.gnome.org/GNOME/gnome-themes-extra/tree/gnome-3-14/themes/Adwaita/metacity-1) (legacy)
113
> For other upstream theme sources of apps/DEs, see the comments in the source code.
115
### Tips
117
- [Material Design Guidelines](https://www.material.io/guidelines/)
119
- [CSS Guidelines for Materia](https://github.com/nana-4/materia-theme/wiki/CSS-Guidelines)
120
- [The GTK Inspector](https://blog.gtk.org/2017/04/05/the-gtk-inspector/)
121
- [Theming in GTK 4](https://developer.gnome.org/gtk4/stable/theming.html)
122
- [Theming in GTK 3](https://developer.gnome.org/gtk3/stable/theming.html)
123
- [GTK 2 Theming Tutorial](https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkThemes)
124
- [The Pixmap Engine](https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkEngines/PixmapEngine)
125
- [Designing Metacity Themes](https://wiki.gnome.org/Attic/GnomeArt/Tutorials/MetacityThemes)
126
- [Unity/Theming](https://wiki.ubuntu.com/Unity/Theming)
127
- [Xfwm4 theme how-to](https://wiki.xfce.org/howto/xfwm4_theme)
128
- [Chrome Themes](https://developer.chrome.com/extensions/themes)
129