diff --git a/packages/docs/content/blog/release-6.0.mdx b/packages/docs/content/blog/release-6.0.mdx index 52055bd576..d796af82c6 100644 --- a/packages/docs/content/blog/release-6.0.mdx +++ b/packages/docs/content/blog/release-6.0.mdx @@ -19,17 +19,17 @@ Previously we had two options for teams consuming our design system styles: CSS Sass to CSS -With this move, [as we mentioned in our previous blog post](https://design.cms.gov/blog/?theme=core#sasscss-changes), we've decided to stop distributing a Sass version of our stylesheets in our npm package, but we are still providing Sass files with the Sass versions of all our theme variables while teams transition over to using CSS Custom Properties. You can [read about how to use the CSS files and our theme variables](https://design.cms.gov/getting-started/for-developers/) in our getting-started guide for developers. +With this move, [as we mentioned in our previous blog post](/blog/#sasscss-changes), we've decided to stop distributing a Sass version of our stylesheets in our npm package, but we are still providing Sass files with the Sass versions of all our theme variables while teams transition over to using CSS Custom Properties. You can [read about how to use the CSS files and our theme variables](/getting-started/for-developers/) in our getting-started guide for developers. If you're currently using Sass, we've put together a more detailed [Sass to CSS migration guide for you](/migration-guides/sass-to-css/). ### New masked fields and automatic SSN obfuscation -When we created the [single-input date field](https://design.cms.gov/components/date-field/single-input-date-field/) a while back, we introduced a new masking pattern called the [label-mask](https://design.cms.gov/components/text-field/label-masked-field/). Now that we've been using it internally for a few months, we've decided to open it up for use as a drop-in replacement for our old [input-mask](https://design.cms.gov/components/text-field/input-masked-field/) pattern. The label-mask now supports every feature that the old input-mask supported, with the additional improvement that the Social Security Number (SSN) field now automatically obfuscates the SSN when the input doesn't have focus by only showing the last four digits. +When we created the [single-input date field](/components/date-field/single-input-date-field/) a while back, we introduced a new masking pattern called the [label-mask](/components/text-field/label-masked-field/). Now that we've been using it internally for a few months, we've decided to open it up for use as a drop-in replacement for our old [input-mask](/components/text-field/input-masked-field/) pattern. The label-mask now supports every feature that the old input-mask supported, with the additional improvement that the Social Security Number (SSN) field now automatically obfuscates the SSN when the input doesn't have focus by only showing the last four digits.
Animated screen capture of inputting a Social Security Number using the new label-mask pattern
-Hiding the SSN is previously something application teams had to implement themselves to use the SSN field and maintain their users' privacy. You can [read more about the label-mask pattern](https://design.cms.gov/components/text-field/label-masked-field/)—what it is and why we built it—on the new documentation page. +Hiding the SSN is previously something application teams had to implement themselves to use the SSN field and maintain their users' privacy. You can [read more about the label-mask pattern](/components/text-field/label-masked-field/)—what it is and why we built it—on the new documentation page. ### Sunsetting InVision DSM @@ -54,7 +54,7 @@ In our [3.6.0 release](https://github.com/CMSgov/design-system/releases/tag/%40c Color ramps from the 'System Color Tokens' page, showing a range of light to dark shades of a color -In this release we've added a page to the design system to show all color tokens in an easy-to-read and scannable way. We're exposing this base set of tokens to better highlight the design decisions made within a particular theme. Think of them as [a complete box of crayons](https://design.cms.gov/foundation/system-color-tokens/?theme=core). Our themes make use of certain colors from the crayon box but not all of them. +In this release we've added a page to the design system to show all color tokens in an easy-to-read and scannable way. We're exposing this base set of tokens to better highlight the design decisions made within a particular theme. Think of them as [a complete box of crayons](/foundation/system-color-tokens/). Our themes make use of certain colors from the crayon box but not all of them. ### Streamlining the ZIP Code design pattern @@ -62,7 +62,7 @@ We dove deep into a dozen CMS, HealthCare, and Medicare products, and what we di Some products used a 5-digit ZIP code pattern, others used a 9-digit ZIP code pattern for stricter data validation. We also discovered services using an autocomplete feature for users to confirm their geo-location. -ZIP codes are an important part of how we search for services and determine eligibility at CMS. Overall, we're thrilled to bring these design insights to the table and excited to see the impact they'll have on our user's experiences. [ZIP code pattern guidance](https://design.cms.gov/patterns/zip-codes/?theme=core). +ZIP codes are an important part of how we search for services and determine eligibility at CMS. Overall, we're thrilled to bring these design insights to the table and excited to see the impact they'll have on our user's experiences. [See ZIP code pattern guidance](/patterns/zip-codes/). ### Sketch layer order diff --git a/packages/docs/content/foundation/typography/content.mdx b/packages/docs/content/foundation/typography/content.mdx new file mode 100644 index 0000000000..677ad7ec26 --- /dev/null +++ b/packages/docs/content/foundation/typography/content.mdx @@ -0,0 +1,16 @@ +--- +title: Content +order: 0 +intro: The "ds-content" class provides an easy way to style written content on your page +core: + githubLink: design-system/src/styles/_base.scss +--- + +For pages that are mainly about written content or places where you want to use a standard mapping of heading-level styles to semantic heading levels, we have a special `ds-content` CSS class. Applying this class to an element that surrounds your content will automatically apply design system heading styles to the appropriate `h1`, `h2`, `h3`, `h4`, `h5`, and `h6` tags as well as `ol` and `ul` list tags. + +## Example + + \ No newline at end of file diff --git a/packages/docs/content/foundation/typography/headings.mdx b/packages/docs/content/foundation/typography/headings.mdx index 55c3676324..b421ea54d6 100644 --- a/packages/docs/content/foundation/typography/headings.mdx +++ b/packages/docs/content/foundation/typography/headings.mdx @@ -164,12 +164,7 @@ This is an optional header design. ### The `ds-content` class -For pages that are mainly about written content or places where you want to use a standard mapping of heading-level styles to semantic heading levels , we have a special `ds-content` CSS class. Applying this class to an element that surrounds your content will automatically apply design system heading styles to the appropriate `h1`, `h2`, `h3`, `h4`, `h5`, and `h6` tags. - - +For pages that are mainly about written content or places where you want to use a standard mapping of heading-level styles to semantic heading levels, consider using the [`ds-content`](/foundation/typography/content/) class. ### Responsive typography diff --git a/packages/docs/content/migration-guides/agnostic-typography-classes.mdx b/packages/docs/content/migration-guides/agnostic-typography-classes.mdx index 628978fc16..3d49df2c71 100644 --- a/packages/docs/content/migration-guides/agnostic-typography-classes.mdx +++ b/packages/docs/content/migration-guides/agnostic-typography-classes.mdx @@ -1,6 +1,6 @@ --- title: Using agnostic typography classes -order: 40 +order: 90 --- In [version 2.5.0](https://github.com/CMSgov/design-system/releases/tag/core-2.5.0), we updated the font size and typography utility classes to make them more flexible. We removed the semantic heading-level references (h1, h2, etc...) from the class names and replaced them with a basic sizing scale (xl, lg, …). Semantic heading levels in an HTML document don't always match the visual hierarchy in designs, so we're no longer pretending they do. diff --git a/packages/docs/content/migration-guides/migrating-to-new-buttons.mdx b/packages/docs/content/migration-guides/migrating-to-new-buttons.mdx index 72ac691466..ccfdd323ba 100644 --- a/packages/docs/content/migration-guides/migrating-to-new-buttons.mdx +++ b/packages/docs/content/migration-guides/migrating-to-new-buttons.mdx @@ -1,6 +1,6 @@ --- title: Migrating to v4 buttons -order: 20 +order: 70 intro: We've created a more consistent, scalable, and themable button framework for the CMS design system. --- diff --git a/packages/docs/content/migration-guides/migrating-to-v2.mdx b/packages/docs/content/migration-guides/migrating-to-v2.mdx index 33faec6d22..ff629b76fe 100644 --- a/packages/docs/content/migration-guides/migrating-to-v2.mdx +++ b/packages/docs/content/migration-guides/migrating-to-v2.mdx @@ -1,6 +1,6 @@ --- title: Migrating to v2 -order: 30 +order: 80 --- The CMS Design System v2 release introduces several breaking changes, and this migration guide outlines high-level steps to upgrade. See the [release notes](https://github.com/CMSgov/design-system/releases/tag/core-2.0.0) for a detailed list of changes. diff --git a/packages/docs/content/migration-guides/sass-to-css.mdx b/packages/docs/content/migration-guides/sass-to-css.mdx new file mode 100644 index 0000000000..6f1d3cb01a --- /dev/null +++ b/packages/docs/content/migration-guides/sass-to-css.mdx @@ -0,0 +1,113 @@ +--- +title: Sass to CSS +order: 60 +intro: New features in CSS have allowed us to stop relying on Sass to share design tokens with product teams. We're now only distributing our styles as CSS. +--- + +## What we changed and why + +Prior to [version 6.0.0](https://github.com/CMSgov/design-system/releases/tag/%40cmsgov%2Fdesign-system%406.0.0), we provided two ways of consuming our design system styles: as [Sass](https://sass-lang.com/) and as CSS. We used to recommend that product teams use our [Sass](https://sass-lang.com/) files because only then would they gain access to our [design tokens](/foundation/theme-colors/) and [theme variables](/components/alert/#styles). However, these three things lead us to reconsider Sass's future in the design system: + +1. Sass has a new compiler, but the upgrade path is messy and difficult to synchronize across teams +2. Having product teams build our Sass source files is exposing them to unnecessary complexity +3. Features we once relied on Sass for, like [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*), are now available in CSS + +We researched and prototyped and eventually [published an RFC](https://github.com/CMSgov/design-system/discussions/2223) proposing that use Sass internally but only distribute the compiled CSS output. We shared our findings with product teams and heard no objections, so we went forward with the change. + +## Updating style imports + +If you're consuming the design system styles as Sass, you likely have something like this in your project: + +```css +/* Old way of importing design-system styles */ +$font-path: '~@cmsgov/design-system/dist/fonts'; +$image-path: '~@cmsgov/design-system/dist/images'; +@import '@cmsgov/design-system/dist/scss/index'; + +/* Your styles here */ +``` + +Due to [limitations with some build systems](/getting-started/for-developers/#with-an-asset-bundler) and the Sass compiler, these `$font-path` and `$image-path` variables were necessary to make sure the bundler knew where to get fonts and images. In the move to CSS, we've made these paths static. It assumes these files exist at a location relative to your CSS bundle. + +For best results, we recommend importing our CSS files in the most direct way possible given your particular build system. That could be importing them from within a JavaScript module, creating a `` tag in your HTML, or importing them with a `.css` extension in Sass. Take a look at the [_Including the CSS_](https://design.cms.gov/getting-started/for-developers/#including-the-css) section of our developer docs and [our example projects](https://github.com/CMSgov/design-system/tree/main/examples/) for more info. + +Note that if you need your project Sass to evaluate the CSS files as Sass so you can do Sassy things, you'll have to [leave out the `.css` extension](https://sass-lang.com/documentation/at-rules/import#plain-css-imports). However, we have provided alternatives to several things that you might have needed Sass for previously, so be sure to read the sections below. + +## What to do about the focus-style mixin + +Your project might have previously used our `focus-styles` [mixin](https://sass-lang.com/documentation/at-rules/mixin) to apply design-system focus styles to custom components. In that case, you will want to [use the new focus utility classes](/utilities/focus/) instead. We're no longer distributing any Sass mixins with the design system. + +## What to do with instances of `@extends` + +It's still possible to use the `@extends` rule to apply design system styles to your own CSS rules if you import our CSS files into one of your Sass files and [leave out the `.css` extension](https://sass-lang.com/documentation/at-rules/import#plain-css-imports); however, you may not need to. + +We've introduced a new [`ds-content`](/foundation/typography/content/) CSS class that is useful for styling content that lives in plain HTML elements that aren't decorated with design system classes. For instance, you may have previously done something like this + +```css +h1 { + @extend .ds-text-heading--3xl; +} + +h2 { + @extend .ds-text-heading--2xl; +} + +/* et cetera */ +``` + +so you could get design system styling for content like this + +```html +
+

I'm a page heading

+

This is a really thoughtful sentence.

+

I'm a section heading

+
+``` + +Now you can style that content without any Sass by applying the `ds-content` class to a parent element of that content (direct or indirect parent does not matter): + +```html +
+

I'm a page heading

+

This is a really thoughtful sentence.

+

I'm a section heading

+
+``` + +Note that the mapping of heading styles to semantic heading levels represents what we consider sane defaults and that there may be cases where you want to override a particular heading's styles. In those cases we'd recommend applying one of the [headings classes](/foundation/typography/headings/) to the element. + +## Referencing our variables in CSS + +Most likely the biggest change you will want to make is referencing our design tokens and theme variables as [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*). We have a section on [using our CSS custom properties](/getting-started/for-developers/#css-custom-properties) in the developer docs, but just note that you don't have to make this transition right away. If you're using the Sass variables, they're still there; they've just moved (see next section). If you were always using CSS, you now have access to our variables in your stylesheets! + +## Sass variables are still available + +To help teams transition to using CSS custom properties in their own time, we're still providing Sass equivalents of all our variables. The example below shows which files you will need to import from your project Sass. + + + +```css +@import '@cmsgov/design-system/dist/scss/core-tokens'; +@import '@cmsgov/design-system/dist/scss/core-component-tokens'; +``` + + + + + +```css +@import '@cmsgov/ds-healthcare-gov/dist/scss/healthcare-tokens'; +@import '@cmsgov/ds-healthcare-gov/dist/scss/healthcare-component-tokens'; +``` + + + + + +```css +@import '@cmsgov/ds-medicare-gov/dist/scss/medicare-tokens'; +@import '@cmsgov/ds-medicare-gov/dist/scss/medicare-component-tokens'; +``` + + diff --git a/packages/docs/content/utilities/focus.mdx b/packages/docs/content/utilities/focus.mdx index 56b00108cb..9ebf10f12a 100644 --- a/packages/docs/content/utilities/focus.mdx +++ b/packages/docs/content/utilities/focus.mdx @@ -17,10 +17,10 @@ Use the `.ds-u-focus` utility to conditionally apply focus styles to your compon Click or tab into the following example to see this utility in action. - + Select a color - + **Focus-visible** @@ -30,10 +30,10 @@ Use the `.ds-u-focus-visible` utility to conditionally apply focus styles to you Tab into the following example to see this utility in action. - + Select another color - + **Focus-within** diff --git a/packages/docs/src/components/layout/PageHeader.tsx b/packages/docs/src/components/layout/PageHeader.tsx index 536bdfcbcc..d703e17cb5 100644 --- a/packages/docs/src/components/layout/PageHeader.tsx +++ b/packages/docs/src/components/layout/PageHeader.tsx @@ -3,6 +3,7 @@ import { FrontmatterInterface } from '../../helpers/graphQLTypes'; import { withPrefix } from 'gatsby'; import { makeGithubUrl, makeSketchUrl, makeStorybookUrl } from '../../helpers/urlUtils'; import GithubIcon from '../icons/GithubIcon'; +import classNames from 'classnames'; type PageHeaderProps = { frontmatter?: FrontmatterInterface; @@ -19,39 +20,53 @@ const PageHeader = ({ frontmatter = { title: '' }, theme }: PageHeaderProps) => const ghPath = themeLinks?.githubLink || core?.githubLink || null; const sketchId = themeLinks?.sketchLink || null; const storyId = themeLinks?.storybookLink || core?.storybookLink || null; + const showLinkBar = Boolean(ghPath || sketchId || storyId); + + const headerClassNames = classNames( + 'ds-u-padding-x--3', + 'ds-u-sm-padding-x--6', + 'ds-u-sm-padding-top--2', + showLinkBar ? 'ds-u-md-margin-bottom--7' : 'ds-u-md-margin-bottom--3' + ); return ( -
+

{title}

- {intro &&

{intro}

} -
- {ghPath && ( - - - Github - - )} - {storyId && ( - - Storybook logo - Storybook - - )} - {sketchId && ( - - Sketch logo - Sketch - - )} -
+ {intro && ( +

+ {intro} +

+ )} + {showLinkBar && ( +
+ {ghPath && ( + + + Github + + )} + {storyId && ( + + Storybook logo + Storybook + + )} + {sketchId && ( + + Sketch logo + Sketch + + )} +
+ )}
); };