docs(Card): improve a11y of storybook examples

change/@fluentui-react-card-b924c1a0-fd8f-451e-9edb-7633490f4256.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "docs: improve a11y of card storybook examples",
+  "packageName": "@fluentui/react-card",
+  "email": "[email protected]",
+  "dependentChangeType": "none"
+}

packages/react-components/react-card/stories/Card/CardAppearance.stories.tsx

@@ -85,7 +85,7 @@ const CardExample = ({ className, ...props }: CardProps) => {
   return (
     <Card {...props} className={mergeClasses(className, styles.card)} onClick={onClick}>
       <CardHeader
-        image={<img className={styles.logo} src={resolveAsset('app_logo.svg')} />}
+        image={<img className={styles.logo} src={resolveAsset('app_logo.svg')} alt="App name logo" />}
         header={<Text weight="semibold">App Name</Text>}
         description={<Caption1 className={styles.caption}>Developer</Caption1>}
         action={<Button appearance="transparent" icon={<MoreHorizontal20Filled />} aria-label="More options" />}
@@ -105,7 +105,7 @@ export const Appearance = () => {
     <div className={styles.main}>
       <section>
         <ExampleHeader
-          title="Default"
+          title="Filled (Default)"
           description="This is the default style to use for cards. Use this style variant for most of your card
           designs."
         />

packages/react-components/react-card/stories/Card/CardDefault.stories.tsx

@@ -25,7 +25,7 @@ export const Default = () => {
   return (
     <Card className={styles.card}>
       <CardHeader
-        image={<img src={resolveAsset('avatar_elvia.svg')} alt="Face of a person" />}
+        image={<img src={resolveAsset('avatar_elvia.svg')} alt="Elvia Atkins avatar picture" />}
         header={
           <Body1>
             <b>Elvia Atkins</b> mentioned you
@@ -34,8 +34,8 @@ export const Default = () => {
         description={<Caption1>5h ago · About us - Overview</Caption1>}
       />
 
-      <CardPreview logo={<img src={resolveAsset('word_logo.svg')} alt="Microsoft Word logo" />}>
-        <img src={resolveAsset('doc_template.png')} alt="Preview of a Word document " />
+      <CardPreview logo={<img src={resolveAsset('word_logo.svg')} alt="Microsoft Word document" />}>
+        <img src={resolveAsset('doc_template.png')} alt="Preview of a Word document: About Us - Overview" />
       </CardPreview>
 
       <CardFooter>

packages/react-components/react-card/stories/Card/CardDescription.md

@@ -1 +1,3 @@
-The Card component is a framework for organizing content within the confines of a container. It's main function is to provide the scaffolding for hosting actions and content for a single topic within a card.
+A card is a container that holds information and actions related to a single concept or object, like a document or a contact.
+
+Cards can give information prominence and create predictable patterns. While they're very flexible, it's important to use them consistently for particular use cases across experiences.

packages/react-components/react-card/stories/Card/CardOrientation.stories.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { makeStyles, shorthands, Avatar, Button, Caption1, Text, tokens, Subtitle1 } from '@fluentui/react-components';
+import { makeStyles, shorthands, Button, Caption1, Text, tokens, Subtitle1 } from '@fluentui/react-components';
 import { MoreHorizontal20Filled } from '@fluentui/react-icons';
 import { Card, CardHeader, CardPreview } from '@fluentui/react-card';
 
@@ -18,6 +18,12 @@ const useStyles = makeStyles({
     flexWrap: 'wrap',
   },
 
+  card: {
+    width: '360px',
+    maxWidth: '100%',
+    height: 'fit-content',
+  },
+
   section: {
     width: 'fit-content',
   },
@@ -27,14 +33,8 @@ const useStyles = makeStyles({
   },
 
   horizontalCardImage: {
-    width: '60px',
-    height: '60px',
-  },
-
-  verticalCard: {
-    width: '360px',
-    maxWidth: '100%',
-    height: 'fit-content',
+    width: '64px',
+    height: '64px',
   },
 
   headerImage: {
@@ -69,9 +69,11 @@ export const Orientation = () => {
     <div className={styles.main}>
       <section className={styles.section}>
         <Title>'vertical' (Default)</Title>
-        <Card className={styles.verticalCard}>
+        <p>With image as part of header</p>
+
+        <Card className={styles.card}>
           <CardHeader
-            image={<img src={resolveAsset('app_logo.svg')} className={styles.headerImage} />}
+            image={<img className={styles.headerImage} src={resolveAsset('app_logo.svg')} alt="App Name Document" />}
             header={<Text weight="semibold">App Name</Text>}
             description={<Caption1 className={styles.caption}>Developer</Caption1>}
             action={<Button appearance="transparent" icon={<MoreHorizontal20Filled />} aria-label="More options" />}
@@ -86,16 +88,16 @@ export const Orientation = () => {
 
       <section className={styles.section}>
         <Title>'horizontal'</Title>
+        <p>With image as part of preview</p>
 
-        <Card size="small" orientation="horizontal">
+        <Card className={styles.card} orientation="horizontal">
           <CardPreview className={styles.horizontalCardImage}>
-            <img src={resolveAsset('logo.svg')} alt="Company Logo" />
+            <img className={styles.horizontalCardImage} src={resolveAsset('app_logo.svg')} alt="App Name Document" />
           </CardPreview>
 
           <CardHeader
-            image={<Avatar badge={{ status: 'available' }} image={{ src: resolveAsset('avatar_elvia.svg') }} />}
-            header={<Text weight="semibold">Strategy 2021</Text>}
-            description={<Caption1>https://aka.ms/fluentui</Caption1>}
+            header={<Text weight="semibold">App Name</Text>}
+            description={<Caption1 className={styles.caption}>Developer</Caption1>}
             action={<Button appearance="transparent" icon={<MoreHorizontal20Filled />} aria-label="More options" />}
           />
         </Card>

packages/react-components/react-card/stories/Card/CardSelectable.stories.tsx

@@ -50,9 +50,9 @@ const CardExample = (props: CardProps) => {
     <Card className={styles.card} {...props}>
       <CardPreview
         className={styles.grayBackground}
-        logo={<img className={styles.logoBadge} alt="app logo" src={resolveAsset('logo3.svg')} />}
+        logo={<img className={styles.logoBadge} src={resolveAsset('logo3.svg')} alt="Figma app logo" />}
       >
-        <img alt="Presentation Preview" src={resolveAsset('office1.png')} className={styles.smallRadius} />
+        <img className={styles.smallRadius} src={resolveAsset('office1.png')} alt="Presentation Preview" />
       </CardPreview>
 
       <CardHeader

packages/react-components/react-card/stories/Card/CardSelectableIndicator.stories.tsx

@@ -82,9 +82,9 @@ export const SelectableIndicator = () => {
         >
           <CardPreview
             className={styles.grayBackground}
-            logo={<img className={styles.logoBadge} alt="app logo" src={resolveAsset('logo3.svg')} />}
+            logo={<img className={styles.logoBadge} src={resolveAsset('logo3.svg')} alt="Figma app logo" />}
           >
-            <img alt="Presentation Preview" src={resolveAsset('office1.png')} className={styles.smallRadius} />
+            <img className={styles.smallRadius} src={resolveAsset('office1.png')} alt="Presentation Preview" />
           </CardPreview>
 
           <CardHeader
@@ -102,9 +102,9 @@ export const SelectableIndicator = () => {
         >
           <CardPreview
             className={styles.grayBackground}
-            logo={<img className={styles.logoBadge} alt="app logo" src={resolveAsset('logo3.svg')} />}
+            logo={<img className={styles.logoBadge} src={resolveAsset('logo3.svg')} alt="Figma app logo" />}
           >
-            <img alt="Presentation Preview" src={resolveAsset('office1.png')} className={styles.smallRadius} />
+            <img className={styles.smallRadius} src={resolveAsset('office1.png')} alt="Presentation Preview" />
           </CardPreview>
 
           <CardHeader

packages/react-components/react-card/stories/Card/CardSize.stories.tsx

@@ -66,8 +66,8 @@ const CardExample = (props: CardProps) => {
   return (
     <Card className={styles.card} {...props}>
       <header className={styles.flex}>
-        <img className={styles.appIcon} src={resolveAsset('logo.svg')} />
-        <img className={styles.appIcon} src={resolveAsset('logo2.svg')} />
+        <img className={styles.appIcon} src={resolveAsset('logo.svg')} alt="Application one logo" />
+        <img className={styles.appIcon} src={resolveAsset('logo2.svg')} alt="Application two logo" />
       </header>
 
       <CardHeader

packages/react-components/react-card/stories/Card/CardTemplates.stories.tsx

@@ -22,12 +22,9 @@ import {
 import { Card, CardHeader, CardPreview } from '@fluentui/react-card';
 
 const useStyles = makeStyles({
-  mainContainer: {
+  container: {
     ...shorthands.gap('16px'),
-    width: 'fit-content',
-    height: '256px',
     display: 'flex',
-    flexDirection: 'column',
     flexWrap: 'wrap',
   },
 
@@ -59,6 +56,12 @@ const useStyles = makeStyles({
     display: 'flex',
     alignItems: 'flex-start',
   },
+
+  grid: {
+    ...shorthands.gap('16px'),
+    display: 'flex',
+    flexDirection: 'column',
+  },
 });
 
 const resolveAsset = (asset: string) => {
@@ -76,13 +79,7 @@ export const Templates = () => {
   const styles = useStyles();
 
   return (
-    <div className={styles.mainContainer}>
-      <Card className={styles.card}>
-        <CardPreview>
-          <img src={resolveAsset('intelligence.png')} alt="Intelligence - Design to Amplify" />
-        </CardPreview>
-      </Card>
-
+    <div className={styles.container}>
       <Card className={styles.card}>
         <header className={mergeClasses(styles.flex, styles.labels)}>
           <Badge color="severe" shape="rounded" appearance="tint">
@@ -146,32 +143,48 @@ export const Templates = () => {
         </footer>
       </Card>
 
-      <Card className={styles.card} size="small">
-        <CardHeader
-          image={{ as: 'img', src: powerpointLogoURL }}
-          header={<Text weight="semibold">Team Offsite 2020</Text>}
-          description={<Caption1 className={styles.caption}>OneDrive &gt; Presentations</Caption1>}
-          action={<Button appearance="transparent" icon={<MoreHorizontal20Filled />} />}
-        />
-      </Card>
-
-      <Card className={styles.card} size="small">
-        <CardHeader
-          image={{ as: 'img', src: excelLogo }}
-          header={<Text weight="semibold">Team Budget</Text>}
-          description={<Caption1 className={styles.caption}>OneDrive &gt; Spreadsheets</Caption1>}
-          action={<Button appearance="transparent" icon={<MoreHorizontal20Filled />} />}
-        />
+      <Card className={styles.card}>
+        <CardPreview>
+          <img src={resolveAsset('intelligence.png')} alt="Intelligence - Design to Amplify" />
+        </CardPreview>
       </Card>
 
-      <Card className={styles.card} size="small">
-        <CardHeader
-          image={{ as: 'img', src: wordLogo }}
-          header={<Text weight="semibold">Secret Project Briefing</Text>}
-          description={<Caption1 className={styles.caption}>OneDrive &gt; Documents</Caption1>}
-          action={<Button appearance="transparent" icon={<MoreHorizontal20Filled />} />}
-        />
-      </Card>
+      <div className={styles.grid} role="list">
+        <Card className={styles.card} size="small" role="listitem">
+          <CardHeader
+            image={{ as: 'img', src: powerpointLogoURL, alt: 'PowerPoint app logo' }}
+            header={<Text weight="semibold">Team Offsite 2020</Text>}
+            description={<Caption1 className={styles.caption}>OneDrive &gt; Presentations</Caption1>}
+            action={<Button appearance="transparent" icon={<MoreHorizontal20Filled />} />}
+          />
+        </Card>
+
+        <Card className={styles.card} size="small" role="listitem">
+          <CardHeader
+            image={{ as: 'img', src: excelLogo, alt: 'Excel app logo' }}
+            header={<Text weight="semibold">Team Budget</Text>}
+            description={<Caption1 className={styles.caption}>OneDrive &gt; Spreadsheets</Caption1>}
+            action={<Button appearance="transparent" icon={<MoreHorizontal20Filled />} />}
+          />
+        </Card>
+
+        <Card className={styles.card} size="small" role="listitem">
+          <CardHeader
+            image={{ as: 'img', src: wordLogo, alt: 'Word app logo' }}
+            header={<Text weight="semibold">Secret Project Briefing</Text>}
+            description={<Caption1 className={styles.caption}>OneDrive &gt; Documents</Caption1>}
+            action={<Button appearance="transparent" icon={<MoreHorizontal20Filled />} />}
+          />
+        </Card>
+      </div>
     </div>
   );
 };
+
+Templates.parameters = {
+  docs: {
+    description: {
+      story: 'Cards can be composed with other components to build rich elements for a page.',
+    },
+  },
+};