+ Read more below for in-depth information about the stystem or go to
+ {' '}
+
+ to dive right in and start using Mayflower.
+ {' '}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/packages/core/stories/about/Usage.stories.mdx b/packages/core/stories/about/Usage.stories.mdx
new file mode 100644
index 0000000000..1540574e2b
--- /dev/null
+++ b/packages/core/stories/about/Usage.stories.mdx
@@ -0,0 +1,155 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+import { linkTo } from '@storybook/addon-links';
+import { Button } from '@massds/mayflower-react';
+
+import generateTitle from '../util/generateTitle';
+const { STORYBOOK_CDN_PATH, STORYBOOK_CDN, STORYBOOK_PKG } = process.env;
+
+
+
+
+
Get Started with Mayflower version {process.env.VERSION}
+
+
+
+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.
+
+
+## Quick Start
+To kickstart an HTML page with Mayflower Header, Footer, basic layout and styles:
+
+
+To start building with Mayflower in HTML, start by importing the global styles and then incrementally add the styles and JS for each Mayflower component:
+
+- To import fonts and get started with basic Mayflower styles, link to the compiled `css/global.css` (or the minified version, `css/global.min.css`) from the @massds/mayflower-assets package or the assets CDN.
+ > {`${STORYBOOK_CDN_PATH}/css/global.css`}
+
+- To include basic page layout styles from Mayflower, link to the compiled `css/layout.css` (or the minified version, `css/layout.min.css`) from the @massds/mayflower-assets package or the assets CDN.
+ > {`${STORYBOOK_CDN_PATH}/css/layout.css`}
+
+- To use a Mayflower branding component on your site, go to the documentation of the component, copy and paste the HTML code snippet, and link to the CDN version of CSS and JS files in the appropriate sections of your HTML.
+
+> For a production site, you should always link to the Mayflower CDN at a specific version. That way, you never have to worry about your website getting impacted by any Mayflower breaking updates, and you can upgrade to a new Mayflower version whenever your team is ready. Alternatively, you can host the CSS and JS downloaded from mayflower assets package.
+
+> To view a specific version of this documentation, go to https://mayflower.digital.mass.gov/core/v/:version
+
+
+
+
+## Mayflower Assets and CDN
+
+To enable and ensure the branding and visual cohesion, Mayflower delivers the following static assets and generated artifacts as a version controlled package.
+```
+├── css
+├── js
+├── scss
+├── static
+ ├── fonts
+ └── images
+ ├── icons
+ └── logos
+```
+### 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.
+
+To load any file from the @massds/mayflower-assets package using a URL like:
+
+```
+unpkg.com/@massds/mayflower-assets@:version/:file
+```
+
+To explore the whole package for a specific version, you can
+1. browse the `@massds/mayflower-assets` package of the lastest version at:
+{`${STORYBOOK_CDN}browse/${STORYBOOK_PKG}/`}
+
+2. Navigate on the resource you want to link to, e.g. css/global.css
+3. Click on “View Raw” and copy the URL for the file.
+
+For examples:
+
+
+
+
+
+## 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”,
+ $c-primary: #xxxxxx
+);
+@use "03-organism/header"
+```
+
+If you use Node.js, you can install Sass using npm by running:
+
+```$ npm install -g sass```
+
+And compile any sass files by running
+```$ sass source.scss output.scss```
diff --git a/packages/core/stories/components/Footer/Footer.stories.js b/packages/core/stories/components/Footer/Footer.stories.js
new file mode 100644
index 0000000000..8499a87420
--- /dev/null
+++ b/packages/core/stories/components/Footer/Footer.stories.js
@@ -0,0 +1,206 @@
+import React from 'react';
+import FooterSlim from '@massds/mayflower-react/dist/FooterSlim';
+import Footer from '@massds/mayflower-react/dist/Footer';
+import SiteLogo from '@massds/mayflower-react/dist/SiteLogo';
+import logo from '@massds/mayflower-assets/static/images/logo/stateseal.png';
+import { attachHTML } from '../../util/renderCode';
+
+const { STORYBOOK_CDN_PATH } = process.env;
+
+const footerBasic = (
+
+)}
+ title="Massachusetts Executive Office of Eductation (EDU)"
+ />
+);
+
+const footerDuelLogo = (
+
+
+
+
+)}
+ stackedLogo
+ title="Massachusetts Executive Office of Eductation (EDU)"
+ />
+);
+
+const footer = (
+
+);
+
+const notesFooterSlim = `// Link to CSS: `;
+
+const notesFooter = `// Link to CSS: `;
+
+export const footerExample = () => footerBasic;
+
+export const footerSlim = () => footerBasic;
+attachHTML(footerSlim, footerBasic, notesFooterSlim);
+
+export const footerSlimDuelLogo = () => footerDuelLogo;
+attachHTML(footerSlimDuelLogo, footerDuelLogo, notesFooterSlim);
+
+export const footerFullNav = () => footer;
+attachHTML(footerFullNav, footer, notesFooter);
diff --git a/packages/core/stories/components/Footer/Footer.stories.mdx b/packages/core/stories/components/Footer/Footer.stories.mdx
new file mode 100644
index 0000000000..40bfd9390a
--- /dev/null
+++ b/packages/core/stories/components/Footer/Footer.stories.mdx
@@ -0,0 +1,61 @@
+import { Meta, Story, Canvas } from '@storybook/addon-docs/blocks';
+import generateTitle from '../../util/generateTitle';
+import * as stories from './Footer.stories.js';
+
+
+
+# Footer
+
+Footers are containers located at the bottom of each page to provide for authorship information, copyright information, contact information, sitemap, back to home and back to top links, and related links.
+
+
+
+## Overview
+Mayflower footer content are organized in two or more columns:
+- The first column from the left contains
+ - Site logo(s)
+ - Authorship information
+ - Copyright information
+- The other columns(s) contains
+ - Other site navigation
+ - Contact information
+ - Sitemap
+ - Related Links
+
+
+## Variations
+
+For web apps and websites that have a simple sitemap or navigation structure, the footer is used mostly for displaying branding, copyright, and contact information.
+
+
+### Footer (Slim Version)
+A most simplified version of a header contains a blue bar (height: 15px) at the top and a site logo and site name linked to the home of the website, placed on a light gray background ($c-gray-lightest)
+
+
+
+### Footer (Slim Version with Duel Logos)
+There are some scenarios where more than one logos need to be displayed in the footer:
+Joint brand with a parent or sibling organization
+Logos available for both the service (application) and the organization
+
+
+
+
+
+### Footer (With More Footer Links)
+
+For sites with more complex information architecture, the footer also provides the opportunity for users to explore additional navigation options when they reach the bottom of the page. In this case, top level navigation menu items and other supporting forms and documents can be organized into up to three columns following the first column. For a live example, see the footer used on Mass.gov.
+
diff --git a/packages/core/stories/components/Header/Header.stories.js b/packages/core/stories/components/Header/Header.stories.js
new file mode 100644
index 0000000000..146134a401
--- /dev/null
+++ b/packages/core/stories/components/Header/Header.stories.js
@@ -0,0 +1,138 @@
+import React from 'react';
+import HeaderSlim from '@massds/mayflower-react/dist/HeaderSlim';
+import Header from '@massds/mayflower-react/dist/Header';
+import HeaderHamburger from '@massds/mayflower-react/dist/HeaderHamburger';
+import SiteLogo from '@massds/mayflower-react/dist/SiteLogo';
+import ButtonWithIcon from '@massds/mayflower-react/dist/ButtonWithIcon';
+import IconSearch from '@massds/mayflower-react/dist/Icon/IconSearch';
+import IconLatlonglobe from '@massds/mayflower-react/dist/Icon/IconLatlonglobe';
+import IconLogin from '@massds/mayflower-react/dist/Icon/IconLogin';
+import logo from '@massds/mayflower-assets/static/images/logo/stateseal.png';
+
+import mainNavData from './main-nav.data';
+
+import { attachHTML } from '../../util/renderCode';
+
+const { STORYBOOK_CDN_PATH } = process.env;
+
+const headerBasic = (
+
+)}
+ />
+);
+
+const headerUtil = (
+
+)}
+ skipNav={skip to main content}
+ utilityNav={(
+ <>
+
+
+ English
+
+
+
+ Log in
+
+
+ )}
+ />
+);
+
+const headerUtilSearch = (
+ } />}
+ siteLogo={(
+
+)}
+ skipNav={skip to main content}
+ utilityNav={(
+ <>
+
+
+ English
+
+
+
+ Log in
+
+
+ )}
+ />
+);
+
+const header = (
+
+);
+
+const headerHamburger = (
+
+);
+
+const notesHeaderSlim = `
+ // Link to CSS:
+`;
+
+const notesHeader = `
+ // Link to CSS:
+ // Link to JS:
+`;
+
+const notesHeaderHamburger = `
+ // Link to CSS:
+ // Link to JS:
+`;
+
+export const headerExample = () => headerBasic;
+
+export const headerSlimmest = () => headerBasic;
+attachHTML(headerSlimmest, headerBasic, notesHeaderSlim);
+
+export const headerSlimUtil = () => headerUtil;
+attachHTML(headerSlimUtil, headerUtil, notesHeaderSlim);
+
+export const headerSlimUtilSearch = () => headerUtilSearch;
+attachHTML(headerSlimUtilSearch, headerUtilSearch, notesHeaderSlim);
+
+export const headerFullNav = () => header;
+attachHTML(headerFullNav, header, notesHeader);
+
+export const headerFullNavHamburger = () => headerHamburger;
+attachHTML(headerFullNavHamburger, headerHamburger, notesHeaderHamburger);
diff --git a/packages/core/stories/components/Header/Header.stories.mdx b/packages/core/stories/components/Header/Header.stories.mdx
new file mode 100644
index 0000000000..ae6f19e961
--- /dev/null
+++ b/packages/core/stories/components/Header/Header.stories.mdx
@@ -0,0 +1,83 @@
+import { Meta, Story, Canvas } from '@storybook/addon-docs/blocks';
+import HeaderSlim from '@massds/mayflower-react/dist/HeaderSlim';
+import Header from '@massds/mayflower-react/dist/Header';
+import SiteLogo from '@massds/mayflower-react/dist/SiteLogo';
+import ButtonWithIcon from '@massds/mayflower-react/dist/ButtonWithIcon';
+import IconSearch from '@massds/mayflower-react/dist/Icon/IconSearch';
+import IconLatlonglobe from '@massds/mayflower-react/dist/Icon/IconLatlonglobe';
+import IconLogin from '@massds/mayflower-react/dist/Icon/IconLogin';
+import logo from '@massds/mayflower-assets/static/images/logo/stateseal.png';
+
+import generateTitle from '../../util/generateTitle';
+import * as stories from './Header.stories.js';
+
+
+
+# Header
+
+Headers are containers that span across the top of each page to house product-wide branding and global actions and navigation, as well as user preferences.
+
+
+
+## Overview
+Mayflower header consists of the following parts:
+- Utility nav — a blue bar spans across the top of the header that is used to house global actions such as:
+ - Log in/ logout
+ - Global hamburger navigation
+ - Language translation
+ - Other global utilities
+- Site logo and title
+- Navigation items such a drop down menu or a search bar
+
+## Variations
+
+Base on the complexity of the navigation functionality, we can categorize Mayflower headers into the following two types:
+- **A Slim Header:**
+A flexible container that includes the site logo and styles of the Mayflower header with fully configurable utility nav and main nav areas
+
+- **A Full-Menu Header:**
+Header with full menu is designed for sites with more complex information architecture, it includes a main nav that allows up to two levels of navigation
+
+
+### Header (Slimmest)
+A most simplified version of a header contains a blue bar (height: 15px) at the top and a site logo and site name linked to the home of the website, placed on a light gray background ($c-gray-lightest)
+
+
+### Header (Slim version with utility nav links)
+For web apps and websites that provide multi-language localization and login/logout functionalities, add the action links or buttons in the utility navigation bar as such:
+
+
+### Header (Slim version with utility nav links and search)
+For simple navigation options, add the main navigation links and search bar in the header nav container `.ma__header_slim__nav`
+
+
+### Header (With Dropdown Menu)
+
+For sites with more complex information architecture, Mayflower provides examples of headers with a fully integrated, responsive and interactive menu. The menu can contain up to two levels of navigation links and is available in two options:
+
+Header with a dropdown menu. This option is specifically for websites and pages where the top level navigation is important for the users to browse and find the information they need. For example, this header option is used on the Mass.gov homepage.
+
+
+
+
+### Header (With Hamburger Menu)
+The hamburger menu by default collapses the main navigation of the site into a side drawer that opens up when users interact with the “Menu” icon. This option saves the header space for content pages whose primary goals are for accessing the information and actions in the main content area. For example this header option is used on the Mass.gov content pages that are not the homepage.
+
+
diff --git a/packages/core/stories/components/Header/main-nav.data.js b/packages/core/stories/components/Header/main-nav.data.js
new file mode 100644
index 0000000000..aca6fc6a18
--- /dev/null
+++ b/packages/core/stories/components/Header/main-nav.data.js
@@ -0,0 +1,148 @@
+export default [
+ {
+ text: 'Living',
+ active: '',
+ subNav: [
+ {
+ href: 'https://mass.gov',
+ text: 'Health & Social Services'
+ },
+ {
+ href: '/patterns/05-pages-topic/05-pages-topic.html',
+ text: 'Family & Children'
+ },
+ {
+ href: '#',
+ text: 'Housing'
+ },
+ {
+ href: '#',
+ text: 'Transportation'
+ },
+ {
+ href: '#',
+ text: 'Legal & Justice'
+ },
+ {
+ href: '#',
+ text: 'Public Safety'
+ },
+ {
+ href: '#',
+ text: 'Voting'
+ },
+ {
+ href: '#',
+ text: 'Taxes'
+ }
+ ]
+ },
+ {
+ href: '#',
+ text: 'Working',
+ active: '',
+ subNav: [
+ {
+ href: '#',
+ text: 'Unemployment'
+ },
+ {
+ href: '#',
+ text: 'Finding a Job'
+ },
+ {
+ href: '#',
+ text: 'Worker’s Rights & Safety'
+ },
+ {
+ href: '#',
+ text: 'Business Services & Resources'
+ },
+ {
+ href: '#',
+ text: 'Professional Licensing & Certification'
+ },
+ {
+ href: '#',
+ text: 'Professional Training'
+ }
+ ]
+ },
+ {
+ href: '#',
+ text: 'Learning',
+ active: '',
+ subNav: [
+ {
+ href: '#',
+ text: 'Early Childhood Education'
+ },
+ {
+ href: '#',
+ text: 'K-12 Schools'
+ },
+ {
+ href: '#',
+ text: 'Higher Education'
+ },
+ {
+ href: '#',
+ text: 'Continuing Education'
+ }
+ ]
+ },
+ {
+ href: '/patterns/05-pages-section-landing/05-pages-section-landing.html',
+ text: 'Visiting & Exploring',
+ active: 'true',
+ subNav: [
+ {
+ href: '#',
+ text: 'Recreational Licenses & Permits'
+ },
+ {
+ href: '#',
+ text: 'State Parks & Recreation'
+ },
+ {
+ href: '#',
+ text: 'Travel & Tourism'
+ },
+ {
+ href: '#',
+ text: 'Arts & Culture'
+ }
+ ]
+ },
+ {
+ href: '#',
+ text: 'Your Government',
+ active: '',
+ subNav: [
+ {
+ href: '#',
+ text: 'Office of the Governor'
+ },
+ {
+ href: '#',
+ text: 'State Agencies'
+ },
+ {
+ href: '/patterns/05-pages-topic-your-government/05-pages-topic-your-government.html',
+ text: 'Executive Branch'
+ },
+ {
+ href: '#',
+ text: 'Judicial Branch'
+ },
+ {
+ href: '#',
+ text: 'Legislative Branch'
+ },
+ {
+ href: '#',
+ text: 'Local Government'
+ }
+ ]
+ }
+];
diff --git a/packages/core/stories/components/Template/Template.stories.js b/packages/core/stories/components/Template/Template.stories.js
new file mode 100644
index 0000000000..d0bac2c32e
--- /dev/null
+++ b/packages/core/stories/components/Template/Template.stories.js
@@ -0,0 +1,93 @@
+import React from 'react';
+import * as headerStories from '../Header/Header.stories';
+import * as footerStories from '../Footer/Footer.stories';
+
+import { attachHTML } from '../../util/renderCode';
+
+const { STORYBOOK_CDN_PATH } = process.env;
+
+export const template = ({ renderHeader, renderFooter, reversed }) => (
+
+ {renderHeader}
+
+
+
+ Pre Content
+
+
+
+
+ Main Content
+
+
+
+ { reversed && (
+
+ )}
+
+
+ Main Content
+
+
+ { !reversed && (
+
+ )}
+
+
+
+ Post Content
+
+ {renderFooter}
+
+);
+
+const templateSlim = template({ renderHeader: headerStories.headerSlimmest(), renderFooter: footerStories.footerSlim() });
+
+const templateFullNav = template({ renderHeader: headerStories.headerFullNav(), renderFooter: footerStories.footerFullNav(), reversed: true });
+
+const notesTemplateSlim = `
+ // Link to CSS:
+
+
+
+
+`;
+
+const notesTemplate = `
+ // Link to CSS:
+
+
+
+
+
+ // Link to JS:
+
+`;
+
+export const notesTemplateCSS = `
+
+
+
+
+
+
+
+`;
+
+export const notesTemplateJS = `
+
+`;
+
+export const templateBasic = () => templateSlim;
+attachHTML(templateBasic, templateSlim, notesTemplateSlim);
+
+export const templateFull = () => templateFullNav;
+attachHTML(templateFull, templateFullNav, notesTemplate);
diff --git a/packages/core/stories/components/Template/Template.stories.mdx b/packages/core/stories/components/Template/Template.stories.mdx
new file mode 100644
index 0000000000..91c7f4122b
--- /dev/null
+++ b/packages/core/stories/components/Template/Template.stories.mdx
@@ -0,0 +1,56 @@
+import { Meta, Story, Canvas, Source } from '@storybook/addon-docs/blocks';
+import { linkTo } from '@storybook/addon-links';
+
+import generateTitle from '../../util/generateTitle';
+import * as stories from './Template.stories.js';
+import { renderReactMarkup } from '../../util/renderCode';
+
+
+
+# Template
+
+The templates demostrates how to assemble a page with a Mayflower Header, Footer and a basic page layout.
+
+> Refer to and , copy and paste the Header and Footert HTML, CSS and JS (if any) into the template snippet.
+
+
+ ${renderReactMarkup(stories.template({renderHeader: '// Insert Header HTML here', renderFooter: '// Insert Footer HTML here'}))}
+ ${stories.notesTemplateJS}
+
+ `
+} />
+
+
+## Usage
+To kick-start a page in HTML:
+1. Copy the code above or jump to an example below and click on "Show code" to copy the HTML snippet from the example
+4. Add the links to CSS and JS at the appropriate places
+ - **CSS**: Link to CSS inside the ``
+ - **JS**: Link to JS before the closing body tag ``
+5. Replace the `.ma__placeholder` divs with real content
+
+
+
+## Examples
+
+### Header and Footer (Slim)
+A demo page with the Slim Header, Slim Footer, and a layout of a full-width block, and two-column block with a right-rail.
+
+
+
+### Header and Footer (With Full Navigation)
+A demo page with the Full Nav Header, Full Nav Footer, and a layout of a full-width block, and two-column block with a left-rail.
+
+
diff --git a/packages/core/stories/elements/Button/Button.stories.js b/packages/core/stories/elements/Button/Button.stories.js
new file mode 100644
index 0000000000..36acd1bceb
--- /dev/null
+++ b/packages/core/stories/elements/Button/Button.stories.js
@@ -0,0 +1,21 @@
+import { attachCSS } from '../../util/renderCode';
+
+const { STORYBOOK_CDN_PATH } = process.env;
+
+const cssButton = `// Link to CSS: `;
+
+// exported story names must be unique
+export const buttonCSS = () => null;
+attachCSS(buttonCSS, cssButton);
+
+export const buttonCSS2 = () => null;
+attachCSS(buttonCSS2, cssButton);
+
+export const buttonCSS3 = () => null;
+attachCSS(buttonCSS3, cssButton);
+
+export const buttonCSS4 = () => null;
+attachCSS(buttonCSS4, cssButton);
+
+export const buttonCSSDisabled = () => null;
+attachCSS(buttonCSSDisabled, cssButton);
diff --git a/packages/core/stories/elements/Button/Button.stories.mdx b/packages/core/stories/elements/Button/Button.stories.mdx
new file mode 100644
index 0000000000..8c2d97a502
--- /dev/null
+++ b/packages/core/stories/elements/Button/Button.stories.mdx
@@ -0,0 +1,164 @@
+import { Meta, Story, Canvas } from '@storybook/addon-docs/blocks';
+import Button from '@massds/mayflower-react/dist/Button';
+import generateTitle from '../../util/generateTitle';
+import { renderReactMarkup } from '../../util/renderCode';
+import * as stories from './Button.stories.js';
+
+
+
+# Buttons
+
+Buttons are used in forms and interactive applications to trigger actions.
+
+
+
+Following web best practices buttons have a target area of 45 pixels. To provide more visual affordance that they are clickable—not just text in a box—they have a shadow to appear slightly raised. Small buttons can be used for secondary tasks on forms—for example image upload—and filters on listing pages. Large buttons should be used for form submits or primary calls to action. There should usually be only one primary button in any UI. Font sizes reduce slightly on mobile.
+
+---
+
+### Primary Buttons
+
+- **Usage:** For the main action in a form, or for a call-to-action link on a page.
+- **Style:** Default buttons are solid color with contrasting uppercase text. The hover state lightens the primary button background color.
+
+
+
+---
+
+### Secondary Buttons
+
+- **Usage:** For secondary actions.
+- **Style:** The outline button has less visual prominence than the primary button so it can be used alongside it as a secondary action, for example "Cancel". The hover state of the secondary button inverts the background and foreground colors.
+
+
+
+---
+
+### Tertiary Buttons
+
+- **Usage:** For third-level actions.
+- **Style:** The gray color is even less prominent than outline button to de-emphasize third-level tasks. The hover state lightens the tertiary button background color.
+
+
+
+---
+
+### Quaternary Buttons
+
+- **Usage:** For fourth-level actions or actions.
+- **Style:** Appears as a link, with a small amount of letterspacing and underline (Actually a `border-bottom` not a text underline). The hover state darkens the underline and increases it's weight.
+
+
+
+---
+
+### Disabled Buttons
+
+- **Usage:** Disabled buttons should not be clickable. The disabled attribute (as opposed to hidden) can be applied for actions where the user should see the action and it's state but may not be able to perform it because they either don't have permission or some other condition in the form has not been met.
+- **Style:** Disabled buttons have no box shadow (since the box shadow is what suggests clickability). Their opacity is `0.5.`, no hover or focus states are provided and the cursor is set to `not-allowed`.
+
+
+
+
+---
+
+### Accessibility & Best Practices
+
+- **Always** use `