Added designer notes content in markdown to most components.

demo/i18n/en.js

@@ -29,7 +29,7 @@ I18n.translations['en'] = {
 
     get_started: {
       ready: 'Ready to Get Started?',
-      checkout: 'Checkout the Github repository or download Carbon'
+      checkout: 'Check out the Github repository or download Carbon'
     },
 
     learn_more: {
@@ -47,7 +47,7 @@ I18n.translations['en'] = {
 
     page_header_large: {
       heading1: 'Carbon is a library of React components for building great web applications.',
-      heading2: 'Carbon is open source. It’s hosted, developed, and maintained on Github.',
+      heading2: 'Carbon is Open Source. It’s hosted, developed, and maintained on Github.',
       version: 'Currently: v1.0.0.beta'
     },
 
@@ -73,7 +73,7 @@ I18n.translations['en'] = {
       },
       brush: {
         heading: 'Designed for UX',
-        text: 'Meet your users’ needs with a simple, elegant, delightful experience'
+        text: 'Meet your users’ needs with a simple, elegant, delightful experience.'
       },
       hammer: {
         heading: 'Build smarter',
@@ -91,7 +91,8 @@ I18n.translations['en'] = {
   },
 
   component_page: {
-    design_notes: 'Designer Notes'
+    design_notes: 'Designer Notes',
+    related_components: 'Related Components'
   },
 
   errors: {
@@ -105,11 +106,11 @@ I18n.translations['en'] = {
 
   style: {
     colors: {
-      subtitle: 'Enables a consistent styling across your application'
+      subtitle: 'A vibrant palette for a consistent visual style across your app.'
     },
 
     icons: {
-      subtitle: 'Free open source icons to use in your project',
+      subtitle: 'Free icons to use in your project.',
     },
   }
 };

demo/views/common/information-styles/information-styles.js

@@ -0,0 +1,13 @@
+import React from 'react';
+
+/**
+ * Wraps children in styling wrapper
+ *
+ * @param {object} props
+ * @return {InformationStyled}
+ */
+export default props => (
+  <div className='demo-information-styles'>
+    { props.children }
+  </div>
+);

demo/views/common/information-styles/information-styles.scss

@@ -0,0 +1,18 @@
+@import 'colors';
+
+.demo-information-styles {
+  a {
+    color: $blue;
+    font-weight: bold;
+    text-decoration: none;
+
+    &:hover {
+      color: $blue-dark;
+      text-decoration: underline;
+    }
+  }
+
+  li {
+    line-height: 20px;
+  }
+}

demo/views/common/information-styles/package.json

@@ -0,0 +1,4 @@
+{
+  "main": "./information-styles.js",
+  "style": "./information-styles.scss"
+}

demo/views/common/page-content-area/page-content-area.js

@@ -11,7 +11,7 @@ import SimpleHeading from './../../../components/simple-heading';
  * @return {PageContentArea}
  */
 export default props => (
-  <section className='demo-page-content-area'>
+  <section className={ classNames(props.className, 'demo-page-content-area') }>
     <SimpleHeading title={ props.title } link={ props.link } />
     <div className='demo-page-content-area__content'>
       { props.children }

demo/views/common/sub-page-navigation/sub-page-navigation.scss

@@ -27,7 +27,7 @@
   .demo-arrow-link {
     align-items: stretch;
     &__icon {
-      margin-top: 1em;
+      padding-top: 20px;
     }
   }
 }

demo/views/pages/component/component.js

@@ -5,6 +5,7 @@ import I18n from 'i18n-js';
 
 // App Components
 import PageContentArea from '../../common/page-content-area';
+import InformationStyles from '../../common/information-styles';
 import ComponentPreview from './component-preview';
 import ComponentAPI from './component-api';
 
@@ -25,17 +26,34 @@ class Component extends React.Component {
 
         { this.renderAPIs(definition) }
         { this.renderDesignerNotes(definition) }
+        { this.renderRelatedComponentsNotes(definition) }
       </div>
     );
   }
 
+  renderRelatedComponentsNotes = (definition) => {
+    let relatedComponentsNotes = definition.get('relatedComponentsNotes');
+
+    if (relatedComponentsNotes) {
+      return (
+        <PageContentArea title={ I18n.t('component_page.related_components') }>
+          <InformationStyles>
+            <div dangerouslySetInnerHTML={{ __html: marked(relatedComponentsNotes) }} />
+          </InformationStyles>
+        </PageContentArea>
+      );
+    }
+  }
+
   renderDesignerNotes = (definition) => {
     let designerNotes = definition.get('designerNotes');
 
     if (designerNotes) {
       return (
         <PageContentArea title={ I18n.t('component_page.design_notes') }>
-          <div dangerouslySetInnerHTML={{ __html: marked(designerNotes) }} />
+          <InformationStyles>
+            <div dangerouslySetInnerHTML={{ __html: marked(designerNotes) }} />
+          </InformationStyles>
         </PageContentArea>
       );
     } else {

demo/views/pages/document/document.js

@@ -4,6 +4,7 @@ import ReactCSSTransitionGroup from 'react-addons-css-transition-group';
 import DocumentStore from './../../../stores/document';
 import DocumentActions from './../../../actions/document';
 import marked from 'marked';
+import InformationStyles from '../../common/information-styles';
 import Spinner from 'components/spinner';
 import Row from 'components/row';
 import Highlight from 'react-highlight';
@@ -53,20 +54,22 @@ class Document extends React.Component {
     }
 
     return (
-      <div className="demo-document">
-        { content }
+      <InformationStyles>
+        <div className="demo-document">
+          { content }
 
-        <ReactCSSTransitionGroup
-          className={ this.loadingClasses() }
-          transitionName="demo-document__loading"
-          transitionAppear={ true }
-          transitionAppearTimeout={ 300 }
-          transitionEnterTimeout={ 300 }
-          transitionLeaveTimeout={ 0 }
-        >
-          { spinner }
-        </ReactCSSTransitionGroup>
-      </div>
+          <ReactCSSTransitionGroup
+            className={ this.loadingClasses() }
+            transitionName="demo-document__loading"
+            transitionAppear={ true }
+            transitionAppearTimeout={ 300 }
+            transitionEnterTimeout={ 300 }
+            transitionLeaveTimeout={ 0 }
+          >
+            { spinner }
+          </ReactCSSTransitionGroup>
+        </div>
+      </InformationStyles>
     );
   }
 }

demo/views/pages/document/document.scss

@@ -14,17 +14,6 @@ $doc-animation: opacity 100ms 200ms ease-in;
     }
   }
 
-  a {
-    color: $blue;
-    font-weight: bold;
-    text-decoration: none;
-
-    &:hover {
-      color: $blue-dark;
-      text-decoration: underline;
-    }
-  }
-
   code {
     background-color: $grey-dark-blue-15;
     border-radius: 4px;

src/components/alert/definition.js

@@ -3,6 +3,20 @@ import OptionsHelper from '../../utils/helpers/options-helper';
 import Definition from './../../../demo/utils/definition';
 
 let definition = new Definition('alert', Alert, {
+  description: `An important message that interrupts user activity, but can be dismissed.`,
+  designerNotes: `
+* Useful if a message is so important you’d like to prevent any other activity until the user resolves it.
+* If the message isn’t so important, or you want to avoid disrupting the user’s activity, consider showing a static Message component in the underlying screen.
+* Include a Message component within the Alert component, use plain text, or apply a standard Carbon Error or Warning icon.
+* This component has the same options and properties as the Dialog component.
+  `,
+  relatedComponentsNotes: `
+* Simple positive or negative confirmation? [Try Flash](/components/flash).
+* Longer message which stays on-screen? [Try Message](/components/message).
+* Longer, time sensitive message that must be dismissed? [Try Toast](/components/toast).
+* Confirm or cancel an action I’ve initiated? [Try Confirm](/components/confirm).
+* Simple task in context? [Try Dialog](/components/dialog).
+  `,
   propOptions: {
     size: OptionsHelper.sizesFull
   },

src/components/animated-menu-button/definition.js

@@ -3,6 +3,18 @@ import OptionsHelper from '../../utils/helpers/options-helper';
 import Definition from './../../../demo/utils/definition';
 
 let definition = new Definition('animated-menu-button', AnimatedMenuButton, {
+  description: `Quick access to a number of especially useful hyperlinks.`,
+  designerNotes: `
+* A quick way for users to access a number of useful hyperlinks in context.
+* This pattern tends to be used as a quick way of allowing the user to create a range of new items (e.g. New Sales Invoice, New Quote, New Payment).
+* Try not to mix navigation options with action options.
+* Try not to create any duplication between the Menu component, and this component.
+  `,
+  relatedComponentsNotes: `
+* Choosing between variants of the same page, or filtering content? [Try Tabs](/components/tabs).
+* Positioning your primary navigation? [Try Navigation Bar](/components/navigation-bar).
+* Navigating the hierarchy of the app? [Try Menu](/components/menu).
+  `,
   hiddenProps: ["children"],
   propOptions: {
     direction: OptionsHelper.alignBinary,

src/components/app-wrapper/definition.js

@@ -3,6 +3,12 @@ import OptionsHelper from '../../utils/helpers/options-helper';
 import Definition from './../../../demo/utils/definition';
 
 let definition = new Definition('app-wrapper', AppWrapper, {
+  description: `Wraps all components inside an overall container.`,
+  relatedComponentsNotes: `
+* Need a container for your primary navigation? [Try Navigation Bar](/components/navigation-bar).
+* Navigating the hierarchy of the app? [Try Menu](/components/menu).
+* Laying out a page in columns? [Try Row](/components/row).
+ `,
   propValues: {
     children: "This component will wrap its children within the width constraints of your application."
   },

src/components/button-toggle/definition.js

@@ -3,6 +3,20 @@ import Definition from './../../../demo/utils/definition';
 import OptionsHelper from 'utils/helpers/options-helper';
 
 let definition = new Definition('button-toggle', ButtonToggle, {
+  description: `Selects one option from a small number of highly visible options.`,
+  designerNotes: `
+* Useful if the user has a choice between a small number of options, that you’d like to be highly visible (e.g. choosing between three or fewer subscription packages, with short names).
+* To make the meaning of an option clearer, you can add an icon to it. Just name one of the Carbon icons.
+  `,
+  relatedComponentsNotes: `
+* Performing a single action? [Try Button](/components/button).
+* Range of buttons where one is more important? [Try Split Button](/components/split-button).
+* Range of buttons of the same importance? [Try Multi Action Button](/components/multi-action-button).
+* Choosing one option from a longer list? [Try Radio Button](/components/radio-button).
+* Choosing one option from a very long list? [Try Dropdown](/components/dropdown).
+* Choosing more than one option? [Try Checkbox](/components/checkbox).
+* Need a visual? [Try Icons](/style/icons).
+ `,
   type: 'action',
   numberOfExamples: 3,
   propOptions: {

src/components/button/definition.js

@@ -3,6 +3,20 @@ import OptionsHelper from '../../utils/helpers/options-helper';
 import Definition from './../../../demo/utils/definition';
 
 let definition = new Definition('button', Button, {
+  description: `Performs an action.`,
+  designerNotes: `
+* Avoid using buttons for navigation (taking the user somewhere else) - use them for performing an action or command.
+* Use a Primary configuration for positive actions that are the main goal for the user (e.g. Save, Submit, Continue).
+* Avoid placing Secondary actions on a form if you can.
+* If an action is particularly destructive (e.g. Delete or Clear), consider using Red configuration. It might be a good idea to show a confirmation dialog, or the ability to undo it too.
+* Try to create a single path to completion by aligning your action with your inputs.
+* You can disable a Button, but try to avoid this. If you need to, make it clear what the user needs to do in order to activate the Button. A good case for disabling an action is to prevent a form being submitted twice (e.g. on a payment page).
+  `,
+  relatedComponentsNotes: `
+* Range of buttons where one is more important? [Try Split Button](/components/split-button).
+* Range of buttons all of the same importance? [Try Multi Action Button](/components/multi-action-button).
+* Choosing one option from a highly visible range? [Try Button Toggle](/components/button-toggle).
+ `,
   propOptions: {
     as: OptionsHelper.themesBinary,
     theme: OptionsHelper.buttonColors,

src/components/carousel/definition.js

@@ -4,6 +4,11 @@ import Definition from './../../../demo/utils/definition';
 import slideDefinition from './slide/definition';
 
 let definition = new Definition('carousel', Carousel, {
+  description: `Steps through a series of images.`,
+  designerNotes: `
+* Presents a series of images which the user can step through one-by-one, or quickly jump to a particular step.
+* Useful for showcasing a set of new features, for example.
+ `,
   associatedDefinitions: [slideDefinition],
   propTypes: {
     children: 'Node',

src/components/checkbox/definition.js

@@ -2,6 +2,18 @@ import Checkbox from './';
 import Definition from './../../../demo/utils/definition';
 
 let definition = new Definition('checkbox', Checkbox, {
+	description: `Selects more than one option.`,
+	designerNotes: `
+* Checkbox provides a way to efficiently select more than one item from a list.
+* Disabled or read-only checkboxes might be difficult for a user to distinguish visually, so try to avoid this.
+* Consider ‘smart default’ selections, based on what your user is likely to choose. But, users may well leave the defaults in place, so make sure any consequences are easy to undo, and not harmful.
+* Rather than a checkbox to accept legal terms, consider labelling a button ‘Accept Terms and Continue’ instead.
+  `,
+  relatedComponentsNotes: `
+* Choosing one option from a longer list? [Try Radio Button](/components/radio-button).
+* Choosing one option from a very long list? [Try Dropdown](/components/dropdown).
+* Choosing one option from a highly visible range? [Try Button Toggle](/components/button-toggle).
+ `,
   type: 'form',
   propTypes: {
     reverse: 'Boolean'

src/components/confirm/definition.js

@@ -3,6 +3,21 @@ import OptionsHelper from '../../utils/helpers/options-helper';
 import Definition from './../../../demo/utils/definition';
 
 let definition = new Definition('confirm', Confirm, {
+  description: `Confirms or cancels an action.`,
+  designerNotes: `
+* Shows a static message in a dialog which asks the user to confirm or cancel an action they’ve initiated.
+* Useful to confirm actions which may be difficult to undo, or potentially harmful.
+* Include a Message component within the Alert component (a warning Message component may be particularly useful for a potentially harmful choice), use plain text, or apply a standard Carbon Error or Warning icon.
+* This component has the same options and properties as the Dialog component.
+* A good example could be confirming deletion of a large number of records.
+  `,
+  relatedComponentsNotes: `
+* Simple positive or negative confirmation? [Try Flash](/components/flash).
+* Longer message which stays on-screen? [Try Message](/components/message).
+* Longer, time sensitive message that must be dismissed? [Try Toast](/components/toast).
+* Error or warning message that interrupts activity? [Try Alert](/components/alert).
+* Simple task in context? [Try Dialog](/components/dialog).
+ `,
   propOptions: {
     size: OptionsHelper.sizesFull
   },

src/components/content/definition.js

@@ -3,6 +3,16 @@ import OptionsHelper from '../../utils/helpers/options-helper';
 import Definition from './../../../demo/utils/definition';
 
 let definition = new Definition('content', Content, {
+  description: `Text content with simple styles.`,
+  designerNotes: `
+* Useful to show simple text content in a common arrangement.
+* Shows a title in bold, with plain text content children.
+* Make sure that the colour of all text has a contrast ratio of at least 4.5.1, to meet the [WCAG 2.0 AA standard](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) for text less than 19px in size. Webaim have a good online [Contrast Checker](http://webaim.org/resources/contrastchecker/).
+  `,
+  relatedComponentsNotes: `
+* Prominent text callout? [Try Detail](/components/detail).
+* Headings and sections? [Try Heading](/components/heading).
+ `,
   propValues: {
     title: "Content Component",
     children: "An example of some content."

src/components/create/definition.js

@@ -3,6 +3,16 @@ import OptionsHelper from '../../utils/helpers/options-helper';
 import Definition from './../../../demo/utils/definition';
 
 let definition = new Definition('create', Create, {
+  description: `Creates a new set of content that's grouped together.`,
+  designerNotes: `
+* Creates an item of data usually presented in a Pod or Fieldset, for example, an address.
+  `,
+  relatedComponentsNotes: `
+* Editing a number of closely related inputs? [Try Fieldset](/components/fieldset).
+* Filling in a broad series of inputs? [Try Form](/components/form).
+* Viewing content that’s grouped together visually? [Try Pod](/components/pod).
+* Using Fieldset and Pod components together? [Try Show/Edit Pod](/components/show-edit-pod).
+ `,
   hiddenProps: ["linkProps"],
   propValues: {
     children: "Resource Name"