Harmony Design System

Harmony is a next-generation UI design system that combines elements of UITK and UICL into a comprehensive React component library. This unified platform leverages the best of both worlds, providing a robust toolkit that empowers designers and developers to create scalable, brand-compliant, and accessible web applications with ease.

With Harmony, you're not just using a component library — you’re harnessing the collective power and proven success of two company-established design systems. Harmony is the design system for Optum's B2B software products. It is best used for multi-tenant commercial "software as a service" (SaaS) products and includes components with functionality to support healthcare industry needs such as:

• Patient and Member Engagement
• Eligibility and Claims
• Care Operations and Management
• Payment and Reimbursement
• Data Analytics and Insights

Harmony follows the general guidelines of the corporate Design Standards and builds on it to address the specific needs of healthcare industry payers and providers. The Harmony Design Guidelines outline the Harmony components from a design perspective and describe their benefits for the user, while the React components used to build the software are documented on the Harmony Storybook site. Our documentation resources work together to ensure that our digital products benefit from a cohesive design language and codebase.

Our Principles

Harmony empowers our product design and development teams to efficiently craft consistent UIs that are both valuable and intuitive for the end users of Optum products. We're guided by the principles that govern product development for Optum Insight, and make sure that our decisions align with them:

• Optimize product development through standardization We reuse experience patterns and code that meets our standards for improved speed, efficiency, and engineering quality.

• Avoid arbitrary differences We use the fewest number of distinct components possible and eliminate redundancy. Purposeful difference is allowed if supported by real-world use cases and customer validation.

• Validate with end users We test both "desirability" (are we solving the right problems) and "usability" (are we solving those problems in the easiest way) with end users as we design and after we build using objective, measurable methods.

• Design to meet multiple needs Custom, single-use UX/UI experience is discouraged. Our components and experiences are designed, coded, and configured to be useful across product boundaries and in as many contexts as possible.

• Share code across teams and experiences We share code that meets Optum Insight engineering standards in a centralized repository, allowing engineers on different teams to learn from each other, build upon existing work, and accelerate innovation across the organization.

These principles elevate us from a set of design and software guidelines to a true "platform" design system, which lets us work faster and more efficiently while also improving the quality of the experiences we build.

Benefits of Using Harmony

Efficiency for Teams, Simplicity for Customers

• Designers and developers can work faster and solve the unique problems associated with their product experiences without having to "reinvent the wheel" every time.
• Product owners can focus more on innovation and less on basic development, shortening the design and development cycles and creating more value for the money allocated to their projects.
• Customers benefit from a consistent user experience, with powerful tools that require little training — plus the peace of mind that comes from using familiar, proven products.

##Consistent, Trusted Experiences

• Harmony delivers uniform experiences that build trust and strengthen the Optum brand.
• Customers using multiple Optum products benefit from shared components, patterns, and branding elements that behave consistently across platforms.
• Familiar, validated UI patterns help users complete tasks more easily and confidently.
• Continuous feedback from end users and stakeholders fuels ongoing improvements to the design system.

Validated, Accessible, and Built for Healthcare

• Harmony's UX patterns are used daily by thousands of customers and are rigorously validated through usability testing and real-world feedback — especially from users in the healthcare space.
• Accessibility is built in from the start, with all the components meeting WCAG level AA standards to ensure inclusivity for all users.

Reusable Foundations for Faster Delivery

• Harmony reuses shared design assets, saving design and development time, and is more easily scaled and maintained. When functionality is designed and built within the platform framework, the code can be reused in other products with little rework required.
• The modular design system allows designers, developers, and QA teams to all work more efficiently.
• If a component exists, we use it. If new ones are needed, they're designed, tested, developed, and added to the library.
• Our extensive documentation and built-in code mean that new Optum team members can become productive quickly.

Installation

Prerequisites for using the library

