Key Notation

Last Updated 09.28.03

General Description

Key Notation is a type of legend used to define icons, elements, or terms that are used within the content of a page or a section of page content. Common uses for Key Notation include definitions of the Required Field icon, currency, and abbreviations of standard terms or phrases. The notation can be applicable to the entire page, a section of content, or a table. The content of this guideline is as follows:

Note: Key Notation should not be confused with a graph legend -- a page may contain no more than one Key Notation area, but may contain a separate legend for each graph.

Guideline Attributes

Spec Version # - 3.1
Spec Contributors - Betsy Beier, Mervyn Dennehy, Lisa Serface, Craig Louis
UI Models - all models
Example Products - all products
Related Guidelines - Common Formats, Abbreviations, Accessibility , Icons, Language in UI, Page Stamps, Component Order, Tables, Hide/Show

Interaction and Usage Specifications

General Principles

Key Notation should be used when a page contains status icons, symbols, or terms that may not be self-explanatory to users of an application.

Example of Key Notation for Entire Page with Sample Page Content
image to come...

Types of Key Notation

There are three types of Key Notation syntax, depending on the type of element being defined:

Note that scaling can also be defined with the {Term} = {Definition} syntax. The following table lists common types of Key Notation that use these three syntaxes.

Type of Key Element Defined Examples Related Guidelines
Icons and other images Icon Indicates required field
Indicates changed items
Map symbols Indicates major road n/a
Terms and character-based symbols Monetary Units (with a single currency on page) Currency = German Marks Common Formats
Monetary Units (with multiple currencies on page) USD = United States Dollars
DM = German Marks
Time setting Time Zone = Pacific Standard Time
Measures Weight = Metric Tonnes
Distance = Miles
Standard abbreviations Res = Resource Abbreviations
Standard acronyms RMA = Return Material Authorization
Contracted phrase Rate = Annual Percentage Rate
Yield = Annual Percentage Yield
Context-specific term or phrase On Hold = Item already requested by another user n/a
Scales of values (in scale format) Numeric values Amounts in thousands Common Formats
Population in Millions
Amounts in millions, except per share data

Methods of Displaying Key Notation

Key Notation can be displayed in four ways:

The method chosen depends on the number and type of keys, and other elements on the page.

Key Notation Under a Header Component

This is the standard method of displaying Key Notation. In this approach, up to 4 keys of any type can be displayed beneath the page title, a subheader, or a subsubheader. Definitions are presented above the first occurrence of the icon or term, but content is pushed further down the page. When associated with a Hide/Show More Information component, users can hide the Key Notation when it is no longer useful.

Example of Multiple Keys Under a Header
Key Notation example with both term and scaling defintions

Caution: Key Notation of numeric scales, such as "Amount in thousands" should not be associated with a Hide/Show component, as hidden scales could lead to serious user error.

Example of Key Notation with Hide/Show
Key Notation example with Hide/Show

Key Notation in a Message Page

In this approach, place a link to a message page in a Tip, or place an Information Icon in the column header of a table. When the user clicks the link or Information Icon, Key Notation is displayed in the message page. This method is useful when more than 4 keys require definition. However, if any of those keys provide definitions of numeric scales, they should be displayed prominently under a header component, while the remaining keys are defined on a message page.

Note: If your application allows users to turn off Key Notation in their Global Preferences, any Tips that link to Key Notation in message pages remain, allowing users to still access the Key Notation on message pages. In this case to completely eliminate Key Notation, Tips must also be turned off. Refer to the Preferences Global Page section of the Global Templates BLAF guideline for more on Preferences.

Example of a Key Notation Info Link in a Tip
Tip with link to message page containing Key Notation

Note: If icons appear in more than one column of a table, use a Tip to display the message page, rather than placing info icons in each column header.

Example of a Message Page with Key Notation
Message page containing multiple keys

Key Notation in a Content Container

In this alternate approach, up to seven keys can be placed in a content container, right-aligned below a header component. This method allows space to the left for other informational page elements such as contextual information, Tips, Page Stamps, and Instruction Text.

Example of a Key Notation in a Content Container
Key Notation in a right-aligned content container

Consider the following principles when placing Key Notation in content containers:

Key Notation Under a SubTab

Key Notation can be placed underneath a SubTab when the information is specific to that SubTab. Each SubTab can have its own separate Key Notation where needed.

Example of Key Notation Under a SubTab
Key Notation beneath a SubTab

Combining Methods of Key Notation

When using more than one method of Key Notation to define elements on a page:

Example of Combined Methods of Key Notation
Key Notation both below the page title and in a content container

Setting Limits on Key Notation

Excessive use of Key Notation can be annoying to users who are either experienced in an application or familiar with the terminology common to a specific domain. However, new users may fail to complete a task if they are not provided with certain definitions. There are four ways to address these conflicting requirements:

Visual Specifications

Contents of Key Notation

Placement of Key/Legend Notation

Key Notation (only one per page) is associated with the header component. If Key Notation exists it is either underneath a header (or page title), a subheader, or a subsubheader. There are also other components that are positioned in this area, including Instruction Text, the Hide/Show component, and Page Stamps.

For the specific vertical layout order and placement of the Key/Legend compare to other components, see Component Order.

Key/Legend Placement with Instruction Text

Example of Key Notation for Entire Page with Instruction Text
image to come...

Example of Key Notation for Section of a Page with Instruction Text
image to come...

Key/Legend Placement with Hide/Show Component

NOTE: It is not recommended to place a required field within a hidden section of content

Example of Key Notation for Section of Page with Section Hidden
image to come...

Example of Key Notation for Section of Page with Section Shown
image to come...

Open/Closed Issues