diff --git a/src/components/DocumentationTopic.vue b/src/components/DocumentationTopic.vue
index fc1debf06..56dc7e049 100644
--- a/src/components/DocumentationTopic.vue
+++ b/src/components/DocumentationTopic.vue
@@ -73,10 +73,11 @@
             />
           </div>
           <Topics
-            v-if="topicSections"
+            v-if="shouldRenderTopicSection"
             :sections="topicSections"
             :isSymbolDeprecated="isSymbolDeprecated"
             :isSymbolBeta="isSymbolBeta"
+            :topicStyle="topicSectionsStyle"
           />
           <DefaultImplementations
             v-if="defaultImplementationsSections"
@@ -113,6 +114,7 @@ import BetaLegalText from 'theme/components/DocumentationTopic/BetaLegalText.vue
 import LanguageSwitcher from 'theme/components/DocumentationTopic/Summary/LanguageSwitcher.vue';
 import DocumentationHero from 'docc-render/components/DocumentationTopic/DocumentationHero.vue';
 import WordBreak from 'docc-render/components/WordBreak.vue';
+import { TopicSectionsStyle } from '@/constants/TopicSectionsStyle';
 import OnThisPageNav from 'theme/components/OnThisPageNav.vue';
 import Abstract from './DocumentationTopic/Description/Abstract.vue';
 import ContentNode from './DocumentationTopic/ContentNode.vue';
@@ -238,6 +240,10 @@ export default {
       type: Array,
       required: false,
     },
