Handling UI in user stories

Should user story scenarios (acceptance criteria) be used to describe the elements of UI?

More to the point, should the stories describe what the target UI looks like?

In this post, I’ll try to answer “Why UI has no place in user story acceptance criteria”. This naturally leads to the question “How best to handle UI requirements”.


Why UI has no place in user story acceptance criteria

Consider this, you sit in a co-located, cross-functional Agile team. You have UX/UI people, the developers, testers, and product all within the earshot. You’re one of the lucky ones!

The UX and Product people have spent time in advance thinking through the customer journey including screens and what the user experience will look (and feel) like. And they have built (sharp intake of breath), clickable wireframes!

Wow, looks like as a BA, you are in a pretty good spot. Suppose you pick up a story that has some UI elements to it. Lets pick the usual suspect, the login story.

The story goes something like, As a <some kind of user> I want to be able to log into the system So that I can use it. The UX people have come up with the following screen.

You have workshopped the hell out of various scenarios and you are now ready to capture the requirements in the form of scenarios for the story (in the BDD style of course).

So, should you describe, in intricate details, the different elements of the UI? Do you write something like…

Given I have a link to the system
When I click the link
Then the login page will be displayed
And it will have a text box for username
And a text box for password
And a function to Submit
And a function to reset password

When it comes to writing unambiguous requirements, translating pictures into words goes against all sense. It can give birth to too much confusion and misunderstanding. While we can list many different problems in the above scenario, lets just focus on UI in this post.


Keep your acceptance criteria independent of the solution

If one were to write the requirements for a login function like the example above, that would make the acceptance criteria too closely tied to solution. What if we could allow users to login without having to provide a username and a password?

What if we wanted different labels for the buttons or the text fields? We shouldn’t have to change the specification for small changes in the UI requirements as the intent behind the system behaviour doesn’t change. Moreover, the above style makes the specifications non-negotiable (as in the INVEST model).

Let’s rewrite the above example without involving the UI too much. Given that there is more than one avenue that the user can take while logging in, handling all that within a single scenario would make it complex. So let’s first specify what scenarios should cover everything that is important to cover in a login story:

  1. User successfully logs in
  2. User authentication failed
  3. User has forgotten their login details:

Scenario: User successfully logs in
Given a logged out user has been prompted to login
And the user has provided their login details
When they are successfully authenticated
Then they will see their logged in homepage

*P.S: I’m making up business rules as I go for convenience, although in a real life situation, where the user ends up after successful login may be driven by business rules.


Scenario Outline: User authentication failed
Given the user has provided their login details
When their authentication fails due to <reason>
Then they will see an error message
And they will be able to log in again

| reason |
| incorrect username and password combination |
| user account is disabled |


Scenario Outline: User has forgotten their login details
Given the user has forgotten their <login detail>
When they request to retrieve their login detail
Then the system will send an email reminding them of their login details

| login detail |
| username |
| password |


The above three scenarios capture the basic requirements associated with a standard login feature without being tied too closely to the UI or the solution design.

At this point, it would be useful to answer the question what role do user stories and specifications play in BDD. Where do they fit in the bigger scheme of things when it comes to defining requirements for a project. What is the purpose of writing user story acceptance criteria using, for example, the Given/When/Then format?

User stories and their associated specifications describe the behaviour of the system when a user (human or otherwise) interacts with it. When I include details of what the UI should look like in the acceptance criteria, I’m taking the focus away from what the specification should really be capturing; behaviour of the system.

One could argue that we can have separate scenarios covering the system behaviour and the UI, but that would just be muddying the waters. Remember, a useful specification is a clear, easy to read specification; adding unnecessary details would only make the specification long and hard to read.

UI requirements are more than just building text boxes and buttons

So what’s wrong with including UI details in user story scenarios? Describing UI in scenarios would be like saying “a word is worth a thousand pictures”, which, obviously, is quite counter-intuitive.

When you describe UI in user stories, you’ll probably use phrases like “there is a button”, but there is more to building a UI than just knowing that a button is to be built.

Assuming that we have established beyond doubt that a button does need to be built, there are other factors that need to be considered.

Factors like, where on the screen should the button be placed. What style button is it? What color schemes are we following? All these things are pretty important to most companies that operate websites because these factors are driven by the company’s corporate colours, accessibility, and the quest for a good user experience. To capture these details in words is futile while an actual picture will do a much better job.

