Core/base elements content only

packages/core/stories/elements/Button/Button.stories.mdx

@@ -12,160 +12,153 @@ import * as stories from './Button.stories.js';
 />
 
 # Buttons
-Buttons express what action will occur when the user clicks or touches it. Buttons are used to initialize an action, either in the background or foreground of an experience.
-<Canvas withSource="none" >
+
+Buttons are used in forms and interactive applications, but also as prominent call-to-action links on website pages.
+
+<Canvas withSource="none">
   <Story
-    name='test'
-    parameters={{ docs: { source: {code: null}}}}>
-    <Button text="Button" />
-    </Story>
+		name="button-primary"
+    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="" text="Button"/>) } }}>
+      <Button usage="" text="Button" />
+  </Story>
 </Canvas>
 
-## Overview
-Buttons are vital for creating a smooth conversational flow on the web, and should be used sparingly. Buttons should adhere to standard web practices, and afford for a target area of 45 pixels. They should also appear slightly raised, and not be completely flat. They have a slight shadow on them so they appear clickable. The small buttons are often used on forms and to set filters on listing pages. The large buttons should be used for primary calls to action. Font sizes reduce slightly on mobile.
+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.
 
+---
 
-## Variations
-<br />
+### Primary Buttons
 
-### Primary Button
-**Usage:** For the principle call to action on the page.
+- **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. For actions with text longer than two words use the `title-case` class. On hover the Background color becomes lighter.
 
-**Style:**
-Default buttons are solid colors with uppercased button text (this is configurable with an capitalized option for longer button text) Box shadow are used to accentuate the actions. Background color of the primary button lightens when being hovered over.
 <Canvas>
   <Story
     name="button-primary-c-primary"
-    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="" text="button"/>) } }}>
-      <Button usage="" text="button" />
+    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="" text="Primary"/>) } }}>
+      <Button usage="" text="Primary" />
   </Story>
   <Story
     name="button-primary-c-primary-alt"
-    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="" theme="c-primary-alt" text="button"/>) } }}>
-      <Button usage="" theme="c-primary-alt" text="button"/>
+    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="" theme="c-primary-alt" text="Primary"/>) } }}>
+      <Button usage="" theme="c-primary-alt" text="Primary"/>
   </Story>
   <Story
     name="button-primary-c-highlight"
-    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="" theme="c-highlight" text="button"/>) } }}>
-      <Button usage="" theme="c-highlight" text="button"/>
+    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="" theme="c-highlight" text="Primary"/>) } }}>
+      <Button usage="" theme="c-highlight" text="Primary"/>
   </Story>
   <Story
     name="button-primary-c-gray"
-    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="" theme="c-gray-dark" text="button"/>) } }}>
-      <Button usage="" theme="c-gray-dark" text="button"/>
+    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="" theme="c-gray-dark" text="Primary"/>) } }}>
+      <Button usage="" theme="c-gray-dark" text="Primary"/>
   </Story>
   <Story story={stories.buttonCSS} />
 </Canvas>
 
+---
 
-<hr className="sp--top" />
+### Secondary Buttons
 
-### Secondary Button
-**Usage:** For the secondary action on a page.
+- **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.
 
-**Style:**
-The outline button provides a less prominent visual to indicate an less important action on a page, e.g. the Back button. The hover state of the secondary button inverts the background/foreground colors.
 <Canvas>
   <Story
     name="button-secondary-c-primary"
-    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="secondary" text="button"/>) } }}>
-      <Button usage="secondary" text="button" />
+    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="secondary" text="Secondary"/>) } }}>
+      <Button usage="secondary" text="Secondary" />
   </Story>
   <Story
     name="button-secondary-c-primary-alt"
-    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="secondary" theme="c-primary-alt" text="button"/>) } }}>
-      <Button usage="secondary" theme="c-primary-alt" text="button"/>
+    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="secondary" theme="c-primary-alt" text="Secondary"/>) } }}>
+      <Button usage="secondary" theme="c-primary-alt" text="Secondary"/>
   </Story>
   <Story
     name="button-secondary-c-highlight"
-    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="secondary" theme="c-highlight" text="button"/>) } }}>
-      <Button usage="secondary" theme="c-highlight" text="button"/>
+    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="secondary" theme="c-highlight" text="Secondary"/>) } }}>
+      <Button usage="secondary" theme="c-highlight" text="Secondary"/>
   </Story>
   <Story
     name="button-secondary-c-gray"
-    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="secondary" theme="c-gray-dark" text="button"/>) } }}>
-      <Button usage="secondary" theme="c-gray-dark" text="button"/>
+    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="secondary" theme="c-gray-dark" text="Secondary"/>) } }}>
+      <Button usage="secondary" theme="c-gray-dark" text="Secondary"/>
   </Story>
   <Story story={stories.buttonCSS2} />
 </Canvas>
 
-<hr className="sp--top" />
+---
 
-### Tertiary Button
-**Usage:** For the third action on a page.
+### Tertiary Buttons
 
