From 160488187cf2c29f4fa6cba9ec7182f006c6688a Mon Sep 17 00:00:00 2001
From: Chaz Dean <59836805+chazdean@users.noreply.github.com>
Date: Fri, 28 Oct 2022 11:45:06 -0400
Subject: [PATCH] Update `AlphaCard` docs

---
 .changeset/five-bats-attend.md                |  5 ++
 .../content/components/alpha-card.md          | 27 ++++++++---
 .../pages/examples/alpha-card-default.tsx     | 11 ++---
 .../pages/examples/alpha-card-subdued.tsx     | 18 --------
 .../alpha-card-with-rounded-corners.tsx       | 15 ++++++
 .../alpha-card-with-subdued-background.tsx    | 15 ++++++
 .../alpha-card-with-varying-padding.tsx       | 46 +++++++++++++++++++
 .../alpha-card-without-border-radius.tsx      | 28 -----------
 8 files changed, 105 insertions(+), 60 deletions(-)
 create mode 100644 .changeset/five-bats-attend.md
 delete mode 100644 polaris.shopify.com/pages/examples/alpha-card-subdued.tsx
 create mode 100644 polaris.shopify.com/pages/examples/alpha-card-with-rounded-corners.tsx
 create mode 100644 polaris.shopify.com/pages/examples/alpha-card-with-subdued-background.tsx
 create mode 100644 polaris.shopify.com/pages/examples/alpha-card-with-varying-padding.tsx
 delete mode 100644 polaris.shopify.com/pages/examples/alpha-card-without-border-radius.tsx

diff --git a/.changeset/five-bats-attend.md b/.changeset/five-bats-attend.md
new file mode 100644
index 00000000000..c2bc31dd49a
--- /dev/null
+++ b/.changeset/five-bats-attend.md
@@ -0,0 +1,5 @@
+---
+'polaris.shopify.com': patch
+---
+
+Update `AlphaCard` component docs
diff --git a/polaris.shopify.com/content/components/alpha-card.md b/polaris.shopify.com/content/components/alpha-card.md
index af10764c0da..6e58899087b 100644
--- a/polaris.shopify.com/content/components/alpha-card.md
+++ b/polaris.shopify.com/content/components/alpha-card.md
@@ -1,6 +1,6 @@
 ---
 title: Alpha card
-description: Cards are used to group similar concepts and tasks together to make Shopify easier for merchants to scan, read, and get things done.
+description: Cards are used to group similar concepts and tasks together for merchants to scan, read, and get things done. It displays content in a familiar and recognizable style.
 category: Structure
 keywords:
   - layout
@@ -26,10 +26,23 @@ status:
 examples:
   - fileName: alpha-card-default.tsx
     title: Default
-  - fileName: alpha-card-subdued.tsx
-    title: With subdued for secondary content
-    description: Use for content that you want to deprioritize. Subdued cards don’t stand out as much as cards with white backgrounds so don’t use them for information or actions that are critical to merchants.
-  - fileName: alpha-card-without-border-radius.tsx
-    title: Without border radius
-    description: Border radius can be toggled to display only past a certain breakpoint.
+  - fileName: alpha-card-with-subdued-background.tsx
+    title: With subdued background
+    description: >-
+      Use for content that you want to deprioritize. Subdued cards don’t stand out as much as cards with white backgrounds so don’t use them for information or actions that are critical to merchants.
+  - fileName: alpha-card-with-varying-padding.tsx
+    title: With varying padding
+    description: >-
+      Use the `padding` property to adjust the spacing within a card. You can also specify spacing values at different breakpoints.
+  - fileName: alpha-card-with-rounded-corners.tsx
+    title: Rounded corners
+    description: >-
+      Cards have an 8px border radius by default. Rounding may also be applied responsively with the roundedAbove prop. This enables cards to be softened on larger screens, but squared off when they are full bleed on smaller devices.
 ---
+
+## Best practices
+
+Cards should:
+
+- Group related information
+- Display information in a way that prioritizes what the merchant needs to know most first
diff --git a/polaris.shopify.com/pages/examples/alpha-card-default.tsx b/polaris.shopify.com/pages/examples/alpha-card-default.tsx
index 3bcfc34bf9a..50986b57f56 100644
--- a/polaris.shopify.com/pages/examples/alpha-card-default.tsx
+++ b/polaris.shopify.com/pages/examples/alpha-card-default.tsx
@@ -1,16 +1,13 @@
-import {AlphaCard, Text, AlphaStack} from '@shopify/polaris';
+import {AlphaCard, Text} from '@shopify/polaris';
 import React from 'react';
 import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
 
 function AlphaCardExample() {
   return (
     <AlphaCard>
-      <AlphaStack spacing="5">
-        <Text as="h3" variant="headingMd">
-          Online store dashboard
-        </Text>
-        <p>View a summary of your online store’s performance.</p>
-      </AlphaStack>
+      <Text as="h2" variant="bodyMd">
+        Content inside a card
+      </Text>
     </AlphaCard>
   );
 }
