DEV-GUIDE.md (3999B)
1 # Information for contribution/development 2 3 ## Introduction 4 5 The main intent of this section is to help contributors decide on how to use 6 colors and looks when contributing. 7 8 In a simplified sense it might be beneficial to imagine the light theme as 9 being as close as possible to writing written text on paper with a few tools 10 like markers and coloured pencils at hand to highlight **exceptional 11 circumstances**. 12 13 This is not meant to be a strict guide but it can probably be followed in most 14 situations. 15 16 ## Upstream Solarized palette usage documentation 17 18 The base Solarized colors have a canonical 19 [usage documentation](http://ethanschoonover.com/solarized#usage-development) 20 21 When referring to colors, the convention is to use the dark theme's 22 base color names directly, e.g. `(:foreground ,base0)`. They will switch to 23 their counterparts automatically in the light theme. 24 25 Usage table for the automatic dark/light base colors: 26 27 * `,base1` - optional emphasized content 28 * `,base0` - body text / default code / primary content 29 * `,base00` - unspecified (it's a separator) 30 * `,base01` - comments / secondary content 31 * `,base02` - background highlights 32 * `,base03` - background 33 34 ## Basic strategy for selecting colors 35 36 The most important general rule is to **avoid color pasta**. 37 38 Examples: 39 40 - Try to start by not using accent colors at all. It's common to get a good 41 enough visual separation by just using the baseXX colors. 42 - Avoid having several accent colors grouped in a small space 43 - Avoid having accent colors that are cycled or striped repeatedly. 44 - It's sometimes even preferable to hide information by reusing colors rather 45 than creating more visual noise. It's hard to decide (for other people) what 46 to simplify/reduce away but it leads to a better reading experience. 47 - For small spaces like indicators, the baseXX are usually enough. The 48 indicator symbols themselves are probably good enough carriers of 49 information. 50 51 ## Accent colors that are used in special ways 52 53 (Draft note: This is a simplified list written in haste, needs much more 54 details. In worst case scenario it's even wrong, probably not though. Some of 55 the bullet points lack explanation right now) 56 57 Generally I try to only use the most basic colors which I guess is 58 cyan/blue/green/yellow (again, if possible). 59 60 Some specific color information: 61 62 - **magenta** is used as a temporary highlight color, in most cases it matches 63 direct user input actions such as isearch matches, ... 64 - **red** is used to indicate errors only. 65 - Exception: In buffers displaying only or mostly a diff, **red** is ok for 66 indicating "removed". 67 - **orange** is used to indicate errors only but be a little more relaxed with 68 that rule as opposed to **red**. 69 - **violet** is very rarely used at all 70 - **blue** / **green** / **red** can be used for diff like things indicating 71 modified/added/removed 72 73 ## Block highlighting colors 74 75 **These colors can probably be avoided for more or less everything that isn't a 76 diff.** 77 78 There are 4 additional variants for all accent colors that are meant to be used 79 in pairs as two levels of soft and harder highlight. 80 81 - **green-1bg** + **green-1fg** are used together to form a soft highlighted 82 section (useful for diffs) 83 - **green-2bg** + **green-2fg** are used together to form a more pronounced 84 highlighted section (useful for diffs hunk highlight) 85 86 Using **blue-1fg** on anything other than **blue-1bg** is currently considered 87 an undefined result and might break visibility/contrast/lightness rules and 88 might break even more with later tweaks to the color generation changes. 89 90 91 ## Additional accent color variants 92 93 **Avoid using these at all, they might even be phased out completely** 94 95 There are also variants of each color suffixed `-d` (dark), `-l` (light), `-lc` 96 (low contrast), `-hc` (high contrast). 97 98 These colors were designed with almost the same intent as the block highlight 99 colors but they are considerably less solarized looking. Can probably be 100 avoided altogether. 101 102 103