Five-Minute Introduction

A short intro to the basics of using You'll learn how to create states, add transitions, and nest states into groups. helps you think about and describe the behavior of a system, while building prototype user interfaces on top of it.

To illustrate how this works, let’s specify a super-simple system: a traffic light. How does a traffic light behave? It has three lights that turn on in succession, with only one light on at a time. Let’s model each illuminated light as a state of our system:

Tip: The asterisk means that Green is the starting state. (Every system needs to start somewhere, and for our light we’ve arbitrarily decided to start there.) The asterisk is optional; without it, you’ll just start in the first listed state.

Now that we’ve got three states, how does the system move between them — from green to yellow and yellow to red and red to green? For that, we need to specify transitions, which define how to move from one state to another in response to an event.

Our simple traffic light is driven by a timer, which emits a tick event at regular intervals. Here’s our spec with transitions added:

Tip: Click the underlined event name in the system diagram above to move the stoplight through its states.

Clicking through the diagram helps us verify the behavior: If the tick event occurs while the light is Green, the system moves to the Yellow state. If the tick occurs while the light is Yellow, it moves to Red.

Cool. We’re not even five minutes in and we have a well-defined, interactive model of our system’s behavior, which we can share with colleagues to seed discussions.

But this model is still pretty abstract — it’d be easier to communicate if we had a prototype to visualize how the traffic light should look in each state:

Tip: You can edit the code above to change the prototype.

Imagine you presented this spec and prototype to your team, and an astute coworker asked how the traffic light should behave when it loses power.

Good question. When our stoplight loses power, it should blink red. But when it has power, it should act as we’ve already described.

We could refine our specification by adding Blinking Red On and Blinking Red Off states:

However, we’ve had to repeat ourselves quite a bit. The power failed and power restored transitions are defined everywhere, even though there are really only two cases: Either the light is powered (and the power fails) or it’s unpowered (and the power is restored).

We can make this system easier to understand by defining these “parent” states explicitly, and grouping the others underneath them:

Tip: to nest one state in another in the editor, simply indent it two spaces underneath the parent state.

This hierarchy matches how we think about the behavior: It doesn’t matter which light is illuminated when the power fails, since the behavior is the same: Transition to the Unpowered state (which starts at Red On).

That covers the elements of — it might not feel like much, but you’ve actually learned enough to specify, explore, and test many different complex systems and their behaviors!

Check out these examples:

Or, if you want to dive deeper: