diff options
| -rw-r--r-- | README.md | 24 | ||||
| -rw-r--r-- | docs/README.md | 131 | ||||
| -rw-r--r-- | docs/theme-templates-guide.md | 67 | ||||
| -rw-r--r-- | docs/theme-versioning.md | 48 |
4 files changed, 265 insertions, 5 deletions
@@ -17,14 +17,28 @@ Since [v1.16](https://blog.protonmail.ch/protonmail-beta-v1-16-release-notes/), - [Supporting and maintaining the project](#supporting-and-maintaining-the-project) - [Where can I find more themes?](#where-can-i-find-more-themes) - [Web References](#web-references) + +#### Documentation 📖 + +- [Documentation](#documentation) + - [Quick Setup Guide](#quick-setup-guide) + - [Themes](#themes) + - [Templates](#templates) + - [Theme Compilation](#theme-compilation) + - [Contributing](#contributing) + - [Is there something missing?](#is-there-something-missing) +- [Project's README](../README.md) +- [Theme Template Guide](./theme-template-guide.md) +- [Theme Versioning](./theme-versioning.md) </details> + ### How to use a theme 1. Pick one from the themes folder in the repository. -2. Select the theme and select the raw view to see all the code. -3. Select all and copy the code. -4. At ProtonMail's website head over to **Settings**, click Themes under the **Appearance** section. -5. Paste the code under the *Custom Theme* section and press save. +1. Select the theme and select the raw view to see all the code. +1. Select all and copy the code. +1. At ProtonMail's website head over to **Settings**, click Themes under the **Appearance** section. +1. Paste the code under the *Custom Theme* section and press save. > *In order to remove a theme, switch to default or remove Custom Theme contents and press save.* The theme should be applied and you should see the changes immediately. @@ -32,7 +46,7 @@ The theme should be applied and you should see the changes immediately. ### Available themes Check out some of the available themes you can choose from. -> There is also a `full` version available, that applies to the messages panel and more elements. +> There is also a `full` version available, that applies theme colors to the messages panel and more elements. <details> <summary><b>Expand theme list</b> 👩🏻🎨</summary> diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..525e5c0 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,131 @@ +# Documentation + +A breakdown of how the project works, and details on how themes are generated and now to create new ones. + +<details> +<summary>Click to show available documentation</summary> + +- [Documentation](#documentation) + - [Quick Setup Guide](#quick-setup-guide) + - [Creating a theme](#creating-a-theme) + - [Themes](#themes) + - [Templates](#templates) + - [Theme Compilation](#theme-compilation) + - [Contributing](#contributing) + - [Is there something missing?](#is-there-something-missing) +- [Project's README](../README.md) +- [Theme Template Guide](./theme-template-guide.md) +- [Theme Versioning](./theme-versioning.md) +</details> + +## Quick Setup Guide +> **Required for theme creation only** + +Before making a contribution you might want to setup the project in order to test fixes and compile themes. Install NodeJS first and after forking/cloning this repository install the dependencies: + +```bash +cd protonmail-themes +npm install +``` + +Themes can be created by duplicating and renaming the [example theme folder](../templates/theme_example) and its `.scss` file to the chosen theme name. + +A theme name folder and file should be separared by undercores if it has more than one word and should be places in [`/templates/`](../templates): + +```bash +. +├── @theme-base +├── green_lume +│ └── green_lume.scss +├── your_theme +│ └── your_theme.scss +``` + +Then edit that file by chaging the color variables available. Please [follow the theme templates guide](./theme-templates-guide.md) for more detail on what this looks like and how to customise a theme. + +Two commands are available to compile themes: + +```bash +// Compiles themes as changes are made. +npm run watch + +// Compiles all themes. +npm run build +``` + +## Creating a theme + +Themes can be created in `/templates` and should be contained on a folder with the same name of the theme. For instance: +``` +/templates + /new_theme + /new_theme.scss +``` + +After creating your theme folder and file, `new_theme.scss` should look similar to this snippet: +```scss +/*! =========================================== * + * Template THEME + * Version: #{$version} + * Author: You name here + * Website: Your website here + * Tweets Your twitter handle + * =========================================== */ + +// Change colors here and they will change everywhere. +$base: #1C1C1C; +$search: #000; +$highlight: #2FBF71; +$navigation: #fff; + +$text_color: #0d0d0d; +$extra_color: #e6eaf0; +$danger_color: #d62646; +$warning_color: #ffaa00; + +@import "../@theme-base/styles"; +// @import "../@theme-base/full"; +// Please do not remove the import above, add overrides and other partials below this line. +``` + +The snippet will change the colors of the elements across the theme. However, you can extend or override the theme further by adding changes to `_override.scss`. Additionally, [custom partials can be added](https://sass-lang.com/guide). You can refer to [the guide on editing theme templates](./theme-templates-guide.md) for more information on customizing themes. + +## Themes +Ready to use themes are stored at [`/themes`](../themes) and can be copied over to the Custom Theme text area avalaible at the `Appearance -> Themes` section on your ProtonMail settings. Each theme has it's own folder with one or more `.css` files in it. The text inside these `.css` files is what needs to be copied to the custom theme section in ProtonMail for the theme to be applied. + +These themes are compiled from `.scss` templates into a final `.css`. + +## Templates +The templates folder at [`/templates`](../templates) hold style rules for all the themes as well as their particular color palettes. All themes import their styles from the [`/@theme-base/_styles.scss`](../templates/@theme-base/_styles.scss) partial and this is the file that should be changed when fixing a bug in styling or adding styles to a newly introduced element in the UI. + +In addition to [`_styles.scss`](../templates/@theme-base/_styles.scss), the [`/@theme-base/_full.scss`](../templates/@theme-base/_full.scss) will create a version of the theme where the base colour will be applied to further areas in the UI and can be used to have themes closer to a "dark mode" aesthetic. + +Changes made in these two files will apply to all themes. Two `.css` files are created per theme as a result (is a full version is available.). + +Theme colors be changed in their template files and can be found inside in their theme template folder. For instance, to change the Green Lume theme, change the variables at `/template/gree_lume/green_lume.scss`. The color values applied to those variables will replicate across ProtonMail's UI when the theme is applied. + +The [`/@theme-base`](../templates/@theme-base/) folder also includes two other folders with styling. These are [part of ProtonMail's Design System](https://github.com/ProtonMail/design-system/tree/master/_sass) and serve as a starting point to create the themes. + +## Theme Compilation + +Themes are written in `.scss` in order to allow multiple themes to be generated from a single template (`_styles.scss`). To achieve this a `gulpfile.js` is used to generate `.css` files for the themes. + +This file makes sure templates get converted into themes by making two commands available (NodeJS required). Most of the time there's no need to change this file. These commands can be run from your terminal: + +```bash +// Compiles themes as changes are made. +npm run watch + +// Compiles all themes. +npm run build +``` + +# Contributing +Everyone who is learning or already has a grasp of SASS and CSS is encouraged to contribute to the project. If you're applying a fix to `gulpfile.js` or any other files there's not set rules for now. + +Most contributions are usually theme related and if you're thinking of making a pull request please change the respective `.scss` file in favor of the compiled stylesheet (in `/themes`) in order to make these changes permanent and available for everyone. Templates can be found at `/templates/@theme-base`. + +If this is not clear please don't worry! Feel free to open a PR anyway and I'm happy to walk you through it. + +# Is there something missing? +If your question wasn't addressed here please feel free open an issue.
\ No newline at end of file diff --git a/docs/theme-templates-guide.md b/docs/theme-templates-guide.md new file mode 100644 index 0000000..4c1c91a --- /dev/null +++ b/docs/theme-templates-guide.md @@ -0,0 +1,67 @@ +# Theme Template + +There's a template provided at [`/templates/theme_example`](`../templates/theme_example`) that allows anyone that knows a bit a about `SCSS` to quickly generate a theme. + +This template does not style every single element of ProtonMail's UI and sticks to changing the `color` of elements rather than `position` or `font`. + +Feel free to extend and adapt this template to your needs bu creating an `_override.scss` file and adding new styles there, those styles will be scoped to your theme only. The [Ochin theme can be consulted as an example](../templates/ochin) of using overrides can be used on a theme. + +## Creating a theme from the template + +Sass was used to enable users and contributors to create themes without having to create a stylesheet from scratch. In order to create a theme it will require [some knowledge of how variables work in Sass](http://sass-lang.com/guide). + +### 1. Setting color palette +Decide at least four colors you would like to use in your theme, then replace the `hex` values on the following variables: + +```scss +$base: #1C1C1C; +$search: #000; +$highlight: #2FBF71; +$navigation: #fff; +``` + +Each variable applies to a certain area of the UI. The `$base` color changes the top and side navigation bars so this color will be prominent. The `$search` color on the other hand only applies to the search element. The `$highlight` color tends to be applied to elements that need contrast, for instance the compose button. Finally the `$navigation` variable sets the color of navigation links. + +> [Coolors is a good tool to create a palette](https://coolors.co/) if you're unsure of which colors to use! + +#### (Optional) Changing other variables +There is another set of variables available that will change elements that tend to fall out of the groups defined earlier. This could include content boxes, warnings, or elements that usually show up on the Settings part of the app. Feel free to experiment changing these if you are looking for a bit more customization (for adding more to the theme you can also extend the template, we'll get to this later). + +``` scss +$text_color: #0d0d0d; +$extra_color: #e6eaf0; +$danger_color: #d62646; +$warning_color: #ffaa00; +``` + +### 2. Compiling the template from SASS into a CSS theme +This project [includes a way of compiling themes using Gulp](./README.md#theme-compilation) but the way you do this is entirely up to you. You could do it through the command line, perhaps you use [Atom](https://atom.io/) and a plugin to compile your `.scss` files into CSS as you write them. Use [Webpack](https://webpack.js.org/) or [Sassmeister](https://www.sassmeister.com/). This project can compile your theme by running `npm run build`, provided that dependencies were installed. + +Regardless of the way you choose to do this you should end up with a `theme_template.css` *not* `.scss`. + +### 3. (Optional) Extending you theme. +Editing the variables can create a decent theme but you might want to further develop it and style as many elements as you like. To further customize your theme, add the extra CSS to an `_override.scss` file and add additional styles there. The file should be in `/templates/you_theme/`: + +```bash +. +├── @theme-base +├── green_lume +│ └── green_lume.scss +├── your_theme +│ └── your_theme.scss +│ └── _override_.scss +``` + +Override styles will be scoped to your theme only. The [Ochin theme can be consulted as an example](../templates/ochin) of using overrides can be used on a theme. Notice how the override partial is imported in the theme file: + +```scss +// Color variables here... + +@import "../@theme-base/styles"; +// @import "../@theme-base/full"; +// Please do not remove the import above, add overrides and other partials below this line. +@import 'override'; +``` + +### Final touches +Test your theme on ProtonMail and re-iterate as needed. If you think your theme is ready and *cool* you can submit a pull request and add it to this repo so everyone can use it. diff --git a/docs/theme-versioning.md b/docs/theme-versioning.md new file mode 100644 index 0000000..87fcf07 --- /dev/null +++ b/docs/theme-versioning.md @@ -0,0 +1,48 @@ +# Theme Versioning + +In `templates/@theme-base/` there is a `_version.scss` partial. This partial includes a single line of code that aids in keeping the version of all themes up to date: + +```scss +$version: 'v4.0.0-beta15'; +``` + +This variable is used in all themes by default and it will print the current version when a theme is compiled. For example, this theme header: + +```scss +@import "../@theme-base/version"; + +/*! =========================================== * + * SLICK THEME + * Version: #{$version} + * Author: ProtonMail + * Website: www.protonmail.com + * Twitter: @protonmail + * =========================================== */ +``` + +Will compile to: + +```scss +/*! =========================================== * + * SLICK THEME + * Version: v4.0.0-beta15 + * Author: ProtonMail + * Website: www.protonmail.com + * Twitter: @protonmail + * =========================================== */ +``` + +In some cases a theme might have a specific version it is compatible with. In that case the variable can be pointed to another version on the theme template file: + +```scss +@import "../@theme-base/version"; +$version: "v4.0.0-beta3"; + +/*! =========================================== * + * SLICK THEME + * Version: #{$version} + * Author: ProtonMail + * Website: www.protonmail.com + * Twitter: @protonmail + * =========================================== */ +``` |