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 color palette definitions. We don't recommend editing this unless Google updates the color scheme.
_theme-color.scss | Global color definitions. We keep the number of defined colors to a necessary minimum. It covers both the light variant and the dark variant.
_public-colors.scss | SCSS colors exported through GTK to allow for 3rd party apps color 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 basically edited on text-based. So if you just want to change the colors of SVG files, it is recommended to use a text editor instead of a image 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 color scheme
Script
To easily change the color 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.
Note: This script doesn't support Chrome extensions for now.
For example, to change the color 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 color scheme in more detail, edit the files where colors 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 colors 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 colors of
manifest.jsonare defined in RGB format, so you need to convert your colors 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 color palette definitions. We don't recommend editing this unless Google updates the color scheme.
25
`_theme-color.scss` | Global color definitions. We keep the number of defined colors to a necessary minimum. It covers both the light variant and the dark variant.
26
`_public-colors.scss` | SCSS colors exported through GTK to allow for 3rd party apps color 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 basically edited on
37
text-based. So if you just want to change the colors of SVG files, it is
38
recommended to use a **text editor** instead of a image 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 color scheme
44
### Script
46
To easily change the color 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
> Note: This script doesn't support Chrome extensions for now.
54
For example, to change the color scheme to the previous Flat-Plat, run the
56
script as follows:
57
For `bash`:
59
```bash
61
./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")
62
```
63
For `fish`:
65
```fish
67
./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)
68
```
69
### Manual
71
If you want to change the color scheme in more detail, edit the files where
73
colors are defined.
74
#### SCSS
76
- `src/_sass/_color-palette.scss`
78
- `src/_sass/_theme-color.scss`
79
#### SVG
81
- `src/gtk-3.0/assets.svg`
83
- `src/gtk-2.0/assets{,-dark}.svg`
84
- `src/cinnamon/assets/*.svg`
85
- `src/gnome-shell/assets{,-dark}/*.svg`
86
- `src/unity/*/*.svg`
87
- `src/xfwm4/xfwm4{,-dark,-light}/*.svg`
88
- `src/chrome/chrome-scrollbar{,-dark}/icons/*.svg`
89
> Note: Do not forget to run `./render-assets.sh` after changing the colors of
91
`src/gtk-3.0/assets.svg` and `src/gtk-2.0/assets{,-dark}.svg`.
92
#### Misc
94
- `src/gtk-2.0/gtkrc{,-dark,-light}`
96
- `src/metacity-1/metacity-theme-2{,-light}.xml`
97
- `src/xfwm4/xfwm4{,-dark,-light}/themerc`
98
- `src/chrome/chrome-theme{,-dark,-light}/manifest.json`
99
> Note: The colors of `manifest.json` are defined in RGB format, so you need to
101
convert your colors from HEX format to RGB format.
102
After all the steps, run `meson install` to rebuild the themes.
104
## Useful Links
106
### Upstream theme sources
108
- [GTK 4](https://gitlab.gnome.org/GNOME/gtk/tree/master/gtk/theme/Adwaita)
110
- [GTK 3](https://gitlab.gnome.org/GNOME/gtk/tree/gtk-3-24/gtk/theme/Adwaita)
111
- [GTK 2](https://gitlab.gnome.org/GNOME/gnome-themes-extra/tree/master/themes/Adwaita/gtk-2.0)
112
- [GNOME Shell](https://gitlab.gnome.org/GNOME/gnome-shell/tree/master/data/theme)
113
- [Sass sources](https://gitlab.gnome.org/GNOME/gnome-shell-sass) (legacy)
114
- [Metacity](https://gitlab.gnome.org/GNOME/gnome-themes-extra/tree/gnome-3-14/themes/Adwaita/metacity-1) (legacy)
115
> For other upstream theme sources of apps/DEs, see the comments in the source code.
117
### Tips
119
- [Material Design Guidelines](https://www.material.io/guidelines/)
121
- [CSS Guidelines for Materia](https://github.com/nana-4/materia-theme/wiki/CSS-Guidelines)
122
- [The GTK Inspector](https://blog.gtk.org/2017/04/05/the-gtk-inspector/)
123
- [Theming in GTK 4](https://developer.gnome.org/gtk4/stable/theming.html)
124
- [Theming in GTK 3](https://developer.gnome.org/gtk3/stable/theming.html)
125
- [GTK 2 Theming Tutorial](https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkThemes)
126
- [The Pixmap Engine](https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkEngines/PixmapEngine)
127
- [Designing Metacity Themes](https://wiki.gnome.org/Attic/GnomeArt/Tutorials/MetacityThemes)
128
- [Unity/Theming](https://wiki.ubuntu.com/Unity/Theming)
129
- [Xfwm4 theme how-to](https://wiki.xfce.org/howto/xfwm4_theme)
130
- [Chrome Themes](https://developer.chrome.com/extensions/themes)
131