diff --git a/polaris.shopify.com/pages/examples/alpha-card-subdued.tsx b/polaris.shopify.com/pages/examples/alpha-card-subdued.tsx
deleted file mode 100644
index 0a8abcdf28d..00000000000
--- a/polaris.shopify.com/pages/examples/alpha-card-subdued.tsx
+++ /dev/null
@@ -1,18 +0,0 @@
-import {AlphaCard, Text, AlphaStack} from '@shopify/polaris';
-import React from 'react';
-import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
-
-function AlphaCardExample() {
-  return (
-    <AlphaCard background="surface-subdued">
-      <AlphaStack spacing="5">
-        <Text as="h3" variant="headingMd">
-          Online store dashboard
-        </Text>
-        <p>View a summary of your online store’s performance.</p>
-      </AlphaStack>
-    </AlphaCard>
-  );
-}
-
-export default withPolarisExample(AlphaCardExample);
diff --git a/polaris.shopify.com/pages/examples/alpha-card-with-rounded-corners.tsx b/polaris.shopify.com/pages/examples/alpha-card-with-rounded-corners.tsx
new file mode 100644
index 00000000000..dade684c47f
--- /dev/null
+++ b/polaris.shopify.com/pages/examples/alpha-card-with-rounded-corners.tsx
@@ -0,0 +1,15 @@
+import {AlphaCard, Text} from '@shopify/polaris';
+import React from 'react';
+import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
+
+function AlphaCardExample() {
+  return (
+    <AlphaCard roundedAbove="md">
+      <Text as="h2" variant="bodyMd">
+        Content inside a card
+      </Text>
+    </AlphaCard>
+  );
+}
+
+export default withPolarisExample(AlphaCardExample);
diff --git a/polaris.shopify.com/pages/examples/alpha-card-with-subdued-background.tsx b/polaris.shopify.com/pages/examples/alpha-card-with-subdued-background.tsx
new file mode 100644
index 00000000000..c2cf0838a10
--- /dev/null
+++ b/polaris.shopify.com/pages/examples/alpha-card-with-subdued-background.tsx
@@ -0,0 +1,15 @@
+import {AlphaCard, Text} from '@shopify/polaris';
+import React from 'react';
+import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
+
+function AlphaCardExample() {
+  return (
+    <AlphaCard background="surface-subdued">
+      <Text as="h2" variant="bodyMd">
+        Content inside a card
+      </Text>
+    </AlphaCard>
+  );
+}
+
+export default withPolarisExample(AlphaCardExample);
diff --git a/polaris.shopify.com/pages/examples/alpha-card-with-varying-padding.tsx b/polaris.shopify.com/pages/examples/alpha-card-with-varying-padding.tsx
new file mode 100644
index 00000000000..1582ce55195
--- /dev/null
+++ b/polaris.shopify.com/pages/examples/alpha-card-with-varying-padding.tsx
@@ -0,0 +1,46 @@
+import {AlphaCard, Text, AlphaStack} from '@shopify/polaris';
+import React from 'react';
+import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
+
+function AlphaCardExample() {
+  return (
+    <AlphaStack spacing="4" fullWidth>
+      <AlphaCard>
+        <Placeholder label="Content inside a card" />
+      </AlphaCard>
+      <AlphaCard padding="4">
+        <Placeholder label="Content inside a card" />
+      </AlphaCard>
+      <AlphaCard padding="2">
+        <Placeholder label="Content inside a card" />
+      </AlphaCard>
+      <AlphaCard padding="0">
+        <Placeholder label="Content inside a card" />
+      </AlphaCard>
+    </AlphaStack>
+  );
+}
+
+const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
+  return (
+    <div
+      style={{
+        background: '#7B47F1',
+        height: height ?? undefined,
+        width: width ?? undefined,
+      }}
+    >
+      <div
+        style={{
+          color: '#FFFFFF',
+        }}
+      >
+        <Text as="h2" variant="bodyMd">
+          {label}
+        </Text>
+      </div>
+    </div>
+  );
+};
+
+export default withPolarisExample(AlphaCardExample);
diff --git a/polaris.shopify.com/pages/examples/alpha-card-without-border-radius.tsx b/polaris.shopify.com/pages/examples/alpha-card-without-border-radius.tsx
deleted file mode 100644
index cd731241ad2..00000000000
--- a/polaris.shopify.com/pages/examples/alpha-card-without-border-radius.tsx
+++ /dev/null
@@ -1,28 +0,0 @@
-import {AlphaCard, Text, AlphaStack} from '@shopify/polaris';
-import React from 'react';
-import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
-
-function AlphaCardExample() {
-  return (
-    <AlphaStack>
-      <AlphaCard hasBorderRadius={false}>
-        <AlphaStack spacing="5">
-          <Text as="h3" variant="headingMd">
-            Online store dashboard
-          </Text>
-          <p>View a summary of your online store’s performance.</p>
-        </AlphaStack>
-      </AlphaCard>
-      <AlphaCard roundedAbove="sm">
-        <AlphaStack spacing="5">
-          <Text as="h3" variant="headingMd">
-            Online store dashboard
-          </Text>
-          <p>View a summary of your online store’s performance.</p>
-        </AlphaStack>
-      </AlphaCard>
-    </AlphaStack>
-  );
-}
-
-export default withPolarisExample(AlphaCardExample);