Sage · SeanArmstrong · Apr 4, 2017 · Mar 7, 2017 · Mar 10, 2017 · Mar 10, 2017
@@ -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.
+
+### Related Components
+* __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
   },

@@ -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.
+
+### Related Components
+* __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,

@@ -3,6 +3,10 @@ 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.`,
+  designerNotes: `
+* __Laying out a page in columns?__ Try Row.
+ `,
   propValues: {
     children: "This component will wrap its children within the width constraints of your application."
   },

@@ -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.
+
+### Related Components
+* __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).
+* __[Icons](/style/icons).__
+ `,
   type: 'action',
   numberOfExamples: 3,
   propOptions: {

@@ -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).
+
+### Related Components
+* __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,

@@ -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',

@@ -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.
+
+### Related Components
+* __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'

@@ -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.
+
+### Related Components
+* __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
   },

@@ -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.
+
+### Related Components
+* __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.
+ `,
   hiddenProps: ["linkProps"],
   propValues: {
     children: "Resource Name"

@@ -3,6 +3,13 @@ import OptionsHelper from '../../utils/helpers/options-helper';
 import Definition from './../../../demo/utils/definition';
 
 let definition = new Definition('date-range', DateRate, {
+  description: `Captures a start and end date.`,
+  designerNotes: `
+* Used to filter a Table of data according to a start and end date, or to set two dates which are related to each other, for example, a hotel booking.
+
+### Related Components
+* __Entering or picking a single date only?__ [Try Date Input](/components/date-input).
+ `,
   hiddenProps: ["value", "startDateProps", "endDateProps"],
   propTypes: {
     onChange: "Function",

@@ -2,6 +2,15 @@ import DateInput from './';
 import Definition from './../../../demo/utils/definition';
 
 let definition = new Definition('date-input', DateInput, {
+  description: `Captures a single calendar date.`,
+  designerNotes: `
+* If the date is likely to be close to today (e.g. an invoice due date), then a datepicker may be useful. If the date is likely to be far in the past (e.g. a date of birth), then it may be better to use separate inputs for day, month, and year.
+* Field focus automatically opens the datepicker, but a user can key in dates too, which many users find more convenient, especially in financial applications.
+* Carbon handles a range of formats, like dd/mm/yyyy, dd/mm/yy, dd/mm, or dd. Configuration can be regional, and copes with space, slash, full stop, or colon as separators.
+
+### Related Components
+* __Entering or picking a start and end date together?__ [Try Date Range](/components/date-range).
+ `,
   type: 'form',
   propTypes: {
     minDate: "String",

@@ -3,6 +3,17 @@ import Definition from './../../../demo/utils/definition';
 import OptionsHelper from './../../utils/helpers/options-helper';
 
 let definition = new Definition('decimal', Decimal, {
+  description: `Captures a number with a decimal point, or a currency value.`,
+  designerNotes: `
+* For currency values, show currency symbols outside the field rather than inserting one for the user dynamically.
+* Carbon offers a Precision configuration, so you can choose how many decimal places to show.
+* Decimals are usually right-aligned, so that the decimal places of numbers presented in rows line up for easy comparison by the user.
+* Even if the user just enters a string of numbers, consider presenting them into a format with the separators which apply in the user’s country (e.g. £12,345.67 for the UK, and €12 345,67 for France).
+* Where it’s clear a field only accepts numerals, you could disable entry of other characters - but remember to cater for a minus sign if necessary.
+
+### Related Components
+* __Entering whole numbers without a decimal point?__ [Try Number Input](/components/number-input).
+ `,
   type: 'form',
   propTypes: {
     align: "String",

@@ -2,6 +2,17 @@ import DialogFullScreen from './';
 import Definition from './../../../demo/utils/definition';
 
 let definition = new Definition('dialog-full-screen', DialogFullScreen, {
+  description: `A full-width and full-height dialog overlaid on the top of any page.`,
+  designerNotes: `
+* Useful to perform an action in context without navigating the user to a separate page.
+* Whilst a standard Dialog component’s width might constrain what you can do, the full screen dialog uses the full width and height available.
+* A good example could be importing a large volume of data, and checking for errors, in the context of an underlying Table of data.
+
+### Related Components
+* __Simple task in context?__ [Try Dialog](/components/dialog).
+* __Need to refer back to the underlying page?__ [Try Sidebar](/components/sidebar).
+
+ `,
   propValues: {
     title: 'Example Title for a DialogFullScreen',
     children: 'This is an example of a dialog full screen.',

@@ -3,6 +3,17 @@ import OptionsHelper from '../../utils/helpers/options-helper';
 import Definition from './../../../demo/utils/definition';
 
 let definition = new Definition('dialog', Dialog, {
+  description: `A dialog box overlaid on the top of any page.`,
+  designerNotes: `
+* Useful to perform an action in context without navigating the user to a separate page.
+* Several pre-set widths are available - the height of the dialog will flex to fit the content. It’s best to avoid dialogs that are taller than the user’s viewport height. Typical user viewport heights can be as little as 650 pixels.
+* Choose whether a dark tint is applied behind the dialog which helps to focus the user on the dialog.
+* A configuration shows a close icon at the top right of the Dialog. Sometimes users are more likely to click this than a traditional ‘Cancel’ button.
+
+### Related Components
+* __Complex task that needs more space?__ [Try Dialog Full Screen](/components/dialog-full-screen).
+* __Need to refer back to the underlying page?__ [Try Sidebar](/components/sidebar).
+ `,
   propOptions: {
     size: OptionsHelper.sizesFull
   },

@@ -3,6 +3,21 @@ import OptionsHelper from '../../utils/helpers/options-helper';
 import Definition from './../../../demo/utils/definition';
 
 let definition = new Definition('dropdown-filter', DropdownFilter, {
+  description: `Selects one option from a very long list, with the ability to filter and create new items.`,
+  designerNotes: `
+* The user can select an item using the mouse or keyboard, and also enter a search term to filter the list items presented - this is particularly helpful for very long lists (e.g. a list of customers or suppliers).
+* Useful to show more than about 5 options.
+* The Create configuration allows the user to add a term they enter to the list.
+* The Suggest configuration removes the menu handle, and only shows options to the user once they enter 3 characters of a search term. For example, if users need to select from a very long list of business classification terms (e.g. SIC codes), showing a menu on field focus may mean users tend to choose from the top of the list, rather than filter and select the best option. This configuration makes the component behave more like a search field.
+* Use placeholder content like ‘Please select…’ to make it clear to the user that the Dropdown is unset.
+* Consider a ‘smart default’ selection, 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.
+
+### Related Components
+* __Don’t need to filter or add new items?__ [Try Dropdown](/components/dropdown).
+* __Choosing one option from a shorter list?__ [Try Radio Button](/components/radio-button).
+* __Choosing more than one option?__ [Try Checkbox](/components/checkbox).
+* __Choosing one option from a highly visible range?__ [Try Button Toggle](/components/button-toggle).
+ `,
   hiddenProps: ['options'],
   toggleFunctions: ['create'],
   js: `function getOptions() {

@@ -3,6 +3,20 @@ import OptionsHelper from '../../utils/helpers/options-helper';
 import Definition from './../../../demo/utils/definition';
 
 let definition = new Definition('dropdown', Dropdown, {
+  description: `Selects one option from a very long list.`,
+  designerNotes: `
+* Behaves like a simple browser menu control - the user can select an item using the mouse or keyboard.
+* Useful to show more than about 5 options.
+* Use placeholder content like ‘Please select…’ to make it clear to the user that the Dropdown is unset.
+* Consider a ‘smart default’ selection, 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.
+
+### Related Components
+* __Filtering menu options to find the right one?__ [Try Dropdown Filter](/components/dropdown-filter).
+* __Adding a new option within the menu?__ [Try Dropdown Filter](/components/dropdown-filter).
+* __Choosing one option from a shorter list?__ [Try Radio Button](/components/radio-button).
+* __Choosing more than one option?__ [Try Checkbox](/components/checkbox).
+* __Choosing one option from a highly visible range?__ [Try Button Toggle](/components/button-toggle).
+ `,
   hiddenProps: ['options'],
   js: `function getOptions() {
   return ImmutableHelper.parseJSON([{

@@ -4,6 +4,24 @@ import Definition from './../../../demo/utils/definition';
 import textboxDefinition from './../textbox/definition';
 
 let definition = new Definition('fieldset', Fieldset, {
+  description: `Edits a set of closely related inputs that are grouped together.`,
+  designerNotes: `
+* You can nest any Carbon input into this component.
+* Useful for presenting a series of inputs that are closely related, within a wider Form or Pod (e.g. an address or contact details).
+* Configure Pod and Fieldset components to work together, or choose the pre-configured Show/Edit Pod component.
+* The [Show/Edit Pod](/components/show-edit-pod) component automatically presents content as a read-only Pod, until the user clicks an edit icon, which shows the same information in an editable Fieldset. 
+* But, configuring Pod and Fieldset components manually will give you more customization options, like the following.
+* Top-aligned labels (Carbon default) or inline right-aligned labels are usually fastest for users.
+* Create a single path to completion with your inputs, and between your inputs and the primary action Button.
+* Indicate mandatory, or optional fields, whichever is the minority. Think carefully before collecting optional data - don’t collect information you don’t need! Try suffixing ‘(optional)’ after your field label.
+* More guidance is available for each of the individual inputs you might place inside this component.
+
+### Related Components
+* __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).
+* __Creating a new entity that is usually presented in a pod?__ [Try Create](/components/create).
+ `,
   propTypes: {
     legend: "String"
   },