Consolidating packages

[pwolfert]

Background

At the moment the CMS Design System consists of a "core" design system and three "child design systems." Today it primarily serves CMS.gov, HealthCare.gov, and Medicare.gov, and each of those domains has its own child design system. The concept of a "child design system" evolved from earlier methods of organizing the design system prior to the formation of a fully staffed, dedicated Experience Team to maintain it. Since then, the way those child design systems are governed and maintained has changed. They went from being independent code repositories to living in a single mono-repo maintained by one team. They went from having separate release processes, timelines, and deployment pipelines to having synchronized releases on a predictable schedule. They went from defining their colors and styles by their deviation from the core design system to having standardized and systemized styles through design tokens. We made these changes to be able to maintain and improve on the quality of our design system despite being only one team with limited capacity and needing to serve a variety of products across multiple domains. These changes have been slowly moving the CMS Design System toward being one design system represented by multiple brands.

However, we are not there yet. Though there are multiple ways we still fall short of that goal, this document will deal with one in particular: Each child design system has its own independent code version. The current version of the core design system is 6.0.0; for HealthCare.gov, it is 10.0.0; for Medicare.gov, it is 8.0.0; and CMS.gov is still in pre-release. These version numbers show minor and patch versions that are in sync, but their major versions are not. There are actually good reasons to keep those versions independent when the design systems have unique differences. Those reasons have been balanced against arguments in favor synchronization, like how much it would improve our ability to communicate about versions and updates if they were all the same. But now we've reached a tipping point where not only does it makes sense to synchronize, but also code changes have made it much easier than it would have been a year ago. I propose that we to go a step further than version-number synchronization; we should consolidate the design system packages themselves.

Proposal

A package can be thought of as a distributable collection of assets. We have one for the core design system and one for each child design system. Teams are meant to use the package that is relevant to them and their domain. For our packages, there is a hierarchical relationship behind the scenes. The child design systems inherit the core, customize it, expand upon it, and get distributed as their own collection of assets available for direct consumption by products in their domain.

Consolidating four packages into one isn't as simple as moving code. There are three primary functions of a child design system that need to be addressed in order to be able to represent all brands by one package:

1. Styles
2. JavaScript overrides
3. Unique components

Styles

Thanks to all the work the team has done in the past year, the styles are now very simple to move.

1. First, we moved the child design systems into a monorepo, which made dependencies between the packages easier to manage.
2. Second, @forrestbaer created an elegant design-tokens system using TypeScript, which allowed us to centrally define the styles for each brand based on a standard set of colors, spacer values, et cetera. He then worked with our talented designers to develop a brand theme for each child design system.
3. Third, @scheul93 migrated us away from documentation websites generated for each child design system to a unified documentation site. The documentation used to be embedded as comments within CSS files and needed to follow a very specific structure, and now we have the flexibility to adapt our information architecture and content as we evolve.
4. Fourth, @zarahzachz synthesized the CSS-related discovery efforts of the whole team and defined the path forward that ultimately led to us distributing one core CSS file configured by CSS Custom Properties.

And that's where we are now. There is one core CSS file with all the style rules and then individual theme CSS files that define the custom properties referenced in those rules. When consolidating packages, we can pretty much just pile them all into the same directory, like so:

dist/
└── css/
    ├── index.css (the core styles)
    ├── core-theme.css
    ├── cmsgov-theme.css
    ├── healthcare-theme.css
    └── medicare-theme.css

The only main difference is that there will be some residual CSS overrides in some of the child design systems that will need to be placed in the theme files for now.

The change for application teams will be only the package they import from. Right now a HealthCare.gov team might import like this:

@import '@cmsgov/ds-healthcare-gov/css/index';
@import '@cmsgov/ds-healthcare-gov/css/healthcare-theme';

which would change to this:

@import '@cmsgov/design-system/css/index';
@import '@cmsgov/design-system/css/healthcare-theme';

Additional integration

Instead of just changing the location where the CSS files get placed during the build step of the design-system-tokens package, we can take the opportunity to further improve the integration of the tokens package into the core package and tools. Right now building the tokens package is an implicit prerequisite for building the design system. It creates theme CSS files and copies them into all the relevant directories for each design system plus the docs and Storybook. We've tied several of our build commands together to make sure the tokens build first in most cases, but the relationship isn't as explicit as it could be.

