diff --git a/CHANGELOG.md b/CHANGELOG.md
index a07d349deb..89e616d8e0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -30,6 +30,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
### Documentation
- Accessibility: improve introduction section @jurokapsiar ([#1368](https://github.com/stardust-ui/react/pull/1368))
+- Accessibility: improve accessibility descriptions for components @jurokapsiar ([#1371](https://github.com/stardust-ui/react/pull/1371))
## [v0.31.0](https://github.com/stardust-ui/react/tree/v0.31.0) (2019-05-21)
diff --git a/docs/src/components/ComponentDoc/AccessibilityDescription.tsx b/docs/src/components/ComponentDoc/AccessibilityDescription.tsx
new file mode 100644
index 0000000000..3b54ba3505
--- /dev/null
+++ b/docs/src/components/ComponentDoc/AccessibilityDescription.tsx
@@ -0,0 +1,8 @@
+import * as React from 'react'
+import * as ReactMarkdown from 'react-markdown'
+
+const AccessibilityDescription: React.FunctionComponent<{ value: string }> = ({ value }) => (
+
+)
+
+export default AccessibilityDescription
diff --git a/docs/src/components/ComponentDoc/ComponentDocAccessibility.tsx b/docs/src/components/ComponentDoc/ComponentDocAccessibility.tsx
index 970bb6e333..9eee0ea4a8 100644
--- a/docs/src/components/ComponentDoc/ComponentDocAccessibility.tsx
+++ b/docs/src/components/ComponentDoc/ComponentDocAccessibility.tsx
@@ -1,6 +1,8 @@
import * as React from 'react'
import * as _ from 'lodash'
-import { Flex, Text, Accordion } from '@stardust-ui/react'
+import { Flex, Loader, Text, Accordion } from '@stardust-ui/react'
+
+const AccessibilityDescription = React.lazy(() => import('./AccessibilityDescription'))
const behaviorMenu = require('docs/src/behaviorMenu')
@@ -19,26 +21,38 @@ const ComponentDocAccessibility = ({ info }) => {
const accessibilityDetails = (
<>
- {description && {description}}
+ {description && (
+
+ }>
+
+
+
+ )}
{behaviorName && (
-
- Default behavior:{' '}
- {behaviorName}
-
+ <>
+
+ Default behavior:{' '}
+ {behaviorName}
+
+
+
)}
{info.behaviors && (
-
- Available behaviors:{' '}
- {info.behaviors.map(behavior => (
-
-
- {behavior.displayName}
- {' '}
-
- ))}
-
+ <>
+
+ Available behaviors:{' '}
+ {info.behaviors.map(behavior => (
+
+
+ {behavior.displayName}
+ {' '}
+
+ ))}
+
+
+
)}
)
@@ -46,8 +60,13 @@ const ComponentDocAccessibility = ({ info }) => {
const accessPanels = [
{
key: 'accessibility',
- content: { content: accessibilityDetails },
- title: { content: 'Accessibility', as: 'h2' },
+ content: { content: accessibilityDetails, styles: { paddingLeft: '14px' } },
+ title: {
+ content: ,
+ as: 'span',
+ 'aria-level': '2',
+ styles: { paddingBottom: '0', paddingTop: '0' },
+ },
},
]
diff --git a/package.json b/package.json
index 08572231b4..dc715f115d 100644
--- a/package.json
+++ b/package.json
@@ -112,6 +112,7 @@
"react-dom": "^16.8.6",
"react-element-to-jsx-string": "^14.0.2",
"react-hot-loader": "^4.8.2",
+ "react-markdown": "^4.0.8",
"react-router": "^4.1.2",
"react-router-dom": "^4.1.2",
"react-source-render": "2.0.0-beta.6",
diff --git a/packages/internal-tooling/babel/index.js b/packages/internal-tooling/babel/index.js
index ab20d49530..efe4eab581 100644
--- a/packages/internal-tooling/babel/index.js
+++ b/packages/internal-tooling/babel/index.js
@@ -4,7 +4,11 @@ module.exports = {
'@babel/preset-react',
'@babel/preset-typescript',
],
- plugins: ['@babel/plugin-proposal-class-properties', '@babel/plugin-transform-runtime'],
+ plugins: [
+ '@babel/plugin-proposal-class-properties',
+ '@babel/plugin-syntax-dynamic-import',
+ '@babel/plugin-transform-runtime',
+ ],
env: {
delelopment: {
plugins: ['react-hot-loader/babel'],
diff --git a/packages/internal-tooling/package.json b/packages/internal-tooling/package.json
index f3fd26619a..f1b80ec5d7 100644
--- a/packages/internal-tooling/package.json
+++ b/packages/internal-tooling/package.json
@@ -4,6 +4,7 @@
"dependencies": {
"@babel/core": "^7.3.4",
"@babel/plugin-proposal-class-properties": "^7.3.4",
+ "@babel/plugin-syntax-dynamic-import": "^7.2.0",
"@babel/plugin-transform-runtime": "^7.3.4",
"@babel/preset-env": "^7.3.4",
"@babel/preset-react": "^7.0.0",
diff --git a/packages/react/src/components/Accordion/Accordion.tsx b/packages/react/src/components/Accordion/Accordion.tsx
index 8ee2a5f6c0..c787ea238d 100644
--- a/packages/react/src/components/Accordion/Accordion.tsx
+++ b/packages/react/src/components/Accordion/Accordion.tsx
@@ -310,7 +310,8 @@ class Accordion extends AutoControlledComponent, Acco
/**
* An accordion allows users to toggle the display of sections of content.
* @accessibility
- * Implements ARIA Accordion design pattern (keyboard navigation not yet supported).
- * Consider using Tree if you intend to wrap Lists in an Accordion.
+ * Implements [ARIA Accordion](https://www.w3.org/TR/wai-aria-practices-1.1/#accordion) design pattern (keyboard navigation not yet supported).
+ * Do use Accordion for grouping parts of the UI (multipart forms, articales...).
+ * Do use Tree component to display a hierarchical structure that allows user to select one item.
*/
export default withSafeTypeForAs(Accordion)
diff --git a/packages/react/src/components/Alert/Alert.tsx b/packages/react/src/components/Alert/Alert.tsx
index 631e19a62c..803338e675 100644
--- a/packages/react/src/components/Alert/Alert.tsx
+++ b/packages/react/src/components/Alert/Alert.tsx
@@ -137,8 +137,8 @@ class Alert extends UIComponent, AlertState> {
/**
* A Alert displays information that explains nearby content.
* @accessibility
- * Other considerations:
- * - by default, content from warning and danger variants is announced by the screen reader. To announce the content of other variants, a mechanism similar to react-aria-live can be used
- * - if Alert contains action slot, textual representation needs to be provided by using 'title', 'aria-label' or 'aria-labelledby' attributes
+ * Do use warning and danger variants to announce the alert by the screen reader.
+ * Do use other libraries (for example react-aria-live) if the content of default or success variant needs to be announced.
+ * Do add textual representation to action slot if they only contain an icon (using title, aria-label or aria-labelledby props on the slot).
*/
export default withSafeTypeForAs(Alert)
diff --git a/packages/react/src/components/Button/Button.tsx b/packages/react/src/components/Button/Button.tsx
index f12688906b..34c347cb9c 100644
--- a/packages/react/src/components/Button/Button.tsx
+++ b/packages/react/src/components/Button/Button.tsx
@@ -180,8 +180,6 @@ Button.create = createShorthandFactory({ Component: Button, mappedProp: 'content
/**
* A button indicates a possible user action.
* @accessibility
- * Other considerations:
- * - for disabled buttons, add 'disabled' attribute so that the state is properly recognized by the screen reader
- * - if button includes icon only, textual representation needs to be provided by using 'title', 'aria-label' or 'aria-labelledby' attributes
+ * Do add textual representation if the component only contains an icon (using title, aria-label or aria-labelledby props).
*/
export default withSafeTypeForAs(Button)
diff --git a/packages/react/src/components/Dialog/Dialog.tsx b/packages/react/src/components/Dialog/Dialog.tsx
index afee4df74f..7ba0400503 100644
--- a/packages/react/src/components/Dialog/Dialog.tsx
+++ b/packages/react/src/components/Dialog/Dialog.tsx
@@ -274,6 +274,8 @@ Dialog.slotClassNames = {
}
/**
- * A Dialog indicates a possible user action.
+ * A Dialog displays important information on top of a page which usually requires user's attention, confirmation or interaction.
+ * @accessibility
+ * Implements [ARIA Dialog (Modal)](https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal) design pattern.
*/
export default withSafeTypeForAs(Dialog)
diff --git a/packages/react/src/components/Dropdown/Dropdown.tsx b/packages/react/src/components/Dropdown/Dropdown.tsx
index 15f5bf9656..fa7cf63045 100644
--- a/packages/react/src/components/Dropdown/Dropdown.tsx
+++ b/packages/react/src/components/Dropdown/Dropdown.tsx
@@ -1291,6 +1291,8 @@ Dropdown.slotClassNames = {
* Dropdown allows user to select one or more values from a list of items.
* Can also be created with search capability.
* @accessibility
- * Implements ARIA collapsible Listbox design pattern, uses aria-live to announce state changes.
+ * Implements [ARIA Combo Box](https://www.w3.org/TR/wai-aria-practices-1.1/#combobox) design pattern, uses aria-live to announce state changes.
+ * Do provide getA11ySelectionMessage, getA11yStatusMessage, noResultsMessage and loadingMessage props to announce state changes correctly.
+ * Do provide aria-label to triggerButton slot for non-searchable variants if the placeholder prop is not used.
*/
export default withSafeTypeForAs(Dropdown)
diff --git a/packages/react/src/components/Embed/Embed.tsx b/packages/react/src/components/Embed/Embed.tsx
index 739ac2e957..ad7e8be152 100644
--- a/packages/react/src/components/Embed/Embed.tsx
+++ b/packages/react/src/components/Embed/Embed.tsx
@@ -177,7 +177,7 @@ class Embed extends AutoControlledComponent, EmbedState>
Embed.create = createShorthandFactory({ Component: Embed })
/**
- * A GIF is a muted segment of a video
+ * A GIF is a muted segment of a video.
* @accessibility
* If GIF should be visible to screen readers, textual representation needs to be provided in 'alt' or 'title' property.
*
diff --git a/packages/react/src/components/Form/Form.tsx b/packages/react/src/components/Form/Form.tsx
index 8be86f7dc4..3dc3f8472d 100644
--- a/packages/react/src/components/Form/Form.tsx
+++ b/packages/react/src/components/Form/Form.tsx
@@ -104,6 +104,6 @@ class Form extends UIComponent, any> {
/**
* A Form displays a set of related user input fields in a structured way.
* @accessibility
- * Label needs to be provided by using 'aria-label', or 'aria-labelledby' attributes on the