From 61a30e8631de4d5c4338314f0e2b21314f064e8b Mon Sep 17 00:00:00 2001 From: Terrence Kevin Oleary Date: Tue, 24 Nov 2020 17:56:39 -0600 Subject: [PATCH] Docs work typography (#1277) * Imported mayflower theme to docs For some reason storybook requires it to be impoerted there as well to available in the docs pages. Also made somee tweaks to the Mayflower sstorybook theme. * Updates to styles, markup and content for typography. Plus a few minor content changes to 'about' * Update packages/core/stories/tokens/typography/Typography.stories.mdx Co-authored-by: Minghua Sun * Update packages/core/stories/tokens/typography/Typography.stories.mdx Co-authored-by: Minghua Sun * Update packages/core/stories/about/Usage.stories.mdx Co-authored-by: Minghua Sun * Updated vertical spacing -reverted fallbacks -reverted numbers -added class for language labels -added language labels to languages that didn't have them -indented language labels to differentiate from scripts -Corrected script names -added rtl class for labels -Moved sample to top * Apply suggestions from code review Co-authored-by: Minghua Sun --- packages/core/.storybook/mayflowerTheme.js | 6 +- packages/core/.storybook/preview.js | 7 +- packages/core/stories/about/Usage.stories.mdx | 16 +- packages/core/stories/styles/index.scss | 44 +++ .../tokens/typography/Typography.stories.mdx | 283 +++++++++++------- 5 files changed, 244 insertions(+), 112 deletions(-) diff --git a/packages/core/.storybook/mayflowerTheme.js b/packages/core/.storybook/mayflowerTheme.js index eaee1b023c..dc8751dcbe 100644 --- a/packages/core/.storybook/mayflowerTheme.js +++ b/packages/core/.storybook/mayflowerTheme.js @@ -3,14 +3,14 @@ import logo from './mayflower-logo.png'; export default create({ base: 'light', - // colorPrimary: 'hotpink', + colorPrimary: '#388557', colorSecondary: '#14558F', // UI appBg: '#F2F2F2', - // appContentBg: 'silver', + appContentBg: '#FFFFFF', appBorderColor: '#DCDCDC', - appBorderRadius: 6, + appBorderRadius: 0, // Typography fontBase: '"Noto Sans VF", "Noto Sans", "Helvetica", "Arial", sans-serif', diff --git a/packages/core/.storybook/preview.js b/packages/core/.storybook/preview.js index dfb8c71b78..632ab7f8ab 100644 --- a/packages/core/.storybook/preview.js +++ b/packages/core/.storybook/preview.js @@ -1,3 +1,5 @@ +import mayflowerTheme from './mayflowerTheme'; + const storyKindOrder = [ 'Get Started', 'Design Principles', @@ -16,5 +18,8 @@ export const parameters = { previewTabs: { canvas: { hidden: true } }, - viewMode: 'docs' + viewMode: 'docs', + docs: { + theme: mayflowerTheme, + } } diff --git a/packages/core/stories/about/Usage.stories.mdx b/packages/core/stories/about/Usage.stories.mdx index c7319eaf04..129a0e72d0 100644 --- a/packages/core/stories/about/Usage.stories.mdx +++ b/packages/core/stories/about/Usage.stories.mdx @@ -3,9 +3,11 @@ import { Meta } from '@storybook/addon-docs/blocks'; import generateTitle from '../util/generateTitle'; const { STORYBOOK_CDN_PATH, STORYBOOK_CDN, STORYBOOK_PKG } = process.env; + # Install Mayflower + We encourage all Commonwealth web properties to implement the Mayflower Design System for a consistent look and feel. It’s important that constituents know they are on an official state government website, and the visual cues that come from using a cohesive design help convey that legitimacy. ## Mayflower assets @@ -21,15 +23,16 @@ To enable and ensure the branding and visual cohesion, Mayflower delivers the fo ├── icons └── logos ``` -### Download the package -NPM Package -This package is named @massds/mayflower-assets and is published on NPM. If you use Node.js, you can download the whole package simply by running the following command line: +### Download the NPM package + +The package @massds/mayflower-assets is published on NPM. If you use Node.js, you can install it by running: ``` npm install @massds/mayflower-assets ``` ### Link to the Mayflower CDN + Mayflower leverages the UNPKG CDN and allows you to load any file in the @massds/mayflower-assets package directly. We highly recommend that you link to the CDN at a specific version. That way, you never have to worry about your website get impacted by any Mayflower breaking updates, and you can upgrade to a new Mayflower version whenever your team is ready. To load any file from the @massds/mayflower-assets package using a URL like: @@ -103,13 +106,15 @@ For examples: ## Build with Mayflower -To import fonts and get started with basic Mayflower layout CSS, you need to import `scss/global.scss` (@use `scss/global.scss`) or link to the compiled `static/fonts/css/global.css` (a minified version is available as global.min.css). -To implement a Mayflower branding component in your website, navigate to the documentation of the component and copy and paste the html and CSS (and JS) snippets into your code to get started. You can also link to the CDN version of CSS and JS files for the component directly in the head of your HTML. + +To import fonts and get started with basic Mayflower layout CSS, import `scss/global.scss` (`@use scss/global.scss`) or link to the compiled `static/fonts/css/global.css` (or the minified version, global.min.css). To use a Mayflower branding component on your site, go to the documentation of the component and copy and paste the html and link to the CDN version of CSS and JS files in the head of your HTML. You can also host the CSS and JS downloaded from mayflower assets package. ## Configure Your Theme + Mayflower style guide is derived from our research, experience, and expertise, and decision making in creating Mass.gov. We recognize that not all aspects of this branding guide will make sense for every organization, and that some organizations have their own distinct branding. We provide SCSS variables and partials for organizations to configure and compile their own Mayflower stylesheets, based on individual branding needs. You can configure all the variables declared in scss/00-base with a !default flag, such as _variables.scss _colors.scss _color-tokens.scss _breakpoints.scss _z-index.scss For example to theme the Mayflower header with your own primary color: + ``` @use "00-base/configure" with ( $assets-path: "~@massds/mayflower-assets/static”, @@ -119,6 +124,7 @@ For example to theme the Mayflower header with your own primary color: ``` If you use Node.js, you can install Sass using npm by running: + ```$ npm install -g sass``` And compile any sass files by running diff --git a/packages/core/stories/styles/index.scss b/packages/core/stories/styles/index.scss index 4cb7789266..cd73d99fe2 100644 --- a/packages/core/stories/styles/index.scss +++ b/packages/core/stories/styles/index.scss @@ -46,6 +46,11 @@ } } +.sb-block.borderless { + margin: 3rem 0 !important; + padding: 0 !important; + border: 0 !important; +} // Intro story .row.ma__row--three-up { @@ -85,3 +90,42 @@ ul.sg-colors { } } } + +// Typography story +.font-specimen { + font-size: 1.7rem !important; + line-height: 1.25 !important; + word-break: break-all; + font-weight: 300; + + &.large { + font-size: 2.5rem !important; + } + & strong { + font-weight: 400; + } +} + +p.font-specimen { + margin: 0 0 .5rem; +} + +p.lang-label { + font-weight: 450; + margin: 0; + + &.rtl { + direction: rtl; + } +} + +p.font-specimen, +p.lang-label { + padding: 0 1rem; +} + +.reset-vspace * { + line-height: 1.5; + margin-block-start: 0; + margin-block-end: 0; +} diff --git a/packages/core/stories/tokens/typography/Typography.stories.mdx b/packages/core/stories/tokens/typography/Typography.stories.mdx index 276519428c..39cf649b6c 100644 --- a/packages/core/stories/tokens/typography/Typography.stories.mdx +++ b/packages/core/stories/tokens/typography/Typography.stories.mdx @@ -1,7 +1,6 @@ import { Meta, Story, ArgsTable } from '@storybook/addon-docs/blocks'; import DecorativeLink from '@massds/mayflower-react/dist/DecorativeLink'; import Heading from '@massds/mayflower-react/dist/Heading'; -// import RichText from '@massds/mayflower-react/dist/RichText'; import { characters, letters, @@ -23,146 +22,224 @@ import generateTitle from '../../util/generateTitle'; }} /> -# Noto Sans -**The official typeface of Mayflower is Noto Sans.** -It’s carefully chosen for the following reasons: -- Accessible and easy to read -- To enable all Commonwealth agencies to design, produce and deliver online and offline content with consistent typography, without additional costs or legal barriers. -- To provide comprehensive language coverage for content internationalization. -- To support the guiding principles of the Mass.gov brand identities: modern, dignified, human, helpful +# Typography + +
+ +## The typeface of Mayflower is **Noto Sans** + +
{letters.toUpperCase()}
{letters}
{numbers}
+ +### Noto Sans was chosen because it's... + +- **Accessible** and easy-to-read for users with all levels of language proficiency +- **Free** and Open-source so agencies can produce print and digital design, without barriers +- **Multilingual** to cover the languages our constituents speak and read +- **Modern** and consistent with the principles of the Mass.gov brand Using these fonts for your print and digital assets is a subtle but compelling way to create a voice that is cohesive and unified with the rest of the Commonwealth digital ecosystem, and to ensure the text is accessible and easy to read. +
+ > Noto Sans is an open source typeface jointly designed and developed by Google and Monotype. It has the most comprehensive language coverage — including more than 800 languages and 100 written scripts. You can directly download the fonts from Google Font, or for web projects, link to the fonts via Mayflower Assets CDN +
+

Characters*

+
{characters}
+

*Latin 1 Block, shown in light weight (350)

+
+ +
+

Styles and Usage

+

Noto Sans is used for all headings and body text. If your HTML is [semantic](https://developer.mozilla.org/en-US/docs/Glossary/Semantics) and uses tags that match the hierarchy of the content on a page, the Mayflower defaults will automatically style your headings with an appropriate amount of contrast.

+ { Object.keys(headings).map((key, keyIndex) => ( + (key === "Body text") ? + (

{key}

) : + () + ) + )} +
+ +### CSS weight classes + +

Mayflower uses 5 custom weights of Noto Sans:
Lighter (250); Light, (350); Normal, (400); Bold, (550); and Bolder, (650).

-## Characters - -
{letters.toUpperCase()}
-
{letters}
-
-
{numbers}
-
{numbersReverse}
-
-
{characters}
- +

Use the following classes to style text with those weights:

+
+ { + styles.map((style, styleIndex) => { + const className = `ma-fonts-${slugifyStyle(style)}`; + return( + + Weight: {style} + + CSS Class: + + {`.${className}`} + + + + ); + }) + } +
## Languages by Script + The following languages are officially supported by [Mass.gov](https://www.mass.gov). If your project needs to support an addtional language, please [submit a feature request](https://github.com/massgov/mayflower/issues/new/choose) on Github. -#### Arabic -Arabic: مرحبا بكم في ماساتشوستس -Persian: به ماساچوست خوش آمدید -Urdu: میساچوسٹس میں آپ کا استقبال ہےد + -#### Armenian -Բարի գալուստ Մասաչուսեթս +### Left-to-right -#### Chinese -Simplified: 欢迎来到马萨诸塞州 -Tranditional: 歡迎來到馬薩諸塞州 +--- -#### Cyrillic -Russian: Добро пожаловать в Массачусетс -Ukrainian: Ласкаво просимо до Массачусетсу +#### Armenian script -#### Greek -Καλώς ήλθατε στη Μασαχουσέτη + +

Armenian:

+

Բարի գալուստ Մասաչուսեթս

-#### Gujarati -મેસેચ્યુસેટ્સમાં +#### Chinese, simplified script + +

Chinese:

+

欢迎来到马萨诸塞州

-#### Hebrew -ברוך הבא למסצ'וסט.ס +#### Chinese, traditional script -#### Hindi -मैसाचुसेट्स में आपका स्वागत है + +

Chinese:

+

歡迎來到馬薩諸塞州

-#### Japanese -マサチューセッツへようこそ +#### Cyrillic script -#### Khmer -សូមស្វាគមន៍មកកាន់ម៉ាសាឈូសេត +

Russian:

+

Добро пожаловать в Массачусетс

-#### Korean -매사추세츠에 오신 것을 환영합니다 +

Ukrainian:

+

Ласкаво просимо до Массачусетсу

-#### Lao -ຍິນດີຕ້ອນຮັບສູ່ Massachusetts +#### Greek script -#### Latin -English: Welcome to Massachusetts -Filipino: Maligayang pagdating sa Massachusetts -French: Bienvenue au Massachusetts -German: Willkommen in Massachusetts -Haitian Creole: Byenveni nan Massachusetts -Arabic: Maligayang pagdating sa Massachusetts -Italian: Benvenuto in Massachusetts -Polish: Witamy w Massachusetts -Portuguese: Bem vindo a Massachusetts -Spanish: Bienvenido a massachusetts +

Greek:

+

Καλώς ήλθατε στη Μασαχουσέτη

-#### Malayalam -മസാച്ചുസെറ്റ്സിലേക്ക് സ്വാഗതം +#### Gujarati script -#### Tamil -மாசசூசெட்ஸுக்கு வருக + +

Gujarati:

+

મેસેચ્યુસેટ્સમાં

-#### Telugu -మసాచుసెట్స్‌కు స్వాగతం +#### Devanagari script -#### Thai -ยินดีต้อนรับสู่แมสซาชูเซตส์ + +

Hindi:

+

मैसाचुसेट्स में आपका स्वागत है

-#### Vietnamese -Chào mừng đến với Massachusetts +#### Hiragana script -## Styles and Usage -Noto Sans is being used both as the display fonts and the text fonts. -When being used as the display fonts for headings, it should be styled at large sizes and in bold, with enough visual contrast to the body text to show the content hierarchy. + +

Japanese:

+

マサチューセッツへようこそ

-
- { Object.keys(headings).map((key, keyIndex) => ( - (key === "Body text") ? - (

{key}

) : - () - ) - )} -
+#### Khmer script +

Khmer:

+

សូមស្វាគមន៍មកកាន់ម៉ាសាឈូសេត

+#### Hangul script -Mayflower uses the the following 5 font weight options of Noto Sans: + +

Korean:

+

매사추세츠에 오신 것을 환영합니다

-| Font weight | Specs | -| :--- | :--- | -| Lighter | 250 | -| Light | 350 | -| Normal | 400 | -| Bold | 550 | -| Bolder | 650 | +#### Lao script + +

Lao:

+

ຍິນດີຕ້ອນຮັບສູ່ Massachusetts

-
- { - styles.map((style, styleIndex) => { - const className = `ma-fonts-${slugifyStyle(style)}`; - return( - - {style} - - {`.${className}`} - - - ); - }) - } -
+#### Latin script + +

English:

+

Welcome to Massachusetts

+ +

Filipino:

+

Maligayang pagdating sa Massachusetts

+ +

French:

+

Bienvenue au Massachusetts

+ +

German:

+

Willkommen in Massachusetts

+ +

Haitian Creole:

+

Byenveni nan Massachusetts

+ +

Arabic:

+

Maligayang pagdating sa Massachusetts

+ +

Italian:

+

Benvenuto in Massachusetts

+ +

Polish:

+

Witamy w Massachusetts

+ +

Portuguese:

+

Bem vindo a Massachusetts

+ +

Spanish:

+

Bienvenido a massachusetts

+ +

Vietnamese:

+

Chào mừng đến với Massachusetts

+ +#### Malayalam script + + +

Malayalam:

+

മസാച്ചുസെറ്റ്സിലേക്ക് സ്വാഗതം

+ +#### Tamil script + +

Tamil:

+

மாசசூசெட்ஸுக்கு வருக

+ +#### Telugu script + +

Telugu:

+

మసాచుసెట్స్‌కు స్వాగతం

+ +#### Thai script + +

Thai:

+

ยินดีต้อนรับสู่แมสซาชูเซตส์

+ +### Right-to-Left + +--- + +#### Arabic script + +

Arabic:

+

مرحبا بكم في ماساتشوستس

+ +

Persian:

+

به ماساچوست خوش آمدید

+ +

Urdu:

+

میساچوسٹس میں آپ کا استقبال ہےد

+ +#### Hebrew script +

Hebrew:

+

ברוך הבא למסצ'וסט.ס

## License -Noto Sans is an open source font licensed under SIL Open Font License 1.1 (OFL) by the Google team. The OFL allows the licensed fonts to be used, studied, modified and -redistributed freely as long as they are not sold by themselves. For more details, refer to the [license](https://github.com/googlefonts/noto-fonts/blob/master/LICENSE). +Noto Sans is an open source font licensed under SIL Open Font License 1.1 (OFL) by the Google team. The OFL allows the licensed fonts to be used, studied, modified and redistributed freely as long as they are not sold by themselves. For more details, refer to the [license](https://github.com/googlefonts/noto-fonts/blob/master/LICENSE).