{ props.children }
diff --git a/demo/views/common/sub-page-navigation/sub-page-navigation.scss b/demo/views/common/sub-page-navigation/sub-page-navigation.scss
index 8e5125f2e6..c17678ced9 100644
--- a/demo/views/common/sub-page-navigation/sub-page-navigation.scss
+++ b/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;
}
}
}
diff --git a/demo/views/pages/component/component.js b/demo/views/pages/component/component.js
index 5a2dcfc1f2..23eb04a65f 100644
--- a/demo/views/pages/component/component.js
+++ b/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) }
);
}
+ renderRelatedComponentsNotes = (definition) => {
+ let relatedComponentsNotes = definition.get('relatedComponentsNotes');
+
+ if (relatedComponentsNotes) {
+ return (
+
+
+
+
+
+ );
+ }
+ }
+
renderDesignerNotes = (definition) => {
let designerNotes = definition.get('designerNotes');
if (designerNotes) {
return (
-
+
+
+
);
} else {
diff --git a/demo/views/pages/document/document.js b/demo/views/pages/document/document.js
index 7dae62b433..2a24c86e4f 100644
--- a/demo/views/pages/document/document.js
+++ b/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 (
-
- { content }
+
+
+ { content }
-
- { spinner }
-
-
+
+ { spinner }
+
+ Content!
",
diff --git a/src/components/multi-action-button/definition.js b/src/components/multi-action-button/definition.js
index f6e5f20b94..f482f6db20 100644
--- a/src/components/multi-action-button/definition.js
+++ b/src/components/multi-action-button/definition.js
@@ -4,6 +4,20 @@ import Definition from './../../../demo/utils/definition';
import buttonDefinition from './../button/definition';
let definition = new Definition('multi-action-button', MultiActionButton, {
+ description: `Related buttons of equal importance that are shown on hover.`,
+ designerNotes: `
+* Offers related actions to the user, but without taking up valuable space by showing them separately.
+* But, users may not always discover them, and could miss out.
+* Useful to show about 5 options or less.
+* Only use this component for commands that are related (e.g. Export PDF, Export CSV).
+* Don’t use this component if one option is more generic or important than the others.
+* Carbon has a Transparent configuration, with subtle visual style, which could be useful to present less important or infrequently used options to the user, without calling attention to them.
+ `,
+ relatedComponentsNotes: `
+* Performing a single action? [Try Button](/components/button).
+* Range of buttons where one is more important? [Try Split Button](/components/split-button).
+* Choosing one option from a highly visible range? [Try Button Toggle](/components/button-toggle).
+ `,
propOptions: {
as: OptionsHelper.themesBinary,
align: OptionsHelper.alignBinary
diff --git a/src/components/navigation-bar/definition.js b/src/components/navigation-bar/definition.js
index 52e3c2bdd2..8c2e015d53 100644
--- a/src/components/navigation-bar/definition.js
+++ b/src/components/navigation-bar/definition.js
@@ -3,6 +3,16 @@ import OptionsHelper from '../../utils/helpers/options-helper';
import Definition from './../../../demo/utils/definition';
let definition = new Definition('navigation-bar', NavigationBar, {
+ description: `Provides a container for your app's primary and secondary navigation.`,
+ designerNotes: `
+* Provides a container for [Menu](/components/menu) - together providing your app's primary and secondary navigation.
+* Everything can be contained within an [App Wrapper](/components/app-wrapper).
+ `,
+ relatedComponentsNotes: `
+* Need an overall container? [Try App Wrapper](/components/app-wrapper).
+* Navigating the hierarchy of the app? [Try Menu](/components/menu).
+* Laying out a page in columns? [Try Row](/components/row).
+ `,
propOptions: {
as: OptionsHelper.themesBinary,
},
diff --git a/src/components/number/definition.js b/src/components/number/definition.js
index 9d72a48b40..09a5c8108d 100644
--- a/src/components/number/definition.js
+++ b/src/components/number/definition.js
@@ -2,6 +2,14 @@ import NumberInput from './';
import Definition from './../../../demo/utils/definition';
let definition = new Definition('number-input', NumberInput, {
+ description: `Captures a whole number (not a decimal or currency value).`,
+ designerNotes: `
+* Where it’s clear a field only accepts numerals, you could disable entry of other characters. But, remember than for some regions, phone numbers and postcodes might contain dashes, and remember to cater for a minus sign if necessary.
+ `,
+ relatedComponentsNotes: `
+* Entering a number including a decimal point? [Try Decimal](/components/decimal).
+* Entering numbers, symbols, and letters, or handling various formats? [Try Textbox](/components/textbox).
+ `,
type: 'form'
});
diff --git a/src/components/pager/definition.js b/src/components/pager/definition.js
index a06638d107..6e264718e4 100644
--- a/src/components/pager/definition.js
+++ b/src/components/pager/definition.js
@@ -4,6 +4,15 @@ import OptionsHelper from 'utils/helpers/options-helper';
import ComponentActions from './../../../demo/actions/component';
let definition = new Definition('pager', Pager, {
+ description: `Steps through a series of pages within a table.`,
+ designerNotes: `
+* Useful to handle larger tables of data - clicking the forward or back arrows will step the user sequentially through the data loaded into the table.
+* The 'Show Page Size Selection' configuration shows 10, 25, or 50 records on each page.
+ `,
+ relatedComponentsNotes: `
+* Table of relational data? [Try Table](/components/table).
+* Table with Ajax? [Try Table](/components/table-ajax).
+ `,
type: 'form',
hiddenProps: ['currentPage', 'pageSizeSelectionOptions'],
propOptions: {
diff --git a/src/components/pill/definition.js b/src/components/pill/definition.js
index 8093034ddd..8f6e4aa5d2 100644
--- a/src/components/pill/definition.js
+++ b/src/components/pill/definition.js
@@ -3,6 +3,12 @@ import OptionsHelper from './../../utils/helpers/options-helper';
import Definition from './../../../demo/utils/definition';
let definition = new Definition('pill', Pill, {
+ description: `A visual indicator which helps the user visually scan for something in common.`,
+ designerNotes: `
+* An eye catching visual indicator used to help a user visually scan and identify items with something in common from a wider list.
+* A range of colours and visual styles is available.
+* Pills could work particularly well in Tables, for example, to distinguish which invoices are overdue in a long list, or which subscriptions a client has, or to indicate that a feature has ‘beta’ status.
+ `,
type: 'misc',
propOptions: {
as: OptionsHelper.colors
diff --git a/src/components/pod/definition.js b/src/components/pod/definition.js
index f4f1d2bef8..d344648b4b 100644
--- a/src/components/pod/definition.js
+++ b/src/components/pod/definition.js
@@ -3,6 +3,22 @@ import OptionsHelper from 'utils/helpers/options-helper';
import Definition from './../../../demo/utils/definition';
let definition = new Definition('pod', Pod, {
+ description: `A set of content that’s grouped together visually.`,
+ designerNotes: `
+* Presents content grouped visually together. This can be text, or other components. A good example is a ‘tile’ showing contact information for an individual.
+* 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.
+* The On Edit property shows a standard edit icon, which can be used to show a fieldset. You can choose whether this icon appears inside or outside the pod, and whether it appears only on hover. You can also choose whether clicking only the icon triggers the On Edit property, or clicking anywhere on the pod.
+* Choose from various visual options, including padding, borders, and primary, secondary, or tertiary appearance.
+* Set the pod to flex to the width of its content, or take up the full width of its container.
+ `,
+ relatedComponentsNotes: `
+* Editing a number of closely related inputs? [Try Fieldset](/components/fieldset).
+* Filling in a broad series of inputs? [Try Form](/components/form).
+* Using Fieldset and Pod components together? [Try Show/Edit Pod](/components/pod).
+* Creating a new entity that is usually presented in a pod? [Try Create](/components/create).
+ `,
type: 'form',
toggleFunctions: ['onEdit'],
propRequires: {
diff --git a/src/components/portrait/definition.js b/src/components/portrait/definition.js
index 9e5ad6616b..69ce27d5d5 100644
--- a/src/components/portrait/definition.js
+++ b/src/components/portrait/definition.js
@@ -3,6 +3,15 @@ import Definition from './../../../demo/utils/definition';
import OptionsHelper from 'utils/helpers/options-helper';
let definition = new Definition('portrait', Portrait, {
+ description: `Represents a person with their initials or an avatar.`,
+ designerNotes: `
+* Useful to represent a person, user, or organisation.
+* Use initials rather than an avatar if you prefer.
+* Works with [Gravatar](http://en.gravatar.com/) as a source of avatars.
+ `,
+ relatedComponentsNotes: `
+* Combining Portrait with some text? [Try Profile](/components/profile).
+ `,
propOptions: {
size: OptionsHelper.sizesFull,
shape: OptionsHelper.shapesVaried
diff --git a/src/components/profile/definition.js b/src/components/profile/definition.js
index 93f3e7418f..0032e04ace 100644
--- a/src/components/profile/definition.js
+++ b/src/components/profile/definition.js
@@ -3,6 +3,17 @@ import Definition from './../../../demo/utils/definition';
import OptionsHelper from 'utils/helpers/options-helper';
let definition = new Definition('profile', Profile, {
+ description: `Represents a person with their initials or an avatar, and some text.`,
+ designerNotes: `
+* Combines the [Portrait](/components/portrait) and [Detail](/components/detail) components in a single configuration.
+* Useful to represent a person, user, or organisation.
+* Use initials rather than an avatar if you prefer.
+* Works with [Gravatar](http://en.gravatar.com/) as a source of avatars.
+ `,
+ relatedComponentsNotes: `
+* Initials or avatar without text? [Try Portrait](/components/portrait).
+* Text without initials or avatar? [Try Detail](/components/detail).
+ `,
propValues: {
name: "Andrew Tait",
email: "andrew.tait@sage.com"
diff --git a/src/components/radio-button/definition.js b/src/components/radio-button/definition.js
index 066bb8d428..d33dc8e0e6 100644
--- a/src/components/radio-button/definition.js
+++ b/src/components/radio-button/definition.js
@@ -2,6 +2,17 @@ import RadioButton from './';
import Definition from './../../../demo/utils/definition';
let definition = new Definition('radio-button', RadioButton, {
+ description: `Selects one option from a longer list.`,
+ designerNotes: `
+* 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.
+* Useful to show less than about 10 options.
+* Disabled or read-only radio buttons might be difficult for a user to distinguish visually, so try to avoid this.
+ `,
+ relatedComponentsNotes: `
+* Choosing one option from a very long list? [Try Dropdown](/components/dropdown).
+* Choosing more than one option? [Try Checkbox](/components/checkbox).
+* Choosing one option from a highly visible small range? [Try Button Toggle](/components/button-toggle).
+ `,
type: 'form',
numberOfExamples: 2,
propTypes: {
diff --git a/src/components/rainbow/definition.js b/src/components/rainbow/definition.js
index 6eb2680b9e..523273febd 100644
--- a/src/components/rainbow/definition.js
+++ b/src/components/rainbow/definition.js
@@ -2,6 +2,11 @@ import Rainbow from './';
import Definition from './../../../demo/utils/definition';
let definition = new Definition('rainbow', Rainbow, {
+ description: `Simple information visualised in a chart.`,
+ designerNotes: `
+* Helps the user visualise some data in a chart - it works best to show a relative proportion, a little like how you might use a pie chart.
+* Specify the source data, and the colours to use. Check out the Carbon Colours in the Style section.
+ `,
hiddenProps: ['config', 'data'],
js: `function getData() {
return Immutable.List([{
diff --git a/src/components/row/definition.js b/src/components/row/definition.js
index 3ad1926b4c..6de8268c7f 100644
--- a/src/components/row/definition.js
+++ b/src/components/row/definition.js
@@ -3,6 +3,16 @@ import OptionsHelper from 'utils/helpers/options-helper';
import Definition from './../../../demo/utils/definition';
let columnDefinition = new Definition('child', {}, {
+ description: `Sets up a basic column-based UI layout.`,
+ designerNotes: `
+* Useful to organise the UI of a page into a simple column-based layout.
+* Configure the number of columns, the margin between them, and any separators.
+ `,
+ relatedComponentsNotes: `
+* Need an overall container? [Try App Wrapper](/components/app-wrapper).
+* Need a container for your primary navigation? [Try Navigation Bar](/components/navigation-bar).
+* Need a layout with controls and guidance text? [Try Settings Row](/components/settings-row).
+ `,
props: ['columnOffset', 'columnSpan', 'columnAlign', 'columnClasses'],
propTypes: {
columnOffset: "String",
diff --git a/src/components/settings-row/definition.js b/src/components/settings-row/definition.js
index f8fd15be7c..ddc4a6fc2b 100644
--- a/src/components/settings-row/definition.js
+++ b/src/components/settings-row/definition.js
@@ -2,6 +2,16 @@ import SettingsRow from './';
import Definition from './../../../demo/utils/definition';
let definition = new Definition('settings-row', SettingsRow, {
+ description: `Sets up a column-based UI layout with explanatory text and UI controls.`,
+ designerNotes: `
+* Useful to create a series of rows with a heading, explanatory text, and UI controls in each row.
+* A good example is a settings page, or step-by-step wizard.
+ `,
+ relatedComponentsNotes: `
+* Need an overall container? [Try App Wrapper](/components/app-wrapper).
+* Need a container for your primary navigation? [Try Navigation Bar](/components/navigation-bar).
+* Laying out a page in columns? [Try Row](/components/row).
+ `,
propTypes: {
children: "Node",
description: "String",
diff --git a/src/components/show-edit-pod/definition.js b/src/components/show-edit-pod/definition.js
index 7716009611..40c5488f0e 100644
--- a/src/components/show-edit-pod/definition.js
+++ b/src/components/show-edit-pod/definition.js
@@ -5,6 +5,26 @@ import formDefinition from './../form/definition';
import { assign } from 'lodash';
let definition = new Definition('show-edit-pod', ShowEditPod, {
+ description: `Presents and edits a set of content that’s grouped together visually (in one pre-configured component).`,
+ designerNotes: `
+* Nest any Carbon input into this component.
+* Configure Pod and Fieldset components to work together, or choose this pre-configured Show/Edit Pod component:
+* The 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.
+* Choose whether the editable state has a disabled or enabled Save button, a Cancel button, or a Delete button, and their alignment.
+* Choose from various visual options, including borders, and primary, secondary, or tertiary appearance.
+* Set the pod to flex to the width of its content, or take up the full width of its container.
+* 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.
+ `,
+ 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).
+* Creating a new entity that is usually presented in a pod? [Try Create](/components/create).
+ `,
hiddenProps: ['editing', 'validateOnMount', 'transitionName'],
toggleFunctions: ['onDelete'],
propOptions: assign({}, formDefinition.propOptions, {
diff --git a/src/components/sidebar/definition.js b/src/components/sidebar/definition.js
index fe3128d45d..178fa84f7b 100644
--- a/src/components/sidebar/definition.js
+++ b/src/components/sidebar/definition.js
@@ -4,6 +4,17 @@ import Definition from './../../../demo/utils/definition';
import sidebarHeaderDefinition from './sidebar-header/definition';
let definition = new Definition('sidebar', Sidebar, {
+ description: `A sidebar overlaid at the right or left of a page.`,
+ designerNotes: `
+* Useful to perform an action in context without navigating the user to a separate page.
+* Useful if the user might need to refer back to the page behind the sidebar. For example, the user could select from a list of clients on the page, with detailed information on the client loading in the sidebar.
+* Several pre-set widths are available, and the height is always 100%. It’s best to avoid sidebars that are taller than the user’s viewport height, as a scroll would hide some information. 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 sidebar, but don’t select this option if the user needs to refer back to the underlying page.
+ `,
+ relatedComponentsNotes: `
+* Simple task in context? [Try Dialog](/components/dialog).
+* Complex task that needs more space? [Try Dialog Full Screen](/components/dialog-full-screen).
+ `,
associatedDefinitions: [sidebarHeaderDefinition],
propOptions: {
position: OptionsHelper.alignBinary,
diff --git a/src/components/simple-color-picker/definition.js b/src/components/simple-color-picker/definition.js
index f8c3d3cd92..58eda2969c 100644
--- a/src/components/simple-color-picker/definition.js
+++ b/src/components/simple-color-picker/definition.js
@@ -4,6 +4,13 @@ import Definition from './../../../demo/utils/definition';
import ComponentActions from './../../../demo/actions/component';
let definition = new Definition('simple-color-picker', SimpleColorPicker, {
+ description: `A small number of pre-set colour options to select from.`,
+ designerNotes: `
+* Choose from a small palette of pre-set colours, with indication of a currently selected colour.
+ `,
+ relatedComponentsNotes: `
+* [Colors](/style/colors).
+ `,
hiddenProps: ['availableColors'],
propTypes: {
availableColors: "Array",
diff --git a/src/components/spinner/definition.js b/src/components/spinner/definition.js
index 2ef4bde37a..0a9758d84a 100644
--- a/src/components/spinner/definition.js
+++ b/src/components/spinner/definition.js
@@ -3,6 +3,13 @@ import OptionsHelper from './../../utils/helpers/options-helper';
import Definition from './../../../demo/utils/definition';
let definition = new Definition('spinner', Spinner, {
+ description: `Represents an activity in progress.`,
+ designerNotes: `
+* Various colours and sizes are available - the colours match the states for Messages, Toasts, and other components.
+* Created with HTML and CSS rather than an animated graphic, which allows for easier customisation.
+* If the spinner is likely to appear for a long time, consider placing some dynamic messaging on-screen to reassure the user that something is in progress, and they shouldn’t re-load the page manually.
+* Carbon doesn’t feature a progress bar, as it’s often difficult to accurately calculate when many processes will complete, and many are relatively fast.
+ `,
type: 'misc',
propOptions: {
as: OptionsHelper.colors,
diff --git a/src/components/split-button/definition.js b/src/components/split-button/definition.js
index aa17fed80e..20bf4b6573 100644
--- a/src/components/split-button/definition.js
+++ b/src/components/split-button/definition.js
@@ -4,6 +4,19 @@ import Definition from './../../../demo/utils/definition';
import buttonDefinition from './../button/definition';
let definition = new Definition('split-button', SplitButton, {
+ description: `Related buttons that are shown on hover where one option is more important than the others.`,
+ designerNotes: `
+* Offers one more important action to the user, with some related actions also quickly accessible, but without taking up valuable space by showing them all separately.
+* But, users may not always discover the related items, and could miss out.
+* Useful to show about 5 options or less.
+* Only use this component for buttons that are very closely related (e.g. Save, Save and Email, Save and Print, Save and New).
+* Only use this component if one option is more generic or important than the others.
+ `,
+ relatedComponentsNotes: `
+* Taking a single positive or negative action? [Try Button](/components/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,
},
diff --git a/src/components/table-ajax/definition.js b/src/components/table-ajax/definition.js
index 53032fa9e9..04670c463c 100644
--- a/src/components/table-ajax/definition.js
+++ b/src/components/table-ajax/definition.js
@@ -7,6 +7,11 @@ import tableHeaderDefinition from './../table/table-header/definition';
import tableSubheaderDefinition from './../table/table-subheader/definition';
let definition = new Definition('table-ajax', TableAjax, {
+ description: `Ajax control: A table of relational data to view or interact with.`,
+ designerNotes: `
+* This control is the same as [Table](/components/table), but uses Ajax.
+* Ajax loads data from a specified source as needed, rather than data in the page markup.
+ `,
associatedDefinitions: [
tableRowDefinition, tableCellDefinition, tableHeaderDefinition, tableSubheaderDefinition
],
diff --git a/src/components/table/definition.js b/src/components/table/definition.js
index 2194a797a6..3720d5bb09 100644
--- a/src/components/table/definition.js
+++ b/src/components/table/definition.js
@@ -15,6 +15,16 @@ setTimeout(() => {
}, 1000);
let definition = new Definition('table', Table, {
+ description: `A table of relational data to view or interact with.`,
+ designerNotes: `
+* Shows relational data to the user.
+* The content of rows and columns can be plain or styled text, Icons, or even inputs. Achieve this by nesting components inside a Table component.
+* Don’t add too many columns for the user’s available viewport width. Aiming for a screen width of 1366 pixels is a good target, but also consider how your table may look for tablet or mobile devices. Avoid the need for horizontal scrolling, either on the page as a whole, or within a Table component.
+* To save space, you could show multiple lines of data within a cell (e.g. the constituents of an address).
+* If there is likely to be a large number of rows, you can specify how many rows to show, and whether to add a pagination control to the bottom of the table. Consider the data load on your application and infrastructure to decide this. Some applications apply this configuration as an application-wide setting.
+* The Selectable configuration places a checkbox at the start of each row, and the ability for a user to select one or more rows. This is useful to allow the user to perform single or batch actions.
+* The Highlightable configuration allows the user to click an option, and for the option to be marked visually. This could be useful if the user can select an option which then loads in a Sidebar, for example.
+`,
associatedDefinitions: [
tableRowDefinition, tableCellDefinition, tableHeaderDefinition, tableSubheaderDefinition
],
diff --git a/src/components/tabs/definition.js b/src/components/tabs/definition.js
index 17cd58d30a..86fbfa1d53 100644
--- a/src/components/tabs/definition.js
+++ b/src/components/tabs/definition.js
@@ -4,6 +4,22 @@ import OptionsHelper from '../../utils/helpers/options-helper';
import tabDefinition from './tab/definition';
let definition = new Definition('tabs', Tabs, {
+ description: `Switches between variants of a page or different tables.`,
+ designerNotes: `
+* switch between variants of a page or different tables (e.g. separate tables showing unread and read emails).
+* There are two position options:
+* __Top - shows the tabs in a line, typically above a Table - best for short lists of tabs.
+* __Left - show the tables in a column, typically to the left of a Table - best for longer lists of tabs.
+* You can also set the left or right alignment of the tabs. This configuration:
+* __Sets the text alignment for ‘Left’ tabs.
+* __Sets left or right page position for ‘Top’ tabs.
+* Only use tabs if there’s more than one, and show the content of one tab by default. Avoid multiple rows of tabs, nested tabs, or using vertical and horizontal tabs at the same time.
+ `,
+ relatedComponentsNotes: `
+* Navigating the hierarchy of the app? [Try Menu](/components/menu).
+* Positioning your primary navigation? [Try Navigation Bar](/components/navigation-bar).
+* Quickly accessing useful hyperlinks? [Try Animated Menu Button](/components/animated-menu-button).
+`,
type: 'layout',
associatedDefinitions: [tabDefinition],
propOptions: {
diff --git a/src/components/textarea/definition.js b/src/components/textarea/definition.js
index 43d7a5937e..7d8950cba6 100644
--- a/src/components/textarea/definition.js
+++ b/src/components/textarea/definition.js
@@ -2,6 +2,16 @@ import Textarea from './';
import Definition from './../../../demo/utils/definition';
let definition = new Definition('textarea', Textarea, {
+ description: `Captures more than one line of text.`,
+ designerNotes: `
+* Useful for collecting a significant amount of text (e.g. notes about clients, or a short email message).
+* Only handles plain text at this time - not markup or markdown, but it does handle line breaks.
+* If content in a textarea is read-only, remove the field border so it appears as static text.
+* Use placeholder text to give the user context or examples of what to write.
+ `,
+ relatedComponentsNotes: `
+* Just a single line of text? [Try Textbox](/components/textbox).
+`,
type: 'form',
propRequires: {
enforceCharacterLimit: 'characterLimit'
diff --git a/src/components/textbox/definition.js b/src/components/textbox/definition.js
index cec8c7b25c..634171d523 100644
--- a/src/components/textbox/definition.js
+++ b/src/components/textbox/definition.js
@@ -2,6 +2,17 @@ import Textbox from './';
import Definition from './../../../demo/utils/definition';
let definition = new Definition('textbox', Textbox, {
+ description: `Captures a single line of text.`,
+ designerNotes: `
+* Use placeholder text to give the user examples of data formats (e.g. AB123456C for a UK National Insurance number).
+* Use prefixes if your data always begins with a certain sequence (e.g. a UK VAT number usually starts with ‘GB’).
+* If content in a textbox is never editable, think about removing the field border so it appears as static text.
+* You can disable a textbox, but try to avoid this. If you need to, make it clear what the user needs to do in order to activate the textbox.
+* Use wider fields for longer data (e.g. an address line), and narrower fields for shorter data (e.g. a postcode), to give the user a clue about the data expected.
+ `,
+ relatedComponentsNotes: `
+* More than a single line of text? [Try Textarea](/components/textarea).
+`,
type: 'form'
});
diff --git a/src/components/toast/definition.js b/src/components/toast/definition.js
index 725c03eedd..96bfb6dbfc 100644
--- a/src/components/toast/definition.js
+++ b/src/components/toast/definition.js
@@ -3,6 +3,25 @@ import OptionsHelper from './../../utils/helpers/options-helper';
import Definition from './../../../demo/utils/definition';
let definition = new Definition('toast', Toast, {
+ description: `A longer, timely message that the user must dismiss, but doesn’t interrupt their activity.`,
+ designerNotes: `
+* Presents a message in a dialog at the top-right of the screen that animates in. The user can manually dismiss it, and it animates out.
+* Useful for instant notifications, or information which is time sensitive (e.g. a ‘push notification’ style). If the message isn’t time sensitive, consider the Message component.
+* The message stays on-screen until dismissed, giving the user time to interpret the message.
+* Various types are available. ‘Error’ and ‘Success’ are by far the most useful - others are present for completeness by may not be practically used very often:
+* __Error__ - tells the user about a negative outcome that has already happened. Try to focus the message text on the action the user needs to take to be successful, rather than what went wrong (e.g. ‘Payment failed, please try again’).
+* __Help__ - not frequently used.
+* __Info__ - gives context or advice to the user where there’s no risk of a negative outcome (e.g. ‘Your monthly statements are ready to review’).
+* __Maintenance__ - warns the user if a particular service or feature may go offline shortly.
+* __New__ - highlights a new feature to the user (e.g. ‘You can now send batch statements in Sage One’).
+* __Success__ - indicates that an activity was successful (e.g. ‘Your subscription upgrade was successful’).
+* __Warning__ - warns the user about a potential negative outcome that hasn’t happened yet.
+ `,
+ relatedComponentsNotes: `
+* Simple positive or negative confirmation? [Try Flash](/components/flash).
+* Longer message which stays on-screen? [Try Message](/components/message).
+* Error or warning message that interrupts activity? [Try Alert](/components/alert).
+`,
type: 'notification',
toggleFunctions: ["onDismiss"],
propOptions: {
diff --git a/src/components/tooltip/definition.js b/src/components/tooltip/definition.js
index 3b89b593ab..a748418ccb 100644
--- a/src/components/tooltip/definition.js
+++ b/src/components/tooltip/definition.js
@@ -3,6 +3,15 @@ import Definition from './../../../demo/utils/definition';
import OptionsHelper from '../../utils/helpers/options-helper';
let definition = new Definition('tooltip', Tooltip, {
+ description: `Additional information presented by hovering on a component.`,
+ designerNotes: `
+* A short paragraph of plain-text information shown to the user in context when they hover on any component. For example, to define how a particular figure is calculated, or the definition of a difficult technical term.
+ `,
+ relatedComponentsNotes: `
+* Tooltip hovering on any Carbon icon? [Try Icon](/components/icon).
+* Tooltip from a question mark icon? [Try Help](/components/help).
+* Need a visual? [View Icons](/style/icons).__
+`,
type: 'miscellaneous',
propValues: {
isVisible: true,