Block colour

Most Blockly apps use a variety of block colours to visually group the blocks into categories. The blocks shipped with Blockly include eight categories, with the colours mirrored by the various toolbar categories in the demos:

A screenshot of a workspace with an example of each block color.

Additional colours on the block are derived from the main colour. For example, shadow blocks are a desaturated version of the main colour, and border colours are a darker version.

Defining the block colour

The block colour can be defined in either the JSON or JavaScript notations:

JSON

{
  // ...,
  "colour": 160,
}

JavaScript

init: function() {
  // ...
  this.setColour(160);
}

Note the British spelling. Failure to set the colour results in a black block.

The colour value can take one of several forms. The simplest is a number between 0-360, defining the block's hue in the hue-saturation-value (HSV) colour model.

Using HSV with saturation and value fixed for all block colours allows you to easily select a block colour, while ensuring all blocks share a cohesive palette.

Several color pickers offer the HSV colour space, such as HSV picker. Enter Blockly's saturation and value constants (the defaults are 45% and 65% respectively), then slide the hue as desired. Use this hue number as the colour value (JSON), or the argument to the this.setColour(..) function (JavaScript).

The saturation and values can be adapted for each application by calling the following functions:

Blockly.colour.setHsvSaturation() // 0 (inclusive) to 1 (exclusive), defaulting to 0.45
Blockly..colour.setHsvValue() // 0 (inclusive) to 1 (exclusive), defaulting to 0.65

Colour references

Often, multiple blocks share the same colour, and centralizing the colour definitions simplifies managing the colours and adding new blocks of the correct colour. Block colours can use string table references to do exactly that.

Blockly includes nine colour constants in the string table, corresponding to the toolbox categories, plus a distinct colour for dynamic variables:

'%{BKY_LOGIC_HUE}'
'%{BKY_LOOPS_HUE}'
'%{BKY_MATH_HUE}'
'%{BKY_TEXTS_HUE}'
'%{BKY_LISTS_HUE}'
'%{BKY_COLOUR_HUE}'
'%{BKY_VARIABLES_HUE}'
'%{BKY_VARIABLES_DYNAMIC_HUE}'
'%{BKY_PROCEDURES_HUE}'

These string values can be used in both the JSON definitions and block.setColour(..).

You can add your own colour constants by adding to Blockly.Msg:

// Define the colour
Blockly.Msg.EVERYTHING_HUE = 42;
// Use in a block or block definition:
block.setColour('%{BKY_EVERYTHING_HUE}');

Storing the colours in the localization string table, may seem unusual, but it is convenient given the JSON notation already has support for the references. It also allows colors to be localized, if desired.

Customizing saturation and value

The saturation and values can be adapted for each application by calling the following functions:

Blockly.colour.setHsvSaturation() // 0 (inclusive) to 1 (exclusive), defaulting to 0.45
Blockly..colour.setHsvValue() // 0 (inclusive) to 1 (exclusive), defaulting to 0.65

Colour values in hex

Using the HSV colour space is highly recommended, but Blockly does support block colors specified as #RRGGBB hexidecimals. While this can facilitate coordination with other application colors (e.g., styles in CSS) and design applications (e.g., Photoshop), it is a design risk that could easily lead to uncoordinated blocks if not chosen carefully.

An example of poorly selected colors.

Unless you have dedicated visual design resources, working within the constraints of the HSV colour space is recommended. If attempting to redefine all colours in this manner, consider Google's Material Design resources on colour.

Accessibility concerns

Blockly uses colour as a strong hint about the role of each block, and to group blocks together. For the included blocks, this affordance is secondary to the text on the block, and so not a critical attribute. However, when choosing a block colour palette, colour blindness should be a consideration.

Blockly provides several themes in an effort to accommodate some types of colour vision deficiency. This page includes example 7, 12, and 15 colour palettes that attempt to maximize distinction across the most common forms of colour blindness. Note that this would not map to 7, 12, or 15 block categories in Blockly, because some shades should be reserved for shadow blocks and fields.