Harmony license key To use the Harmony library, you must have a valid Harmony license key. You can obtain a license key quickly and easily by completing the short form [here](https://forms.office.com/Pages/ResponsePage.aspx?id=yvoF2yrInUu5xQ9ktnVUIeqWH6fSQhNCrtsdftpoL_5UMFpQMzFUUE0xRzZPREZJMkMwUU9ONE42Qy4u.

You will need to provide your AskID/AIDE_ID and the email address of the primary contact for your project.

Node.js Node.js 20.x or higher is required, and can be installed from the UHG App Store.

The Harmony library is packaged as an NPM module, and you will need Node.js (which includes NPM) to install and consume it in your React application.

React version To consume Harmony components your React application must have React 18.3.0 or higher. Please ensure your application is using React 18.3.0+ to get the best experience and avoid compatibility issues.

Note: When using React 18.3.0+, you may see warnings for deprecated APIs that will be removed in React 19. These warnings are expected.

Configure NPM to pull from the Enterprise Registry (jFrog SaaS Artifactory)

Harmony can be downloaded from artifactory here:

https://centraluhg.jfrog.io/artifactory/glb-npm-vir/%40uhg-harmony/react/-/%40uhg-harmony/react-1.0.1.tgz

they may need help with setting up the ~/.npmrc file to access the UHG Artifactory in the users home directory.

example ~/.npmrc file:

@<SCOPE>:registry=https://centraluhg.jfrog.io/artifactory/api/npm/glb-npm-vir/
//centraluhg.jfrog.io/artifactory/api/npm/glb-npm-vir/:_authToken=<their token>
//centraluhg.jfrog.io/artifactory/api/npm/glb-npm-vir/:[email protected]
//centraluhg.jfrog.io/artifactory/api/npm/glb-npm-vir/:always-auth=true

For more information on configuring Artifactory, see the Artifactory documentation.

Install Dependencies

In the root of your React project, install the UI component library and its dependencies with the following commands:

npm install @uhg-harmony/react                 # The Harmony React component library
npm install @uhg-harmony/foundations           # Design tokens and themes
npm install @uhg-harmony/icons-react           # Icon library (optional)
npm install react react-dom styled-components@^5.3.11  # Peer dependencies

Importing the library

Applications using the Harmony library need to be wrapped by the Harmony wrapper component that provides theming and optional utility classes for spacing and grids.

You also need to supply your license key via the licenseKey prop. The appId is optional, but may be useful if you are managing multiple React apps that use Harmony.

import { Harmony } from '@uhg-harmony/react';

<Harmony appId="your-app-id" licenseKey="your-license-key">
  <App />
</Harmony>

You can also specify spacing and grid on the Harmony wrapper. This will allow you to use the grid classes to create the layout of your page, and apply spacing classes to your elements, e.g. padding ('pt-base') and margin ('ml-l').

<Harmony appId="your-app-id" licenseKey="your-license-key" spacing grid>
  <App />
</Harmony>

Components can then be imported from the same namespace:

import { Fieldset } from '@uhg-harmony/react';

Spacing Class Syntax

The spacing classes are made up of a css property label for margin/padding:

• padding - "p"
• margin - "m"

A placement where the spacing will be applied:

• top - "t"
• bottom - "b"
• left - "l"
• right - "r"
• vertical - "v"
• horizontal - "h"
• all - "a"

And a size:

• extra extra small - "xxs"
• extra small - "xs"
• small - "s"
• base - "base"
• medium - "m"
• large - "l"
• extra large - "xl"
• extra extra large - "xxl"

Example: <div className="mb-s" /> adds a margin bottom small.

Technologies

The main technologies used are:

• React
• TypeScript
• Styled Components

Foundations

• Typography - Typography components provides a standardized approach to text styling.
• Grid - Harmony React provides a separate grid library which can be consumed by applications. The grid consists of a container, rows and columns.
• Icons - This story displays all available icons from the @uhg-harmony/icons-react package.
• Design Tokens - Harmony Design Tokens are the fundamental elements of all UI components. These tokens are consistently utilized across designs, tools, and codebases.

For detailed guidance on Harmony Foundations, refer to ./harmony-foundation.instructions.md.

Components

The Harmony React component library provides the following components:

Actions

• Button - Interactive button with multiple variants
• DropdownButton - A Dropdown Button combines standard button functionality with an expandable dropdown menu
• IconButton - Button with icon only
• SplitButton - Button with dropdown menu

Containers

• Accordion - Collapsible content sections
• Modal - Dialog/overlay modal
• Panel - Content panel container
• TabbedPanel - Tabbed content interface

Feedback

• HelperText - Form helper text
• Label - Form field labels
• Tooltip - Contextual tooltip

Indicators

• Avatar - User avatar with initials/image
• Badge - Status indicator badges
• Chip - Selectable/dismissible tag components
• Count - Numerical count display
• LoadingIndicator - Loading state indicator
• ProgressIndicator - Progress bar
• StepTracker - Multi-step progress indicator

Inputs

• Checkbox - Form checkbox input
• DatePicker - Date selection input
• DropdownMulti - The Multi Select Dropdown enables the selection of multiple options from a dropdown list.
• DropdownSingle - The Single Select Dropdown enables the selection of a single option from a dropdown list.
• Fieldset - The Fieldset component groups related form elements under a shared legend or label.
• RadioButtonGroup - The RadioButtonGroup component allows the grouping of multiple radio buttons for exclusive selection.
• SearchField - Search input field
• TextArea - Multi-line text input
• TextInput - Single line text input
• ToggleSwitch - Toggle switch control

Navigation

• Breadcrumb - Navigation breadcrumb trail
• Link - Links are navigational elements that direct users to other sections of the application or external resources.

Patterns

• Modal - A Modal is an overlay dialog that focuses user attention on a single task or piece of information using a temporary window that covers part of the page.
• ReadOnly - The Read Only pattern is used to display previously entered form values in a non-editable format.
• Wizard - The Wizard is a UI pattern designed to guide users through complex workflows by dividing them into a series of sequential steps.

Coming Soon

• Card - Content container with header/media
• Footer - Page footer
• Navigation - Navigation container
• Pagination - Data pagination controls
• Select - The Select component is a customizable dropdown selector for user input. It provides a list of options, from which users can select one, enhancing the user interaction in form-based interfaces.
• Table - Basic Table

For more information and examples, see Harmony Components Instructions.

Complete Application Example

import React from 'react';
import { 
  Harmony, 
  Header, 
  Navigation, 
  Heading, 
  Text, 
  Button,
  Card,
  Footer
} from '@uhg-harmony/react';
import { optum } from '@uhg-harmony/foundations';
import '@uhg-harmony/foundations/Brand_optum/fonts.css';

const App = () => {
  const navigationItems = [
    { label: 'Home', href: '/' },
    { label: 'About', href: '/about' },
    { label: 'Contact', href: '/contact' }
  ];

  return (
    <Harmony 
      appId="my-harmony-app" 
      licenseKey="your-license-key"
      theme={optum}
      spacing
      grid
    >
      <div className="ph-base">
        <Header>
          <Navigation 
            variant="primary-horizontal"
            items={navigationItems}
          />
        </Header>
        
        <main className="row">
          <div className="col-12">
            <Heading>Welcome to Harmony</Heading>
            <Text className="pb-base">
              This is a sample application using the Harmony React component library.
            </Text>
            
            <Card
              header="Getting Started"
              content={
                <div>
                  <Text>Follow the examples above to build your application with Harmony components.</Text>
                  <div className="pt-base">
                    <Button>Get Started</Button>
                  </div>
                </div>
              }
            />
          </div>
        </main>
        
        <Footer />
      </div>
    </Harmony>
  );
};

export default App;

Quick Start

For automated project setup, use the VS Code Agent mode with the prompt:

/harmony-create-demo-app.prompt.md

you can find this prompt in OTC AWESOME LLM search for "Harmony" and it will be a prompt.

This will create a working Harmony application with all dependencies configured correctly.

Available Themes

Import themes from the foundations package:

import { optum, uhc } from '@uhg-harmony/foundations';

// Import corresponding font files
import '@uhg-harmony/foundations/Brand_optum/fonts.css';  // For Optum theme
import '@uhg-harmony/foundations/Brand_uhc/fonts.css';   // For UHC theme

Additional Resources

Quick Project Setup

For automated project creation, use the VS Code Agent mode prompt:

/harmony-create-demo-app.prompt.md

you can use OTC AWESOME LLM search for "Harmony" to find this prompt. It will create a working Harmony application with all dependencies configured correctly.

Getting Help

• Harmony Storybook: https://storybook-harmony.ofp-elr.optum.com/
• GitHub Repository: https://github.com/OptumInsight-Platform/harmony
• Design Guidelines: https://optum.zeroheight.com/styleguide/s/125389/p/14cfc5-oi-harmony-design-system
• Teams Channel: Harmony Support
• License Form: https://forms.office.com/r/2a1b0d8c6C

More Examples

• Healthcare Form: A comprehensive form for patient intake, including various input types and validation. Example Form
• Claims Workflow: A step-by-step workflow for processing claims, including status tracking and a data table. Example Workflow