-**Style:** This is a solid gray button with a lighter background color than the foreground text. The muted color makes this button less prominent on a page than the secondary outline button a providing an option for a tertiary action. The hover state of this button will invert background color with white color text.
+- **Usage:** For third-level actions on a page.
+- **Style:** The gray color is even less prominent than outline button to de-emphasize third-level tasks. The hover state inverts the background and text colors.
 
 <Canvas>
   <Story
     name="button-tertiary"
-    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="tertiary" text="button"/>) } }}>
-      <Button usage="tertiary" text="button"/>
+    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="tertiary" text="Tertiary"/>) } }}>
+      <Button usage="tertiary" text="Tertiary"/>
   </Story>
   <Story story={stories.buttonCSS3} />
 </Canvas>
 
-<hr className="sp--top" />
+---
 
-### Quaternary Button
-**Usage:** For the third action on a page.
+### Quaternary Buttons
 
-**Style:**
-Appears as a link.
+- **Usage:** For fourth-level actions or actions.
+- **Style:** Appears as a link.
 
 <Canvas>
   <Story
     name="button-quaternary"
-    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="quaternary" text="button" />) } }}>
-      <Button usage="quaternary" text="button" />
+    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="quaternary" text="Quaternary" />) } }}>
+      <Button usage="quaternary" text="Quaternary" />
   </Story>
   <Story story={stories.buttonCSS4} />
 </Canvas>
 
-### Disabled Button
-**Usage:** A disabled button is unusable and un-clickable. The disabled attribute can be set to keep a user from clicking on the button until some other condition has been met.
+---
+
+### 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`.
 
-**Style:**
-Box shadow on default buttons are used to accentuate the actions. For disabled buttons, box shadow is removed and opacity for the button is set to 0.5 for a muted look and no hover or focus state is provided.
 
 <Canvas>
   <Story
     name="button-primary--disabled"
-    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="" text="button" disabled/>) } }}>
-      <Button usage="" text="button" disabled/>
+    parameters={{ docs: { transformSource: () => renderReactMarkup(<Button usage="" text="Disabled" disabled/>) } }}>
+      <Button usage="" text="Disabled" disabled/>
   </Story>
   <Story
     name="button-secondary--disabled"
-    parameters={{ docs: { transformSource: (src) => renderReactMarkup(<Button usage="secondary" text="button" disabled/>) } }}>
-      <Button usage="secondary" text="button" disabled/>
+    parameters={{ docs: { transformSource: (src) => renderReactMarkup(<Button usage="secondary" text="Disabled" disabled/>) } }}>
+      <Button usage="secondary" text="Disabled" disabled/>
   </Story>
   <Story
     name="button-tertiary--disabled"
-    parameters={{ docs: { transformSource: (src) => renderReactMarkup(<Button usage="tertiary" text="button" disabled/>) } }}>
-      <Button usage="tertiary" text="button" disabled/>
+    parameters={{ docs: { transformSource: (src) => renderReactMarkup(<Button usage="tertiary" text="Disabled" disabled/>) } }}>
+      <Button usage="tertiary" text="Disabled" disabled/>
   </Story>
   <Story
     name="button-quaternary--disabled"
-    parameters={{ docs: { transformSource: (src) => renderReactMarkup(<Button usage="quaternary" text="button" disabled/>) } }}>
-      <Button usage="quaternary" text="button" disabled/>
+    parameters={{ docs: { transformSource: (src) => renderReactMarkup(<Button usage="quaternary" text="Disabled" disabled/>) } }}>
+      <Button usage="quaternary" text="Disabled" disabled/>
   </Story>
   <Story story={stories.buttonCSSDisabled} />
 </Canvas>
 
+---
+
 ### Accessibility & Best Practices
-* Avoid using `<div>` or `<img>` tags to create buttons. Screen readers don't automatically know either is a usable button.
-* Buttons should display a visible focus state when users tab to them.
-* The label text and the background have a color contrast to meet the WCAG guideline.
-* `<button>` has built-in keyboard accessibility — it can be tabbed between, and activated using Return/Enter.
-* When an icon or any image is included in `<button>`;
-  1. if the icon or image is NOT decorative, make sure they have text alternative presentation.
-  2. if it is decorative \(= use them supplementary\) with text for its label, do not add any text alternative to it.  Use `aria-hidden="true"`, empty alt attribute `alt=""`. Do not use `title` and other aria attributes to make the icon or image recognizable to assistive technologies.
-* When styling links to look like buttons, remember that screen readers handle links slightly differently than they do buttons. Pressing the Space key triggers a button, but pressing the Enter key triggers a link.
-* Avoid using `<div>` or `<img>` tags to create buttons. Screen readers don't automatically know either is a usable button.
-* Buttons should display a visible focus state when users tab to them.
-* The label text and the background have a color contrast to meet the WCAG guideline.
-* `<button>` has built-in keyboard accessibility — it can be tabbed between, and activated using Return/Enter.
-* When an icon or any image is included in `<button>`;
-  1. if the icon or image is NOT decorative, make sure they have text alternative presentation.
-  2. if it is decorative \(= use them supplementary\) with text for its label, do not add any text alternative to it.  Use `aria-hidden="true"`, empty alt attribute `alt=""`. Do not use `title` and other aria attributes to make the icon or image recognizable to assistive technologies.
-* When styling links to look like buttons, remember that screen readers handle links slightly differently than they do buttons. Pressing the Space key triggers a button, but pressing the Enter key triggers a link.
+
+- **Always** use `<button>` or `<a>` tags,** never** `<div>` or `<img>` tags so they are recognizable to screen readers.
+- **Always** Make sure text and background colors have sufficient contrast to meet WCAG guidelines.
+- **Never** disable or hide the browser focus state so focussed elements always have a visual affordance.
+- When using icons in buttons:
+  1. **Never** use an icon alone without text and always provide text for the icon itself, unlesss the icon is purely decorative.
+  2. If it is decorative, use `aria-hidden="true"`, with an empty alt attribute `alt=""`, and do not use `title` or other aria attributes.
+- When styling links as buttons, remember the keyboard handles links and buttons differently. The **Space** key triggers a button, but the **Enter** key triggers a link. Your UI help text should reflect that.

