Blocks Design Standards

1. Blocks category design conventions

1.1 Block category

Block category refers to grouping blocks based on function.

All blocks also fall into three main types: input blocks, export blocks, and other blocks.

1 Input blocks

Blocks containing value input, such as sensors, or value blocks.

Block example: "Microphone loudness"

2 Export blocks

Blocks concerning power output or execution.

Block example: "move forward at power (50)%"

3 Other blocks

Blocks difficult to be categorized, such as Wi-Fi blocks.

Block example: "recognize (English) for (3) seconds"

1.2 Block recommended color

Users tend to locate different blocks according to block colors. Therefore, it is crucial to use a unique color for each block category.

The mBlock Extension Builder provides a table of recommended colors for different block types, and we suggest developers choose from these colors except for special occasions.

1.3 Category icon

Image formats:

File type: SVG
Size: 100*100
Background: transparent
Color: colored image

The color of category icon should be the same as block color.

1.4 Block icon

Image formats:

File type: SVG
Size: 100*100
Background: transparent
Color: white image

The importance of block icon:

As subject of the block
Shortens the length of each block
Makes a block more readable
Showcases the device/extension, easy for users to locate

1.5 Category name

Use less than 12 characters.

2. Block design conventions

2.1 Description convention

Punctuation and spaces

Use lower-case "x", "y", and "z" for the axes
Use a space between the subject and other characters

Note in "()"

Use "()" to include a note.

For instance, the unit of measurement for returned value:

2.2 Parameter processing

Scratch programming tends to avoid error reporting, so it is important to standardize parameter processing:

Apply force conversion. The converted value should be acceptable to the block. (Floating number to integer follows the basic rounding rule)
For empty input, or unacceptable converted value, the block shouldn't be executed
Parameter with a range value has the converting rule as: input greater than the max value will be rounded down the max value; input smaller than the minimum value will be rounded up to the minimum value

The following parts discuss three specific data types: integers, floats, and strings.

Integers

ID of the RGB LED should be an integer.
Integer input will be executed. Input greater than the max value will be rounded down the max value; input smaller than the minimum value will be rounded up to the minimum value
Floats will be rounded.
String input will be detected. Numeric input will be rounded to the nearest integer. For non-numeric input, the block won't be executed.

Floats

Beats of the buzzer: integers greater than 0.
Integers will be processed as integers of the same value
Float input will be executed normally
String input will be detected. Numeric input will be rounded to the nearest integer. For non-numeric input, the block won't be executed.

Strings

All input will be processed as string type and executed normally.