[DST-510]: Revise-checkbox-page (#4108)

* Adding appearance demo

* adding anatomy section

* Adding anatomy image

* Adding usage section

* Adding more description

* Adding long lists section

* Revising examples

* Adding related section

* fix

* Enhancce exmaple

* Delete example title

* resolve changes

* resolving comments

* Resolve comments

* Resolving comments

* Resolving comments

* Add changeset

* resolve comments

* Remove unwatned comments

* Resolve comments

.changeset/silly-bottles-sniff.md

@@ -0,0 +1,5 @@
+---
+'@marigold/docs': patch
+---
+
+docs[DST-512]: Revise `<Checkbox>` Page

docs/content/components/form/checkbox/checkbox-appearance.demo.tsx

@@ -0,0 +1,10 @@
+import { CheckboxGroup, CheckboxGroupProps } from '@marigold/components';
+import { Checkbox } from '@marigold/components';
+
+export default (props: CheckboxGroupProps) => (
+  <CheckboxGroup {...props}>
+    <Checkbox value="ham">Ham</Checkbox>
+    <Checkbox value="cucumber">Cucumber</Checkbox>
+    <Checkbox value="onions">Onions</Checkbox>
+  </CheckboxGroup>
+);

docs/content/components/form/checkbox/checkbox-group.demo.tsx

@@ -6,18 +6,18 @@ export default () => {
   return (
     <>
       <CheckboxGroup
-        label="Choose your toppings:"
+        label="Choose your event activities:"
         onChange={setSelected}
-        description="Just click on the options"
+        description="Select the activities you'd like to participate in"
       >
-        <Checkbox value="ham">🐖 Ham</Checkbox>
-        <Checkbox value="beef" disabled>
-          🐄 Beef (out of stock)
+        <Checkbox value="concerts">🎸 Concerts</Checkbox>
+        <Checkbox value="meetups">🤝 Meetups</Checkbox>
+        <Checkbox value="tours" disabled>
+          🚌 Guided Tours
         </Checkbox>
-        <Checkbox value="tuna">🐟 Tuna</Checkbox>
-        <Checkbox value="tomatos">🍅 Tomatos</Checkbox>
-        <Checkbox value="onions">🧅 Onions</Checkbox>
-        <Checkbox value="pineapple">🍍 Pineapple</Checkbox>
+        <Checkbox value="dining">🍽️ Dining Experiences</Checkbox>
+        <Checkbox value="exhibitions">🖼️ Art Exhibitions</Checkbox>
+        <Checkbox value="sports">⚽ Sports Events</Checkbox>
       </CheckboxGroup>
       <hr />
       <pre>Selected values: {selected.join(', ')}</pre>

docs/content/components/form/checkbox/checkbox.mdx

@@ -1,26 +1,126 @@
 ---
 title: Checkbox
 caption: Component to select one or more options.
+badge: updated
 ---
 
-The `<Checkbox>` component allows users to select one or more options from a set of options. In order to group multiple checkboxes, use the `<CheckboxGroup>` component.
+The `<Checkbox>` component allows users to select one or more options from a set of options. In order to group multiple checkboxes, use the `<Checkbox.Group>` component.
 
-There are several props for the `<Checkbox>` and the `<CheckboxGroup>`.
+There are several props for the `<Checkbox>` and the `<Checkbox.Group>`, allowing customization of behavior, appearance, and accessibility.
 
-You don't have to click on the `<Checkbox>` itself, you can also just click on the label next to the box.
+You don't have to click on the `<Checkbox>` itself, you can also just click on the label next to the box, making it more user-friendly and accessible.The `<Checkbox>` component supports both controlled and uncontrolled states, giving you flexibility in how you manage the selection.
 
-## Import
+## Anatomy
 
-```tsx
-import { Checkbox, CheckboxGroup } from '@marigold/components';
-```
+The checkbox component is comprised of a checkbox label and a checkbox input. If there is a group of checkboxes, a group label can be added.
+
+<Image
+  src="/checkbox/checkbox-anatomy.jpg"
+  alt="Anatomy of a checkbox"
+  width={800}
+  height={550}
+  className="mx-auto block"
+/>
+
+- **Group label:** Communicates what needs to be selected below.
+
+- **Checkbox input:** A checkbox input indicating the appropriate state. By default it is unselected.
+
+- **Checkbox label:** Describes the information you want to select or unselect.
 
 ## Appearance
 
+<AppearanceDemo component={title} />
+
 <AppearanceTable component={title} />
 
+## Usage
+
+Checkboxes are used when there are multiple items to select in a list. Each checkbox works independently from other checkboxes in the list, therefore checking an additional box does not affect any other selections. Users can select zero, one, or any number of items. Checkboxes are commonly used in forms where users need to make multiple selections from a set of options.
+
+Particularly checkboxes are useful in settings where users need to make non-exclusive selections. They provide a clear and straightforward way to toggle options on or off. When used in a group, they can help simplify complex decision-making processes. Additionally, checkboxes can be combined with other form elements.
+
+### Choosing and managing options
+
+If a user can select only one option from a list, radio buttons should be used instead of checkboxes because checkboxes allow the user to select multiple items in a set whereas radio buttons allow the user to select only one option.
+
+If you have number of options is moderate to large, typically more than 10-15 options use checkbox, but if the options is too large , then use [Multiple Selection Pattern](/patterns/multiple-selection/link) because it minimizes the screen clutter by displaying only the selected items, keeping the interface clean and user-friendly.
+
+<GuidelineTiles>
+  <Dont>
+    <Dont.Figure>
+      <Image
+        width={700}
+        height={700}
+        unoptimized
+        src="/checkbox/checkbox-dont-select.jpg"
+        alt="Don't use checkboxes when only one item can be selected."
+      />
+    </Dont.Figure>
+    <Dont.Description>
+      Don't use checkboxes when only one item can be selected.
+    </Dont.Description>
+  </Dont>
+  <Dont>
+    <Dont.Figure>
+      <Image
+        width={700}
+        height={700}
+        unoptimized
+        src="/checkbox/checkbox-dont-long-options.jpg"
+        alt="Don't use checkbox with long list of options."
+      />
+    </Dont.Figure>
+    <Dont.Description>
+      Don't use checkbox with long list of options.
+    </Dont.Description>
+  </Dont>
+</GuidelineTiles>
+
+### Overflow content
+
+We recommend checkbox labels being fewer than three words because shorter checkbox labels improve readability and reduce cognitive load, making it easier for users to quickly understand and select options. This enhances the overall user experience, especially on small screens.
+
+If you are tight on space, consider rewording the label. Do not truncate checkbox label text with an ellipsis.
+
+Long labels may wrap to a second line, and this is preferable to truncation.
+Text should wrap beneath the checkbox.
+
+<GuidelineTiles>
+  <Do>
+    <Do.Figure>
+      <Image
+        width={400}
+        height={400}
+        unoptimized
+        src="/checkbox/checkbox-do-multipleline.jpg"
+        alt="If the label is long, wrap to a second line."
+      />
+    </Do.Figure>
+    <Do.Description>
+      If the label is long, wrap to a second line.
+    </Do.Description>
+  </Do>
+  <Dont>
+    <Dont.Figure>
+      <Image
+        width={400}
+        height={400}
+        unoptimized
+        src="/checkbox/checkbox-dont-multipleline.jpg"
+        alt="Do not truncate checkbox label text with an ellipsis."
+      />
+    </Dont.Figure>
+    <Dont.Description>
+      Do not truncate checkbox label text with an ellipsis.
+    </Dont.Description>
+  </Dont>
+</GuidelineTiles>
+
 ## Props
 
+<StorybookHintMessage component={title} />
+
 ### Checkbox
 
 <PropsTable component={title} />
@@ -45,6 +145,69 @@ Use indeterminate state when it represents both selected and not selected values
 
 ### Group checkboxes
 
-In this example the `<Checkbox>` are wrapped within the `<CheckboxGroup>`. You see that the `onChange` property is also set. It has also a helptext within which you can set with the `description` property for the `<CheckboxGroup>`.
+In this example the `<Checkbox>` are wrapped within the `<Checkbox.Group>`. You see that the `onChange` property is also set. It has also a helptext within which you can set with the `description` property for the `<Checkbox.Group>`.
 
 <ComponentDemo file="./checkbox-group.demo.tsx" />
+
+## Alternative components
+
+Choosing the right alternative to checkbox is important for providing an optimal user experience, especially when different types of selections are required. Depending on the nature of the choices and the desired interaction, the following components can serve as an alternative to checkboxes:
+
+<ul>
+  <li>
+    [SelectList](/components/collection/selectlist): shows a list of interactive
+    elements with which you can select several elements at the same time.
+  </li>
+  <li>
+    [TagGroup](/components/collection/tag): It is a type of multiple selection
+    interface that allows users to select multiple options and displays the
+    selected options as tags.
+  </li>
+</ul>
+
+## Related
+
+<TeaserList
+  items={[
+    {
+      title: 'Building forms',
+      href: '../../patterns/building-forms',
+      caption: 'Learn how to build forms.',
+      icon: (
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width={24}
+          height={24}
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth={2}
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <path d="M12 3H5a2 2 0 00-2 2v14a2 2 0 002 2h14a2 2 0 002-2v-7" />
+          <path d="M18.375 2.625a2.121 2.121 0 113 3L12 15l-4 1 1-4z" />
+        </svg>
+      ),
+    },
+    {
+      title: 'Multiple Selection',
+      href: '/patterns/multiple-selection',
+      caption: 'represents different ways and guideline for muliple selection.',
+      icon: (
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          viewBox="0 0 24 24"
+          fill="currentColor"
+          className="size-6"
+        >
+          <path
+            fillRule="evenodd"
+            d="M2.625 6.75a1.125 1.125 0 1 1 2.25 0 1.125 1.125 0 0 1-2.25 0Zm4.875 0A.75.75 0 0 1 8.25 6h12a.75.75 0 0 1 0 1.5h-12a.75.75 0 0 1-.75-.75ZM2.625 12a1.125 1.125 0 1 1 2.25 0 1.125 1.125 0 0 1-2.25 0ZM7.5 12a.75.75 0 0 1 .75-.75h12a.75.75 0 0 1 0 1.5h-12A.75.75 0 0 1 7.5 12Zm-4.875 5.25a1.125 1.125 0 1 1 2.25 0 1.125 1.125 0 0 1-2.25 0Zm4.875 0a.75.75 0 0 1 .75-.75h12a.75.75 0 0 1 0 1.5h-12a.75.75 0 0 1-.75-.75Z"
+            clipRule="evenodd"
+          />
+        </svg>
+      ),
+    },
+  ]}
+/>