UX specification best practices - how to add annotations


Dear UXers,

I am a junior UX designer who is struggling with spec :D. After I’ve been working at this startup for 4 months and watching/doing so hard our UX specification documentation progress, I decided to discover what other solutions there are for this problem.

I thought I will write a bit about our process, to let you know our situations and tools which we are using, after that I will put my questions regarding the solutions.

So basically after apps were designed in Sketch, we upload them to InVision and there we give feedback to each other. After this, we send the InVision link to client, so they are able to give feedback as well. Specifications are written into a Google doc and sent to client and devs. But unfortunately they are so havy and long, that neither our devs, neither our clients don’t want to waste their time with reading it.

So the ideal solution for this situation would be a separate document which is not too long, compatible with mobile (I know that Axure has some which could resolve this problem, but that is not mobile specific), and that would be nice as well to be linkable to invision/sketch.

if not, just try to write about your process of writing specifications.

Thanks in advance,


Hi Andrea,
Are you prototyping all states of every screen into InVision and annotating them as needed inside the tool? That could reduce or possibly even eliminate the need for a heavy specifications doc. Hope that helps!


@maryshaw Do you think that it might behoove @andrea and her team to start soliciting feedback from the rest of the team earlier in the design process? My thinking is that if the team can catch and cure any potential issues earlier, it will eliminate the need for much of the bulk in their documentation. I’m curious to hear your thoughts.


I’m working as a UX Engineer at a startup too, and we have a very lean spec system.

Before I describe the process, a disclaimer: we have our own development team in house, and I’m the guy that bridges UX and Development. Its a product company and so there are no clients - just users.

Our team follows a SCRUM model of product development (all teams working on their own goals parallely).
For UX, we follow a similar approach as you: Balsamiq-> Evaluate -> Sketch, Invision -> Evaluate.
At the end of each evaluation session, we make the spec sheet only for that part of the sprint we just completed. This moves on to developers, and we generate a spec document only for that module of the product.

So basically chunk the product into distinct pieces, so our work remains agile, and specs - lean.
When there is a problem we need to address with some part of the product, we just refer to that separate spec document.

I know dealing with clients changes things, but if they are open to it, you could try this approach.


Thanks Doug - absolutely! We start soliciting team feedback at the sketching stage, well before any formal designs are created, and get users involved as early as possible.


Another thing that can help after a while is having a living style guide (either code based ideally or a design one).
Then you can have patterns, and just point to those, and everyone then knows, this is how buttons look/feel throughout all interactions etc.

Although you do need to make sure that this is maintained, as it is still a living document :slight_smile: and otherwise it can become quickly outdated and un-useful. This would only really be helpful for a long term client or if you work on in-house products.


Dear @maryshaw, first of all, thanks for your answer! :slight_smile: we use InVision as a prototype, so we can show it to the others/client. This means, that client and designers can leave their comment on the prototype. We could use comment feature to describe specifications but we prefer writing a separate UX spec. document, where everybody (client, devs, designers) can follow changes.

Second, what happens if a screen changes? We will have to change the comment and screen as well, and I am not sure if these changes will be traceable.


@dougcollins and @maryshaw you are both right!:slight_smile: Users should be involved as early phase as it’s possible (this was my first thing which I was missing from our process after becoming involved to the projects), but unfortunately as we know, there are some phases/clients when the budget doesn’t permit user testing. But maybe we should show the design at an early phase to designer team at least. Maybe it would help. But please specify how this would eliminate the documentation, I’m not sure I understand :slight_smile:


hello @natalie_eustace, and thanks for your answer!:slight_smile: Not sure I understand what do you mean with having a living style guide with patterns. This sounds more like a design specific something than a UX specification :slight_smile:

Please let me know, if I missunderstood something!


Hey @andrea no problem :slight_smile:

A style guide is both for design and UX. When it can really start coming in handy for us is for patterns. I.e if you have a specific way of doing something in terms of not just look and feel but interactions and behaviour, you can record it in one place and then reference it when you use it or adapt it for other things. But then again, they are helpful for consistency across your design as well (i.e. button states etc). Depends what you mean by UX specs I guess, as when we think about them at our work, we are thinking about the whole user experience, so that includes design, interaction behaviour, etc.

A really bad example (best off the top of my head). Say you have a specific type of modal that has a max height, scrolling behaviour with sticky buttons at the bottom. You’ve done research and found that this is a really good way to handle specific things and working for particular situations. You record rationale behind it and this design, and then when using it in other places, you can point to this pattern.

I like @maryshaw 's suggestion of making the Invision pages your specification, because with that you can track changes over time through the comments and history etc.

I’ve also used Axure in the past, as you can annotate and then export a specification document that references relevant pieces, but this can be a hefty document, and relies on keeping things up to date in the Axure comments etc.