DST-628: revise search field page

docs/content/components/form/search-field/search-field.mdx

@@ -4,17 +4,15 @@ caption: Component which allows user to enter and clear a search query.
 badge: updated
 ---
 
-The `<SearchField>` component is a versatile UI element that enables users to search for specific information within a given context or data set. It offers a user-friendly input field specifically designed for search queries, often accompanied by a search icon or button to initiate the search action.
-
-`<SearchField>` consists of an input element, a label, and an optional clear button. `<SearchField>` automatically manages the labeling and relationships between the elements, and handles keyboard events. Users can press the Escape key to clear the `<SearchField>`, or the Enter key to trigger the `onSubmit` event.
+The `<SearchField>` component offers a user-friendly input field specifically designed for search queries, often accompanied by a search icon or button to initiate the search action.
 
 ## Anatomy
 
-A table is composed of a container element that organizes data into rows and columns. Each cell within the table can hold either plain text or focusable elements. If the table allows multiple row selection, the first column of each row include a checkbox for selecting that row and the first column header will contain a "select all" checkbox.
+A `<SearchField>` consists of an input element, a label, and an optional clear button.
 
 <Image
-  src="/table/table-anatomy.jpg"
-  alt="Anatomy of table"
+  src="/search-field/search-field-anatomy.jpg"
+  alt="Anatomy of search field"
   width={800}
   height={550}
   className="mx-auto block"
@@ -28,42 +26,194 @@ A table is composed of a container element that organizes data into rows and col
 
 ## Usage
 
+The `<SearchField>` component is a versatile UI element that enables users to search for specific information within a given context or data set.
+
+### Placement
+
+The placement of a search field plays a critical role in its effectiveness and usability. A well-positioned search field ensures users can easily find and use it, enhancing their overall experience on a website or application.
+
+<GuidelineTiles>
+  <Do>
+    <Do.Figure>
+      <Image
+        width={700}
+        height={700}
+        unoptimized
+        src="/search-field/search-field-do-placement.jpg"
+        alt="Do: Position the search field prominently"
+      />
+    </Do.Figure>
+    <Do.Description>Position the search field prominently.</Do.Description>
+  </Do>
+  <Dont>
+    <Dont.Figure>
+      <Image
+        width={700}
+        height={700}
+        unoptimized
+        src="/search-field/search-field-dont-placement.jpg"
+        alt="Don’t place the search field in an obscure location"
+      />
+    </Dont.Figure>
+    <Dont.Description>
+      Don’t place the search field in an obscure location.
+    </Dont.Description>
+  </Dont>
+</GuidelineTiles>
+
+### Label
+
+In general label should be short and precise about what is expected from the user. Avoid unnecessary instructional
+verbs (doing words) in your labels and hints because it’s already implied by the input field.
+Avoid placeholder text in most cases, as there’s no need for it (more about it in the next section).
+
+<GuidelineTiles>
+  <Do>
+    <Do.Figure>
+      <Image
+        width={700}
+        height={700}
+        unoptimized
+        src="/search-field/search-field-do-label.jpg"
+        alt="Do: Use short labels"
+      />
+    </Do.Figure>
+    <Do.Description>Use short labels.</Do.Description>
+  </Do>
+  <Dont>
+    <Dont.Figure>
+      <Image
+        width={700}
+        height={700}
+        unoptimized
+        src="/search-field/search-field-dont-label.jpg"
+        alt="Don’t use unnecessary instructional verbs"
+      />
+    </Dont.Figure>
+    <Dont.Description>
+      Don’t use unnecessary instructional verbs.
+    </Dont.Description>
+  </Dont>
+</GuidelineTiles>
+
+### Placeholder
+
+Placeholder text is a short hint displayed inside an input field before
+a user enters a value. To save space, placeholder text is often used instead of a label, as shown in the first
+example.
+This is problematic for the following reasons:
+
+- Placeholder text disappears once a person starts filling in an input field, causing some to forget what the
+  field
+  was for
+- Some might miss or skip fields with placeholder text, as it can look like the field has already been pre-filled.
+- Placeholder text colour contrast is almost always inaccessible, as it’s very light by design. This means many
+  will struggle to read the label.
+
+<GuidelineTiles>
+  <Do>
+    <Do.Figure>
+      <Image
+        width={700}
+        height={700}
+        unoptimized
+        src="/search-field/search-field-do-placeholder.jpg"
+        alt="Do: Provide a short description of what the user will be able to search for."
+      />
+    </Do.Figure>
+    <Do.Description>
+      Provide a short description of what the user will be able to search for.
+    </Do.Description>
+  </Do>
+  <Dont>
+    <Dont.Figure>
+      <Image
+        width={700}
+        height={700}
+        unoptimized
+        src="/search-field/search-field-dont-placeholder.jpg"
+        alt="Don’t use placeholder alone"
+      />
+    </Dont.Figure>
+    <Dont.Description>Don’t use placeholder alone.</Dont.Description>
+  </Dont>
+</GuidelineTiles>
+
 ## Props
 
 <StorybookHintMessage component={title} />
 
 <PropsTable component={title} />
 
-## Alternative components
-
 ## Related
 