packages/core/stories/elements/Heading/Heading.stories.js

@@ -4,11 +4,12 @@ import ColoredHeading from '@massds/mayflower-react/dist/ColoredHeading';
 import CompHeading from '@massds/mayflower-react/dist/CompHeading';
 import SidebarHeading from '@massds/mayflower-react/dist/SidebarHeading';
 import { attachHTML } from '../../util/renderCode';
+import { attachCSS } from '../../util/renderCode';
 
 const { STORYBOOK_CDN_PATH } = process.env;
 
 const coloredHeading = (
-  <>
+  <section>
     <ColoredHeading
       color="blue"
       level="2"
@@ -21,16 +22,15 @@ const coloredHeading = (
       text="Colored Heading (Primary Alt)"
     />
     <ColoredHeading
-      color=""
+      color="gray"
       level="2"
       text="Colored Heading (Gray)"
     />
-  </>
-
+</section>
 )
 
 const compHeading = (
-  <>
+  <section>
     <CompHeading
       centered={false}
       color=""
@@ -58,7 +58,7 @@ const compHeading = (
       title="Comp Heading (Gray | H5)"
       titleContext=""
     />
-  </>
+</section>
 )
 
 

packages/core/stories/elements/Heading/Heading.stories.mdx

@@ -21,49 +21,47 @@ import {
 
 Headings are used as the titles of each major section of a page in the interface.
 
-<div className="sb-block">
+<div className="sb-block reset-vspace">
   { Object.keys(headings).map((key, keyIndex) => (
       (key !== "Body text") &&
       (<Heading level={headings[key]} key={`element.key.${keyIndex}`} text={key} />)
     )
   )}
 </div>
 
-<br />
+Numbered headings create a hierarchy in your pages so users can scan them easily, but they are also used by search engines and screen readers to navigate your content. The `<h1>` is most important with usually only one per page followed by `<h2>` through `<h6>` in decreasing size and importance. In mayflower—as in most design systems—headings of the same level are often styled differently based on their context. For example an `<h2>` inside `.ma__header` has a different size and font weight than an `<h2>` inside `.ma__section-links`, but within any given context the relative sizes are consistent.
 
-## Overview
-These elements represent headings for their sections.These elements have a rank given by the number in their name. The `<h1>` element is said to have the highest rank, the `<h6>` element has the lowest rank, and two elements with the same name have equal rank.
-Navigating through the `<h1>` and `<h2>` elements allows the user to understand the overall purpose of a page and how its content is structured. The `<h3>` through `<h6>` elements provide a quick understanding of the details in each section.
-
-<br />
-
-## Variations
-<br />
+---
 
 ### Colored Heading Variations
+
 Should be used as a navigational heading, high up on the page. If a page heading H1 exists, should use a lower heading level than the page heading, usually as H2. Color is for styling purposes with no semantic differences.
 
 <Canvas>
   <Story story={stories.headingColored} />
 </Canvas>
 
-<br />
+---
 
 ### Component Heading Variations
-Should be used to to separate content within a big section. If used under Colored Heading, should use a lower heading level than the colored heading, usually as H3 or lower. When nesting Color Headings, use colors as an indicator of the hierarchy in this order: Primary Alt > Highlight > Gray.
+
+Should be used to to separate content within a big section. If used under Colored Heading, should use a lower heading level than the colored heading, usually as an `<h3>` or lower. When nesting Color Headings, use colors as an indicator of the hierarchy in this order: Primary Alt > Highlight > Gray.
 
 <Canvas>
   <Story story={stories.headingComp} />
 </Canvas>
 
-<br />
+---
 
 ### List Heading Variations
+
 Should be used as a heading of a list either full width or in a 50/50 split the main content well.
+
 <Canvas>
   <Story story={stories.headingSidebar} />
 </Canvas>
 
-## Accessibility & Best Practices
-Headings should not be used to convey style items
-Headings must be hierarchical and properly nested (all h2’s within an h1 etc) so as to maintain proper navigability for low or non-sighted users
+## Accessibility Best-practices
+
+- Headings should not be used to convey style items.
+- Headings must be hierarchical and properly nested (all h2’s within an h1 etc) so as to maintain proper navigability for low or non-sighted users