Introduction

Writing code for UI is hard and time-consuming. Therefore, it’s worth the time and effort to talk about what we can do to improve the process of converting specs to actual UIs. Trust me, time spent upfront on understanding the UI specs is time well spent. I’ve been writing (mostly web) UI code for many years now, and have had to learn the hard way some valuable lessons. I want to share some of my thoughts here in hope that it might help others.

Right and Wrong Ways

There are many wrong ways to create the UI specs, convey them to developers and then write the code, and at the end they are all miserable in their own ways. For eg, starting to write UI code without a good understanding of business requirements is a for-sure way to lose. Also, having the developers create the UI specs in the first place is also NOT a good idea because the end result is just that: UIs created by developers, and they typically suck.

The right way to do this is to have a dedicated team of business and UX folks, and possibly some dev team involvement, who work together to come up with the specs. The business folks will make sure the use cases are implemented by the specs, and the UX folks will make sure these use cases are fulfilled by the software with a good user experience.

What The UI Specs Should Cover

The UI spec docs should cover the following aspects, assuming you are designing the UIs for all screen sizes:

• Spacing – horizontal and vertical.
• Color and font – make sure to cover all texts and UI components.
• Behavior/interaction – UI interactions/flow from one screen to the next. Hidden UI elements such as popups, spinners, etc.
• Validation state – UI with validation messages.
• Error state – UI with error messages.

What Questions Should Developers Ask When Getting Specs

Questions to ask the UX team when getting specs from them (some of these are stolen learned from Estelle Weyl):

• What is the main use case of each UI flow?
• What are the rare use cases of each UI flow?
• For every  user action available on the page, what is the application reaction?
• When grids are involved, are the ratios and other characteristics of the content accounted for?
• What should happen when a line of text is too long for the width?
• What is the touch, keyboard and mouse interactions for each interactive UI component/step?
• If you have an existing UI style guide, are there any UI components that are not covered by the style guide?
• Is there a standard layout in the application?
• Are there enough room included in all the components in the specs for internationalization?
• What are the UI components they will likely have a performance impact?
• Does the application have any accessibility requirements?

Additional Comments

• Specs should flow from left to right, top to bottom.
• Unless the UI has a fixed height, there’s no need to define spacing to the bottom of page.
• Define specs in terms of boxes as much as possible b/c everything in CSS is a box model.
• Consider using HSLa for CSS color instead of RGB or HEX b/c it’s more intuitive.

Sample UI Spec Docs

A few years ago I worked on a website for a business that makes airplane repair equipments, and these are the UI spec docs I got from the designer I was working with. I’m including them here as a reference in case you find them helpful. Note that these specs were defined with only desktop PC screen sizes in mind at the time, and they all assumed fixed sizes in width and height (man how nice that was back then!). So they don’t apply to responsive design principles completely, but I think you should still be able to find them helpful. I like how the designer defined the specs in well defined grids/boxes with exact dimensions.

The live site for this project is www.cftools.us.

Here’s the spec doc for the common site layout:

Here’s the spec doc for the home page with detailed spacing, font and color info:

Here’s a screenshot of the finished home page:

 

Conclusion

As you can see, there’s a lot that goes into defining good UI specs and communicating them to the developers. This blog post barely scratches the surface. For any professional team out there, if you care about what the final product will look and behave, this process should never be overlooked or hastened. Otherwise you can end up with a half-baked, amateur-looking, or worse yet, unusable and frustrating software user experience that leaves users confused and disgruntled. Chances are they will probably never use your software again.

But if this process is done correctly, even though it will take a little more time upfront, long term the total amount of time taken for the project will probably be shorter, and the results can be very rewarding for all parties involved: the team that implemented this will feel proud of their work and more synergy will be generated, the users will have a great experience which means increased traffic and usage, and this in turn usually translates to the bottom line: more $$ and more happiness for the team!