Documentation for designers
How to work with the VA.gov Design System
The VA.gov Design System is VA.gov’s front-end framework. This site documents most of the components in the Sketch library. However, some components will be migrated over the next few release cycles.
Before getting started, we recommend that you get familiar with the VA.gov Design System and how you can use it as part of your design process. Each section includes some helpful information:
- Content style guide: Our house style guide for VA.gov. Follow the guidelines to help you create a consistent, helpful experience for Veterans.
- Design: This section explains VA.gov’s base styles and visual language. You should set margins and padding in your design comps using the 8pt spacing units.
- Components: Components are the “UI fragments,” such as buttons and accordions. Some of these have strict usage guidelines, so please become familiar with them.
- Utilities: This section mostly describes CSS, but that doesn’t mean it is only for front-end developers. Formation guides design implementation, so understanding the utilities may assist in how designers describe their work. Many of the utilities are responsive and can be used to modify or enhance designs for different screen widths at a low development cost.
- Patterns: How components, content strategy, information architecture, accessibility, and visual design work in tandem to solve Veterans’ needs. Here, you will find information on how Hub pages are structured, how to build multi-part forms, etc.
- Layout: The layout section describes the design grid and tools you can use to create page or design pattern structure.
The website displays HTML and CSS examples of the various components and patterns in use on VA.gov. You can use your browser’s web inspector to view the specs for each component. If you use Sketch, each of the components has been added to a VA pattern library as well.
Sketch for Teams at VA
Design teams at VA use Sketch for Teams to view, share, and collaborate on our work. Only designers actively working on products at VA.gov can be added to Sketch for Teams. Once you have been added, you may access the VA pattern library in the cloud or via download.
Get added to Sketch for Teams
- Go to sketch.com and create a Sketch account
- In the #design channel in Slack, ping a Sketch for Teams admin (currently Ryan Thurlwell) requesting to be added
- Receive the invite via email, accept the invitation
- Boom, you’re in!
Using Sketch for Teams
Sketch for Teams contains a few important features that help teams work together:
- Files (including libraries) live in the cloud, rather than locally on your machine
- You receive library updates automatically (a big advantage of using Sketch for Teams)
- You can see what everyone else is working on in the VA workspace
- Developers can inspect any element on a page
To get started on a new project, there are only a couple of steps:
- Duplicate and rename the Sketch for Teams Template in your team’s folder
- In the Sketch app, go to Sketch > Preferences > Libraries and add the VA-gov-Pattern-Library.
Do not modify the VA-gov-Pattern-Library. Only OCTO-DE and the Design System Team should edit the library. If you have questions about how to use component symbols, contact Natalie Hill, the Design System Team’s UX Designer.
Load the VA.gov pattern library
Use the master VA.gov pattern library to access components, page templates, and mark up tags for your work.
In Sketch for Teams, the master library lives in the cloud, which means you no longer have to manually download the library every time it’s updated.
To access and enable the master VA.gov pattern library, follow these steps:
- In the Sketch menu bar, navigate to Sketch > Preferences (or press
,) to open the Preferences modal
- In the modal, select the Libraries tab
- You should see a section called VA.gov Design Libraries. Select the checkbox next to the library named “VA-gov-Pattern-Library”
Once you’ve loaded the library, you should be able to access everything in it by navigating to Insert > Symbols > VA-gov-Pattern-Library.
We use naming conventions to organize Sketch files in order for other people to easily view, update, or edit your Sketch files.
Pages contain all of the artboards for the product. Each page should have a specifc purpose—iterations on a specific user flow, a prototype, etc.
Name pages in such a way other designers, engineers, product folks, and stakeholders can understand and navigate them. Always start version numbering with 3 digits (e.g. v001).
Name pages like this:
[Product name - purpose - focus (optional) - version number)]
- VAOSR - Exploration - Calendar widget - v001
- VAOSR - Prototype - Community care - v001
- VAOSR - Direct schedule - v001
Artboard naming conventions should reflect the page they reside just like breadcrumbs on a website. Use numbers or descriptions for clarity as needed.
If the page name is
- VAOSR - Exploration - Calendar widget - v001
Then artboards would be named
- VAOSR - Exploration - Calendar widget - 001
- Sometimes preview version of artboards on Sketch for Teams have display errors. Try embedding fonts or asking someone else open and close the file—weirdly this seems to work.
Leaving Sketch for Teams
People change projects frequently, and we have a limited number of licenses for Sketch for Teams. If you roll off work at VA or no longer use Sketch for Teams, please email Ryan Thurwell.