Update HACKING.md

HACKING.md

@@ -2,24 +2,31 @@ Summary

                                
                                
                                
                            
                                
                                    
                                        
                                            2  
                                            -------
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            3  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            4  
                                            - Do not edit the CSS directly, edit the source SCSS files and run `./parse-sass.sh`
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        5 -
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        6 -
                                        - To be able to use the latest/adequate version of sass, install `sassc`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        5 +
                                        - To be able to use the latest/adequate version of Sass, install `sassc`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        6 +
                                        - To change the SVG assets color, use a text editor instead of a image editor
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            7  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            8  
                                            How to tweak the theme
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            9  
                                            ----------------------
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            10  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            11  
                                            Flat-Plat is a complex theme, so to keep it maintainable it's written and
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        12 -
                                        processed in SASS.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        12 +
                                        processed in Sass.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        13 +
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        14 +
                                        Here's a rundown of the _supporting_ stylesheets, that are unlikely to be the
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        15 +
                                        right place for a drive by stylesheet fix:
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        16 +
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        17 +
                                        - `_variables.scss`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        18 +
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        19 +
                                          variables to allow easier definition of widget sizing/styling.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            20  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        14 -
                                        It is very likely your change will happen in the `_common.scss` file. That's where
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        15 -
                                        all the widget selectors are defined. Here's a rundown of the "supporting"
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        16 -
                                        stylesheets, that are unlikely to be the right place for a drive by stylesheet
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        17 -
                                        fix:
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        21 +
                                        - `_color-palette.scss`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        22 +
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        23 +
                                          material design color palette definitions. We don't recommend editing this
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        24 +
                                          unless Google updates the color scheme.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            25  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            26  
                                            - `_colors.scss`
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            27  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            28  
                                              global color definitions. We keep the number of defined colors to a necessary
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        22 -
                                          minimum, most colors are derived form a handful of basics. It covers both the
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        29 +
                                          minimum, most colors are derived from a handful of basics. It covers both the
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            30  
                                              light variant and the dark variant.
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            31  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            32  
                                            - `_colors-public.scss`
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        

