Documenting the Design of Rich Internet Applications: A Visual Language for State

December 17, 2007

Ajax and Rich Internet Applications (RIAs) have revolutionized the way users interact with Web sites. However, documenting the design of any page that uses Ajax is a challenge, because the page—and, more importantly, components on the page—can have different states, depending on how users interact with the page’s components.

When I use the term state, I refer to a page or a page component that displays different information—content or user interface (UI) elements—depending on a user’s interactions or the information available to the system. For example, the following components have state:

  • a navigation bar whose links appear in boldface to indicate a user’s current location within a Web site
  • a link that changes from Register to Sign in depending on whether a user is logged in
  • an Ajax widget that lets a user add a tag to a picture

Champion Advertisement
Continue Reading…

Since the information on a page or within a UI component on a page depends on the available information, rarely does all of the information that might appear within a component appear in that component at once. So, when we describe state, we have to identify both the information that is available for display and the conditions under which to display it. Said another way, as a user interacts with a UI component, what information should appear in that UI component?

So, how do we document both the state-to-state interactions on a page or in a component, as well as the types of interactions that modify their states? Designers have proposed various ways of bridging this gap—particularly storyboards and prototypes. Both of these techniques have their strengths.

Storyboards—much like scenarios—let you communicate the intent of a page’s functionality. However, unless its functionality is simple, documenting all of its conditions and their resulting states can be cumbersome.

Prototypes let you demonstrate functionality to stakeholders and engineers, but prototypes are difficult to use as documentation. For example, if you design ten states for a UI component, how does an engineer know the conditions under which each of the ten states appears? You could annotate each condition, but doesn’t that defeat the purpose of the prototype?

What’s more, there are no simple prototyping tools that let designers effortlessly design state behavior. Most prototyping tools document page-to-page behaviors, not state-to-state behaviors. Unless a designer knows Flash or HTML, CSS, and JavaScript—it’s necessary to assign a production development resource to create the prototype, which means the interaction designer still needs a way to communicate the design.

While both storyboards and prototypes can be helpful in some cases, neither technique provides the kind of robust language an interaction designer needs for communicating state-to-state interactions.

Even some traditional documentation techniques that provide a language for designing interactions come up a bit short when it comes to documenting RIAs. In task flows, as they currently exist, there is no clear indication when a site should

  • transition to the next page or
  • simply reload a single component on the same page

With wireframes, it’s impossible to identify all the conditions under which specific information should appear, in a manner that a development team can easily understand. However, if we add a few new symbols to the language of wireframes and task flows, we can overcome this shortcoming.


I’ll start with wireframes. We need to add a symbol to our visual vocabulary: the region. Figure 1 shows a region.

Figure 1—Region symbol
Region symbol

A region symbol blocks out an area of a wireframe in which a UI component—in its various states—always appears. For example, in the wireframe of a page header shown in Figure 2, the Sign in / Welcome region might contain different information, depending on what is known about a user.

Figure 2—Header wireframe
Header wireframe

To help people better understand a page layout, always include each component in some state as an example. You should name each region, making it easier for stakeholders and engineers to locate additional information about a region.

Task Flows

But how do we determine or communicate what information should appear within a given region of a page and when it should appear? That is the question.

Task flows, workflows, activity diagrams—whatever you call them—have served interaction designers well in documenting how users interact with a system. By adding some additional symbols to our visual vocabulary, task flows can also be a great tool for documenting state changes within a UI component.

For the purposes of this article, I’m going to extend Jesse James Garret’s visual vocabulary, but you can apply these same concepts to your preferred vocabulary.

First, we need to identify how a component responds to user interactions—that is, do its responses occur asynchronously or synchronously. Second, we need a way to represent each UI component—and its current state—in a task flow.

Asynchronous State Changes

For user interactions that do not require a page reload, asynchronous interactions—whether implemented in JavaScript, CSS, Ajax, or another RIA technology—use an arrow with a dotted line like that shown in Figure 3.

