docs[DST-511]: revise switch component (#4110)

* DST-511: typo button page

* DST-511: revise switch component page

* Create seven-ads-kiss.md

* DST-511: revise switch component page

* DST-511: edit comments

.changeset/seven-ads-kiss.md

@@ -0,0 +1,6 @@
+---
+"@marigold/docs": patch
+"@marigold/components": patch
+---
+
+docs[DST-511]: Revise switch component.

docs/content/components/form/button/button.mdx

@@ -190,7 +190,7 @@ In general, it's best to avoid using disabled buttons. However, if they are nece
     Tooltips aren't accessible on all devices or by some assistive technologies,
     and they should never be used on non-interactive elements.
 
-    For more information see the [toolip page](/components/overlay/tooltip).
+    For more information see the [tooltip page](/components/overlay/tooltip).
 
   </SectionMessage.Content>
 </SectionMessage>

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

@@ -0,0 +1,7 @@
+import { Container, Switch, SwitchProps } from '@marigold/components';
+
+export default (props: SwitchProps) => (
+  <Container size={'small'}>
+    <Switch {...props}>Default Switch</Switch>
+  </Container>
+);

docs/content/components/form/switch/switch.mdx

@@ -1,51 +1,99 @@
 ---
 title: Switch
 caption: Component that switches between two states.
+badge: updated
 ---
 
 The `<Switch>` component allows the users to select between two states, e.g. on and off.  
 It consists of a visual selection indicator and a label.
 
 Users may click or touch a Switch to toggle the state, or use the tab key to navigate to it and the space key to toggle it.
 
-The styles are separated into some parts (container, label, thumb, track) that you can style in a custom variant.
+## Anatomy
 
-## Import
+<Image
+  src="/switch/switch-anatomy.jpg"
+  alt="Anatomy of table"
+  width={800}
+  height={550}
+  className="mx-auto block"
+/>
 
-```tsx
-import { Switch } from '@marigold/components';
-```
+The styles are separated into some parts (container, label, thumb, track) that you can style in a custom variant.
 
 ## Appearance
 
-<AppearanceTable component={title} />
-
-## Props
-
-<PropsTable component={title} />
-
-## Examples
+<AppearanceDemo component={title} />
 
-### Default
-
-In this example you can see a simple `<Switch>` component with no properties.
-
-<ComponentDemo file="./switch-basic.demo.tsx" />
-
-### Active
-
-Here you can see an already active `<Switch>`. It can be used when e.g. settings options are per default set to true.
+<AppearanceTable component={title} />
 
-<ComponentDemo file="./switch-active.demo.tsx" />
+## Usage
+
+Switches are best used to adjust settings and other standalone options. They make a binary selection, like on and off or true and false.
+
+The effects of a switch should start immediately, without needing to save.
+
+<GuidelineTiles>
+  <Do>
+    <Do.Figure>
+      <Image
+        width={700}
+        height={700}
+        unoptimized
+        src="/switch/switch-do-settings.jpg"
+        alt="Immediately activate or deactivate something"
+      />
+    </Do.Figure>
+    <Do.Description>
+      <strong>Immediately</strong> activate or deactivate something.
+    </Do.Description>
+  </Do>
+  <Dont>
+    <Dont.Figure>
+      <Image
+        width={700}
+        height={700}
+        unoptimized
+        src="/switch/switch-dont-settings.jpg"
+        alt="Don't use save actions with switches."
+      />
+    </Dont.Figure>
+    <Dont.Description>
+      Avoid using a switch to select multiple options that require people to
+      save. Switches should be immediate.
+    </Dont.Description>
+  </Dont>
+</GuidelineTiles>
+
+<Dont>
+  <Dont.Figure>
+    <Image
+      width={700}
+      height={700}
+      unoptimized
+      src="/switch/switch-dont-opposing-options.jpg"
+      alt="Avoid using switches to toggle between opposing options."
+    />
+  </Dont.Figure>
+  <Dont.Description>
+    Avoid using switches to toggle between opposing options.
+  </Dont.Description>
+</Dont>
 
-### Disabled
+## Props
 
-In this mode the user can not change the status of the `<Switch>`. It can be used e.g. if you want to disable a certain setting for some users.
+<StorybookHintMessage component={title} />
 
-<ComponentDemo file="./switch-disabled.demo.tsx" />
+<PropsTable component={title} />
 
-### Disabled (active)
+## Alternative components
 
-This mode can be used when an option is or was already active and there is a variable that does not allow the user switch to be moved from its "on" mode.
+Alternative selection controls can be used to enter decisions or declare preferences such as settings or dialogs.
 
-<ComponentDemo file="./switch-active-disabled.demo.tsx" />
+<ul>
+  <li>
+    [Checkbox](/components/form/checkbox): Select multiple related options in a
+    list.
+  </li>
+  <li>[Radio](/components/form/radio): Select a single option in a list.</li>
+</ul>

packages/components/src/Switch/Switch.tsx

@@ -14,7 +14,8 @@ type RemovedProps =
   | 'isDisabled'
   | 'isReadOnly'
   | 'isSelected'
-  | 'children';
+  | 'children'
+  | 'slot';
 
 export interface SwitchProps extends Omit<RAC.SwitchProps, RemovedProps> {
   variant?: string;