Update AlphaCard docs

Author: chazdean

.changeset/five-bats-attend.md

@@ -0,0 +1,5 @@
+---
+'polaris.shopify.com': patch
+---
+
+Update `AlphaCard` component docs

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

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>
   );
 }

polaris.shopify.com/pages/examples/alpha-card-subdued.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);

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 background="surface-subdued">
+      <Text as="h2" variant="bodyMd">
+        Content inside a card
+      </Text>
+    </AlphaCard>
+  );
+}
+
+export default withPolarisExample(AlphaCardExample);

polaris.shopify.com/pages/examples/alpha-card-with-subdued-background.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);