Figure 3—Arrow representing an asynchronous state change
Arrow representing an asynchronous state change

Synchronous State Changes

For user interactions that require an entire page to reload, synchronous interactions, use a single-line arrow, as shown in Figure 4. This is the standard arrow Jesse James Garrett uses in his visual vocabulary.

Figure 4—Arrow representing a synchronous state change
Arrow representing a synchronous state change

Putting It All Together: The Wireflow or the Taskframe

So, how do we represent a UI component in a task flow? For simple user interactions, your task flows can include your actual wireframes of a UI component and its various states directly within the task flow. This reduces the time people spend flipping between task flows and wireframes.

Let’s look again at the example of the Ajax login component that appears in the header wireframe in Figure 2. The information that appears in the header region depends entirely on the state of the UI component, which the task flow shown in Figure 5 defines.

Figure 5—Task flow for an Ajax login component
Task flow for an Ajax login component

Notice that this task flow includes a new component container symbol. Figure 6 shows the component container symbol.

Figure 6—Component container symbol
Component container symbol

This container identifies a UI component’s name and represents its current state within a task flow. For example, the component name Sign in / Welcome refers to the name of the region I defined in the wireframe of the page containing this component and Signed in represents that component’s current state. Thus, we get Sign in / Welcome: Signed in.

Now, let’s walk through the combination wireframe/task flow for the Sign in / Welcome component step by step.

  • In the Sign in / Welcome: Unknown User state, the user clicks Sign in. A Sign in / Welcome: Sign in state replaces the Sign in / Welcome: Unknown User state. The dotted line indicates this is an asynchronous behavior—that is, the page should not reload.
  • Once a user provides his email address and password in the Sign in / Welcome component, then clicks Sign in, the site asynchronously sends the login request to the server, as the dotted-line arrow indicates.
  • Per Jesse James Garret’s visual vocabulary, a diamond indicates a system decision point that a user interaction initiates. In this case, the user-initiated login request results in one of the following:
    • If the user provided a matching email address and password, the Sign in / Welcome: Signed in state results.
    • If the user did not enter the correct email address and password, the Sign in / Welcome: Error Signing in state results.

This method works great for illustrating state interactions for most components, but what happens if the interactions get too complex and unwieldy to include the component wireframes within a task flow?

The Straight Workflow

To accommodate very complex state interactions, we need to add another shape to our toolbox: a symbol that concisely represents a UI component and its state within a task flow like that shown in Figure 7.

Figure 7—UI component symbol
UI component symbol

Much like the Web page symbol, this UI component symbol represents a specific state for a UI component on a page. As with the component container symbol, use the following naming convention: [Component Name: State Name]—for example, Sign in / Welcome: Signed in.

Now, let’s recreate the task flow for the login UI component, using the UI component symbol, as shown in Figure 8.

Figure 8—Task flow for the login UI component, incorporating the UI component symbol
Task flow for the login UI component, incorporating the UI component symbol

Why Use This Approach?

Certainly, there are other ways of documenting your designs effectively. However, using wireflows can help you to think through your designs for RIAs more completely, represent them fully in your design documentation, and increase the clarity of your conversations about your designs with other members of your product team. 

Here’s a Visio stencil you can use when following this approach: Visio Stencil

CEO at Bluespark

Co-founder of Ruzuku

Peoria, Illinois, USA

Richard F. CecilRick has nearly a decade of experience envisioning and designing innovative solutions for a variety of companies, including startups, non-profits, universities, and Fortune 100 companies. During his tenure at Motricity, he worked with Cingular, BET, Ask, Alltel, and other clients and was the Design Lead for their core product offering. Rick was a co-founder of both the Interaction Design Group—now the Interaction Design Association (IxDA)—and the Triangle Usability Professionals’ Association (UPA). Active in the UPA, he also serves on the organizing committee for World Usability Day. Rick is also the UXnet Local Ambassador for Research Triangle Park.  Read More

Other Articles on Web Application Design

New on UXmatters