If we start importing the theme files from the @cmsgov/design-system-tokens package directly, that relationship will be explicit, and we can eliminate duplication of those files. The duplication is made more evident by the fact that multiple copies of the files are checked into version control. I'm not proposing we stop checking in that generated code but that we check in only one copy of each in packages/design-system-tokens/dist.

JavaScript overrides

There are two main ways we currently take advantage of the fact that each child design system is its own package with its own independent JavaScript entrypoint: To override default configurations and to override default props on specific components. Those two things are conceptually the same, but how we solve for them will be different.

Both kinds of our JavaScript overrides rely on what are called "side effects." A function or module is said to have side effects if calling that function or importing that module changes the state of something else in the application. Our child design system modules have side effects by design. If you import the TextField component from @cmsgov/ds-healthcare-gov, it does more than just hand you back that component. Because everything passes through that one entrypoint (our index.ts that maps to @cmsgov/ds-healthcare-gov), we can use the import of that module to perform all the necessary side effects to configure the core design system to fit the needs of the HealthCare.gov Child Design System. For instance, the default error placement for HealthCare.gov is below the input fields, so we call setErrorPlacementDefault('bottom'). Because we wouldn't have a separate entrypoint when we consolidate down to one package, we'll need to find ways to achieve the same ends without side-effects. That is what we'll explore in the following sections.

Note that it's possible to have multiple entrypoints in the same package, but I feel that that defeats part of the purpose of consolidation and unification. Imports would become less consistent and more complex, and overall it wouldn't be as nice of a developer experience for our users or ourselves!

Overriding default configurations

The design system uses a handful of "flags" to configure various aspects of our JavaScript library. For instance, analytics can be turned on for all Alert components by passing true to setAlertSendsAnalytics. Right now the HealthCare.gov Design System is the only one left that needs to set custom configs that apply to all applications in its domain, and that's the default error placement configuration. All the other configuration settings are managed by individual applications using the design system. I propose that the one remaining setting be made the responsibility of the applications, but we can also make some changes to improve the developer experience.

First of all, we can start to consolidate our config settings into one function so they can be set all at once:

/**
 * Here's the TypeScript function signature. Notice that the same function
 * can be used to set or get the configuration options.
 */
function config(options: ConfigOptions | undefined): ConfigOptions;

// This is how usage would look in an application. This would normally happen
// in the root of the applications for SPAs or, for other architectures,
// anywhere that will only run once.
import { config } from '@cmsgov/design-system';
config({
  alertSendsAnalytics: true,
  dialogSendsAnalytics: true,
});

Second, we can still provide default settings that are supposed to apply to applications under a particular domain, but app teams would be responsible for handing that to the config function:

import { config } from '@cmsgov/design-system';
config({
  ...config.HEALTHCARE_DEFAULTS,
  alertSendsAnalytics: true,
  dialogSendsAnalytics: true,
});

// And the following would be equivalent to what's above
config(config.HEALTHCARE_DEFAULTS);
config({
  alertSendsAnalytics: true,
  dialogSendsAnalytics: true,
});

In this way we can have custom configurations at the domain (brand) level and the application level without needing separate entry points with side effects.

Overriding default component props

The other way we rely on side effects is to customize individual components for a brand. These customizations consist of importing particular components and modifying their default props before an application uses them. Here's an example of this happening in the Medicare.gov Design System:

// This code can be found in packages/ds-medicare-gov
import { HelpDrawer, CloseIconThin } from '@cmsgov/design-system';

HelpDrawer.defaultProps = {
  ...HelpDrawer.defaultProps,
  closeButtonText: <CloseIconThin className="ds-u-font-size--lg" />,
  closeButtonVariation: 'ghost',
};

These will need to be handled on a case-by-case basis. The answer for some of these will be to move these overrides into CSS and eventually into design tokens. The answer for others might be to standardize between the design systems. For instance, we've heard that both Medicare.gov and HealthCare.gov want to make a similar change to dialog close buttons, but design work needs to be done and a final decision made before we can move forward. Near the end of this document there will be tables proposing strategies for each individual module that needs to be addressed.

Unique components

The last thing to address are components in the child design systems that are unique to those brands. The most obvious examples of this are the website headers and footers. Components that only have a place in a particular brand can be moved into the core package, but their names will need to be changed to avoid conflicts and to be clear about where they're meant to be used. Here's an example of how they would be referenced:

import { HealthcareHeader, HealthcareFooter } from '@cmsgov/design-system';

