From 6293cb15e050521d71a6991434745a5055f97e92 Mon Sep 17 00:00:00 2001
From: Carl Mensah <carl@etch.co>
Date: Thu, 8 Aug 2024 15:56:33 +0100
Subject: [PATCH] docs: improve card docs

---
 .storybook/styles.css                  |  8 +++
 components/canvas/Card/About.mdx       | 70 --------------------------
 components/canvas/Card/Card.stories.ts | 60 ++++++++++++++++++----
 3 files changed, 59 insertions(+), 79 deletions(-)
 delete mode 100644 components/canvas/Card/About.mdx

diff --git a/.storybook/styles.css b/.storybook/styles.css
index ae35084..c712c20 100644
--- a/.storybook/styles.css
+++ b/.storybook/styles.css
@@ -1,3 +1,11 @@
 .docblock-argstable-body label {
   min-height: auto;
 }
+
+docs-placeholder {
+  border: dotted 1px var(--diamond-theme-border-color-hover);
+  border-radius: var(--diamond-radius-sm);
+  display: block;
+  padding: var(--diamond-spacing-lg);
+  text-align: center;
+}
diff --git a/components/canvas/Card/About.mdx b/components/canvas/Card/About.mdx
deleted file mode 100644
index 0497934..0000000
--- a/components/canvas/Card/About.mdx
+++ /dev/null
@@ -1,70 +0,0 @@
-import { Meta, Title, Primary, Controls, Stories } from '@storybook/blocks';
-import * as CardStories from './Card.stories';
-
-
-<Meta of={CardStories}/>
-
-
-## Quickstart guide
-
-The Card component is a simple wrapper, with a single slot for presenting content.
-
-```html
-<diamond-card>
-  <slot>
-</diamond-card>
-```
-
-## Interactive
-
-The interactive `diamond-card` is a regular `diamond-card` element with a wrapper as shown in the examples below. Interactive cards are keyboard focusable, and have an associated action when triggered.
-
-We have two types of interactive card, either wrap the `diamond-card` element with an `a` or an `button` tag.
-
-### Anchor
-<a href="https://etch.co" rel="noopener noreferrer" target="_blank">
-  <diamond-card border>
-      <h3>Card title</h3>
-      <p>
-          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-          eiusmod tempor incididunt ut labore et dolore magna aliqua.
-      </p>
-  </diamond-card>
-</a>
-
-```html
-<a href="https://etch.co" rel="noopener noreferrer" target="_blank">
-  <diamond-card border>
-      <h3>Card title</h3>
-      <p>
-          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-          eiusmod tempor incididunt ut labore et dolore magna aliqua.
-      </p>
-  </diamond-card>
-</a>
-```
-
-### Button
-
-<button type="button">
-  <diamond-card border>
-      <h3>Card title</h3>
-      <p>
-          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-          eiusmod tempor incididunt ut labore et dolore magna aliqua.
-      </p>
-  </diamond-card>
-</button>
-
-```html
-<button type="button">
-  <diamond-card border>
-      <h3>Card title</h3>
-      <p>
-          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-          eiusmod tempor incididunt ut labore et dolore magna aliqua.
-      </p>
-  </diamond-card>
-</button>
-```
-
diff --git a/components/canvas/Card/Card.stories.ts b/components/canvas/Card/Card.stories.ts
index 01f6ae0..6bf5530 100644
--- a/components/canvas/Card/Card.stories.ts
+++ b/components/canvas/Card/Card.stories.ts
@@ -4,7 +4,6 @@ import { html } from 'lit';
 import '../../composition/Grid/Grid';
 import '../../composition/Grid/GridItem';
 import './Card';
-import Guide from './About.mdx';
 
 export default {
   component: 'diamond-card',
@@ -31,9 +30,6 @@ export default {
         'none',
       ],
     },
-    docs: {
-      page: Guide,
-    },
   },
 };
 
@@ -47,11 +43,13 @@ export const Card: StoryObj = {
       padding="${padding}"
       class="diamond-theme-${theme}"
     >
-      <h3>Card title</h3>
-      <p>
-        Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
-        tempor incididunt ut labore et dolore magna aliqua.
-      </p>
+      <docs-placeholder>
+        <h2>Placeholder content</h2>
+        <p>
+          The slot can contain anything, the card component acts as a simple
+          wrapper with optional props for styling the card itself.
+        </p>
+      </docs-placeholder>
     </diamond-card>
   `,
 };
@@ -93,3 +91,47 @@ export const Interactive: StoryObj = {
     </diamond-grid>
   `,
 };
+
+Interactive.parameters = {
+  docs: {
+    description: {
+      story: `The card can be made interactive by wrapping the card in an anchor or button element.
+      `,
+    },
+  },
+};
+
+export const ImageCard: StoryObj = {
+  render: () => html`
+    <diamond-wrap size="sm">
+      <diamond-card border radius shadow class="diamond-theme-light">
+        <diamond-img block responsive>
+          <img
+            src="https://placehold.co/400x300"
+            alt="Placeholder"
+            width="400"
+            height="300"
+            class="diamond-spacing-bottom-md"
+          />
+        </diamond-img>
+        <h3>Card title</h3>
+        <p>
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+          eiusmod tempor incididunt ut labore et dolore magna aliqua.
+        </p>
+
+        <diamond-button variant="primary" size="sm" width="full-width">
+          <button type="button">Button</button>
+        </diamond-button>
+      </diamond-card>
+    </diamond-wrap>
+  `,
+};
+
+ImageCard.parameters = {
+  docs: {
+    description: {
+      story: `As a flexible canvas element, the card can be used for any number of layouts. For example, a simple image card.`,
+    },
+  },
+};