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:

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.

Tip: If you want more control over shadow block or border colours, learn about defining a theme.

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 overriding the following Blockly constants:

Blockly.HSV_SATURATION // 0 (inclusive) to 1 (exclusive), defaulting to 0.45
Blockly.HSV_VALUE // 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}');

Note: While Blockly only supports the BKY_ prefix currently, the reference system will be extended to support other prefixes pointing at other string tables. This should help isolate the application specific code and reduce the chance for conflicts with future versions of Blockly.

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 overriding the following Blockly constants:

Blockly.HSV_SATURATION // 0 (inclusive) to 1 (exclusive), defaulting to 0.45
Blockly.HSV_VALUE // 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.

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.