+    topicSectionsStyle: {
+      type: String,
+      default: TopicSectionsStyle.list,
+    },
     sampleCodeDownload: {
       type: Object,
       required: false,
@@ -376,6 +382,10 @@ export default {
       const icon = pageImages.find(({ type }) => type === 'icon');
       return icon ? icon.identifier : null;
     },
+    shouldRenderTopicSection: ({
+      topicSectionsStyle,
+      topicSections,
+    }) => topicSections && topicSectionsStyle !== TopicSectionsStyle.hidden,
   },
   methods: {
     normalizePath(path) {
diff --git a/src/components/DocumentationTopic/ContentTableSection.vue b/src/components/DocumentationTopic/ContentTableSection.vue
index 93afc47fe..e2279fc53 100644
--- a/src/components/DocumentationTopic/ContentTableSection.vue
+++ b/src/components/DocumentationTopic/ContentTableSection.vue
@@ -11,10 +11,10 @@
 <template>
   <div class="contenttable-section">
     <div class="section-title">
-      <slot name="title">
+      <slot name="title" :className="className">
         <LinkableHeading
           :level="3"
-          class="title"
+          :class="className"
           :anchor="anchorComputed"
           :register-on-this-page="false"
         >{{ title }}</LinkableHeading>
@@ -32,6 +32,8 @@
 import LinkableHeading from 'docc-render/components/ContentNode/LinkableHeading.vue';
 import { anchorize } from 'docc-render/utils/strings';
 
+export const TITLE_CLASS_NAME = 'contenttable-title';
+
 export default {
   name: 'ContentTableSection',
   components: { LinkableHeading },
@@ -47,6 +49,7 @@ export default {
   },
   computed: {
     anchorComputed: ({ title, anchor }) => anchor || anchorize(title),
+    className: () => TITLE_CLASS_NAME,
   },
 };
 </script>
@@ -67,7 +70,7 @@ export default {
   }
 }
 
-/deep/ .title {
+/deep/ .contenttable-title {
   @include font-styles(label);
 }
 
@@ -86,7 +89,7 @@ export default {
     }
   }
 
-  /deep/ .title {
+  /deep/ .contenttable-title {
     margin: 0 0 $contenttable-spacing-single-side 0;
     padding-bottom: 0.5rem;
   }
diff --git a/src/components/DocumentationTopic/Topics.vue b/src/components/DocumentationTopic/Topics.vue
index 73372785e..e99300d10 100644
--- a/src/components/DocumentationTopic/Topics.vue
+++ b/src/components/DocumentationTopic/Topics.vue
@@ -15,10 +15,12 @@
     :isSymbolDeprecated="isSymbolDeprecated"
     :isSymbolBeta="isSymbolBeta"
     :sections="sections"
+    :topicStyle="topicStyle"
   />
 </template>
 
 <script>
+import { TopicSectionsStyle } from '@/constants/TopicSectionsStyle';
 import TopicsTable from './TopicsTable.vue';
 
 export default {
@@ -28,6 +30,11 @@ export default {
     isSymbolDeprecated: Boolean,
     isSymbolBeta: Boolean,
     sections: TopicsTable.props.sections,
+    topicStyle: {
+      type: String,
+      required: true,
+      validator: v => Object.hasOwnProperty.call(TopicSectionsStyle, v),
+    },
   },
 };
 </script>
diff --git a/src/components/DocumentationTopic/TopicsLinkCardGrid.vue b/src/components/DocumentationTopic/TopicsLinkCardGrid.vue
new file mode 100644
index 000000000..5f44d69e3
--- /dev/null
+++ b/src/components/DocumentationTopic/TopicsLinkCardGrid.vue
@@ -0,0 +1,48 @@
+<!--
+  This source file is part of the Swift.org open source project
+
+  Copyright (c) 2022 Apple Inc. and the Swift project authors
+  Licensed under Apache License v2.0 with Runtime Library Exception
+
+  See https://swift.org/LICENSE.txt for license information
+  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+-->
+
+<template>
+  <div class="TopicsLinkCardGrid">
+    <Row :columns="compactCards ? 3 : 2">
+      <Column
+        v-for="item in items"
+        :key="item.title"
+      >
+        <TopicsLinkCardGridItem :item="item" :compact="compactCards" />
+      </Column>
+    </Row>
+  </div>
+</template>
+
+<script>
+import Row from 'docc-render/components/ContentNode/Row.vue';
+import Column from 'docc-render/components/ContentNode/Column.vue';
+import { TopicSectionsStyle } from '@/constants/TopicSectionsStyle';
+import TopicsLinkCardGridItem from './TopicsLinkCardGridItem.vue';
+
+export default {
+  name: 'TopicsLinkCardGrid',
+  components: { TopicsLinkCardGridItem, Column, Row },
+  props: {
+    items: {
+      type: Array,
+      required: true,
+    },
+    topicStyle: {
+      type: String,
+      default: TopicSectionsStyle.compactGrid,
+      validator: v => v === TopicSectionsStyle.compactGrid || v === TopicSectionsStyle.detailedGrid,
+    },
+  },
+  computed: {
+    compactCards: ({ topicStyle }) => topicStyle === TopicSectionsStyle.compactGrid,
+  },
+};
+</script>
diff --git a/src/components/DocumentationTopic/TopicsLinkCardGridItem.vue b/src/components/DocumentationTopic/TopicsLinkCardGridItem.vue
new file mode 100644
index 000000000..ac6c574f7
--- /dev/null
+++ b/src/components/DocumentationTopic/TopicsLinkCardGridItem.vue
@@ -0,0 +1,95 @@
+<!--
+  This source file is part of the Swift.org open source project
+
+  Copyright (c) 2022 Apple Inc. and the Swift project authors
+  Licensed under Apache License v2.0 with Runtime Library Exception
+
+  See https://swift.org/LICENSE.txt for license information
+  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+-->
+
+<template>
+  <Card
+    class="reference-card-grid-item"
+    :url="item.url"
+    :image="imageReferences.card"
+    :title="item.title"
+    floating-style
+    :size="cardSize"
+    :link-text="linkText"
+  >
+    <template v-if="!imageReferences.card" #cover="{ classes }">
+      <div :class="classes" class="reference-card-grid-item__image">
+        <TopicTypeIcon
+          :type="item.role"
+          :image-override="references[imageReferences.icon]"
+          class="reference-card-grid-item__icon"
+        />
+      </div>
+    </template>
+    <ContentNode v-if="!compact" :content="item.abstract" />
+  </Card>
+</template>
+
+<script>
+import Card from 'docc-render/components/Card.vue';
+import TopicTypeIcon from 'docc-render/components/TopicTypeIcon.vue';
+import { TopicRole } from 'docc-render/constants/roles';
+import CardSize from 'docc-render/constants/CardSize';
+
+export const ROLE_LINK_TEXT = {
+  [TopicRole.article]: 'Read article',
+  [TopicRole.overview]: 'Start tutorial',
+  [TopicRole.collection]: 'View API collection',
+  [TopicRole.symbol]: 'View symbol',
+  [TopicRole.sampleCode]: 'View sample code',
+};
+
+export default {
+  name: 'TopicsLinkCardGridItem',
+  components: {
+    TopicTypeIcon,
+    Card,
+    ContentNode: () => import('docc-render/components/ContentNode.vue'),
+  },
+  inject: ['references'],
+  props: {
+    item: {
+      type: Object,
+      required: true,
+    },
+    compact: {
+      type: Boolean,
+      default: true,
+    },
+  },
+  computed: {
+    imageReferences: ({ item }) => (item.images || []).reduce((all, current) => {
+      // eslint-disable-next-line no-param-reassign
+      all[current.type] = current.identifier;
+      return all;
+    }, { icon: null, card: null }),
+    linkText: ({ compact, item }) => (compact ? '' : (ROLE_LINK_TEXT[item.role] || 'Learn more')),
+    cardSize: ({ compact }) => (compact ? undefined : CardSize.large),
+  },
+};
+</script>
+
+<style scoped lang='scss'>
+@import 'docc-render/styles/_core.scss';
+
+.reference-card-grid-item {
+  &__image {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 80px;
+    background-color: var(--color-fill-gray-quaternary);
+  }
+
+  &__icon {
+    display: flex;
+    margin: 0;
+  }
+}
+</style>
diff --git a/src/components/DocumentationTopic/TopicsTable.vue b/src/components/DocumentationTopic/TopicsTable.vue
index 450a202e4..373ccde5f 100644
--- a/src/components/DocumentationTopic/TopicsTable.vue
+++ b/src/components/DocumentationTopic/TopicsTable.vue
@@ -16,11 +16,11 @@
       :title="section.title"
       :anchor="section.anchor"
     >
-      <template v-if="wrapTitle" slot="title">
+      <template v-if="wrapTitle" #title="{ className }">
         <LinkableHeading
           :level="3"
           :anchor="section.anchor"
-          class="title"
+          :class="className"
           :register-on-this-page="false"
         >
           <WordBreak>{{ section.title }}</WordBreak>
@@ -32,13 +32,21 @@
       <template v-if="section.discussion" slot="discussion">
         <ContentNode :content="section.discussion.content" />
       </template>
-      <TopicsLinkBlock
-        v-for="topic in section.topics"
+      <template v-if="shouldRenderList">
+        <TopicsLinkBlock
+          v-for="topic in section.topics"
+          class="topic"
+          :key="topic.identifier"
+          :topic="topic"
+          :isSymbolDeprecated="isSymbolDeprecated"
+          :isSymbolBeta="isSymbolBeta"
+        />
+      </template>
+      <TopicsLinkCardGrid
+        v-else
+        :items="section.topics"
+        :topicStyle="topicStyle"
         class="topic"
-        :key="topic.identifier"
-        :topic="topic"
-        :isSymbolDeprecated="isSymbolDeprecated"
-        :isSymbolBeta="isSymbolBeta"
       />
     </ContentTableSection>
   </ContentTable>
@@ -47,6 +55,8 @@
 <script>
 import ContentNode from 'docc-render/components/DocumentationTopic/ContentNode.vue';
 import WordBreak from 'docc-render/components/WordBreak.vue';
+import { TopicSectionsStyle } from '@/constants/TopicSectionsStyle';
+import TopicsLinkCardGrid from 'docc-render/components/DocumentationTopic/TopicsLinkCardGrid.vue';
 import LinkableHeading from 'docc-render/components/ContentNode/LinkableHeading.vue';
 import ContentTable from './ContentTable.vue';
 import ContentTableSection from './ContentTableSection.vue';
@@ -62,6 +72,7 @@ export default {
     },
   },
   components: {
+    TopicsLinkCardGrid,
     WordBreak,
     ContentTable,
     TopicsLinkBlock,
@@ -94,8 +105,13 @@ export default {
       type: Boolean,
       default: false,
     },
+    topicStyle: {
+      type: String,
+      default: TopicSectionsStyle.list,
+    },
   },
   computed: {
+    shouldRenderList: ({ topicStyle }) => topicStyle === TopicSectionsStyle.list,
     sectionsWithTopics() {
       return this.sections.map(section => ({
         ...section,
diff --git a/src/constants/TopicSectionsStyle.js b/src/constants/TopicSectionsStyle.js
new file mode 100644
index 000000000..cfb56ea04
--- /dev/null
+++ b/src/constants/TopicSectionsStyle.js
@@ -0,0 +1,17 @@
+/**
+ * This source file is part of the Swift.org open source project
+ *
+ * Copyright (c) 2022 Apple Inc. and the Swift project authors
+ * Licensed under Apache License v2.0 with Runtime Library Exception
+ *
+ * See https://swift.org/LICENSE.txt for license information
+ * See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+/* eslint-disable import/prefer-default-export */
+export const TopicSectionsStyle = {
+  list: 'list',
+  compactGrid: 'compactGrid',
+  detailedGrid: 'detailedGrid',
+  hidden: 'hidden',
+};
diff --git a/src/views/DocumentationTopic.vue b/src/views/DocumentationTopic.vue
index 8aee967af..6a270ea43 100644
--- a/src/views/DocumentationTopic.vue
+++ b/src/views/DocumentationTopic.vue
@@ -187,6 +187,7 @@ export default {
         relationshipsSections,
         references = {},
         sampleCodeDownload,
+        topicSectionsStyle,
         topicSections,
         seeAlsoSections,
         variantOverrides,
@@ -212,6 +213,7 @@ export default {
         sampleCodeDownload,
         title,
         topicSections,
+        topicSectionsStyle,
         seeAlsoSections,
         variantOverrides,
         symbolKind,
diff --git a/tests/unit/components/DocumentationTopic.spec.js b/tests/unit/components/DocumentationTopic.spec.js
index e6fdf5efb..fa2d5a783 100644
--- a/tests/unit/components/DocumentationTopic.spec.js
+++ b/tests/unit/components/DocumentationTopic.spec.js
@@ -13,6 +13,7 @@ import DocumentationTopic from 'docc-render/components/DocumentationTopic.vue';
 import Language from 'docc-render/constants/Language';
 import { TopicTypes } from '@/constants/TopicTypes';
 import DocumentationHero from '@/components/DocumentationTopic/DocumentationHero.vue';
+import { TopicSectionsStyle } from '@/constants/TopicSectionsStyle';
 import OnThisPageNav from '@/components/OnThisPageNav.vue';
 import OnThisPageStickyContainer from '@/components/DocumentationTopic/OnThisPageStickyContainer.vue';
 
@@ -462,7 +463,7 @@ describe('DocumentationTopic', () => {
     });
   });
 
-  it('renders `Topics` if there are topic sections', () => {
+  it('renders `Topics` if there are topic sections, passing the `topicSectionStyles` over', () => {
     expect(wrapper.contains(Topics)).toBe(false);
 
     const topicSections = [
@@ -478,11 +479,23 @@ describe('DocumentationTopic', () => {
         identifiers: ['baz'],
       },
     ];
-    wrapper.setProps({ topicSections });
+    wrapper.setProps({ topicSections, topicSectionsStyle: TopicSectionsStyle.detailedGrid });
 
     const topics = wrapper.find(Topics);
     expect(topics.exists()).toBe(true);
     expect(topics.props('sections')).toBe(topicSections);
+    expect(topics.props('topicStyle')).toBe(TopicSectionsStyle.detailedGrid);
+  });
+
+  it('does not render the `Topics` if the `topicSectionsStyle` is `hidden`', () => {
+    const topicSections = [
+      {
+        title: 'Baz',
+        identifiers: ['baz'],
+      },
+    ];
+    wrapper.setProps({ topicSections, topicSectionsStyle: 'hidden' });
+    expect(wrapper.find(Topics).exists()).toBe(false);
   });
 
   it('renders `SeeAlso` if there are see also sections', () => {
diff --git a/tests/unit/components/DocumentationTopic/ContentTableSection.spec.js b/tests/unit/components/DocumentationTopic/ContentTableSection.spec.js
index e1e5c4146..70f802b9e 100644
--- a/tests/unit/components/DocumentationTopic/ContentTableSection.spec.js
+++ b/tests/unit/components/DocumentationTopic/ContentTableSection.spec.js
@@ -9,7 +9,9 @@
 */
 
 import { shallowMount } from '@vue/test-utils';
-import ContentTableSection from 'docc-render/components/DocumentationTopic/ContentTableSection.vue';
+import ContentTableSection, {
+  TITLE_CLASS_NAME,
+} from 'docc-render/components/DocumentationTopic/ContentTableSection.vue';
 
 const {
   LinkableHeading,
@@ -34,12 +36,12 @@ describe('ContentTableSection', () => {
     expect(title.exists()).toBe(true);
     expect(title.props('level')).toBe(3);
     expect(title.props('registerOnThisPage')).toBe(false);
-    expect(title.classes('title')).toBe(true);
+    expect(title.classes()).toContain(TITLE_CLASS_NAME);
     expect(title.text()).toContain(propsData.title);
   });
 
   it('renders an `id` if `anchor` is provided', () => {
-    const title = wrapper.find('.title');
+    const title = wrapper.find(`.${TITLE_CLASS_NAME}`);
     expect(title.attributes('id')).toBe(undefined);
     wrapper.setProps({
       anchor: 'foo-bar',
@@ -50,12 +52,12 @@ describe('ContentTableSection', () => {
   it('renders a slot for a title', () => {
     wrapper = shallowMount(ContentTableSection, {
       propsData,
-      slots: {
-        title: '<div class="title">Title Text</div>',
+      scopedSlots: {
+        title: '<div :class="props.className">Title Text</div>',
       },
     });
     const div = wrapper.find('.section-title');
-    const title = div.find('.title');
+    const title = div.find(`.${TITLE_CLASS_NAME}`);
     expect(title.text()).toEqual('Title Text');
   });
 
diff --git a/tests/unit/components/DocumentationTopic/DefaultImplementations.spec.js b/tests/unit/components/DocumentationTopic/DefaultImplementations.spec.js
index 4bc331958..36c0c77ac 100644
--- a/tests/unit/components/DocumentationTopic/DefaultImplementations.spec.js
+++ b/tests/unit/components/DocumentationTopic/DefaultImplementations.spec.js
@@ -10,6 +10,7 @@
 
 import { shallowMount } from '@vue/test-utils';
 import DefaultImplementations from 'docc-render/components/DocumentationTopic/DefaultImplementations.vue';
+import { TopicSectionsStyle } from '@/constants/TopicSectionsStyle';
 
 const { TopicsTable } = DefaultImplementations.components;
 
@@ -41,6 +42,7 @@ describe('DefaultImplementations', () => {
       isSymbolBeta: false,
       title: 'Default Implementations',
       wrapTitle: true,
+      topicStyle: TopicSectionsStyle.list,
     });
   });
 });
diff --git a/tests/unit/components/DocumentationTopic/SeeAlso.spec.js b/tests/unit/components/DocumentationTopic/SeeAlso.spec.js
index 1f69321b0..bffccadcf 100644
--- a/tests/unit/components/DocumentationTopic/SeeAlso.spec.js
+++ b/tests/unit/components/DocumentationTopic/SeeAlso.spec.js
@@ -10,6 +10,7 @@
 
 import { shallowMount } from '@vue/test-utils';
 import SeeAlso from 'docc-render/components/DocumentationTopic/SeeAlso.vue';
+import { TopicSectionsStyle } from '@/constants/TopicSectionsStyle';
 
 const { TopicsTable } = SeeAlso.components;
 
@@ -26,6 +27,7 @@ describe('SeeAlso', () => {
       sections: [],
       title: 'See Also',
       wrapTitle: false,
+      topicStyle: TopicSectionsStyle.list,
     });
   });
 });
diff --git a/tests/unit/components/DocumentationTopic/Topics.spec.js b/tests/unit/components/DocumentationTopic/Topics.spec.js
index cca8e9621..490cc2ffa 100644
--- a/tests/unit/components/DocumentationTopic/Topics.spec.js
+++ b/tests/unit/components/DocumentationTopic/Topics.spec.js
@@ -10,12 +10,18 @@
 
 import { shallowMount } from '@vue/test-utils';
 import Topics from 'docc-render/components/DocumentationTopic/Topics.vue';
+import { TopicSectionsStyle } from '@/constants/TopicSectionsStyle';
 
 const { TopicsTable } = Topics.components;
 
 describe('Topics', () => {
   it('renders a `TopicsTable` with appropriate anchor/title', () => {
-    const wrapper = shallowMount(Topics, { propsData: { sections: [] } });
+    const wrapper = shallowMount(Topics, {
+      propsData: {
+        sections: [],
+        topicStyle: TopicSectionsStyle.list,
+      },
+    });
 
     const table = wrapper.find(TopicsTable);
     expect(table.exists()).toBe(true);
@@ -26,10 +32,13 @@ describe('Topics', () => {
       sections: [],
       title: 'Topics',
       wrapTitle: false,
+      topicStyle: TopicSectionsStyle.list,
     });
     table.setProps({ isSymbolDeprecated: true });
     expect(table.props('isSymbolDeprecated')).toBe(true);
     table.setProps({ isSymbolBeta: true });
     expect(table.props('isSymbolBeta')).toBe(true);
+    table.setProps({ topicStyle: TopicSectionsStyle.compactGrid });
+    expect(table.props('topicStyle')).toBe(TopicSectionsStyle.compactGrid);
   });
 });
diff --git a/tests/unit/components/DocumentationTopic/TopicsLinkCardGrid.spec.js b/tests/unit/components/DocumentationTopic/TopicsLinkCardGrid.spec.js
new file mode 100644
index 000000000..2c11dcf88
--- /dev/null
+++ b/tests/unit/components/DocumentationTopic/TopicsLinkCardGrid.spec.js
@@ -0,0 +1,59 @@
+/**
+ * This source file is part of the Swift.org open source project
+ *
+ * Copyright (c) 2021 Apple Inc. and the Swift project authors
+ * Licensed under Apache License v2.0 with Runtime Library Exception
+ *
+ * See https://swift.org/LICENSE.txt for license information
+ * See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import TopicsLinkCardGrid from '@/components/DocumentationTopic/TopicsLinkCardGrid.vue';
+import { shallowMount } from '@vue/test-utils';
+import { TopicSectionsStyle } from '@/constants/TopicSectionsStyle';
+import Row from '@/components/ContentNode/Row.vue';
+import Column from '@/components/ContentNode/Column.vue';
+import TopicsLinkCardGridItem from '@/components/DocumentationTopic/TopicsLinkCardGridItem.vue';
+
+const ref1 = { identifier: 'ref1' };
+const ref2 = { identifier: 'ref2' };
+
+const defaultProps = {
+  items: [ref1, ref2],
+};
+
+const createWrapper = ({ propsData, ...others } = {}) => shallowMount(TopicsLinkCardGrid, {
+  propsData: {
+    ...defaultProps,
+    ...propsData,
+  },
+  ...others,
+});
+
+describe('TopicsLinkCardGrid', () => {
+  it('renders the TopicsLinkCardGrid', () => {
+    const wrapper = createWrapper();
+    expect(wrapper.find(Row).props()).toEqual({
+      columns: 3, // compact grid is a 3 column setup
+    });
+    const cols = wrapper.findAll(Column);
+    expect(cols).toHaveLength(2);
+    expect(cols.at(0).find(TopicsLinkCardGridItem).props()).toEqual({
+      item: ref1,
+      compact: true,
+    });
+  });
+
+  it('renders as a `detailedGrid`', () => {
+    const wrapper = createWrapper({
+      propsData: {
+        ...defaultProps,
+        topicStyle: TopicSectionsStyle.detailedGrid,
+      },
+    });
+    expect(wrapper.find(Row).props()).toEqual({
+      columns: 2, // detailed grid is a 2 column setup
+    });
+    expect(wrapper.find(TopicsLinkCardGridItem).props('compact')).toBe(false);
+  });
+});
diff --git a/tests/unit/components/DocumentationTopic/TopicsLinkCardGridItem.spec.js b/tests/unit/components/DocumentationTopic/TopicsLinkCardGridItem.spec.js
new file mode 100644
index 000000000..5f7430bc8
--- /dev/null
+++ b/tests/unit/components/DocumentationTopic/TopicsLinkCardGridItem.spec.js
@@ -0,0 +1,169 @@
+/**
+ * This source file is part of the Swift.org open source project
+ *
+ * Copyright (c) 2021 Apple Inc. and the Swift project authors
+ * Licensed under Apache License v2.0 with Runtime Library Exception
+ *
+ * See https://swift.org/LICENSE.txt for license information
+ * See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import { mount } from '@vue/test-utils';
+import Card from '@/components/Card.vue';
+import { TopicRole } from '@/constants/roles';
+import TopicTypeIcon from '@/components/TopicTypeIcon.vue';
+import TopicsLinkCardGridItem, {
+  ROLE_LINK_TEXT,
+} from '@/components/DocumentationTopic/TopicsLinkCardGridItem.vue';
+import ContentNode from 'docc-render/components/ContentNode.vue';
+
+const defaultProps = {
+  item: {
+    url: 'http://foo.com',
+    images: [{
+      type: 'card',
+      identifier: 'card-reference',
+    }],
+    title: 'Foo',
+    abstract: [{ type: 'text', text: 'Content' }],
+    role: TopicRole.article,
+  },
+};
+
+const iconRef = {
+  identifier: 'iconRef',
+  variants: [{
+    url: 'path/to/icon',
+    traits: [
+      '2x',
+      'light',
+    ],
+  }],
+};
+const references = {
+  iconRef,
+  'card-reference': {
+    variants: [{
+      url: '/path/to/card',
+      traits: [
+        '2x',
+        'light',
+      ],
+    }],
+  },
+};
+
+const createWrapper = ({ propsData, ...others } = {}) => mount(TopicsLinkCardGridItem, {
+  propsData: {
+    ...defaultProps,
+    ...propsData,
+  },
+  provide: { references },
+  ...others,
+});
+
+describe('TopicsLinkCardGridItem', () => {
+  it('renders the TopicsLinkCardGridItem', () => {
+    const wrapper = createWrapper();
+    const card = wrapper.find(Card);
+    expect(card.props()).toMatchObject({
+      url: defaultProps.item.url,
+      image: defaultProps.item.images[0].identifier,
+      title: defaultProps.item.title,
+      floatingStyle: true,
+      size: undefined,
+      linkText: '',
+    });
+    expect(wrapper.find('.reference-card-grid-item__image').exists()).toBe(false);
+    expect(wrapper.find(ContentNode).exists()).toBe(false);
+  });
+
+  it('renders a TopicsLinkCardGridItem, with an icon as a fallback', () => {
+    const wrapper = createWrapper({
+      propsData: {
+        item: {
+          ...defaultProps.item,
+          images: [],
+        },
+      },
+    });
+    const card = wrapper.find(Card);
+    expect(card.props()).toMatchObject({
+      url: defaultProps.item.url,
+      image: null,
+      title: defaultProps.item.title,
+      floatingStyle: true,
+      size: undefined,
+      linkText: '',
+    });
+    expect(wrapper.find(ContentNode).exists()).toBe(false);
+    const imageWrapper = wrapper.find('.reference-card-grid-item__image');
+    expect(imageWrapper.exists()).toBe(true);
+    const icon = imageWrapper.find(TopicTypeIcon);
+    expect(icon.props()).toEqual({
+      type: defaultProps.item.role,
+      imageOverride: null,
+      withColors: false,
+    });
+  });
+
+  it('renders the TopicsLinkCardGridItem, with a specific icon override', () => {
+    const wrapper = createWrapper({
+      propsData: {
+        item: {
+          ...defaultProps.item,
+          images: [{
+            type: 'icon',
+            identifier: iconRef.identifier,
+          }],
+        },
+      },
+    });
+    expect(wrapper.find(TopicTypeIcon).props('imageOverride')).toEqual(iconRef);
+  });
+
+  it('renders a TopicsLinkCardGridItem, in a none compact variant', async () => {
+    const wrapper = createWrapper({
+      propsData: {
+        ...defaultProps,
+        compact: false,
+      },
+    });
+    await wrapper.vm.$nextTick();
+    const card = wrapper.find(Card);
+    expect(card.props()).toMatchObject({
+      url: defaultProps.item.url,
+      image: defaultProps.item.images[0].identifier,
+      title: defaultProps.item.title,
+      floatingStyle: true,
+      size: 'large',
+      linkText: ROLE_LINK_TEXT[TopicRole.article],
+    });
+    expect(wrapper.find(ContentNode).props('content')).toBe(defaultProps.item.abstract);
+  });
+
+  it('renders different text for diff roles', () => {
+    const wrapper = createWrapper({
+      propsData: {
+        ...defaultProps,
+        compact: false,
+        item: { ...defaultProps.item, role: TopicRole.overview },
+      },
+    });
+    // overview
+    const card = wrapper.find(Card);
+    expect(card.props('linkText')).toBe(ROLE_LINK_TEXT[TopicRole.overview]);
+    // collection
+    wrapper.setProps({ item: { ...defaultProps.item, role: TopicRole.collection } });
+    expect(card.props('linkText')).toBe(ROLE_LINK_TEXT[TopicRole.collection]);
+    // symbol
+    wrapper.setProps({ item: { ...defaultProps.item, role: TopicRole.symbol } });
+    expect(card.props('linkText')).toBe(ROLE_LINK_TEXT[TopicRole.symbol]);
+    // sampleCode
+    wrapper.setProps({ item: { ...defaultProps.item, role: TopicRole.sampleCode } });
+    expect(card.props('linkText')).toBe(ROLE_LINK_TEXT[TopicRole.sampleCode]);
+    // other
+    wrapper.setProps({ item: { ...defaultProps.item, role: TopicRole.link } });
+    expect(card.props('linkText')).toBe('Learn more');
+  });
+});
diff --git a/tests/unit/components/DocumentationTopic/TopicsTable.spec.js b/tests/unit/components/DocumentationTopic/TopicsTable.spec.js
index 325cd3f76..49e79a45d 100644
--- a/tests/unit/components/DocumentationTopic/TopicsTable.spec.js
+++ b/tests/unit/components/DocumentationTopic/TopicsTable.spec.js
@@ -10,6 +10,8 @@
 
 import { shallowMount } from '@vue/test-utils';
 import TopicsTable from 'docc-render/components/DocumentationTopic/TopicsTable.vue';
+import { TopicSectionsStyle } from '@/constants/TopicSectionsStyle';
+import TopicsLinkCardGrid from '@/components/DocumentationTopic/TopicsLinkCardGrid.vue';
 
 const {
   ContentTable, TopicsLinkBlock, ContentTableSection, ContentNode, WordBreak, LinkableHeading,
@@ -64,6 +66,9 @@ describe('TopicsTable', () => {
     wrapper = shallowMount(TopicsTable, {
       propsData,
       provide,
+      stubs: {
+        ContentTableSection,
+      },
     });
   });
 
@@ -85,6 +90,7 @@ describe('TopicsTable', () => {
 
   it('renders a `TopicsLinkBlock` for each topic with reference data in a section', () => {
     const sections = wrapper.findAll(ContentTableSection);
+    expect(wrapper.findAll(TopicsLinkCardGrid)).toHaveLength(0);
 
     const firstSectionBlocks = sections.at(0).findAll(TopicsLinkBlock);
     expect(firstSectionBlocks.length).toBe(1);
@@ -105,6 +111,26 @@ describe('TopicsTable', () => {
     });
   });
 
+  it('renders a `TopicsLinkCardGrid` if `topicStyle` is not `list`', () => {
+    wrapper.setProps({ topicStyle: TopicSectionsStyle.compactGrid });
+    expect(wrapper.findAll(TopicsLinkBlock)).toHaveLength(0);
+    const sections = wrapper.findAll(ContentTableSection);
+
+    const firstGrid = sections.at(0).find(TopicsLinkCardGrid);
+    expect(firstGrid.classes('topic')).toBe(true);
+    expect(firstGrid.props()).toEqual({
+      topicStyle: TopicSectionsStyle.compactGrid,
+      items: [foo],
+    });
+
+    const secondGrid = sections.at(1).find(TopicsLinkCardGrid);
+    expect(secondGrid.classes('topic')).toBe(true);
+    expect(secondGrid.props()).toEqual({
+      topicStyle: TopicSectionsStyle.compactGrid,
+      items: [baz],
+    });
+  });
+
   it('can be passed `title` and `anchor` overrides', () => {
     wrapper.setProps({
       anchor: 'foo-bar',
@@ -150,5 +176,6 @@ describe('TopicsTable', () => {
     expect(linkableHeading.props('level')).toBe(3);
     expect(linkableHeading.props('registerOnThisPage')).toBe(false);
     expect(linkableHeading.attributes('anchor')).toBe(propsData.sections[0].anchor);
+    expect(linkableHeading.classes()).toContain('contenttable-title');
   });
 });
diff --git a/tests/unit/views/DocumentationTopic.spec.js b/tests/unit/views/DocumentationTopic.spec.js
index ff35bea80..0b19dcae6 100644
--- a/tests/unit/views/DocumentationTopic.spec.js
+++ b/tests/unit/views/DocumentationTopic.spec.js
@@ -17,6 +17,7 @@ import AdjustableSidebarWidth from '@/components/AdjustableSidebarWidth.vue';
 import NavigatorDataProvider from '@/components/Navigator/NavigatorDataProvider.vue';
 import Language from '@/constants/Language';
 import Navigator from '@/components/Navigator.vue';
+import { TopicSectionsStyle } from '@/constants/TopicSectionsStyle';
 import { storage } from '@/utils/storage';
 import { BreakpointName } from 'docc-render/utils/breakpoints';
 import StaticContentWidth from 'docc-render/components/DocumentationTopic/StaticContentWidth.vue';
@@ -541,6 +542,7 @@ describe('DocumentationTopic', () => {
         swift: ['documentation/swift'],
       },
       enableOnThisPageNav: false,
+      topicSectionsStyle: TopicSectionsStyle.list, // default value
     });
   });
 
@@ -567,6 +569,18 @@ describe('DocumentationTopic', () => {
     expect(wrapper.find(Topic).props('enableOnThisPageNav')).toBe(true);
   });
 
+  it('passes `topicSectionsStyle`', () => {
+    wrapper.setData({
+      topicData: {
+        ...topicData,
+        topicSectionsStyle: TopicSectionsStyle.detailedGrid,
+      },
+    });
+
+    const topic = wrapper.find(Topic);
+    expect(topic.props('topicSectionsStyle')).toEqual(TopicSectionsStyle.detailedGrid);
+  });
+
   it('provides an empty languagePaths, even if no variants', () => {
     wrapper.setData({
       topicData: {