Update search.mdx

aries-site/src/examples/components/search/ClearSearchExample.js

@@ -0,0 +1,16 @@
+import React from 'react';
+import { TextInput } from 'grommet';
+import { Search as SearchIcon } from 'grommet-icons';
+
+export const ClearSearchExample = () => {
+  return (
+    <TextInput
+      aria-label="Search"
+      icon={<SearchIcon />}
+      placeholder="Search"
+      reverse
+      defaultValue="sample search term"
+      type="search"
+    />
+  );
+};

aries-site/src/examples/components/search/SearchExample.js

@@ -1,23 +1,14 @@
 import React from 'react';
-import styled from 'styled-components';
 import { TextInput } from 'grommet';
 import { Search as SearchIcon } from 'grommet-icons';
 
-// Inputs should always be accompanied by labels for accessibility. An icon
-// may serve as a label if 1) the icon meaning is well understood, and 2)
-// has an 'aria-labelledby' attribute. For additional detail:
-// https://www.w3.org/WAI/tutorials/forms/labels/#using-aria-labelledby
-// https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/forms/Basic_form_hints
-const StyledTextInput = styled(TextInput).attrs(() => ({
-  'aria-labelledby': 'search-icon',
-}))``;
-
 export const SearchExample = ({ ...props }) => {
   const [value, setValue] = React.useState();
 
   return (
-    <StyledTextInput
-      icon={<SearchIcon id="search-icon" />}
+    <TextInput
+      aria-label="search"
+      icon={<SearchIcon />}
       placeholder="Search"
       reverse
       value={value}

aries-site/src/examples/components/search/SearchIconPositionExample.js

@@ -1,23 +1,14 @@
 import React from 'react';
-import styled from 'styled-components';
 import { TextInput } from 'grommet';
 import { Search as SearchIcon } from 'grommet-icons';
 
-// Inputs should always be accompanied by labels for accessibility. An icon
-// may serve as a label if 1) the icon meaning is well understood, and 2)
-// has an 'aria-labelledby' attribute. For additional detail:
-// https://www.w3.org/WAI/tutorials/forms/labels/#using-aria-labelledby
-// https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/forms/Basic_form_hints
-const StyledTextInput = styled(TextInput).attrs(() => ({
-  'aria-labelledby': 'search-icon',
-}))``;
-
 export const SearchIconPositionExample = () => {
   const [value, setValue] = React.useState();
 
   return (
-    <StyledTextInput
-      icon={<SearchIcon id="search-icon" />}
+    <TextInput
+      aria-label="search"
+      icon={<SearchIcon />}
       placeholder="Search"
       value={value}
       onChange={event => setValue(event.target.value)}

aries-site/src/examples/components/search/SearchPlaceholder.js

@@ -1,26 +1,21 @@
 import React from 'react';
-import styled from 'styled-components';
 import PropTypes from 'prop-types';
 import { TextInput, Box } from 'grommet';
 import { Search as SearchIcon } from 'grommet-icons';
 
-// Inputs should always be accompanied by labels for accessibility. An icon
-// may serve as a label if 1) the icon meaning is well understood, and 2)
-// has an 'aria-labelledby' attribute. For additional detail:
-// https://www.w3.org/WAI/tutorials/forms/labels/#using-aria-labelledby
-// https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/forms/Basic_form_hints
-const StyledTextInput = styled(TextInput).attrs(() => ({
-  'aria-labelledby': 'search-icon-placeholder',
-}))``;
-
 export const SearchPlaceholder = ({ bestPractice = true }) => {
   const [value, setValue] = React.useState();
 
   return (
     <Box width="medium">
-      <StyledTextInput
-        icon={<SearchIcon id="search-icon-placeholder" color="placeholder" />}
-        placeholder={bestPractice ? 'Search' : 'Search users...'}
+      <TextInput
+        aria-label="search"
+        icon={<SearchIcon />}
+        placeholder={
+          bestPractice
+            ? 'Search'
+            : 'Search first name, last name, role, location, or status'
+        }
         reverse
         value={value}
         onChange={event => setValue(event.target.value)}

aries-site/src/examples/components/search/SearchSimpleExample.js

@@ -1,24 +1,15 @@
 import React from 'react';
-import styled from 'styled-components';
 import { TextInput, Box } from 'grommet';
 import { Search as SearchIcon } from 'grommet-icons';
 
-// Inputs should always be accompanied by labels for accessibility. An icon
-// may serve as a label if 1) the icon meaning is well understood, and 2)
-// has an 'aria-labelledby' attribute. For additional detail:
-// https://www.w3.org/WAI/tutorials/forms/labels/#using-aria-labelledby
-// https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/forms/Basic_form_hints
-const StyledTextInput = styled(TextInput).attrs(() => ({
-  'aria-labelledby': 'search-icon',
-}))``;
-
 export const SearchSimpleExample = () => {
   const [value, setValue] = React.useState();
 
   return (
     <Box background="background-contrast" round="xsmall" width="medium">
-      <StyledTextInput
-        icon={<SearchIcon id="search-icon" color="placeholder" />}
+      <TextInput
+        aria-label="search"
+        icon={<SearchIcon />}
         placeholder="Search"
         plain
         reverse

aries-site/src/examples/components/search/SearchSuggestionsExample.js

@@ -1,17 +1,7 @@
 import React from 'react';
-import styled from 'styled-components';
 import { TextInput } from 'grommet';
 import { Search as SearchIcon } from 'grommet-icons';
 
-// Inputs should always be accompanied by labels for accessibility. An icon
-// may serve as a label if 1) the icon meaning is well understood, and 2)
-// has an 'aria-labelledby' attribute. For additional detail:
-// https://www.w3.org/WAI/tutorials/forms/labels/#using-aria-labelledby
-// https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/forms/Basic_form_hints
-const StyledTextInput = styled(TextInput).attrs(() => ({
-  'aria-labelledby': 'search-icon',
-}))``;
-
 //
 const searchSuggestions = [
   'hpe pointnext',
@@ -85,8 +75,9 @@ export const SearchSuggestionsExample = () => {
   };
 
   return (
-    <StyledTextInput
-      icon={<SearchIcon id="search-icon" />}
+    <TextInput
+      aria-label="search"
+      icon={<SearchIcon />}
       placeholder="Search"
       reverse
       suggestions={suggestions}

aries-site/src/examples/components/search/index.js

@@ -1,4 +1,5 @@
 export * from './SearchExample';
+export * from './ClearSearchExample';
 export * from './SearchIconPositionExample';
 export * from './SearchPlaceholder';
 export * from './SearchSimpleExample';

aries-site/src/pages/components/search.mdx

@@ -1,5 +1,6 @@
 import { BestPracticeGroup, Example } from '../../layouts';
 import {
+  ClearSearchExample,
   SearchExample,
   SearchIconPositionExample,
   SearchPlaceholder,
@@ -27,14 +28,14 @@ Many search best practices extend "behind the scenes," such as how query strings
 
 ### Placeholder
 
-Placeholder text should only contain the text "Search".
+Placeholder text should be brief and to the point.
 
 <BestPracticeGroup>
   <Example
     height="small"
     bestPractice={{
       type: 'do',
-      message: 'Search placeholder only contains the text "Search".',
+      message: 'Make the placeholder text concise.',
     }}
   >
     <SearchPlaceholder />
@@ -43,7 +44,7 @@ Placeholder text should only contain the text "Search".
     height="small"
     bestPractice={{
       type: 'dont',
-      message: `Don’t use specific attributes or descriptors in the search placeholder.`,
+      message: `Avoid lengthly placeholder text that overflows.`,
     }}
   >
     <SearchPlaceholder bestPractice={false} />
@@ -64,14 +65,42 @@ Placeholder text should only contain the text "Search".
 
 ### Accessibility
 
-Search inputs should be accessible. Ensure users have the ability to return results using their keyboard as well as clicking a button.
+Search inputs should be accessible. Ensure users have the ability to return results using their keyboard or by clicking a button.
 
-Inputs should always be accompanied by labels for accessibility. An icon may serve as a label if:
+All search inputs should specify `type="search"`.
 
-1. The icon meaning is well understood.
-2. Has an 'aria-labelledby' attribute.
+Use an `aria-label` in addition to a placeholder unless a visual label is provided.
 
-For additional detail, see [ARIA form hints](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/forms/Basic_form_hints) and ['aria-labelledby'](https://www.w3.org/WAI/tutorials/forms/labels/#using-aria-labelledby).
+For additional detail, see [ARIA form hints](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/forms/Basic_form_hints).
+
+## Search icon
+
+### Placement
+
+The search icon may be placed either to the right or left of the input field. Icon position is controlled via the [reverse](#icon-position) property.
+
+Place the icon in the position that most helps people to scan the page and identify the search field. Working as a visual aid, the intention should be for the search icon to be seen first and the placeholder text second. When deciding where to place the icon, consider where the search bar is located and how the user might be scanning the page (for example, in an F shape pattern from left to right).
+
+### Interactivity
+
+The search icon is not interactive. The search may be submitted either "onChange" as the user types, "onEnter", or in some cases by clicking on an accompanying button.
+
+## Clear search control
+
+When an input has `type="search"`, many browsers will insert a native "clear" control inside the input that allows the user to clear the entire search string.
+
+The styling of this "clear" control is controlled by each browser, so it may differ visually from HPE brand colors and icons.
+
+Click into the search input to see the "clear" control.
+
+<Example
+  code="https://raw.githubusercontent.com/grommet/hpe-design-system/master/aries-site/src/examples/components/search/ClearSearchExample.js"
+  docs="https://v2.grommet.io/textinput?theme=hpe#props"
+  width="medium"
+  height="auto"
+>
+  <ClearSearchExample />
+</Example>
 
 ## Variants
 
@@ -107,7 +136,7 @@ Use simple search when its input field is desired to blend with its surrounding
 
 ### Icon position
 
-The search icon may be placed either to the right or left of the input field. Icon position is controlled via the [reverse](https://v2.grommet.io/textinput?theme=hpe#reverse) property.
+Icon position is controlled via the [reverse](https://v2.grommet.io/textinput?theme=hpe#reverse) property.
 
 <Example
   code="https://raw.githubusercontent.com/grommet/hpe-design-system/master/aries-site/src/examples/components/search/SearchIconPositionExample.js"