const App = () => (
  <>
    <HealthcareHeader />
    <main>
      All sorts of stuff!
    </main>
    <HealthcareFooter />
  </>
);

With tree-shaking in modern build tools, we don't have to worry about extra components being included in the bundles for applications that don't use them. If a team is using the CDN, we will make sure the brand-specific components are bundled separately to avoid unnecessary JavaScript.

Rejected ideas for namespacing

There are several ways we could expose these brand-specific components to our users, and I want to mention them here to explain why they're less ideal. Each example shows two imports to illustrate what the import paths would look like given that you can consume our component library not only as React components but as Preact and Web Components as well.

What is depicted below is healthcare having its own entrypoint that lives in the core package. It is essentially the same thing as having a separate package except that it physically lives in the same package. In order to achieve this, we'd have to manually specify many extra conditional exports in our package.json file. While this would avoid most of the work outlined in this RFC, it somewhat defeats the purpose of consolidation.

import { Header } from '@cmsgov/design-system/healthcare';
import { Header } from '@cmsgov/design-system/healthcare/preact';
<Header />

Another option, which is shown below, is to have a single Header export with multiple brand-specific components attached to it. This is more concise and arguably cleaner, but it doesn't work with tree-shaking. By attaching the components to an object that you import, it necessarily means that the existence of that property on the object is reliant on that component having been imported. Current build tools to my knowledge are unable to identify that something like Header.MedicareGov isn't being used (in the example below) and therefore doesn't have to be imported.

import { Header } from '@cmsgov/design-system';
import { Header } from '@cmsgov/design-system/preact';
<Header.HealthCareGov />

Components that don't have to be unique

There are two components that are unique to Medicare.gov that I would argue don't need to be unique. These are Card and Stars. I propose we promote them to core components, but it will require some design work and for guidance to be written.

Specific actions to be taken for each module

The following tables list each of the modules that exist in the child design systems and what action we should take to reconcile them with the core package.

Table of actions for HealthCare.gov modules

Module	Action	Explanation
Accordion	🔨 Convert	Need to be able to convert this to a CSS solution, which would be easier to do if we were using fonts for icons
Footer	➡️ Move	Can be moved into core but will remain specific to healthcare
Header	➡️ Move	Can be moved into core but will remain specific to healthcare
Logo	➡️ Move	Can be moved into core but will remain specific to healthcare
locale and i18n.ts	➡️ Move	Wouldn't be necessary once we move the components into core
index.ts and flags.ts	➡️ Move	We would get rid of custom entry points and side effects in favor of every application calling a config function that does the same thing
patterns	➡️ Move	Contains one pattern story that can be moved to core

#### Table of actions for Medicare.gov modules

Module	Action	Explanation
Card	🔨 Promote	Should be promoted into a core component, which will require design work
Dialog	🔨 Unify	Align on what the close buttons look like across the design systems
HelpDrawer	🔨 Unify	Align on what the close buttons look like across the design systems
Icons	➡️ Move	Can be moved into core
MedicaregovLogo	➡️🔨 Move and improve	Can be moved into core after we update the component to have different CSS classes for the "Medicare" and ".gov" to be able to replace the two SVG files in that folder
SimpleFooter	➡️ Move	Can be moved into core but will remain specific to medicare
Stars	🔨 Promote	Should be promoted into a core component, which would be easier if we were using fonts for icons

[forrestbaer]

Really great writeup, and thanks for the table at the bottom that really helps visualize next steps. I am in agreement that renaming brand-specific components and not namespacing them under another object. HealthcareHeader & not Header.Healthcare.

Setting up configuration objects for each project is an excellent idea and something we can perhaps move into themes.json even. Might need some tooling updates to make sure we aren't iterating over all keys in some other scripts.

I'm on board! 🚢

[zarahzachz]

I agree with everything Forrest said - especially how cool the config objects are.

I wonder if its worth fielding to non-Experience teams to get their take?

[pwolfert]

Thank you!

I wonder if its worth fielding to non-Experience teams to get their take?

Yeah, definitely. I wanted to run it by you two first.

[pwolfert]

There have been a few reasons we haven't moved forward with this, but I wanted to document a specific issue we've run into so we have a record of it and can know when we have the necessary CSS features to move past it. I was breaking out specific pieces of this RFC that we could implement even if we weren't moving forward with full consolidation, and one of them was creating a dev-dependency relationship between the tokens package and the others. Here are the tasks I wrote in that ticket:

