The Forge design system

Introduction

Design systems standardize component design and code to help teams efficiently create, maintain, and update products. athenahealth has 3 design systems, each for a different use:

  • Spark is a React-based design system developed by the Patient Experience team for patient-facing apps.
  • Foundation is an iOS- and Android-based design system developed by the athenaOne Mobile team for native mobile apps.
  • Forge is a React-based design system developed by the Forge team for internal and provider-facing apps. It’s the official design system of athenahealth.

This guide helps designers who are new to Forge get set up with the tools and knowledge they need to get started with Forge. If you’ve used Forge before but need to access it again, this guide helps with that, too. By the end, you’ll have the tools you need, as well as a basic understanding of how Forge works, thanks to a few examples of proper Forge usage.

Key takeaways

  • To begin designing with Forge, you’ll need access to your team’s design folder in Figma and editing permissions.
  • This guide walks you through the steps to get access, then how to start designing with Forge.
  • It also shares some best practices for working with Forge components and with developers.
  • At the end, we’ve included helpful links to our recommended resources and utilities.

About Forge

The Forge design system consists of several elements:

  1. The React-based code package
  2. The Figma design library
  3. Typography, color, and spacing guidelines
  4. 200+ custom icons
  5. 50+ UI components to use as building blocks to construct apps and products
  6. Rules and standards for using all these elements
About Forge

These elements work together to help designers and developers work efficiently, resulting in smoother releases, a better user experience, and easier product updates as code and design decisions change over time.

The team that builds and maintains Forge is made up of ~10 product owners, developers, and designers based mostly in Watertown. If you have any questions, comments, or just want to say hi, connect with us on Teams.

Who should use Forge

If you and your team work on new React-based web products for providers or internal use at athenahealth, you must use Forge.

If you’re working on existing products that are gradually transitioning to Forge, you can use it in discrete parts of your app. Check with a designer on your team for the best way to do this.

If your entire app is based on an older design system like Classic or Streamlined, your subdivision’s UX leadership may require that any new or updated features are built using Forge. Check with your team for guidance.

What you need to use Forge

Access to internal tools

Forge is optimized for use in Figma, athenahealth’s design tool of choice. We use Figma because it provides best-in-class tools for collaboration and design library management.

Use your athenahealth email address to create an account at Figma.com.

Access to team files

Once you have a Figma account, you might need to take additional steps to access your team’s Figma files. Each zone has at least one Figma admin who manages team access. Ask another designer on your team who the Figma admin is and then request access. Alternatively, ask a colleague to share the URL to your team’s shared folder, then request access via the Figma dialog. To see all the publicly available projects in athenahealth, visit the design org’s parent folder.

A clear file structure

We recommend that every team keep their files in 4 sections: Research/Ideation, Draft/In Progress, Prod/Approved/Dev Ready, and Archive.

  • Keep your research and sketches in the Research section.
  • While your designs are in progress, keep them in Draft.
  • Once they’re approved by stakeholders and ready to be coded, move them to Prod (and try not to touch them after that).
  • When pages are updated, move the original versions to Archive and start the cycle again.
A clear file structure

Many teams use a similar file structure for their Figma folders, but it does vary, so ask your team about their approach.

Creating your first design

  1. Go to Figma.com and sign into your account.
  2. Click New design file at the top of your Figma home page.
  3. Click the Figma logo in the top left corner of the page and select Libraries in the dropdown.
  4. Turn off all libraries except Forge Design System.
  5. Click the Frame icon in the main menu bar at the top of the page, and then select Frame.
  6. In the list of frames on the right, click Desktop, and then select Desktop – 1440 x 1024 in the list of options.
  7. Click Assets in the left nav, then start building a design using the assets in the Forge design system library. Some fun ones to start with are Paginator, FormField, Modal, and Table.
Creating your first design

Best practices

Text and color

To make them easier to use, Forge’s typography and color settings are built into Figma. For example, here’s how to set the typeface and color for a text box:

  1. Insert a new text box on the page.
  2. Type some sample text in the box.
  3. Click once outside the text box to select it.
  4. To change the typeface, click the four-dot style control in the right panel’s Type section and select one of Forge’s text styles in the dropdown.
  5. To change the color, click the style control in the right panel’s Fill section and select one of Forge’s font colors. For body text, use the font color Default.

For more information, see Typography and Color.

To detach, or not to detach?

Forge components in Figma are intended to mirror those in code. This reduces the amount of comparison and visual QA needed between design and code. To this end, components in Figma adhere to the same constraints as those in code (including spacing, color, and font, among others).

We strongly discourage detaching Figma components because developers must do additional work to override the built-in Forge component styling and behavior in the code, adding scope and decreasing efficiency. In addition, detached components aren’t updated automatically as Forge evolves.

If you come across a component in Figma that seems buggy or restrictive, instead of detaching, contact the Forge team so we can discuss solutions. Your feedback helps us resolve issues and identify gaps that improve Forge for all users.

Component guidance

For information about using individual components, see the component pages in this guide. Each page includes detailed guidance about when to use the component, when not to use it, other components to consider, design parameters, content tips, and demos with editable code. We’ve tried to anticipate the most common use cases and questions that might arise, but if anything isn’t clear, reach out to us on Teams.

Prototyping and testing

A clickable prototype is often the easiest way to convey a key flow or interaction. Figma makes prototyping easy, but it does require additional effort. We recommend using prototypes to test new, unproven flows or features with users, or to share complex flows with your team. You probably won’t want to prototype every design, though, because it’s time consuming and can yield diminishing returns. You can learn about prototyping in Figma or via the links in the Resources section.

Working with developers

Most teams at athenahealth use Jira to manage projects. Jira provides a clear view of every step in the design and development process, and it serves as the “source of truth” for the whole team. Each team has a different approach to project management, so check with your product owner or another designer on your team to learn how your team manages their work.

Because the Forge Figma library and code are so tightly integrated, developers can get the component names, states, and other details they need right from your design files. Figma’s automatic dev handoff tools make it easy to find color, font, spacing, and size information, as well as copy text into code. To learn more, see Figma for developers.

To try out component props without editing demo code, check out Storybook, our developer sandbox. Click Controls for a component and try adjusting them.

Going deeper with Forge

Forge provides building blocks for your designs, but new features or use cases might call for a new component, an updated design, or alternative behavior. Contributing your work to Forge expands the design system, which helps the whole community work more efficiently and improves the user experience. It’s easy to contribute, and we have an active pipeline of contributions. Connect with us on Teams to join the discussion with designers, developers, and the Forge team.

Resources

Utilities