[Layout foundations] Update AlphaCard component docs and guidance (#…

…7568)

<!--
  ☝️How to write a good PR title:
- Prefix it with [ComponentName] (if applicable), for example: [Button]
  - Start with a verb, for example: Add, Delete, Improve, Fix…
  - Give as much context as necessary and as little as possible
  - Prefix it with [WIP] while it’s a work in progress
-->

### WHY are these changes introduced?

Fixes #6905  <!-- link to issue if one exists -->

<!--
  Context about the problem that’s being addressed.
-->

### WHAT is this pull request doing?

Updates the `AlphaCard` component docs and guidance

<details>
      <summary>AlphaCard style guide</summary>
<img
src="https://user-images.githubusercontent.com/59836805/198679436-320894fa-017d-4a0c-bb14-3fd8b1cc4c77.gif"
alt="AlphaCard styleguide" width="600">
    </details>

<!--
  Summary of the changes committed.

Before / after screenshots are appreciated for UI changes. Make sure to
include alt text that describes the screenshot.

If you include an animated gif showing your change, wrapping it in a
details tag is recommended. Gifs usually autoplay, which can cause
accessibility issues for people reviewing your PR:

    <details>
      <summary>Summary of your gif(s)</summary>
      <img src="..." alt="Description of what the gif shows">
    </details>
-->

<!-- ℹ️ Delete the following for small / trivial changes -->

### 🎩 checklist

- [ ] Tested on
[mobile](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md#cross-browser-testing)
- [ ] Tested on [multiple
browsers](https://help.shopify.com/en/manual/shopify-admin/supported-browsers)
- [ ] Tested for
[accessibility](https://github.com/Shopify/polaris/blob/main/documentation/Accessibility%20testing.md)
- [ ] Updated the component's `README.md` with documentation changes
- [ ] [Tophatted
documentation](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting%20documentation.md)
changes in the style guide

Co-authored-by: Lo Kim <[email protected]>

.changeset/five-bats-attend.md

@@ -0,0 +1,5 @@
+---
+'polaris.shopify.com': patch
+---
+
+Updated `AlphaCard` component guidance and examples

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

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

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,
+        width: width,
+      }}
+    >
+      <div
+        style={{
+          color: '#FFFFFF',
+        }}
+      >
+        <Text as="h2" variant="bodyMd">
+          {label}
+        </Text>
+      </div>
+    </div>
+  );
+};
+
+export default withPolarisExample(AlphaCardExample);