-## Examples
-
-### Simple Search Field
-
-This is how a basic `<SearchField>` looks like.
-
-<ComponentDemo file="./search-field-basic.demo.tsx" />
-
-### Disabled Search Field
-
-If you want to implement a disabled `<SearchField>` you have to add the `disabled` property.
-
-<ComponentDemo file="./search-field-disabled.demo.tsx" />
-
-### Required Search Field
-
-The `required` property adds an required icon to the label.
-
-<ComponentDemo file="./search-field-req.demo.tsx" />
-
-### Text Field with an Error
-
-The example shows how to set the `error` and `errorMessage` properties. If you fill in the field correctly, it will disappear automatically.
-
-<ComponentDemo file="./search-field-error.demo.tsx" />
-
-### Text Field with readOnly
-
-<ComponentDemo file="./search-field-readoOnly.demo.tsx" />
+{' '}
+<TeaserList
+  items={[
+    {
+      title: 'Building Forms',
+      href: '../../patterns/building-forms',
+      caption:
+        'This page should introduce you on how to build forms with Marigold.',
+      icon: (
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          fill="none"
+          viewBox="0 0 24 24"
+          strokeWidth="1.5"
+          stroke="currentColor"
+          className="size-6"
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="M3.75 6A2.25 2.25 0 0 1 6 3.75h2.25A2.25 2.25 0 0 1 10.5 6v2.25a2.25 2.25 0 0 1-2.25 2.25H6a2.25 2.25 0 0 1-2.25-2.25V6ZM3.75 15.75A2.25 2.25 0 0 1 6 13.5h2.25a2.25 2.25 0 0 1 2.25 2.25V18a2.25 2.25 0 0 1-2.25 2.25H6A2.25 2.25 0 0 1 3.75 18v-2.25ZM13.5 6a2.25 2.25 0 0 1 2.25-2.25H18A2.25 2.25 0 0 1 20.25 6v2.25A2.25 2.25 0 0 1 18 10.5h-2.25a2.25 2.25 0 0 1-2.25-2.25V6ZM13.5 15.75a2.25 2.25 0 0 1 2.25-2.25H18a2.25 2.25 0 0 1 2.25 2.25V18A2.25 2.25 0 0 1 18 20.25h-2.25A2.25 2.25 0 0 1 13.5 18v-2.25Z"
+          />
+        </svg>
+      ),
+    },
+    {
+      title: 'Forms',
+      href: '../../recipes/form-recipes',
+      caption: 'Here you can find some recipes for some form components.',
+      icon: (
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          fill="none"
+          viewBox="0 0 24 24"
+          strokeWidth="1.5"
+          stroke="currentColor"
+          className="size-6"
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="M3 8.25V18a2.25 2.25 0 0 0 2.25 2.25h13.5A2.25 2.25 0 0 0 21 18V8.25m-18 0V6a2.25 2.25 0 0 1 2.25-2.25h13.5A2.25 2.25 0 0 1 21 6v2.25m-18 0h18M5.25 6h.008v.008H5.25V6ZM7.5 6h.008v.008H7.5V6Zm2.25 0h.008v.008H9.75V6Z"
+          />
+        </svg>
+      ),
+    },
+    {
+      title: 'Form Fields',
+      href: '../../foundations/form-fields',
+      caption:
+        'Here you can find a comprehensive guide for working with form fields.',
+      icon: (
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          fill="none"
+          viewBox="0 0 24 24"
+          strokeWidth="1.5"
+          stroke="currentColor"
+          className="size-6"
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="M3 8.25V18a2.25 2.25 0 0 0 2.25 2.25h13.5A2.25 2.25 0 0 0 21 18V8.25m-18 0V6a2.25 2.25 0 0 1 2.25-2.25h13.5A2.25 2.25 0 0 1 21 6v2.25m-18 0h18M5.25 6h.008v.008H5.25V6ZM7.5 6h.008v.008H7.5V6Zm2.25 0h.008v.008H9.75V6Z"
+          />
+        </svg>
+      ),
+    },
+  ]}
+/>

docs/content/components/form/search-field/search-field-disabled.demo.tsx → docs/content/components/form/search-field/searchfield-appearance.demo.tsx

@@ -1,3 +1,3 @@
 import { SearchField } from '@marigold/components/src/SearchField';
 
-export default () => <SearchField label="search" disabled />;
+export default () => <SearchField label="search" />;

packages/components/src/SearchField/SearchField.stories.tsx

@@ -84,6 +84,7 @@ export const Controlled: Story = {
           onChange={setValue}
           required
           label="search field"
+          placeholder="Type something"
         />
         <pre>
           <strong>Input Value:</strong>

packages/components/src/SearchField/SearchField.tsx

@@ -21,11 +21,6 @@ type RemovedProps =
 export interface SearchFieldProps
   extends Omit<RAC.SearchFieldProps, RemovedProps>,
     Pick<FieldBaseProps<'label'>, 'label' | 'description' | 'errorMessage'> {
-  /**
-   * Icon element to display in the search field.
-   */
-  icon?: ReactElement;
-
   /**
    * Action element to display in the search field.
    */