1. Update the tokens package to no longer copy files into separate destinations but just output to its local dist folder. Optionally see if exports for those files can be added explicitly to the token package's package.json file

2. Update the copyThemes part of our build script to make sure the appropriate theme files get copied from the tokens package to the dist folder. In a possible future where all themes are contained in the core package, this will be a very simple operation. For now, we probably want to avoid bundling themes in packages where they don't belong.

3. HOLD UP. The _layouts.scss files throw a wrench in this plan. Right now certain theme-specific information needs to be baked into the styles, like the responsive breakpoints that are used in media queries. There's no real way that I can see to separate the rules from those values without making theme-specific, compiled rules. One alternative would be to remove the ability for themes to have different breakpoint values. AT SOME POINT THIS MIGHT BE SOLVED WITH CSS ENV VARIABLES.

4. Add a dev-dependency of @cmsgov/design-system-tokens to...

   1. the root package.json
   2. the design-system package (for storybook)
   3. the ds-healthcare-gov package
   4. the ds-medicare-gov
   5. the docs package

5. Add the build:tokens command to our other build commands and the storybook command as appropriate

Note the problem with the third item.

[zarahzachz]

For our blocker, I question if we should continue providing media query breakpoints as a design system. Might sound crazy, but hear me out:

• We currently offer 5 breakpoints
  • $media-width-xs: 0px !default;
  • $media-width-sm: 544px !default;
  • $media-width-md: 768px !default;
  • $media-width-lg: 1024px !default;
  • $media-width-xl: 1280px !default;
• Our breakpoints and spacing are currently using absolute CSS units
  • A pixel is not equal to a pixel across all devices
  • Tangent: We should probably use em values for breakpoints
• Device viewport widths are far more varied than the breakpoints we offer
  • There are sooooo many devices out there! (This is the HHS viewport size taken today)
  • Just on iPhones alone, you can have 3 different different viewport widths on the same device (for Safari, in-app browsers, and 3D touch preview)
  • We stop caring about breakpoints after 1280px width - and screen are much larger than that. In fact, we have some users who navigate on televisions (not saying we need to test for this extreme, but it illustrates how varied our user experiences can be).
• Having a set of strict breakpoints perpetuates "pixel perfect design" we want to break away from
• Offering this limited set of breakpoints signals to designers and developers they only need to check these specific breakpoints to confirm a layout is OK
  • Ideally, everyone should be resizing their screens and testing their work for all layout sizes and I don't think that's happening.

In conclusion, I believe we should stop offering media query breakpoints as a set of predefined variables. Thank you for coming to my TED Talk.

[zarahzachz]

OH! Also forgot to add this nugget... With flex, grid, clamp(), @container, etc., we have many tools at our disposal to create flexible layouts. @media has its place, but ideally we should be moving towards flexible layouts to account for our users' preferred way to view government websites. If they wanna view our site on a toaster or giant kiosk screen, the layout should adapt to that without needing specific breakpoints targeting those viewports.

[pwolfert]

Thank you for coming to my TED Talk.

😂

All good points.

• The switch to em is perhaps actionable right now.
• The ideas about greater fluidity would require a greater change in how we and the application teams think.
  • Here's an old issue that was brought up and closed that is somewhat relevant. What was proposed was the opposite of what you're proposing, but the response still applies in this regard: "This design system is a codification of our design princicples and strategies." We need to unpack your ideas more and have a discussion with the larger team!

[zarahzachz]

Might have found the solution to your media query issue... I was poking around on Adam Argyle's Open Props project and came across syntax for a custom media query. It looks like we do have PostCSS as a dependency in our project and could make use of the custom media query plugin to use CSS vars inside media queries. Thoughts?

[pwolfert]

@zarahzachz, that is a build-time solution, but unless we extract all the rules that are inside media queries into the theme files, what we need is a run-time solution. See that plugin's first example:

@custom-media --small-viewport (max-width: 30em);

@media (--small-viewport) {
	/* styles for small viewport */
}

/* becomes */

@media (max-width: 30em) {
	/* styles for small viewport */
}

The values inside the media query get baked into the final CSS. We can achieve the same thing with Sass variables, but the problem we're trying to solve is being able to have a single CSS file with all the rules and be able to load a theme file to do all the customization.

That being said, it's not a complete blocker in that if we wanted to consolidate packages but go back to creating a theme-specific CSS bundle of everything, we could do that.