Below are the start of UI guidelines... this document is a work in progress! Also it may be helpful to note that "guidelines" are just that - not rules. There may be exceptions. So take seriously, but not rigidly. Comments and suggestions are welcome.


Button or Link?

That is the question - and a good one. Sometimes the answer can be ambiguous.

So, when trying to decide what to use, ask yourself:

"Am I going somewhere? Or, am I doing something?"

If you're going somewhere, you're navigating. So use a link. This includes drilling down to another level of content, or going to another page to perform a related action. Nothing about the data changes or is saved (yet), you're simply getting somewhere else or to the next step.

If you're doing something, use a button. This includes committing changes to the database, sending a message, adding or removing fields in a form - something is functionally happening or changing, you're not just moving to another screen.

What about popup modal windows? Do you open these with a button or link? You're proceeding to a next step, but not really going to another page (in fact you'll return to the same page, most likely with a changed state). So, it might be helpful to think of modal windows as "enhanced" doing, or an action that might be considered changing the form in some way, so launching with a button would be appropriate.

What about hover content (panels, tooltips, etc)? These can be activated with buttons or links. Sometimes you just need a little more information about what the button or link does, or what a piece of content or functionality means, so hover content shouldn't be based on the mechanism for revealing it, but on user needs. (note - this section may be adjusted to consider "additional info" or "help" panels activated with a "?" button or link)


Button Labeling

Oh, what to call these things! So many actions to take, so many different types of buttons to label. But, we'd like some consistency, so here's a place to start:

1. Be brief. Use one word - and make it a verb - whenever possible (see the core button list below). If you're tempted to add more words, ask: do the words *really* add meaning, clarity, or differentiation from other buttons on the page? If you find yourself inventing a new button label altogether, is it really a distinct action? If so, perhaps it can be added to the "core" list.

2. Stick with the following "core" buttons as-is, whenever possible:

Button LabelActionShortcut Key
SaveCommit something new or updated to the database, and remain on the page.(key)
Save & CloseCommit something new or updated to the database, and go to the next logical page, a summary view of the data entered, or if neither of these exist, to wherever the user came from before.(key)
DeleteRemove something from the database. 
RevertRevert to a previous state. 
CancelStop an action, discard all changes without prompting and return user to where they were before. 
ResetBefore saving, clear all entries or reset to defaults. 
AddAdd an element to the page or form 
UploadUpload files and data 
ImportPull data into a LabKey format 
ExportPush data out in another format 
InferReconciling data (?) 
ActivateToggle something on 
DeactivateToggle something off 
BrowseOpen a file browser window 
SearchInitiate a search query 
ReloadReload the page to refresh the view 
SendSend something somewhere or to someone 
RunExecute a script or process 


Button Positioning

For guidance when placing buttons, use the following decision tree:

1. first choice: directly below the related fields or form, especially if there is more than one form element (i.e. several text fields, radio buttons, etc that are processed together – button should appear directly below)

2. second choice: to the right of the field or form, especially when there is only one form element (i.e., webpart dropdown, single search field) or it makes sense to directly relate the button to the form element (i.e. a Browse button by text field)

3. third choice: if there is a long table or form that requires scrolling, buttons may appear at the top and the bottom so the user has quick access in either direction.

In addition...

When placing buttons side-by-side: Leave xx pixels of space between each button to minimize the chance of clicking the wrong choice.

When placing the "Cancel" button: Always place to the right of other buttons, so "Cancel" is always the last (rightmost) button in a group.


Using the Webpart Nav Menu

Use this component to reduce the number of text links within webparts, cleaning up the visual display.

What goes in a webpart nav menu... or, what remains a link? Where webpart menus are concerned, it might be easier to think about what *doesn't* go in a menu. When placing a text link, ask:

  • Will this link be used by everyone?
  • Is the link specific to a function within the webpart, where proximity is crucial?
  • Is the link going to be used alot? Is it right in the path of action?

If a link can pass these tests, it might be appropriate to leave as a link, always visible, outside the menu. Otherwise, consider moving as many text links as possible into a logical menu system.

How to word the menu items: Like buttons, use words as sparingly as possible. If you're tempted to add words, ask: do they *really* provide clarity, or differentiation between similar menu items? If not, resist!

If you do write multi-word menu items, follow standard headline/subhead style, i.e. capitalize all major words while leaving prepositions and conjunctions lower case ("at", "the", "and", "but", "to", etc.)



Its definitely a good thing to let users know what's happening. Here are some general guidelines:

Navigating away from a dirty page: If the user tries to leave a page with unsaved changes, the UI should prompt the user with an alert box saying:

"Are you sure you want to leave this page?
There are unsaved changes. Leaving now will abandon those changes.
Press OK to continue, or Cancel to stay on the current page."

Required Fields: When a form field is required, place a "*" next to the field names and note at the bottom of the form: *=required.

Error messages: Error messages should appear within the visible region of the window, and must be comprehensible to non-developers. Do not use code-specific terminology.

Also, whenever possible/appropriate, in addition to the error message provide suggestions on how the user might correct the error. Terminology should be accessible to users familiar with our UI.


Useful Resources


expand all collapse all