UI details make the specification confusing.

Let’s explore the last point a bit further. Lets say that there is a requirement to make the login screen yellow.

You could write something like;

Given …..
When ….
Then the colour of the screen is yellow

Then you may also define what shade of yellow should it be. Is it the same shade of yellow throughout? Or is there a pattern that needs to be built? How does one describe these details in a specification? Even if we are able to, how do we keep it simple? And most importantly, how does it help us in understanding the intent of a feature?


Some common arguments against including UI in acceptance criteria

I have seen teams push back on the idea of not including the UI details in the acceptance criteria. I have listed some of the objections below:

1. This is how we define requirements

You may hear this if you’re joining an already established team. If someone’s idea of requirements is to put a couple of textboxes and a button on a screen, then they have got it all wrong.

When writing acceptance criteria for the login example, we must think about, as Dan North puts it, the what (the problem domain) and the how (the solution domain) of a login feature. The what here is ‘giving access to a user’, and the how may be ‘through the use of a username-password combination’. The what is essentially a business problem that needs to be solved, this problem typically will not change. The how, however, can change depending on the preferred solution. For example, we may choose a solution that involves a user entering a username and password, or we may use the services of a third-party authentication service, or a completely novel solution that doesn’t involve any of this. The point is, if we describe a username and password textbox in the acceptance criteria, then we are tying it too closely to the solution. We are also making the acceptance easily breakable with future changes (i.e. adoption of a different authentication method).

2. How will people who come later know what we built?

Reading documents is hard, and inefficient. If we want to show what we built for the purpose of training or showcasing progress, it is much easier to see the already built and working functionality in a production (or testing) environment. You have the advantage of playing around to learn more about the feature. For most people that would be enough to get familiar with it. For times when you need to know more about business rules working behind the scenes, there are always feature specifications.

3. How will the developers know what to build?

This is my favourite. As I have demonstrated in previous examples, writing down the details of UI doesn’t help, it only causes confusion. When UXers design screens, they take into account not only what ‘buttons’ should there be, but also, where is the best place to put them on the screen, their size, possibly colour and other factors.

Lets say you start elaborating the login story and it involves building a UI that will allow users to enter their authentication details and gain access to secure pages. Before you call the story ready for a developer to pick up, attach a printout of wireframes or designs that show the login screen in various states.

You can have a different picture that shows what the screen looks like the user has not entered anything, or when the user encounters an issue like incorrect login details and an error message needs to be displayed. If you are in a co-located team then you can use the wireframes during story kickoffs.

If you are in a distributed team where the developers and testers are in a different physical location, you can provide the wireframes and designs through a story management system like JIRA.  Even a mock-up built in MS Paint, or a tool like Balsamiq, or a hand drawn picture on the back of a napkin will do a better job than UI features described in words.

A picture will be clear and unambiguous, and has better chance of prompting questions from devs or testers, which is a good outcome. After all as they say, “A picture is worth a thousand words”.


How best to handle UI requirements

UI is best described by, well, UI. When discussing how a screen might look like, it is always easier (and recommended) to draw a picture on a whiteboard or a piece of paper to show your understanding (or ideas). One of the key reasons to adopt BDD is to put the focus back on the behaviour of the system we are trying to build. Keeping behaviour in focus ensures that we keep the business problem that we are trying to fix in mind.

If you are at the stage where you are writing BDD scenarios, we can safely assume that the requirements are pretty well understood. You may even have access to clickable (or static) wireframes. Use your BDD scenarios to describe behaviour of the system and the business requirements.

During your story review, or kickoff (or both) bring out the wireframes/designs and let everyone admire their beauty. There will be questions (something surely is wrong if there aren’t any), record those conversations on the story card (or on the picture itself and attach to the story card ). That way you know what was discussed and if there were any changes required.

