npm:@cmsgov/medicare-site-package

README

A Site Package is a method for sharing common, site-specific, design and code resources between the various teams working on Medicare.gov. These resources are unique to Medicare.gov, and not generalized for inclusion in the Design System. It includes assets like design system overrides and site-specific components.

Usage

Installation

yarn add @cmsgov/medicare-site-package (or you can use npm install).

Once downloaded, you can edit any of the site package files in the src directory if you need to, though it's recommended to put your project's overrides in their own files so that any updates to the M.gov DSSP files can be updated via this process.

If you don't have any overrides you want to make, or you don't want to incorporate SASS/SCSS into your project, you can take the compiled file from /dist/index.css.

Building and Watching the Whole Package

If you haven't done so already, run yarn install to install all of the dependencies needed to build or watch.

Having done so, should you make any changes to your version that necessitate rebuilding it, you can rebuild via yarn build. This will generate new, production-ready versions of /dist/index.js and /dist/index.min.css and will also update the type definition file.

Building and Watching just the Sass/CSS

Having ensured you have a sass compiler installed, run yarn build-css to build a minified CSS version. The resultant file will be /dist/index.min.css. If you are in the midst of testing changes and/or want a non-minified version, running yarn test-css will output /dist/index.css.

Importing Sass

The source files included are written in Sass (.scss). You can add your node_modules directory to your Sass includePaths and import the file like below.

Note: The site package's Sass file imports the core, layout, and support design system Sass files as well, so the following is all you need to import to gain access to those resources:

@import "@cmsgov/medicare-site-package/src/index";

Building and Watching just the React Components

This can be done via yarn build-js and yarn watch-js respectively.

Importing React components

For components distributed through the site package, you can import them like this:

import { Header } from "@cmsgov/medicare-site-package";

Note: Ensure that you use a bundler with tree shaking enabled to avoid bundling unused components.

File structure

├── dist
│   ├── index.css                         Compiled CSS
│   ├── index.css.map                     Compiled CSS Source Map
│   ├── index.d.ts                        TypeScript Definitions File (only useful if you're using TypeScript)
│   ├── index.js                          Compiled JS (pre-minified)
│   ├── index.min.css                     Minified and Compiled CSS
│   └── index.min.css                     Minified and Compiled CSS Source Map
└── src
    ├── components                        React components specially-designed for Medicare.gov sites
    │   └── images                        Componentized images, such as Medicare.gov and DHHS logos
    ├── example-implementations           Example implementations of the components into things like headers and footers
    ├── index.scss                        Main Sass entry point with all imports
    └── scss
        ├── _buttons.scss                 Design system Button variable overrides
        ├── _color.scss                   Design system Color variable overrides
        ├── _font_vars.scss               Design system Font variable overrides
        ├── _fonts_and_typography.scss    Overrides for specific typography-related style rules
        ├── _overrides.scss               Collects `_fonts_and_typography.scss` and `_utilities.scss` into one import
        ├── _utilities.scss               Sass utilities not already-included in the design system
        ├── _variables.scss               Collects the variable overrides into one import
        └── components                    Styles for the Medicare.gov-specific React components

Design assets

You can find a the Medicare design system Sketch file and related fonts in the design-assets folder.

Why a site package?

Medicare.gov consists of multiple codebases maintained by different teams. Deploying a design system avoids the duplication of code and assets across codebases and working against the software development principle to keep things DRY. Having multiple codebases would naturally lead to differences and would cause inefficiencies and inconsistencies to creep across the user interface and user experience.

The Design System is one way we're addressing the issues mentioned above. However, the design system is meant to be used by many CMS (Centers for Medicare & Medicaid Services) websites, not just Medicare.gov. As a result, the resources within the design system are not tied to a particular website.

Goals

The primary goal of the Site Package is to reduce the amount of duplicate instances of Medicare.gov front-end components and design assets, and having a single source of truth which all teams can contribute to and use.

A secondary goal for the Site Package is for it to serve as an intermediate step in a component's journey to becoming a design system component. This gives the teams working on HealthCare.gov a space to share and iterate on components that at first appear to only have a use case on Medicare.gov.

Non-goals

The Site Package is not meant to be as robust or as large as the Design System. It should be as small as possible, and ideally all reusable components would be from the design system.
The Site Package is not meant to serve as a resource for best practices or accessibility guidelines — that's the responsibility of the design system.
The Medicare.gov Site Package is not meant to be a solution for other CMS websites.

Additional links

For more information on the original Design System, check out its GitHub page.

Usage no npm install needed!