HACKING.md: Update

HACKING.md

@@ -1,19 +1,19 @@

                                
                                
                                
                            
                                
                                    
                                        
                                            1  
                                            ## Summary
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            2  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        3 -
                                        - 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`.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        3 +
                                        - To be able to use the latest/adequate version of Sass, install `sassc`.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        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 -
                                          - You'll need to have `inkscape` and `optipng` installed.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        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  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            11  
                                            ## How to tweak the theme
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            12  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            13  
                                            ### SCSS
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            14  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        15 -
                                        Like the upstream Adwaita, to keep it maintainable it's written and processed in
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        16 -
                                        Sass.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        15 +
                                        Materia is a complex theme, so to keep it maintainable it's written and
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        16 +
                                        processed in Sass, like the upstream Adwaita.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            17  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            18  
                                            Here's a rundown of the "supporting" stylesheets, that are unlikely to be the
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            19  
                                            right place for a drive by stylesheet fix:
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        

@@ -24,13 +24,13 @@ File | Description

                                
                                
                                
                            
                                
                                    
                                        
                                            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.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        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  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            31  
                                            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.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        32 +
                                        Once you make your changes to the SCSS files, you can run `meson install`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        33 +
                                        to generate the final CSS files.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            34  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            35  
                                            ### SVG
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            36  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        

@@ -82,12 +82,11 @@ colors are defined.

                                
                                
                                
                            
                                
                                    
                                        
                                            82  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            83  
                                            - `src/gtk-3.0/assets.svg`
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            84  
                                            - `src/gtk-2.0/assets{,-dark}.svg`
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        85 +
                                        - `src/cinnamon/assets/*.svg`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            86  
                                            - `src/gnome-shell/assets{,-dark}/*.svg`
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        86 -
                                        - `src/unity/*.svg`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        87 -
                                        - `src/unity/assets{,-light}/*.svg`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        88 -
                                        - `src/xfwm4/assets{,-light}/*.svg`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        87 +
                                        - `src/unity/*/*.svg`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        88 +
                                        - `src/xfwm4/xfwm4{,-dark,-light}/*.svg`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            89  
                                            - `src/chrome/chrome-scrollbar{,-dark}/icons/*.svg`
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        90 -
                                        - `src/chrome/chrome-theme{,-dark,-light}/*.svg`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            90  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            91  
                                            > Note: Do not forget to run `./render-assets.sh` after changing the colors of
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            92  
                                            `src/gtk-3.0/assets.svg` and `src/gtk-2.0/assets{,-dark}.svg`.
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        

@@ -96,20 +95,20 @@ colors are defined.

                                
                                
                                
                            
                                
                                    
                                        
                                            95  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            96  
                                            - `src/gtk-2.0/gtkrc{,-dark,-light}`
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            97  
                                            - `src/metacity-1/metacity-theme-2{,-light}.xml`
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        99 -
                                        - `src/xfwm4/assets{,-light}/themerc`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        98 +
                                        - `src/xfwm4/xfwm4{,-dark,-light}/themerc`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            99  
                                            - `src/chrome/chrome-theme{,-dark,-light}/manifest.json`
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            100  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            101  
                                            > Note: The colors of `manifest.json` are defined in RGB format, so you need to
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            102  
                                            convert your colors from HEX format to RGB format.
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            103  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        105 -
                                        After all the steps, run `ninja` to rebuild the themes.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        104 +
                                        After all the steps, run `meson install` to rebuild the themes.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            105  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            106  
                                            ## Useful Links
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            107  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            108  
                                            ### Upstream theme sources
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            109  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        111 -
                                        - [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)
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        110 +
                                        - [GTK 4](https://gitlab.gnome.org/GNOME/gtk/tree/master/gtk/theme/Adwaita)
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        111 +
                                        - [GTK 3](https://gitlab.gnome.org/GNOME/gtk/tree/gtk-3-24/gtk/theme/Adwaita)
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            112  
                                            - [GTK 2](https://gitlab.gnome.org/GNOME/gnome-themes-extra/tree/master/themes/Adwaita/gtk-2.0)
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            113  
                                            - [GNOME Shell](https://gitlab.gnome.org/GNOME/gnome-shell/tree/master/data/theme)
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            114  
                                              - [Sass sources](https://gitlab.gnome.org/GNOME/gnome-shell-sass) (legacy)