@@ -29,44 +36,49 @@ fix:

                                
                                
                                
                            
                                
                                    
                                        
                                            36  
                                            - `_drawing.scss`
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            37  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            38  
                                              drawing helper mixings/functions to allow easier definition of widget drawing
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        32 -
                                          under specific context. This is why Flat-Plat isn't 15000 LOC.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        39 +
                                          under specific context.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            40  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            41  
                                            - `_common.scss`
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            42  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            43  
                                              actual definitions of style for each widget. This is where you are likely to
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            44  
                                              add/remove your changes.
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            45  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        39 -
                                        You can read about SASS at http://sass-lang.com/documentation/. Once you make
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        40 -
                                        your changes to the `_common.scss` file, run the `./parse-sass.sh` script.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        46 +
                                        - `_apps.scss` or `_extensions.scss`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        47 +
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        48 +
                                          app/extension specific stylings.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        49 +
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        50 +
                                        You can read about Sass at http://sass-lang.com/documentation/. Once you make
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        51 +
                                        your changes to the SCSS files, run the `./parse-sass.sh` script to rebuild the
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        52 +
                                        CSS files.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            53  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            54  
                                            How to change the assets color
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            55  
                                            ------------------------------
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            56  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        45 -
                                        To keep it maintainable SVG files are basically edited on text-based.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        57 +
                                        To keep it maintainable, SVG files are basically edited on text-based.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            58  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        47 -
                                        So if you just want to change the SVG assets color, I recommend using a
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        59 +
                                        So if you just want to change the SVG assets color, we recommend using a
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            60  
                                            **text editor** instead of **Inkscape**. But please note that in some cases
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        49 -
                                        Inkscape is needed to render PNG assets.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        61 +
                                        Inkscape is needed to render the PNG assets.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            62  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        51 -
                                        Here is an example to change the _accent color_:
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        63 +
                                        Here's an example to change the _accent color_:
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            64  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        53 -
                                        1. Open the following `.svg` files with a **text editor**.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        65 +
                                        1. Open the following SVG files with a **text editor**.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            66  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        55 -
                                          - ./src/gtk-2.0/assets.svg
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        56 -
                                          - ./src/gtk-2.0/assets-dark.svg
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        57 -
                                          - ./src/gtk-3.0/gtk-common/assets.svg
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        58 -
                                          - ./src/gnome-shell/3.18/assets/checkbox.svg
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        59 -
                                          - ./src/gnome-shell/3.18/assets/more-results.svg
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        60 -
                                          - ./src/gnome-shell/3.18/assets/toggle-on.svg
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        61 -
                                          - ./src/gnome-shell/3.18/assets-dark/checkbox.svg
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        62 -
                                          - ./src/gnome-shell/3.18/assets-dark/more-results.svg
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        63 -
                                          - ./src/gnome-shell/3.18/assets-dark/toggle-on.svg
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        67 +
                                          - `./src/gtk-2.0/assets.svg`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        68 +
                                          - `./src/gtk-2.0/assets-dark.svg`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        69 +
                                          - `./src/gtk-3.0/gtk-common/assets.svg`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        70 +
                                          - `./src/gnome-shell/3.18/assets/checkbox.svg`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        71 +
                                          - `./src/gnome-shell/3.18/assets/more-results.svg`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        72 +
                                          - `./src/gnome-shell/3.18/assets/toggle-on.svg`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        73 +
                                          - `./src/gnome-shell/3.18/assets-dark/checkbox.svg`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        74 +
                                          - `./src/gnome-shell/3.18/assets-dark/more-results.svg`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        75 +
                                          - `./src/gnome-shell/3.18/assets-dark/toggle-on.svg`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            76  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            77  
                                            2. Search `#FF4081` (default accent color) and replace with your favorite color.
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            78  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            79  
                                              - The recommended color palette is: https://material.io/guidelines/style/color.html#color-color-palette
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            80  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        69 -
                                        3. For gtk2 and gtk3, delete all png assets before redrawing them.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        81 +
                                        3. For gtk2 and gtk3, delete all PNG assets before redrawing them.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            82  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            83  
                                              ```sh
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            84  
                                              rm -v ./src/gtk-2.0/assets/*.png
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        

@@ -74,7 +86,9 @@ Here is an example to change the _accent color_:

                                
                                
                                
                            
                                
                                    
                                        
                                            86  
                                              rm -v ./src/gtk-3.0/gtk-common/assets/*.png
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            87  
                                              ```
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            88  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        77 -
                                        4. Render png assets with scripts. (Inkscape is required to run the scripts.)
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        89 +
                                        4. Run `./render-assets.sh` or `./render-assets-dark.sh` to render the PNG assets.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        90 +
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        91 +
                                          > Note: Inkscape is required to run the scripts.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            92  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            93  
                                              - for gtk2:
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            94  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        

@@ -96,9 +110,9 @@ Useful Links

                                
                                
                                
                            
                                
                                    
                                        
                                            110  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            111  
                                            Upstream theme sources:
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            112  
                                            - [GTK+ 4](https://github.com/GNOME/gtk/tree/master/gtk/theme/Adwaita)
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        99 -
                                          - [3.22.x](https://github.com/GNOME/gtk/tree/gtk-3-22/gtk/theme/Adwaita)
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        100 -
                                          - [3.20.x](https://github.com/GNOME/gtk/tree/gtk-3-20/gtk/theme/Adwaita)
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        101 -
                                          - [3.18.x](https://github.com/GNOME/gtk/tree/gtk-3-18/gtk/theme/Adwaita)
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        113 +
                                          - [3.22](https://github.com/GNOME/gtk/tree/gtk-3-22/gtk/theme/Adwaita)
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        114 +
                                          - [3.20](https://github.com/GNOME/gtk/tree/gtk-3-20/gtk/theme/Adwaita)
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        115 +
                                          - [3.18](https://github.com/GNOME/gtk/tree/gtk-3-18/gtk/theme/Adwaita)
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            116  
                                            - [GTK+ 2](https://github.com/GNOME/gnome-themes-standard/tree/master/themes/Adwaita/gtk-2.0)
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            117  
                                            - [GNOME Shell](https://github.com/GNOME/gnome-shell/tree/master/data/theme)
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            118  
                                              - [Sass sources](https://github.com/GNOME/gnome-shell-sass)