In conclusion, the most sacred tenets behind BDD are communication and collaboration, and the best way to describe UI requirements is through visual communication.



  • TR

    I learn a lot from these blog posts. Awesome work, keep em coming!

  • Sudhi

    Superbly explained and never ever till date I have covered the UI requirements in the story in this way. Thanks for opening my eyes!! I shall including this in my User Stories going forward!!

  • Suresh Brady

    Good stuff

  • Eoin

    Thanks for this very good post.. What about the project management aspects of SCRUM. If you leave UI aspects out of User Stories how do you then manage the time/difficulty spent by team members in designing UX/UI. If you have no user stories for these tasks then, you have no story points and way of monitoring progress of related tasks in the context of a SCRUM project.

    • Ash

      @Eoin Did you ever find a solution to this? I was wondering a similar thing to this while reading through this article.

      @RYAN MCKERGOW What Eoin has raised is a specific issue of a more general problem: If you don’t include UI/UX requirements as user stories, how then do you sync UI/UX tasks with other work items in an Agile project?

      Clearly any UI work done has to be defined/recorded/tracked/incorporated, because it’s by definition, ‘work’. And since it’s work, it needs an associated work item(s). So if not a user story (and I’m being completely objective here), what should it be? In Agile terms, would it be a Task? Would this Task then be a sibling of user stories (part of the same Feature) that define the functional requirements associated?
      If not a Task, what else could it be?

  • Adam Pearce

    I would say I partially agree but partially disagree with this post. It comes down to what you see as ‘functionality’ vs a visual feature. These days, with touch based sites and very heavy interactivity around the visual design, there’s a fine line between UX/UI and ‘functionality’.
    If you’re talking about a static web page and the position of elements and look and feel of it, then sure, this can be dealt with independent of requirements.
    If you’re implementing given-when-then BDD scenarios and hoping to automate functional testing, then yes it would be a troublesome experiment to include UX/UI in these.
    But that does not mean that UX/UI does not count as ‘work’ that must be defined, estimated, tested, delivered and signed off by a business stakeholder.
    As mentioned above, there are plenty of sites that are fully feature rich and change very little in terms of functionality, but the focus of much of their work is refining the look and feel of the page. The ‘UI’ is not a dirty word because to these companies, changing a visual element could be a major step forward to a user. A user wants a change, so they can achieve a desired (improved) result — that sounds pretty well exactly like the definition of a user story to me!

    So in conclusion I would say, it’s wrong to suggest a “UI has no place in user story acceptance criteria”. It’s entirely possible a user story consists of ONLY a UI change. You can’t argue that’s “not a user story”, and without accepting those criteria, the change cannot be delivered. It’s a wishy-washy distinction. What matters most is agreeing on a standard format to present visual and UX requirements to your delivery team, in such a way that allows greatest flexibility of the less-important elements and focuses testing on the most important functionality. Just what that “most important” stuff is will be different in every organisation. If what you’re doing works for you, then you’re doing the right thing.

  • James

    I’ve had exactly this argument on many projects. This excellent article misses one key point in my view. And that is the massive overhead of maintaining stories with the design level of detail. And it adds nearly no value in the end.

    I’ve had folk tell me that stories need the actual messaging for particular scenarios; and in some cases the API error codes are needed! But then the overhead of maintaining that becomes massive.

    If such information is needed (and for various reasons it may need to be – especially on big Scaled Agile projects) it should be developed and maintained separately as a task measured in points from the team.

  • Willy De la Cruz Sierra

    I agree on specifying what the system does (behavior) rather than how the systems does it (solution) and I think you have explained very well. Nevertheless, there unclear things from your article, like: Is a BDD scenario the same as user story? Are BDD scenarios, from a feature file, acceptance criteria from a user story? Is a BDD feature a user story?

  • lm

    I agree with posters above who, imo, accurately see the distinction of a ui story versus a feature story: the functionality-focus belongs in the development version if a stkry, the “ui” onth, serves the persons if describing the reused graphical interface the element delivering this functionality will have, the ui designers use this story as a basis for delivering their graphical/css/etc. design/wireframe., not the feature itself. Also, as noted abive, you have to keep track of the ui work metrics and not including uo as a story means you do not track the burnups, etc, so the work is “lost” as far is the management aspect of the project goes…

    I’m keeping my ui stories 🙂

  • freddy

    What is BDD and why is it not explained??

    • Luan

      BDD stands for Behaviour Driven Development. Please google it. The reason it’s not explained is because if you’re interested in this article, you should already have some background on what it is.

  • GR

    This is pretty similar to how we handle it in Mural.

    For all those Human Centered Design people.
    How might we define a (HCD) )design method to better the scope and A/C for the UI/UX experience with our Stakeholders?

Leave a Reply

Your email address will not be published. Required fields are marked *