Skip to main content

Document Design Guidelines and Specifications

Learning Objectives

After completing this unit, you’ll be able to:

  • Create detailed design specifications.
  • Describe the six most common interaction states.
  • Write effective design guidelines.

Partnering with Engineers

Turning designs into live, functional code in an application requires a strong partnership between design and engineering. If you’re both the designer and the engineer, that’s easy. If not, you have an engineering partner who will implement your design. The handoff of your design should be accompanied by a deliberate knowledge transfer so the design is built as intended. You document your knowledge in the form of specifications, commonly known as specs. 

Design Specifications

Design specifications document the size, color, typography, and interaction values of your design, so that an engineer can use those values in the code. The design spec for an app describes the appearance of each element, specifying its width and height, RGB or HEX color values, font size and line-height, padding, margin, and interactions. The interactions are defined in an interaction specification.

Design specifications are shown on a screen, including pixel width and values.

Interaction specifications provide the values inputted when a person uses the element you are designing. And in a world of diverse hardware and preferences, users can interact with your design in different ways. For example: 

  • They may be a keyboard user and tab over to your element.
  • They could be a mouse user and move their cursor to your design.
  • They could be using a touchscreen device and tap the element with their finger.

An important part of any element’s interaction spec is the element’s interaction states.

Interaction States

Interaction specs show how the design changes based on interaction by the user. There are six main interaction states that all designs must have specifications for.




The most common state, default, is when an app first opens, and no interaction has occurred. 

Designers always address the default state, but often overlook the other states in this table.


An element that supports interaction has focus when a user highlights it through keyboard interaction or by clicking into it. Only interactive elements have a focus state.


Similar to the focus state, the hover state indicates to the user that an element is interactive when they move their mouse cursor over the element.


An element’s disabled state tells users that although it’s usually interactive, it’s not usable now.


Precisely when users encounter the pressed state depends on the device they use to interact with an element. 

  • Keyboard: After a user presses a keyboard key and before they release that key
  • Mouse: After a user clicks a mouse button and before they release the button
  • Touchscreen: After a user presses a finger to a touchscreen and before they lift that finger

The pressed state indicates that an action is about to occur, as soon as this state resolves.


The active state indicates that an element is selected. Commonly seen in menus and lists, the active state often adds a highlight to the current page in a navigation menu, or a checkmark icon next to the selected item in a list.

Six different interaction states shown on screens with an astronaut looking at them.

In addition to the six most common states, your design might warrant states that are specific to a type of element or a supported device. An element that users can move by dragging it across the screen needs a dragged state. Certain design elements may have an affordance that requires on and off states, similar to a light switch. Some elements have notifications for error, success, or warning, requiring three corresponding states. 

Accessibility Guidelines

“[Providing] information conveyed with color through another visual means ensures users who cannot see color can still perceive the information.”
—WCAG 2.0, Use of Color, SC 1.4.1

States don’t always come in the form of a shape or color change. Designs must follow Web Content Accessibility Guidelines (WCAG), ensuring that apps are usable by users of all abilities. The intent is simple: Make web content more accessible to all people. 

The SC 1.4.1 guideline in WCAG 2.0 tells us to make sure states are never indicated by color alone. This means changing the color of an element’s border from gray to red cannot be the only way to indicate an error state. Someone who can’t see color won’t know that there is an error. Adding text to the error state, in addition to the border color change, helps all users accomplish the tasks they need to when using your design.

Design Guidelines

Interaction specifications help engineers code your design as intended. To use a design as intended, designers and engineers need to know its purpose, where it does and doesn’t belong, how it’s used, and what variations support specific use cases. 

A screen showing SLDS website design guidelines.

These broader details are addressed in design pattern guidelines. Guidelines for design patterns describe the usage of macro workflows, such as creating a record, and microinteractive elements, such as buttons and inputs. Some design pattern guidelines also outline reasons to choose one design pattern over another.

Also known as brand style guidelines, foundation guidelines define the visual style of an app. They include details such as layout, typography, color, illustration, iconography, kinetics, and branding.

All these types of guidelines need structure. Within a consistent structure, each guideline should provide information that conveys the proper usage, anatomy, use case, form factor (such as screen size and touch functionality), best practices, and accessibility. 

One of the best ways to document a design is by using do’s and don’ts. 

Do’s and Don’ts 

Do’s and don’ts examples from the SLDS website design guidelines.

Do’s and don’ts are an effective way to communicate rules. An example of what to do beside an example of what not to do helps readers absorb rules quickly. An image accompanied by a brief textual description usually works well.


Over time, a good pattern library evolves. Ideally, your engineering partners build each pattern and its elements as components. As your patterns are codified, the pattern library graduates from a pattern library to a fully fledged design system.

Now that you have a basic understanding of systems design, you’re ready to learn how developers turn elements into components. To learn about coding components, see Lightning Design System Development for Designers.


Keep learning for
Sign up for an account to continue.
What’s in it for you?
  • Get personalized recommendations for your career goals
  • Practice your skills with hands-on challenges and quizzes
  • Track and share your progress with employers
  • Connect to mentorship and career opportunities