ASCII text
Summary
Do not edit the CSS directly, edit the source SCSS files and the CSS files will be generated automatically when building with
meson+ninja.You'll need to have
sasscinstalled.
Do not edit
foo.<theme-name>.scssauto-generated bymeson.Do not edit the PNG directly, edit the source SVG files and run
./render-assets.sh.You'll need to have
inkscapeandoptipnginstalled.
To change the colors of SVG files, use a text editor instead of a image editor.
How to tweak the theme
SCSS
Like the upstream Adwaita, to keep it maintainable it's written and processed in Sass.
Here's a rundown of the "supporting" stylesheets, that are unlikely to be the right place for a drive by stylesheet fix:
File | Description
: | :
_variables.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.
_colors.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.
_colors-public.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.
_apps*.scss _extensions.scss | App/extension specific stylings.
You can read about Sass on its web page.
Once you make your changes to the SCSS files, you can run ninja 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/_colors.scss
SVG
src/gtk-3.0/assets.svgsrc/gtk-2.0/assets{,-dark}.svgsrc/gnome-shell/assets{,-dark}/*.svgsrc/unity/*.svgsrc/unity/assets{,-light}/*.svgsrc/xfwm4/assets{,-light}/*.svgsrc/chrome/chrome-scrollbar{,-dark}/icons/*.svgsrc/chrome/chrome-theme{,-dark,-light}/*.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/assets{,-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 ninja to rebuild the themes.
Useful Links
Upstream theme sources
GTK 4.0 (master)
GTK 3 (3.24)
Sass sources (legacy)
Metacity (legacy)
For other upstream theme sources of apps/DEs, see the comments in the source code.
Tips
1
## Summary
2
- Do not edit the CSS directly, edit the source SCSS files and the CSS files
4
will be generated automatically when building with `meson` + `ninja`.
5
- You'll need to have `sassc` installed.
6
- Do not edit `foo.<theme-name>.scss` auto-generated by `meson`.
7
- Do not edit the PNG directly, edit the source SVG files and run `./render-assets.sh`.
8
- You'll need to have `inkscape` and `optipng` installed.
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
Like the upstream Adwaita, to keep it maintainable it's written and processed in
16
Sass.
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
`_variables.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
`_colors.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
`_colors-public.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
`_apps*.scss` <br> `_extensions.scss` | App/extension specific stylings.
30
You can read about Sass on its [web page](http://sass-lang.com/documentation/).
32
Once you make your changes to the SCSS files, you can run `ninja` to generate the
33
final CSS files.
34
### SVG
36
In Materia, to keep it maintainable, SVG files are basically edited on
38
text-based. So if you just want to change the colors of SVG files, it is
39
recommended to use a **text editor** instead of a image editor.
40
Several SVG files are used to render the PNG assets. Once you make your changes
42
to the SVG files, run the `./render-assets.sh` script to render the PNG assets.
43
## How to change the color scheme
45
### Script
47
To easily change the color scheme, you can use the `change_color.sh` script (or
49
just use the [oomox](https://github.com/themix-project/oomox) app).
50
> Originally, `change_color.sh` and `scripts/*.sh` were implemented for oomox,
52
but you can also run it on the command line without the app.
53
> Note: This script doesn't support Chrome extensions for now.
55
For example, to change the color scheme to the previous Flat-Plat, run the
57
script as follows:
58
For `bash`:
60
```bash
62
./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")
63
```
64
For `fish`:
66
```fish
68
./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)
69
```
70
### Manual
72
If you want to change the color scheme in more detail, edit the files where
74
colors are defined.
75
#### SCSS
77
- `src/_sass/_color-palette.scss`
79
- `src/_sass/_colors.scss`
80
#### SVG
82
- `src/gtk-3.0/assets.svg`
84
- `src/gtk-2.0/assets{,-dark}.svg`
85
- `src/gnome-shell/assets{,-dark}/*.svg`
86
- `src/unity/*.svg`
87
- `src/unity/assets{,-light}/*.svg`
88
- `src/xfwm4/assets{,-light}/*.svg`
89
- `src/chrome/chrome-scrollbar{,-dark}/icons/*.svg`
90
- `src/chrome/chrome-theme{,-dark,-light}/*.svg`
91
> Note: Do not forget to run `./render-assets.sh` after changing the colors of
93
`src/gtk-3.0/assets.svg` and `src/gtk-2.0/assets{,-dark}.svg`.
94
#### Misc
96
- `src/gtk-2.0/gtkrc{,-dark,-light}`
98
- `src/metacity-1/metacity-theme-2{,-light}.xml`
99
- `src/xfwm4/assets{,-light}/themerc`
100
- `src/chrome/chrome-theme{,-dark,-light}/manifest.json`
101
> Note: The colors of `manifest.json` are defined in RGB format, so you need to
103
convert your colors from HEX format to RGB format.
104
After all the steps, run `ninja` to rebuild the themes.
106
## Useful Links
108
### Upstream theme sources
110
- [GTK 4.0](https://gitlab.gnome.org/GNOME/gtk/tree/master/gtk/theme/Adwaita) (master)
112
- [GTK 3](https://gitlab.gnome.org/GNOME/gtk/tree/gtk-3-24/gtk/theme/Adwaita) (3.24)
113
- [GTK 2](https://gitlab.gnome.org/GNOME/gnome-themes-extra/tree/master/themes/Adwaita/gtk-2.0)
114
- [GNOME Shell](https://gitlab.gnome.org/GNOME/gnome-shell/tree/master/data/theme)
115
- [Sass sources](https://gitlab.gnome.org/GNOME/gnome-shell-sass) (legacy)
116
- [Metacity](https://gitlab.gnome.org/GNOME/gnome-themes-extra/tree/gnome-3-14/themes/Adwaita/metacity-1) (legacy)
117
> For other upstream theme sources of apps/DEs, see the comments in the source code.
119
### Tips
121
- [Material Design Guidelines](https://www.material.io/guidelines/)
123
- [CSS Guidelines for Materia](https://github.com/nana-4/materia-theme/wiki/CSS-Guidelines)
124
- [The GTK Inspector](https://blog.gtk.org/2017/04/05/the-gtk-inspector/)
125
- [Theming in GTK 4](https://developer.gnome.org/gtk4/stable/theming.html)
126
- [Theming in GTK 3](https://developer.gnome.org/gtk3/stable/theming.html)
127
- [GTK 2 Theming Tutorial](https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkThemes)
128
- [The Pixmap Engine](https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkEngines/PixmapEngine)
129
- [Designing Metacity Themes](https://wiki.gnome.org/Attic/GnomeArt/Tutorials/MetacityThemes)
130
- [Unity/Theming](https://wiki.ubuntu.com/Unity/Theming)
131
- [Xfwm4 theme how-to](https://wiki.xfce.org/howto/xfwm4_theme)
132
- [Chrome Themes](https://developer.chrome.com/extensions/themes)
133