From 0d918a535598591324fee6473c03abf7e271af76 Mon Sep 17 00:00:00 2001
From: Nisha Yerunkar <nisha@khanacademy.org>
Date: Mon, 6 Nov 2023 13:30:36 -0800
Subject: [PATCH] Add component gallery descriptions (#2104)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary:
A component gallery was added in #2102 without descriptions.
In this PR, I added descriptions for all the listed components.

I also:
- added IDs to the the component headings so that the
  table of components scrolls to the sections correctly.
- added the external link icon to indicate that all
  the tiles link to their respective pages in new tabs.
- made the gallery more mobile-friendly

Issue: https://khanacademy.atlassian.net/browse/WB-1595

## Test plan:
- Go to http://localhost:6061/?path=/docs/overview--docs
- Confirm that the descriptions all make sense and are all in the same tense.

Author: nishasy

Reviewers: jandrade

Required Reviewers:

Approved By: jandrade

Checks: ❌ codecov/project, ✅ Check build sizes (ubuntu-latest, 16.x), ✅ Test (ubuntu-latest, 16.x, 2/2), ✅ Lint (ubuntu-latest, 16.x), ✅ Test (ubuntu-latest, 16.x, 1/2), ✅ Publish npm snapshot (ubuntu-latest, 16.x), ✅ Prime node_modules cache for primary configuration (ubuntu-latest, 16.x), ✅ Check for .changeset entries for all changed files (ubuntu-latest, 16.x), ✅ gerald, ✅ Chromatic - Get results on regular PRs (ubuntu-latest, 16.x), ✅ Test (ubuntu-latest, 16.x, 2/2), ✅ Test (ubuntu-latest, 16.x, 1/2), ✅ Check build sizes (ubuntu-latest, 16.x), ✅ Lint (ubuntu-latest, 16.x), ✅ Chromatic - Build on regular PRs / chromatic (ubuntu-latest, 16.x), ⏭  Publish npm snapshot, ⏭  Chromatic - Skip on Release PR (changesets), ✅ Prime node_modules cache for primary configuration (ubuntu-latest, 16.x), ✅ Check for .changeset entries for all changed files (ubuntu-latest, 16.x), ✅ gerald, ✅ Chromatic - Get results on regular PRs (ubuntu-latest, 16.x), ✅ Check build sizes (ubuntu-latest, 16.x), ✅ Test (ubuntu-latest, 16.x, 2/2), ✅ Lint (ubuntu-latest, 16.x), ✅ Test (ubuntu-latest, 16.x, 1/2), ✅ Chromatic - Build on regular PRs / chromatic (ubuntu-latest, 16.x), ⏭  Chromatic - Skip on Release PR (changesets), ⏭  Publish npm snapshot, ✅ Check for .changeset entries for all changed files (ubuntu-latest, 16.x), ✅ Prime node_modules cache for primary configuration (ubuntu-latest, 16.x)

Pull Request URL: https://github.com/Khan/wonder-blocks/pull/2104
---
 .changeset/brown-planets-relate.md            |   2 +
 .../components/gallery/component-tile.tsx     |  35 +++-
 .../gallery/sections/accordion-section.tsx    |   8 +-
 .../gallery/sections/banner-section.tsx       |  10 +-
 .../sections/birthday-picker-section.tsx      |  14 +-
 .../gallery/sections/breadcrumbs-section.tsx  |  27 +--
 .../gallery/sections/button-section.tsx       |   8 +-
 .../gallery/sections/cell-section.tsx         |   9 +-
 .../gallery/sections/dropdown-section.tsx     | 165 ++++++++++--------
 .../gallery/sections/form-section.tsx         |  11 +-
 .../gallery/sections/icon-button-section.tsx  |   3 +-
 .../gallery/sections/icon-section.tsx         |   7 +-
 .../gallery/sections/link-section.tsx         |  14 +-
 .../gallery/sections/modal-section.tsx        |   6 +-
 .../gallery/sections/pill-section.tsx         |  12 +-
 .../gallery/sections/popover-section.tsx      |  10 +-
 .../sections/progress-spinner-section.tsx     |   8 +-
 .../gallery/sections/search-field-section.tsx |   9 +-
 .../gallery/sections/switch-section.tsx       |  10 +-
 .../gallery/sections/toolbar-section.tsx      |  11 +-
 .../gallery/sections/tooltip-section.tsx      |   9 +-
 21 files changed, 272 insertions(+), 116 deletions(-)
 create mode 100644 .changeset/brown-planets-relate.md

diff --git a/.changeset/brown-planets-relate.md b/.changeset/brown-planets-relate.md
new file mode 100644
index 000000000..a845151cc
--- /dev/null
+++ b/.changeset/brown-planets-relate.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/__docs__/components/gallery/component-tile.tsx b/__docs__/components/gallery/component-tile.tsx
index 9d8d44f37..d875eb244 100644
--- a/__docs__/components/gallery/component-tile.tsx
+++ b/__docs__/components/gallery/component-tile.tsx
@@ -1,8 +1,10 @@
 import * as React from "react";
 import {StyleSheet} from "aphrodite";
+import externalLinkIcon from "@phosphor-icons/core/bold/arrow-square-out-bold.svg";
 
 import Clickable from "@khanacademy/wonder-blocks-clickable";
 import {View} from "@khanacademy/wonder-blocks-core";
+import {PhosphorIcon} from "@khanacademy/wonder-blocks-icon";
 import {tokens} from "@khanacademy/wonder-blocks-theming";
 import {Body, HeadingMedium} from "@khanacademy/wonder-blocks-typography";
 
@@ -17,12 +19,24 @@ export default function ComponentTile(props: Props) {
     const {children, description, name, href} = props;
     return (
         <View style={styles.tile}>
-            <Clickable href={href} target="_blank" style={styles.clickable}>
+            <Clickable
+                href={href}
+                target="_blank"
+                style={styles.clickable}
+                aria-label={`View ${name} component in a new tab.`}
+            >
                 {() => (
                     <>
                         <View style={styles.description}>
-                            <View style={styles.name}>
+                            <View style={styles.headingContainer}>
                                 <HeadingMedium tag="h4">{name}</HeadingMedium>
+                                <View style={styles.externalLinkIcon}>
+                                    <PhosphorIcon
+                                        icon={externalLinkIcon}
+                                        size="small"
+                                        aria-hidden="true"
+                                    />
+                                </View>
                             </View>
                             {description && (
                                 <Body style={styles.descriptionText}>
@@ -38,6 +52,8 @@ export default function ComponentTile(props: Props) {
     );
 }
 
+const mobile = "@media (max-width: 1023px)";
+
 const styles = StyleSheet.create({
     tile: {
         display: "flex",
@@ -46,6 +62,10 @@ const styles = StyleSheet.create({
         // Set the width to half the max width of the stories page content.
         width: 484,
         minHeight: 300,
+
+        [mobile]: {
+            width: "95%",
+        },
     },
     clickable: {
         backgroundColor: tokens.color.offWhite,
@@ -66,8 +86,10 @@ const styles = StyleSheet.create({
     description: {
         padding: tokens.spacing.large_24,
     },
-    name: {
+    headingContainer: {
         width: "fit-content",
+        flexDirection: "row",
+        alignItems: "center",
     },
     descriptionText: {
         marginTop: tokens.spacing.small_12,
@@ -81,5 +103,12 @@ const styles = StyleSheet.create({
         borderEndStartRadius: tokens.spacing.small_12,
         borderEndEndRadius: tokens.spacing.small_12,
         flexGrow: 1,
+
+        [mobile]: {
+            overflowX: "scroll",
+        },
+    },
+    externalLinkIcon: {
+        marginLeft: tokens.spacing.xSmall_8,
     },
 });
diff --git a/__docs__/components/gallery/sections/accordion-section.tsx b/__docs__/components/gallery/sections/accordion-section.tsx
index 1d609c999..151a15f15 100644
--- a/__docs__/components/gallery/sections/accordion-section.tsx
+++ b/__docs__/components/gallery/sections/accordion-section.tsx
@@ -13,7 +13,7 @@ import {styles} from "../styles";
 export default function AccordionGallerySection() {
     return (
         <RenderStateRoot>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge id="accordion" tag="h3" style={styles.sectionLabel}>
                 Accordion
             </HeadingLarge>
 
@@ -21,6 +21,9 @@ export default function AccordionGallerySection() {
                 <ComponentTile
                     name="Accordion"
                     href="/?path=/docs/accordion-accordion--docs"
+                    description={`A vertically stacked list of sections,
+                        each of which contains content that can be expanded
+                        or collapsed by clicking its header.`}
                 >
                     <Accordion>
                         <AccordionSection header="First section">
@@ -39,6 +42,9 @@ export default function AccordionGallerySection() {
                 <ComponentTile
                     name="AccordionSection"
                     href="/?path=/docs/accordion-accordionsection--docs"
+                    description={`A single collapsible section within
+                        an accordion. It can be used by itself or within
+                        an accordion.`}
                 >
                     <AccordionSection header="Accordion Section">
                         This is an accordion section.
diff --git a/__docs__/components/gallery/sections/banner-section.tsx b/__docs__/components/gallery/sections/banner-section.tsx
index 80ed71c4c..e6e81ca9f 100644
--- a/__docs__/components/gallery/sections/banner-section.tsx
+++ b/__docs__/components/gallery/sections/banner-section.tsx
@@ -9,10 +9,16 @@ import {styles} from "../styles";
 export default function BannerSection() {
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge id="banner" tag="h3" style={styles.sectionLabel}>
                 Banner
             </HeadingLarge>
-            <ComponentTile name="Banner" href="/?path=/docs/banner--docs">
+            <ComponentTile
+                name="Banner"
+                href="/?path=/docs/banner--docs"
+                description={`Displays a prominent message and
+                    related optional actions. It can be used as a way
+                    of informing the user of important changes.`}
+            >
                 <Banner text="This is a banner!" layout="floating" />
             </ComponentTile>
         </>
diff --git a/__docs__/components/gallery/sections/birthday-picker-section.tsx b/__docs__/components/gallery/sections/birthday-picker-section.tsx
index 73be9eca3..b8f46a059 100644
--- a/__docs__/components/gallery/sections/birthday-picker-section.tsx
+++ b/__docs__/components/gallery/sections/birthday-picker-section.tsx
@@ -1,6 +1,7 @@
 import * as React from "react";
 
 import BirthdayPicker from "@khanacademy/wonder-blocks-birthday-picker";
+import {View} from "@khanacademy/wonder-blocks-core";
 import {HeadingLarge} from "@khanacademy/wonder-blocks-typography";
 
 import ComponentTile from "../component-tile";
@@ -9,14 +10,23 @@ import {styles} from "../styles";
 export default function BirthdayPickerSection() {
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge
+                id="birthday-picker"
+                tag="h3"
+                style={styles.sectionLabel}
+            >
                 Birthday Picker
             </HeadingLarge>
             <ComponentTile
                 name="BirthdayPicker"
                 href="/?path=/docs/birthdaypicker--docs"
+                description={`Similar to a datepicker, but specifically
+                    for birthdates. It consists of a set of dropdowns
+                    to choose the date.`}
             >
-                <BirthdayPicker onChange={() => {}} />
+                <View style={styles.centerContent}>
+                    <BirthdayPicker onChange={() => {}} />
+                </View>
             </ComponentTile>
         </>
     );
diff --git a/__docs__/components/gallery/sections/breadcrumbs-section.tsx b/__docs__/components/gallery/sections/breadcrumbs-section.tsx
index f5fc8d387..ce85e5d49 100644
--- a/__docs__/components/gallery/sections/breadcrumbs-section.tsx
+++ b/__docs__/components/gallery/sections/breadcrumbs-section.tsx
@@ -4,6 +4,7 @@ import {
     Breadcrumbs,
     BreadcrumbsItem,
 } from "@khanacademy/wonder-blocks-breadcrumbs";
+import {View} from "@khanacademy/wonder-blocks-core";
 import Link from "@khanacademy/wonder-blocks-link";
 import {HeadingLarge} from "@khanacademy/wonder-blocks-typography";
 
@@ -13,22 +14,28 @@ import {styles} from "../styles";
 export default function BannerSection() {
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge id="breadcrumbs" tag="h3" style={styles.sectionLabel}>
                 Breadcrumbs
             </HeadingLarge>
             <ComponentTile
                 name="Breadcrumbs"
                 href="/?path=/docs/breadcrumbs--docs"
+                description={`A breadcrumb trail consists of a list of
+                    links to the parent pages of the current page in
+                    hierarchical order. It helps users find their place
+                    within a website or web application.`}
             >
-                <Breadcrumbs>
-                    <BreadcrumbsItem>
-                        <Link href="">Course</Link>
-                    </BreadcrumbsItem>
-                    <BreadcrumbsItem>
-                        <Link href="">Unit</Link>
-                    </BreadcrumbsItem>
-                    <BreadcrumbsItem>Lesson</BreadcrumbsItem>
-                </Breadcrumbs>
+                <View style={styles.centerContent}>
+                    <Breadcrumbs>
+                        <BreadcrumbsItem>
+                            <Link href="">Course</Link>
+                        </BreadcrumbsItem>
+                        <BreadcrumbsItem>
+                            <Link href="">Unit</Link>
+                        </BreadcrumbsItem>
+                        <BreadcrumbsItem>Lesson</BreadcrumbsItem>
+                    </Breadcrumbs>
+                </View>
             </ComponentTile>
         </>
     );
diff --git a/__docs__/components/gallery/sections/button-section.tsx b/__docs__/components/gallery/sections/button-section.tsx
index 5732ae532..74851b6cc 100644
--- a/__docs__/components/gallery/sections/button-section.tsx
+++ b/__docs__/components/gallery/sections/button-section.tsx
@@ -11,10 +11,14 @@ import {styles} from "../styles";
 export default function BannerSection() {
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge id="button" tag="h3" style={styles.sectionLabel}>
                 Button
             </HeadingLarge>
-            <ComponentTile name="Button" href="/?path=/docs/button--docs">
+            <ComponentTile
+                name="Button"
+                href="/?path=/docs/button--docs"
+                description="Standard button. Triggers an action."
+            >
                 <Button
                     kind="primary"
                     onClick={() => {}}
diff --git a/__docs__/components/gallery/sections/cell-section.tsx b/__docs__/components/gallery/sections/cell-section.tsx
index 209dbdcbc..507c0d2f9 100644
--- a/__docs__/components/gallery/sections/cell-section.tsx
+++ b/__docs__/components/gallery/sections/cell-section.tsx
@@ -13,13 +13,16 @@ import {styles} from "../styles";
 export default function BannerSection() {
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge id="cell" tag="h3" style={styles.sectionLabel}>
                 Cell
             </HeadingLarge>
             <View style={styles.section}>
                 <ComponentTile
                     name="CompactCell"
                     href="/?path=/docs/cell-compactcell--docs"
+                    description={`A compacted-height cell with limited
+                        subviews and accessories. Typically they represent
+                        additional info or selection lists.`}
                 >
                     <View style={localStyles.cellExample}>
                         <CompactCell
@@ -34,6 +37,10 @@ export default function BannerSection() {
                 <ComponentTile
                     name="DetailCell"
                     href="/?path=/docs/cell-detailcell--docs"
+                    description={`A compact cell that allows adding
+                        subtitles before and after the cell title. They
+                        typically represent an item that can be
+                        clicked/tapped to view more complex details.`}
                 >
                     <View style={localStyles.cellExample}>
                         <DetailCell
diff --git a/__docs__/components/gallery/sections/dropdown-section.tsx b/__docs__/components/gallery/sections/dropdown-section.tsx
index cb3ae64ef..3a3339015 100644
--- a/__docs__/components/gallery/sections/dropdown-section.tsx
+++ b/__docs__/components/gallery/sections/dropdown-section.tsx
@@ -20,99 +20,116 @@ export default function BannerSection() {
 
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge id="dropdown" tag="h3" style={styles.sectionLabel}>
                 Dropdown
             </HeadingLarge>
             <View style={styles.section}>
                 <ComponentTile
                     name="ActionMenu"
                     href="/?path=/docs/dropdown-actionmenu--docs"
+                    description={`A dropdown menu that consists of
+                        various types of items.`}
                 >
-                    <ActionMenu menuText="Action Menu">
-                        <ActionItem
-                            label="Profile"
-                            href="http://khanacademy.org/profile"
-                            target="_blank"
-                            testId="profile"
-                        />
-                        <ActionItem
-                            label="Teacher dashboard"
-                            href="http://khanacademy.org/coach/dashboard"
-                            testId="dashboard"
-                        />
-                        <ActionItem
-                            label="Settings (onClick)"
-                            onClick={() => {}}
-                            testId="settings"
-                        />
-                        <ActionItem
-                            label="Help"
-                            disabled={true}
-                            onClick={() => {}}
-                            testId="help"
-                        />
-                        <ActionItem
-                            label="Feedback"
-                            disabled={true}
-                            href="/feedback"
-                            testId="feedback"
-                        />
-                        <SeparatorItem />
-                        <ActionItem
-                            label="Log out"
-                            href="http://khanacademy.org/logout"
-                            testId="logout"
-                        />
-                    </ActionMenu>
+                    <View style={styles.centerContent}>
+                        <ActionMenu menuText="Action Menu">
+                            <ActionItem
+                                label="Profile"
+                                href="http://khanacademy.org/profile"
+                                target="_blank"
+                                testId="profile"
+                            />
+                            <ActionItem
+                                label="Teacher dashboard"
+                                href="http://khanacademy.org/coach/dashboard"
+                                testId="dashboard"
+                            />
+                            <ActionItem
+                                label="Settings (onClick)"
+                                onClick={() => {}}
+                                testId="settings"
+                            />
+                            <ActionItem
+                                label="Help"
+                                disabled={true}
+                                onClick={() => {}}
+                                testId="help"
+                            />
+                            <ActionItem
+                                label="Feedback"
+                                disabled={true}
+                                href="/feedback"
+                                testId="feedback"
+                            />
+                            <SeparatorItem />
+                            <ActionItem
+                                label="Log out"
+                                href="http://khanacademy.org/logout"
+                                testId="logout"
+                            />
+                        </ActionMenu>
+                    </View>
                 </ComponentTile>
 
                 <ComponentTile
                     name="MultiSelect"
                     href="/?path=/docs/dropdown-multiselect--docs"
+                    description={`A dropdown menu that allows multiple
+                        options to be selected.`}
                 >
-                    <MultiSelect
-                        id=""
-                        onChange={(values) => setSelectedValues(values)}
-                        onToggle={() => {}}
-                        selectedValues={selectedValues}
-                        testId=""
-                    >
-                        <OptionItem label="Mercury" value="1" key={1} />
-                        <OptionItem label="Venus" value="2" key={2} />
-                        <OptionItem label="Earth" value="3" disabled key={3} />
-                        <OptionItem label="Mars" value="4" key={4} />
-                        <OptionItem label="Jupiter" value="5" key={5} />
-                        <OptionItem label="Saturn" value="6" key={6} />
-                        <OptionItem label="Neptune" value="7" key={7} />
-                        <OptionItem label="Uranus" value="8" key={8} />
-                    </MultiSelect>
+                    <View style={styles.centerContent}>
+                        <MultiSelect
+                            id=""
+                            onChange={(values) => setSelectedValues(values)}
+                            onToggle={() => {}}
+                            selectedValues={selectedValues}
+                            testId=""
+                        >
+                            <OptionItem label="Mercury" value="1" key={1} />
+                            <OptionItem label="Venus" value="2" key={2} />
+                            <OptionItem
+                                label="Earth"
+                                value="3"
+                                disabled
+                                key={3}
+                            />
+                            <OptionItem label="Mars" value="4" key={4} />
+                            <OptionItem label="Jupiter" value="5" key={5} />
+                            <OptionItem label="Saturn" value="6" key={6} />
+                            <OptionItem label="Neptune" value="7" key={7} />
+                            <OptionItem label="Uranus" value="8" key={8} />
+                        </MultiSelect>
+                    </View>
                 </ComponentTile>
 
                 <ComponentTile
                     name="SingleSelect"
                     href="/?path=/docs/dropdown-singleselect--docs"
+                    description={`A dropdown menu that allows the
+                        selection of one item.`}
                 >
-                    <SingleSelect
-                        isFilterable
-                        onChange={(value) => setSelectedValue(value)}
-                        onToggle={() => {}}
-                        placeholder="Choose a fruit"
-                        selectedValue={selectedValue}
-                    >
-                        <OptionItem label="Banana" value="banana" />
-                        <OptionItem
-                            disabled
-                            label="Strawberry"
-                            value="strawberry"
-                        />
-                        <OptionItem label="Pear" value="pear" />
-                        <OptionItem label="Orange" value="orange" />
-                        <OptionItem label="Watermelon" value="watermelon" />
-                        <OptionItem label="Apple" value="apple" />
-                        <OptionItem label="Grape" value="grape" />
-                        <OptionItem label="Lemon" value="lemon" />
-                        <OptionItem label="Mango" value="mango" />
-                    </SingleSelect>
+                    <View style={styles.centerContent}>
+                        <SingleSelect
+                            isFilterable
+                            onChange={(value) => setSelectedValue(value)}
+                            onToggle={() => {}}
+                            placeholder="Choose a fruit"
+                            selectedValue={selectedValue}
+                        >
+                            <OptionItem label="Banana" value="banana" />
+                            <OptionItem
+                                disabled
+                                label="Strawberry"
+                                value="strawberry"
+                            />
+                            <OptionItem label="Pear" value="pear" />
+                            <OptionItem label="Orange" value="orange" />
+                            <OptionItem label="Watermelon" value="watermelon" />
+                            <OptionItem label="Apple" value="apple" />
+                            <OptionItem label="Grape" value="grape" />
+                            <OptionItem label="Lemon" value="lemon" />
+                            <OptionItem label="Mango" value="mango" />
+                        </SingleSelect>
+                    </View>
                 </ComponentTile>
             </View>
         </>
diff --git a/__docs__/components/gallery/sections/form-section.tsx b/__docs__/components/gallery/sections/form-section.tsx
index 9128d8eca..37624a62c 100644
--- a/__docs__/components/gallery/sections/form-section.tsx
+++ b/__docs__/components/gallery/sections/form-section.tsx
@@ -24,13 +24,14 @@ export default function BannerSection() {
 
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge id="form" tag="h3" style={styles.sectionLabel}>
                 Form
             </HeadingLarge>
             <View style={styles.section}>
                 <ComponentTile
                     name="Checkbox"
                     href="/?path=/docs/form-checkbox--docs"
+                    description="A selection that can be checked or unchecked."
                 >
                     <Checkbox
                         label={"Checkbox label"}
@@ -43,6 +44,7 @@ export default function BannerSection() {
                 <ComponentTile
                     name="CheckboxGroup"
                     href="/?path=/docs/form-checkboxgroup--docs"
+                    description="Allows multiple selections."
                 >
                     <CheckboxGroup
                         groupName="toppings"
@@ -64,6 +66,7 @@ export default function BannerSection() {
                 <ComponentTile
                     name="RadioGroup"
                     href="/?path=/docs/form-radiogroup--docs"
+                    description="Allows only a single selection."
                 >
                     <RadioGroup
                         groupName="pokemon"
@@ -85,6 +88,9 @@ export default function BannerSection() {
                 <ComponentTile
                     name="TextField"
                     href="/?path=/docs/form-textfield--docs"
+                    description={`Standard text input field. This is
+                        used to accept a single line of text from
+                        the user.`}
                 >
                     <TextField
                         id="text-field"
@@ -98,6 +104,9 @@ export default function BannerSection() {
                 <ComponentTile
                     name="LabeledTextField"
                     href="/?path=/docs/form-labeledtextfield--docs"
+                    description={`Used to accept a single line of text
+                        from the user paired with a label, description,
+                        and error field elements.`}
                 >
                     <LabeledTextField
                         label="Name (Label)"
diff --git a/__docs__/components/gallery/sections/icon-button-section.tsx b/__docs__/components/gallery/sections/icon-button-section.tsx
index be2ad4a0b..0ad7d0fd9 100644
--- a/__docs__/components/gallery/sections/icon-button-section.tsx
+++ b/__docs__/components/gallery/sections/icon-button-section.tsx
@@ -11,13 +11,14 @@ import {styles} from "../styles";
 export default function IconButtonSection() {
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge id="icon-button" tag="h3" style={styles.sectionLabel}>
                 Icon Button
             </HeadingLarge>
             <View style={styles.section}>
                 <ComponentTile
                     name="IconButton"
                     href="/?path=/docs/iconbutton--docs"
+                    description="A button whose contents are an SVG image."
                 >
                     <View style={styles.centerContent}>
                         <IconButton
diff --git a/__docs__/components/gallery/sections/icon-section.tsx b/__docs__/components/gallery/sections/icon-section.tsx
index c0b77bc42..520572a9f 100644
--- a/__docs__/components/gallery/sections/icon-section.tsx
+++ b/__docs__/components/gallery/sections/icon-section.tsx
@@ -14,15 +14,18 @@ import {styles} from "../styles";
 export default function IconSection() {
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge id="icon" tag="h3" style={styles.sectionLabel}>
                 Icon
             </HeadingLarge>
             <View style={styles.section}>
                 <ComponentTile
                     name="PhosphorIcon"
                     href="/?path=/docs/icon-phosphoricon--docs"
+                    description={`Displays a small informational or
+                        decorative image available from the
+                        @phosphor-icons/core package.`}
                 >
-                    <View style={localStyles.content}>
+                    <View style={[localStyles.content, styles.centerContent]}>
                         <PhosphorIcon
                             icon={magnifyingGlassBold}
                             size="xlarge"
diff --git a/__docs__/components/gallery/sections/link-section.tsx b/__docs__/components/gallery/sections/link-section.tsx
index 3d11ccc9c..6e663c083 100644
--- a/__docs__/components/gallery/sections/link-section.tsx
+++ b/__docs__/components/gallery/sections/link-section.tsx
@@ -1,5 +1,6 @@
 import * as React from "react";
 
+import {View} from "@khanacademy/wonder-blocks-core";
 import Link from "@khanacademy/wonder-blocks-link";
 import {HeadingLarge} from "@khanacademy/wonder-blocks-typography";
 
@@ -9,12 +10,19 @@ import {styles} from "../styles";
 export default function LinkSection() {
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge id="link" tag="h3" style={styles.sectionLabel}>
                 Link
             </HeadingLarge>
 
-            <ComponentTile name="Link" href="/?path=/docs/link--docs">
-                <Link href="#">This is a link</Link>
+            <ComponentTile
+                name="Link"
+                href="/?path=/docs/link--docs"
+                description={`Standard link. Used to redirect to a new
+                    page or a section within the same page.`}
+            >
+                <View style={styles.centerContent}>
+                    <Link href="#">This is a link</Link>
+                </View>
             </ComponentTile>
         </>
     );
diff --git a/__docs__/components/gallery/sections/modal-section.tsx b/__docs__/components/gallery/sections/modal-section.tsx
index 1a5f14600..310cd2813 100644
--- a/__docs__/components/gallery/sections/modal-section.tsx
+++ b/__docs__/components/gallery/sections/modal-section.tsx
@@ -12,7 +12,7 @@ import {styles} from "../styles";
 export default function ModalSection() {
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge id="modal" tag="h3" style={styles.sectionLabel}>
                 Modal
             </HeadingLarge>
 
@@ -20,6 +20,10 @@ export default function ModalSection() {
                 <ComponentTile
                     name="OnePaneDialog"
                     href="/?path=/docs/modal-onepanedialog--docs"
+                    description={`Standard layout for most straightforward
+                        modal experiences. Modals display in front of the
+                        current view and prevent interaction background until
+                        they are dismissed.`}
                 >
                     <View style={localStyles.previewSizer}>
                         <View style={localStyles.modalPositioner}>
diff --git a/__docs__/components/gallery/sections/pill-section.tsx b/__docs__/components/gallery/sections/pill-section.tsx
index 9e67dc3e1..576a9809f 100644
--- a/__docs__/components/gallery/sections/pill-section.tsx
+++ b/__docs__/components/gallery/sections/pill-section.tsx
@@ -12,11 +12,17 @@ import {styles} from "../styles";
 export default function PillSection() {
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge id="pill" tag="h3" style={styles.sectionLabel}>
                 Pill
             </HeadingLarge>
-            <ComponentTile name="Pill" href="/?path=/docs/pill--docs">
-                <View style={localStyles.grid}>
+
+            <ComponentTile
+                name="Pill"
+                href="/?path=/docs/pill--docs"
+                description={`Used to display a small amount of
+                    information, such as a tag or a status.`}
+            >
+                <View style={[styles.centerContent, localStyles.grid]}>
                     <View>
                         <Pill
                             kind="neutral"
diff --git a/__docs__/components/gallery/sections/popover-section.tsx b/__docs__/components/gallery/sections/popover-section.tsx
index c18d7f757..48b614f90 100644
--- a/__docs__/components/gallery/sections/popover-section.tsx
+++ b/__docs__/components/gallery/sections/popover-section.tsx
@@ -13,17 +13,21 @@ export default function PopoverSection() {
 
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge id="popover" tag="h3" style={styles.sectionLabel}>
                 Popover
             </HeadingLarge>
+
             <ComponentTile
                 name="Popover"
                 href="/?path=/docs/popover-popover--docs"
+                description={`Provides additional information that is
+                    related to a particular element and/or content.
+                    Must be dismissed by clicking an element.`}
             >
                 <View
-                    // Add an artificaial height to the view so that the popover
+                    // Add an artificial height to the view so that the popover
                     // doesn't overlap the description text.
-                    style={{height: 100}}
+                    style={{height: 120}}
                 />
                 <Popover
                     opened={opened}
diff --git a/__docs__/components/gallery/sections/progress-spinner-section.tsx b/__docs__/components/gallery/sections/progress-spinner-section.tsx
index 8d937f88b..6b7f877b3 100644
--- a/__docs__/components/gallery/sections/progress-spinner-section.tsx
+++ b/__docs__/components/gallery/sections/progress-spinner-section.tsx
@@ -10,12 +10,18 @@ import {styles} from "../styles";
 export default function ProgressSpinnerSection() {
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge
+                id="progress-spinner"
+                tag="h3"
+                style={styles.sectionLabel}
+            >
                 Progress Spinner
             </HeadingLarge>
             <ComponentTile
                 name="CircularSpinner"
                 href="/?path=/docs/progressspinner-circularspinner--docs"
+                description={`A circular spinner that can be used to
+                    indicate that a page or part of page is loading.`}
             >
                 <View style={styles.centerContent}>
                     <CircularSpinner />
diff --git a/__docs__/components/gallery/sections/search-field-section.tsx b/__docs__/components/gallery/sections/search-field-section.tsx
index fd463c70c..6123e340b 100644
--- a/__docs__/components/gallery/sections/search-field-section.tsx
+++ b/__docs__/components/gallery/sections/search-field-section.tsx
@@ -10,12 +10,19 @@ export default function SearchFieldSection() {
     const [value, setValue] = React.useState<string>("");
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge
+                id="search-field"
+                tag="h3"
+                style={styles.sectionLabel}
+            >
                 Search Field
             </HeadingLarge>
+
             <ComponentTile
                 name="SearchField"
                 href="/?path=/docs/searchfield--docs"
+                description={`A text field with a search icon at its start
+                    and an X icon at its end (when containing text).`}
             >
                 <SearchField
                     placeholder="Search for a topic"
diff --git a/__docs__/components/gallery/sections/switch-section.tsx b/__docs__/components/gallery/sections/switch-section.tsx
index ba7fd03ad..845537575 100644
--- a/__docs__/components/gallery/sections/switch-section.tsx
+++ b/__docs__/components/gallery/sections/switch-section.tsx
@@ -11,10 +11,16 @@ export default function BannerSection() {
     const [checked, setChecked] = React.useState<boolean>(false);
     return (
         <RenderStateRoot>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge id="switch" tag="h3" style={styles.sectionLabel}>
                 Switch
             </HeadingLarge>
-            <ComponentTile name="Switch" href="/?path=/docs/switch--docs">
+
+            <ComponentTile
+                name="Switch"
+                href="/?path=/docs/switch--docs"
+                description={`An input that allows users to toggle
+                    between two states (typically "on" and "off").`}
+            >
                 <View style={styles.centerContent}>
                     <Switch
                         checked={checked}
diff --git a/__docs__/components/gallery/sections/toolbar-section.tsx b/__docs__/components/gallery/sections/toolbar-section.tsx
index d49127620..b1131049b 100644
--- a/__docs__/components/gallery/sections/toolbar-section.tsx
+++ b/__docs__/components/gallery/sections/toolbar-section.tsx
@@ -13,10 +13,17 @@ import {styles} from "../styles";
 export default function ToolbarSection() {
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge id="toolbar" tag="h3" style={styles.sectionLabel}>
                 Toolbar
             </HeadingLarge>
-            <ComponentTile name="Toolbar" href="/?path=/docs/toolbar--docs">
+
+            <ComponentTile
+                name="Toolbar"
+                href="/?path=/docs/toolbar--docs"
+                description={`A generic toolbar wrapper that exposes
+                    customization options, including a title and left/right
+                    content.`}
+            >
                 <View>
                     <Toolbar
                         title="Counting with small numbers"
diff --git a/__docs__/components/gallery/sections/tooltip-section.tsx b/__docs__/components/gallery/sections/tooltip-section.tsx
index 997675e31..acb3c43e2 100644
--- a/__docs__/components/gallery/sections/tooltip-section.tsx
+++ b/__docs__/components/gallery/sections/tooltip-section.tsx
@@ -10,15 +10,22 @@ import {styles} from "../styles";
 export default function TooltipSection() {
     return (
         <>
-            <HeadingLarge tag="h3" style={styles.sectionLabel}>
+            <HeadingLarge id="tooltip" tag="h3" style={styles.sectionLabel}>
                 Tooltip
             </HeadingLarge>
 
             <ComponentTile
                 name="Tooltip"
                 href="/?path=/docs/tooltip-tooltip--docs"
+                description={`A text label that appears when a user hovers
+                    over or focuses on an element.`}
             >
                 <View style={styles.centerContent}>
+                    <View
+                        // Add an artificial height to the view so that the
+                        // tooltip doesn't overlap the description text.
+                        style={{height: 60}}
+                    />
                     <Tooltip
                         content="This is a text tooltip on the top"
                         opened={true}