-
Notifications
You must be signed in to change notification settings - Fork 96
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: Add documentation for the proposed color system re-structure
- Loading branch information
1 parent
1cacc04
commit 0285186
Showing
1 changed file
with
194 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,194 @@ | ||
| # Color-Style System Documentation | ||
|
|
||
| ## Rapid Colors | ||
|
|
||
| ### Initial Color Approach | ||
| As at [Rapid v2.2.5](https://github.com/facebook/Rapid/releases/tag/rapid-v2.2.5), there were four (4) classes of color definition: | ||
| 1. Colors defined under a name in `StyleSystem.js` | ||
| 2. Colors defined by direct HEX value in `StyleSystem.js` | ||
| 3. Colors defined by direct HEX value in `RapidSystem.js` | ||
| 4. Colors rendered from the map satellite imagery | ||
|
|
||
| Ideally, there would be a central definition of each color which is the same across the Rapid application. | ||
| Before diving into the proposed solution to this problem, each class of color definition will be described to provide suitable context. | ||
|
|
||
| #### 1. Named Color Definition | ||
| These are the colors defined as parts of key-value pairs in `this.STYLE_DECLATATIONS` object in `/modules/core/StyleSystem.js`, where the key is a named color e.g. 'red', 'blue', 'green' (see the code block below). | ||
|
|
||
| ```JS | ||
| red: { | ||
| fill: { color: 0xe06e5f, alpha: 0.3 } // rgb(224, 110, 95) | ||
| } | ||
| ``` | ||
|
|
||
| There are **12** defined "colors", which are referenced **63** times in total by `this.STYLE_SELECTORS`; this property of the `StyleSystem` class maps feature tags to style declarations (see the code block below). | ||
|
|
||
| ```JS | ||
| building: { | ||
| '*': 'red' | ||
| } | ||
| ``` | ||
|
|
||
| An issue with this particular definition system is that this color definition includes more than just the `color` property (see the first code block in this section). It is also specifies an `alpha` value and is encased in an object which specifies the `fill` property of a map feature. | ||
|
|
||
| #### 2. Direct HEX Color Definition | ||
| These colors are also defined as parts of key-value pairs in `this.STYLE_DECLATATIONS` object in `/modules/core/StyleSystem.js`. The difference comes in the nonuse of named colors as keys; rather [OSM tags](https://wiki.openstreetmap.org/wiki/Tags) are used (see the code block below). | ||
|
|
||
| ```JS | ||
| primary: { | ||
| casing: { width: 10, color: 0x70372f }, | ||
| stroke: { width: 8, color: 0xf99806 } | ||
| } | ||
| ``` | ||
|
|
||
| There are **30** distinct HEX codes, which are referenced **75** times in total by `this.STYLE_DECLARATIONS` AND the `styleMatch()` function. Usage in `this.STYLE_DECLARATIONS`, as seen in the code block above, is the | ||
|
|
||
| With this color definition system, only the `color` property has anything to do with a color definition; thus, it does not have the same problem definition type #1 has of combining other style definition into color definition. However, there are two issues with the use of direct HEX code usage: | ||
| * Due to the repitition of very specific strings, it is error-prone and inefficient for refactoring. | ||
| * There are overlaps in the explicitly-defined HEX codes and `color` property values which have already been specified in named color definitions. For instance, the `green.fill.color` is assigned to `0x8cd05f` but this HEX code is also explicitly repeated in five (5) `this.STYLE_DECLARATION` objects such as `amenity: fountain` and `natural: water`. | ||
|
|
||
| #### 3. Rapid Color Definition | ||
| The two defintions above cover the colors of *most* of [OpenStreetMap](https://en.wikipedia.org/wiki/OpenStreetMap)'s features - Points, Lines and Areas - which are rendered with [Pixi.js](https://pixijs.com/). Rapid colors are used when rendering Rapid features; these are the AI-generated OpenStreetMap features based on [Facebook Roads](https://github.com/facebookmicrosites/Open-Mapping-At-Facebook) and [Microsoft Buildings](https://github.com/microsoft/GlobalMLBuildingFootprints). | ||
|
|
||
| Rapid colors are strings containing HEX codes which are elements in an array called `RAPID_COLORS`. An issue identified with this particular system is its redundancy; there are **10** Rapid colors but one of them is assigned to a constant again outside the array (specifically, the default Rapid color, `RAPID_MAGENTA`). This will be addressed in the "Future Works" section, as the proposed color system does NOT cover these colors due to the fact that they are already user-defined. | ||
|
|
||
| #### 4. Map Colors | ||
| These are the colors which show in the satellite imagery rendered by WebGL which forms the basis of the map. These colors are NOT within the control of Rapid developers but are important to consider when thinking about topics like color vision deficiencies. | ||
|
|
||
|
|
||
| ### Current Color Approach | ||
| #### System Aims | ||
| 1. Centralize all color definitions used within the Rapid codebase | ||
| 2. Enable efficient and error-resistant HEX code editing | ||
| 3. Clearly separate color and style definition | ||
|
|
||
| ***NOTE**: This color system only takes care of the first two types of colors in Rapid only: named colors and directly-defined colors.* | ||
|
|
||
| #### System Organization | ||
| * The colors are grouped by well-known color names such as 'red', 'green' | ||
| * There are **11** color groups; these color groups are arranged in ROYGBIV order followed by neutral tones: `brown`, `tan`, `white`, `black` and `grey` | ||
| * A color is defined in the format `<color-group>-<number>` e.g. `red-3`, `blue-4` | ||
| * If a color's number is `0`, that means that it is the only one in its group e.g. `white-0`, `black-0` | ||
| * For numbers `1` and above, the lower the number, the brighter/paler the color is | ||
|
|
||
| #### (Proposed) Color System | ||
| <table style="width:100%; max-width: 600px; min-width:400px"> | ||
| <tr> | ||
| <td> | ||
|
|
||
|  `red-1` <br> | ||
|  `red-2` <br> | ||
|  `red-3` <br> | ||
|  `red-4` <br> | ||
|  `orange-1` <br> | ||
|  `orange-2` <br> | ||
|  `orange-3` <br> | ||
|  `yellow-1` <br> | ||
|  `yellow-2` <br> | ||
|  `yellow-3` <br> | ||
|  `yellow-4` <br> | ||
|  `yellow-5` <br> | ||
|  `green-1` <br> | ||
|
|
||
| </td> | ||
|
|
||
| <td> | ||
|
|
||
|  `green-2` <br> | ||
|  `green-3` <br> | ||
|  `green-4` <br> | ||
|  `green-5` <br> | ||
|  `blue-1` <br> | ||
|  `blue-2` <br> | ||
|  `blue-3` <br> | ||
|  `blue-4` <br> | ||
|  `pink-1` <br> | ||
|  `pink-2` <br> | ||
|  `brown-1` <br> | ||
|  `brown-2` <br> | ||
|  `brown-3` <br> | ||
|
|
||
| </td> | ||
|
|
||
| <td> | ||
|
|
||
|
|
||
|  `brown-4` <br> | ||
|  `tan-1` <br> | ||
|  `tan-2` <br> | ||
|  `tan-3` <br> | ||
|  `white-0` <br> | ||
|  `black-0` <br> | ||
|  `gray-1` <br> | ||
|  `gray-2` <br> | ||
|  `gray-3` <br> | ||
|  `gray-4` <br> | ||
|  `gray-5` <br> | ||
|  `gray-6` <br> | ||
|  `gray-7` <br> | ||
|
|
||
| </td> | ||
|
|
||
| </tr> | ||
| </table> | ||
|
|
||
| #### Relevant Refactoring | ||
| To accomodate for the changes to the application, certain things were changed: | ||
| 1. The `/data/color_schemes.json` file was minified and added to the file system of Rapid in `/scripts/build_data.js` and `/modules/core/DataLoaderSystem.js`, respectively | ||
| 2. `DataLoaderSystem` is added as a dependency of `StyleSystem` | ||
| 3. Variables to hold the default color scheme, current color scheme and all color schemes were created and added the the constructor of `StyleSystem` | ||
| 4. In the `startAsync()` function, `DataLoaderSystem` is used to fetch the color schemes from the `/data/` folder | ||
| 5. A helper function called `getHexColorCode()` was added to `StyleSystem` to get the HEX color code based on the current color scheme selected. This function is used severally in the `styleMatch()` function | ||
| 6. All references to colors through named and directly-defined colors in `this.STYLE_DECLARATIONS` were renamed to match the new system | ||
|
|
||
| ### Adding New Color Schemes | ||
| There are several situations in which a developer may want to change the specific colors used to render features on the map e.g. to ensure colorblind accessibility. The proposed system also takes into consideration the ease with which developers can add a new color scheme. | ||
|
|
||
| 1. Identify the specific colors you want to redefine | ||
|
|
||
| 2. Identify the new HEX codes you want to assign to each new color | ||
|
|
||
| 3. Navigate to `/data/color_schemes.json` | ||
|
|
||
| 4. Add a key-value pair for the new color scheme to the document object in the following format: | ||
| ``` | ||
| "<new_color_scheme_name>": {} | ||
| ``` | ||
| ***NOTE**: The convention for this system is to use [snake_case](https://developer.mozilla.org/en-US/docs/Glossary/Snake_case#:~:text=Snake%20case%20is%20a%20way,the%20reader%20of%20its%20appearance.) when naming your new color scheme.* | ||
|
|
||
| 5. Add the colors with new definitions (along with said definitions) in key-value pairs to the newly created object in the following format: | ||
| ``` | ||
| "<color>": "<new_HEX_code>" | ||
| ``` | ||
|
|
||
| 6. Navigate to `/data/core.yaml` | ||
|
|
||
| 7. In the `en` > `preferences` > `color_selection` section, add the name of the color scheme you've just created as well as how you want the color scheme to be named in the Preferences pane dropdown in the following format | ||
| ``` | ||
| <new_color_scheme_name>: <dropdown_name> | ||
| ``` | ||
| * Ensure that the name you specified in `/data/color_schemes.json` matches the name you refer to it with here | ||
| * Ensure that neither `<new_color_scheme_name>` and `<dropdown_name>` are NOT surrounded in quotation marks | ||
| * `<dropdown_name>`remember that is case-sensitive | ||
|
|
||
| 8. Run `npm run all` jn the terminal to re-build the application with the new color scheme you've just added | ||
|
|
||
| 9. Run `npm run quickstart` in the terminal to start the application and look at your new color scheme in action! | ||
|
|
||
|
|
||
| Here is an example of | ||
| ```JSON | ||
| { | ||
| "colorblind_ibm": { | ||
| "red-3": "0x648fff", | ||
| "red-4": "0x785ef0", | ||
| "orange-1": "0xfe6100", | ||
| "yellow-2": "0xffb000" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ***NOTE**: You will need to rerun `npm run all` anytime you make changes to any file in the `/data/` folder to see the changes in the live application.* | ||
|
|
||
|
|
||
| ## Rapid Styling |