From b4c940dce967b0fdbe15f06cff780bc3eca275dc Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Sun, 15 Dec 2024 21:52:47 +0000
Subject: [PATCH 1/3] Improve docs for Text + Heading

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 packages/canon/.storybook/preview.tsx         |  1 +
 packages/canon/docs/Iconography.mdx           |  4 +-
 packages/canon/docs/Layout.mdx                |  4 +-
 packages/canon/docs/Theme.mdx                 |  4 +-
 packages/canon/docs/Typography.mdx            | 48 +++++++++
 .../canon/docs/components/Chip/styles.css     |  2 +-
 .../canon/docs/components/Table/Table.tsx     | 10 +-
 .../canon/docs/components/Table/styles.css    | 16 +--
 .../canon/docs/components/Text/styles.css     | 21 +++-
 .../canon/docs/components/Title/styles.css    |  3 +-
 .../canon/src/components/Heading/Docs.mdx     | 79 +++++++++++++++
 .../components/Heading/Heading.stories.tsx    | 26 ++++-
 packages/canon/src/components/Text/Docs.mdx   | 98 +++++++++++++++++++
 .../src/components/Text/Text.stories.tsx      | 30 +++++-
 packages/canon/src/components/Text/styles.css | 23 +++++
 packages/canon/src/css/core.css               |  4 +-
 16 files changed, 350 insertions(+), 23 deletions(-)
 create mode 100644 packages/canon/docs/Typography.mdx
 create mode 100644 packages/canon/src/components/Heading/Docs.mdx
 create mode 100644 packages/canon/src/components/Text/Docs.mdx

diff --git a/packages/canon/.storybook/preview.tsx b/packages/canon/.storybook/preview.tsx
index aa8f3feb0e..db17d95afa 100644
--- a/packages/canon/.storybook/preview.tsx
+++ b/packages/canon/.storybook/preview.tsx
@@ -27,6 +27,7 @@ const preview: Preview = {
     options: {
       storySort: {
         method: 'alphabetical',
+        order: ['Core Concepts', 'Components'],
       },
     },
     viewport: {
diff --git a/packages/canon/docs/Iconography.mdx b/packages/canon/docs/Iconography.mdx
index 48cbd2e431..83d181af12 100644
--- a/packages/canon/docs/Iconography.mdx
+++ b/packages/canon/docs/Iconography.mdx
@@ -1,6 +1,8 @@
-import { Unstyled, Source } from '@storybook/blocks';
+import { Unstyled, Source, Meta } from '@storybook/blocks';
 import { Title, Text, IconLibrary } from './components';
 
+<Meta title="Core Concepts/Iconography" />
+
 <Unstyled>
 
 <Title type="h1">Iconography</Title>
diff --git a/packages/canon/docs/Layout.mdx b/packages/canon/docs/Layout.mdx
index 72344672b6..9145f71aed 100644
--- a/packages/canon/docs/Layout.mdx
+++ b/packages/canon/docs/Layout.mdx
@@ -1,7 +1,9 @@
-import { Unstyled, Source } from '@storybook/blocks';
+import { Unstyled, Source, Meta } from '@storybook/blocks';
 import { Title, Text, LayoutComponents } from './components';
 import * as Table from './components/Table';
 
+<Meta title="Core Concepts/Layout" />
+
 <Unstyled>
 
 <Title type="h1">Layout</Title>
diff --git a/packages/canon/docs/Theme.mdx b/packages/canon/docs/Theme.mdx
index 3d76b4e998..1ea7c5c4c6 100644
--- a/packages/canon/docs/Theme.mdx
+++ b/packages/canon/docs/Theme.mdx
@@ -1,7 +1,9 @@
-import { Unstyled, Source } from '@storybook/blocks';
+import { Unstyled, Source, Meta } from '@storybook/blocks';
 import { Title, Text, Chip } from './components';
 import * as Table from './components/Table';
 
+<Meta title="Core Concepts/Theming" />{' '}
+
 <Unstyled>
 
 <Title type="h1">Theming</Title>
diff --git a/packages/canon/docs/Typography.mdx b/packages/canon/docs/Typography.mdx
new file mode 100644
index 0000000000..802b9881be
--- /dev/null
+++ b/packages/canon/docs/Typography.mdx
@@ -0,0 +1,48 @@
+import { Unstyled, Meta, Canvas } from '@storybook/blocks';
+import {
+  Columns,
+  Text,
+  ComponentStatus,
+  Banner,
+  Title,
+  Roadmap,
+} from './components';
+import { list } from './components/Roadmap/list';
+import * as HeadingStories from '../src/components/Heading/Heading.stories';
+import * as TextStories from '../src/components/Text/Text.stories';
+
+<Meta title="Core Concepts/Typography" />
+
+<Unstyled>
+
+<Title type="h1">Typography</Title>
+<Text>
+  Canon offers a suite of typography components designed to seamlessly align
+  with the rest of your Backstage instance. While you can customize their
+  appearance to match your brand, the underlying API remains consistent and
+  unchanged. Each component is built on a responsive structure, allowing you to
+  define different typography values for various breakpoints.
+</Text>
+
+<Title type="h2">Heading</Title>
+<Text>
+  Headings are used to structure the content of your page. They are used to
+  create a hierarchy of information and to make the content more readable. The
+  best way to use add these headings to your page is to import the [Heading
+  component](?path=/docs/components-heading--docs).
+</Text>
+
+<Canvas of={HeadingStories.AllVariants} />
+
+<Title type="h2">Text</Title>
+<Text>
+  Canon provides four distinct text variants, each offering different font sizes
+  carefully designed to cover the majority of use cases. These variants are
+  versatile and can be paired with regular and bold of font weights. You can use
+  the [Text component](?path=/docs/components-text--docs) to add text to your
+  page.
+</Text>
+
+<Canvas of={TextStories.AllVariants} />
+
+</Unstyled>
diff --git a/packages/canon/docs/components/Chip/styles.css b/packages/canon/docs/components/Chip/styles.css
index ebbaf6645f..95cf7cef34 100644
--- a/packages/canon/docs/components/Chip/styles.css
+++ b/packages/canon/docs/components/Chip/styles.css
@@ -17,7 +17,7 @@
 .chip {
   display: inline-flex;
   align-items: center;
-  font-family: 'Geist Mono', monospace;
+  font-family: monospace;
   font-size: 13px;
   border-radius: 6px;
   padding: 0px 8px;
diff --git a/packages/canon/docs/components/Table/Table.tsx b/packages/canon/docs/components/Table/Table.tsx
index 4983038724..74a26a89af 100644
--- a/packages/canon/docs/components/Table/Table.tsx
+++ b/packages/canon/docs/components/Table/Table.tsx
@@ -18,8 +18,8 @@ import React from 'react';
 
 export const Root = ({ children }: { children: React.ReactNode }) => {
   return (
-    <div className="table-wrapper">
-      <table className="table">{children}</table>
+    <div className="sb-table-wrapper">
+      <table className="sb-table">{children}</table>
     </div>
   );
 };
@@ -37,13 +37,13 @@ export const HeaderRow = ({ children }: { children: React.ReactNode }) => {
 };
 
 export const HeaderCell = ({ children }: { children: React.ReactNode }) => {
-  return <th className="table-cell table-header-cell">{children}</th>;
+  return <th className="sb-table-cell sb-table-header-cell">{children}</th>;
 };
 
 export const Row = ({ children }: { children: React.ReactNode }) => {
-  return <tr className="table-row">{children}</tr>;
+  return <tr className="sb-table-row">{children}</tr>;
 };
 
 export const Cell = ({ children }: { children: React.ReactNode }) => {
-  return <td className="table-cell">{children}</td>;
+  return <td className="sb-table-cell">{children}</td>;
 };
diff --git a/packages/canon/docs/components/Table/styles.css b/packages/canon/docs/components/Table/styles.css
index a8c35d3978..fb9faf17eb 100644
--- a/packages/canon/docs/components/Table/styles.css
+++ b/packages/canon/docs/components/Table/styles.css
@@ -14,12 +14,14 @@
  * limitations under the License.
  */
 
-.table-wrapper {
+.sb-table-wrapper {
   border: 1px solid #e7e7e7;
   border-radius: 4px;
   overflow: hidden;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica,
+    Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol';
 
-  & .table {
+  & .sb-table {
     width: 100%;
     margin: 0 !important;
     padding: 0 !important;
@@ -27,7 +29,7 @@
     border-collapse: collapse;
   }
 
-  & .table-cell {
+  & .sb-table-cell {
     padding: 12px 16px !important;
     border: none !important;
     text-align: left;
@@ -41,14 +43,14 @@
     }
   }
 
-  & .table-header-cell {
+  & .sb-table-header-cell {
     background-color: #f5f5f5 !important;
     border-bottom: 1px solid #e7e7e7 !important;
     font-weight: 500;
     font-size: 14px;
   }
 
-  & .table-row {
+  & .sb-table-row {
     border: none;
     border-bottom: 1px solid #e7e7e7;
     &:last-child {
@@ -56,7 +58,7 @@
     }
   }
 
-  & .table-chip {
+  & .sb-table-chip {
     display: inline-block;
     font-size: 14px !important;
     border: 1px solid #e7e7e7;
@@ -65,7 +67,7 @@
     height: 24px;
   }
 
-  & .table-type {
+  & .sb-table-type {
     display: flex;
     flex-wrap: wrap;
     flex-direction: row;
diff --git a/packages/canon/docs/components/Text/styles.css b/packages/canon/docs/components/Text/styles.css
index 0092625c27..7255ea802b 100644
--- a/packages/canon/docs/components/Text/styles.css
+++ b/packages/canon/docs/components/Text/styles.css
@@ -15,7 +15,8 @@
  */
 
 .sb-text {
-  font-family: 'Geist', sans-serif;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica,
+    Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol';
   font-size: 16px;
   line-height: 28px;
   margin: 0;
@@ -23,10 +24,26 @@
   margin-bottom: 16px;
 
   & p {
-    font-family: 'Geist', sans-serif;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
+      Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji',
+      'Segoe UI Symbol';
     font-size: 16px;
     line-height: 28px;
     margin: 0;
     font-weight: 300;
   }
+
+  & code {
+    font-size: 13px;
+    color: #215cff;
+    background-color: #f1f3fc;
+    padding: 4px 4px;
+    border-radius: 4px;
+  }
+
+  & a {
+    color: #215cff;
+    text-decoration: none;
+    border-bottom: 1px solid #215cff;
+  }
 }
diff --git a/packages/canon/docs/components/Title/styles.css b/packages/canon/docs/components/Title/styles.css
index cfb0e6e379..6b4084cf3b 100644
--- a/packages/canon/docs/components/Title/styles.css
+++ b/packages/canon/docs/components/Title/styles.css
@@ -15,7 +15,8 @@
  */
 
 .sb-title {
-  font-family: 'Geist', sans-serif;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica,
+    Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol';
   margin: 0;
   font-weight: 500;
   border: none;
diff --git a/packages/canon/src/components/Heading/Docs.mdx b/packages/canon/src/components/Heading/Docs.mdx
new file mode 100644
index 0000000000..489c023bda
--- /dev/null
+++ b/packages/canon/src/components/Heading/Docs.mdx
@@ -0,0 +1,79 @@
+import { Canvas, Meta, Unstyled, Source } from '@storybook/blocks';
+import * as HeadingStories from './Heading.stories';
+import { Title, Text } from '../../../docs/components';
+import { PropsTable } from '../../../docs/components/PropsTable/PropsTable';
+
+<Meta of={HeadingStories} />
+
+<Unstyled>
+
+<Title type="h1">Heading</Title>
+
+<Text>Headings are used to structure the content of your page.</Text>
+
+<Canvas of={HeadingStories.Title1} />
+
+<Source of={HeadingStories.Title1} dark />
+
+<Title type="h2" style={{ marginBottom: '16px' }}>
+  API reference
+</Title>
+
+<PropsTable
+  data={{
+    variant: {
+      type: ['display', 'title1', 'title2', 'title3', 'title4', 'title5'],
+      responsive: true,
+    },
+    children: {
+      type: 'ReactNode',
+      responsive: false,
+    },
+    className: {
+      type: 'string',
+      responsive: false,
+    },
+    style: {
+      type: 'CSSProperties',
+      responsive: false,
+    },
+  }}
+/>
+
+<Title type="h2">Examples</Title>
+<Text>Here are some examples of how you can use the Heading component.</Text>
+
+<Title type="h3">All variants</Title>
+<Text>
+  The `Heading` component has a `variant` prop that can be used to change the
+  appearance of the heading.
+</Text>
+
+<Canvas of={HeadingStories.AllVariants} />
+
+<Source
+  code={`<Stack gap="md">
+  <Heading variant="title1">Title 1 Lorem ipsum dolor sit amet consectetur...</Heading>
+  <Heading variant="title2">Title 2 Lorem ipsum dolor sit amet consectetur...</Heading>
+  <Heading variant="title3">Title 3 Lorem ipsum dolor sit amet consectetur...</Heading>
+  <Heading variant="title4">Title 4 Lorem ipsum dolor sit amet consectetur...</Heading>
+  <Heading variant="title5">Title 5 Lorem ipsum dolor sit amet consectetur...</Heading>
+  <Heading variant="display">Display Lorem ipsum dolor sit amet consectetur...</Heading>
+</Stack>`}
+  language="tsx"
+  dark
+/>
+
+<Title type="h3">Responsive</Title>
+<Text>
+  You can also use the `variant` prop to change the appearance of the text based
+  on the screen size.
+</Text>
+
+<Source
+  code={`<Heading variant={{ xs: 'title1', md: 'title2' }}>Responsive Lorem ipsum dolor sit amet consectetur...</Heading>`}
+  language="tsx"
+  dark
+/>
+
+</Unstyled>
diff --git a/packages/canon/src/components/Heading/Heading.stories.tsx b/packages/canon/src/components/Heading/Heading.stories.tsx
index d93c7dbb59..ebd9737f89 100644
--- a/packages/canon/src/components/Heading/Heading.stories.tsx
+++ b/packages/canon/src/components/Heading/Heading.stories.tsx
@@ -14,8 +14,10 @@
  * limitations under the License.
  */
 
+import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import { Heading } from './Heading';
+import { Stack } from '../Stack';
 
 const meta = {
   title: 'Components/Heading',
@@ -31,11 +33,33 @@ export const Default: Story = {
   },
 };
 
+export const Title1: Story = {
+  args: {
+    children: 'Look mum, no hands!',
+    variant: 'title1',
+  },
+};
+
+export const AllVariants: Story = {
+  args: {
+    children: 'Heading',
+  },
+  render: () => (
+    <Stack gap="md">
+      <Heading variant="display">Display</Heading>
+      <Heading variant="title1">Title 1</Heading>
+      <Heading variant="title2">Title 2</Heading>
+      <Heading variant="title3">Title 3</Heading>
+      <Heading variant="title4">Title 4</Heading>
+    </Stack>
+  ),
+};
+
 export const Responsive: Story = {
   args: {
     ...Default.args,
     variant: {
-      // xs: 'title4',
+      xs: 'title4',
       sm: 'display',
     },
   },
diff --git a/packages/canon/src/components/Text/Docs.mdx b/packages/canon/src/components/Text/Docs.mdx
new file mode 100644
index 0000000000..0daf16891b
--- /dev/null
+++ b/packages/canon/src/components/Text/Docs.mdx
@@ -0,0 +1,98 @@
+import { Canvas, Meta, Unstyled, Source } from '@storybook/blocks';
+import * as TextStories from './Text.stories';
+import { Title, Text } from '../../../docs/components';
+import { PropsTable } from '../../../docs/components/PropsTable/PropsTable';
+
+<Meta of={TextStories} />
+
+<Unstyled>
+
+<Title type="h1">Text</Title>
+
+<Text>The `Text` component is used to display content on your page.</Text>
+
+<Canvas of={TextStories.Default} />
+
+<Source of={TextStories.Default} dark />
+
+<Title type="h2" style={{ marginBottom: '16px' }}>
+  API reference
+</Title>
+
+<PropsTable
+  data={{
+    variant: {
+      type: ['display', 'title1', 'title2', 'title3', 'title4', 'title5'],
+      responsive: true,
+    },
+    weight: {
+      type: ['regular', 'bold'],
+      responsive: true,
+    },
+    children: {
+      type: 'ReactNode',
+      responsive: false,
+    },
+    className: {
+      type: 'string',
+      responsive: false,
+    },
+    style: {
+      type: 'CSSProperties',
+      responsive: false,
+    },
+  }}
+/>
+
+<Title type="h2">Examples</Title>
+<Text>Here are some examples of how you can use the Text component.</Text>
+
+<Title type="h3">All variants</Title>
+<Text>
+  The `Text` component has a `variant` prop that can be used to change the
+  appearance of the text.
+</Text>
+
+<Canvas of={TextStories.AllVariants} />
+
+<Source
+  code={`<Stack gap="md">
+  <Text variant="subtitle">Subtitle Lorem ipsum dolor sit amet consectetur...</Text>
+  <Text variant="body">Body Lorem ipsum dolor sit amet consectetur...</Text>
+  <Text variant="caption">Caption Lorem ipsum dolor sit amet consectetur...</Text>
+  <Text variant="label">Label Lorem ipsum dolor sit amet consectetur...</Text>
+</Stack>`}
+  language="tsx"
+  dark
+/>
+
+<Title type="h3">All weights</Title>
+<Text>
+  The `Text` component has a `weight` prop that can be used to change the
+  appearance of the text.
+</Text>
+
+<Canvas of={TextStories.AllWeights} />
+
+<Source
+  code={`<Stack gap="md">
+  <Text weight="regular">Regular Lorem ipsum dolor sit amet consectetur...</Text>
+  <Text weight="bold">Bold Lorem ipsum dolor sit amet consectetur...</Text>
+</Stack>`}
+  language="tsx"
+  dark
+/>
+
+<Title type="h3">Responsive</Title>
+<Text>
+  You can also use the `variant` prop to change the appearance of the text based
+  on the screen size.
+</Text>
+
+<Source
+  code={`<Text variant={{ xs: 'label', md: 'body' }}>Responsive Lorem ipsum dolor sit amet consectetur...</Text>`}
+  language="tsx"
+  dark
+/>
+
+</Unstyled>
diff --git a/packages/canon/src/components/Text/Text.stories.tsx b/packages/canon/src/components/Text/Text.stories.tsx
index 82d6514764..2cde7ed553 100644
--- a/packages/canon/src/components/Text/Text.stories.tsx
+++ b/packages/canon/src/components/Text/Text.stories.tsx
@@ -14,8 +14,10 @@
  * limitations under the License.
  */
 
+import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import { Text } from './Text';
+import { Stack } from '../Stack';
 
 const meta = {
   title: 'Components/Text',
@@ -28,10 +30,36 @@ type Story = StoryObj<typeof meta>;
 export const Default: Story = {
   args: {
     children:
-      ' Lorem ipsum dolor sit amet consectetur. Nec arcu vel lacus magna adipiscing nisi mauris tortor viverra. Enim rhoncus quisque consectetur ligula diam ac lacus massa. Id interdum id pellentesque justo ut massa nibh amet. Odio massa in scelerisque tortor massa integer purus amet enim. Eros sit neque nullam facilisis. Purus massa dignissim aliquet purus eu in. Urna consequat ullamcorper arcu amet dictumst. Commodo praesent turpis fringilla tristique congue volutpat in. Nulla in nulla ultrices lacus. In ultrices id tellus ut. Semper duis in in non proin et pulvinar. Sit amet vulputate lorem sit ipsum quis amet pulvinar ultricies. Imperdiet enim molestie habitant eget. Aenean mollis aenean dolor sodales tempus blandit.',
+      'Lorem ipsum dolor sit amet consectetur. Nec arcu vel lacus magna adipiscing nisi mauris tortor viverra. Enim rhoncus quisque consectetur ligula diam ac lacus massa. Id interdum id pellentesque justo ut massa nibh amet. Odio massa in scelerisque tortor massa integer purus amet enim. Eros sit neque nullam facilisis. Purus massa dignissim aliquet purus eu in. Urna consequat ullamcorper arcu amet dictumst. Commodo praesent turpis fringilla tristique congue volutpat in. Nulla in nulla ultrices lacus. In ultrices id tellus ut.',
   },
 };
 
+export const AllVariants: Story = {
+  args: {
+    children: 'Text',
+  },
+  render: () => (
+    <Stack gap="md">
+      <Text variant="subtitle">Subtitle {Default.args?.children}</Text>
+      <Text variant="body">Body {Default.args?.children}</Text>
+      <Text variant="caption">Caption {Default.args?.children}</Text>
+      <Text variant="label">Label {Default.args?.children}</Text>
+    </Stack>
+  ),
+};
+
+export const AllWeights: Story = {
+  args: {
+    children: 'Text',
+  },
+  render: () => (
+    <Stack gap="md">
+      <Text weight="regular">Regular {Default.args?.children}</Text>
+      <Text weight="bold">Bold {Default.args?.children}</Text>
+    </Stack>
+  ),
+};
+
 export const Responsive: Story = {
   args: {
     ...Default.args,
diff --git a/packages/canon/src/components/Text/styles.css b/packages/canon/src/components/Text/styles.css
index 9e78481c97..9bf22ccab5 100644
--- a/packages/canon/src/components/Text/styles.css
+++ b/packages/canon/src/components/Text/styles.css
@@ -24,4 +24,27 @@
     font-size: var(--canon-font-size-body);
     line-height: 140%;
   }
+
+  &.text-subtitle {
+    font-size: var(--canon-font-size-subtitle);
+    line-height: 140%;
+  }
+
+  &.text-caption {
+    font-size: var(--canon-font-size-caption);
+    line-height: 140%;
+  }
+
+  &.text-label {
+    font-size: var(--canon-font-size-label);
+    line-height: 140%;
+  }
+
+  &.text-regular {
+    font-weight: var(--canon-font-weight-regular);
+  }
+
+  &.text-bold {
+    font-weight: var(--canon-font-weight-bold);
+  }
 }
diff --git a/packages/canon/src/css/core.css b/packages/canon/src/css/core.css
index e053b7dfb7..e47103b829 100644
--- a/packages/canon/src/css/core.css
+++ b/packages/canon/src/css/core.css
@@ -57,8 +57,8 @@ body {
   --canon-font-monospace: 'Monospace', monospace;
 
   /* Font weights */
-  --canon-font-normal: 400;
-  --canon-font-bold: 600;
+  --canon-font-weight-regular: 400;
+  --canon-font-weight-bold: 600;
 
   /* Font sizes */
   --canon-font-size-label: 0.625rem; /* 10px */

From 686be3fb61d052167d3cd04933c44836f45191c3 Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Sun, 15 Dec 2024 22:20:09 +0000
Subject: [PATCH 2/3] Improve usage on all components

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 packages/canon/src/components/Box/Docs.mdx    |  7 ++-
 packages/canon/src/components/Button/Docs.mdx |  6 ++-
 .../canon/src/components/Checkbox/Docs.mdx    |  6 ++-
 .../canon/src/components/Container/Docs.mdx   | 10 ++--
 packages/canon/src/components/Grid/Docs.mdx   | 23 +++------
 .../canon/src/components/Heading/Docs.mdx     |  6 ++-
 packages/canon/src/components/Icon/Docs.mdx   | 48 +++++++++++++++++++
 packages/canon/src/components/Icon/Icon.tsx   |  4 +-
 packages/canon/src/components/Icon/types.ts   |  6 +++
 packages/canon/src/components/Inline/Docs.mdx | 14 ++++--
 packages/canon/src/components/Stack/Docs.mdx  | 14 ++++--
 packages/canon/src/components/Text/Docs.mdx   |  5 +-
 12 files changed, 109 insertions(+), 40 deletions(-)
 create mode 100644 packages/canon/src/components/Icon/Docs.mdx

diff --git a/packages/canon/src/components/Box/Docs.mdx b/packages/canon/src/components/Box/Docs.mdx
index a03c6d43d3..af9cd9be76 100644
--- a/packages/canon/src/components/Box/Docs.mdx
+++ b/packages/canon/src/components/Box/Docs.mdx
@@ -16,8 +16,11 @@ import { spacingProperties } from '../../layout/sprinkles.css';
   of our components. It provides a consistent API for styling and layout.
 </Text>
 
-<Title type="h2">Installation</Title>
-<Source code={`import { Box } from "@backstage/canon";`} language="tsx" dark />
+<Title type="h2">Usage</Title>
+<Source code={`import { Box } from "@backstage/canon";
+
+<Box>Hello World!</Box>
+`} language="tsx" dark />
 
 <Title type="h2">API reference</Title>
 
diff --git a/packages/canon/src/components/Button/Docs.mdx b/packages/canon/src/components/Button/Docs.mdx
index 4ddce0c982..9f0e623c55 100644
--- a/packages/canon/src/components/Button/Docs.mdx
+++ b/packages/canon/src/components/Button/Docs.mdx
@@ -12,7 +12,11 @@ import { PropsTable } from '../../../docs/components/PropsTable/PropsTable';
 
 <Canvas of={ButtonStories.Primary} />
 
-<Source of={ButtonStories.Primary} dark />
+<Title type="h2">Usage</Title>
+<Source code={`import { Button } from "@backstage/canon";
+
+<Button>Click me</Button>
+`} language="tsx" dark />
 
 <Title type="h2" style={{ marginBottom: '16px' }}>
   API reference
diff --git a/packages/canon/src/components/Checkbox/Docs.mdx b/packages/canon/src/components/Checkbox/Docs.mdx
index 9d9b4e4915..12e13abf03 100644
--- a/packages/canon/src/components/Checkbox/Docs.mdx
+++ b/packages/canon/src/components/Checkbox/Docs.mdx
@@ -12,7 +12,11 @@ import { PropsTable } from '../../../docs/components/PropsTable';
 
 <Canvas of={CheckboxStories.Primary} />
 
-<Source of={CheckboxStories.Primary} dark />
+<Title type="h2">Usage</Title>
+<Source code={`import { Checkbox } from "@backstage/canon";
+
+<Checkbox label="Checkbox" />
+`} language="tsx" dark />
 
 <Title type="h2" style={{ marginBottom: '16px' }}>
   API reference
diff --git a/packages/canon/src/components/Container/Docs.mdx b/packages/canon/src/components/Container/Docs.mdx
index d4dcf694da..ca81477d44 100644
--- a/packages/canon/src/components/Container/Docs.mdx
+++ b/packages/canon/src/components/Container/Docs.mdx
@@ -15,12 +15,12 @@ import { containerProperties } from './sprinkles.css';
   content on the page.
 </Text>
 
-<Title type="h2">Installation</Title>
+<Title type="h2">Usage</Title>
 <Source
-  code={`import { Container } from "@backstage/canon";`}
-  language="tsx"
-  dark
-/>
+  code={`import { Container } from "@backstage/canon";
+
+<Container>Hello World!</Container>
+`} language="tsx" dark />
 
 <Title type="h2" style={{ marginBottom: '16px' }}>
   API reference
diff --git a/packages/canon/src/components/Grid/Docs.mdx b/packages/canon/src/components/Grid/Docs.mdx
index 7a4ef4de2f..14e3bfb922 100644
--- a/packages/canon/src/components/Grid/Docs.mdx
+++ b/packages/canon/src/components/Grid/Docs.mdx
@@ -13,24 +13,13 @@ import { spacingProperties } from '../../layout/sprinkles.css';
   more complex ones.
 </Text>
 
-<Title type="h2">Installation</Title>
-<Source code={`import { Grid } from "@backstage/canon";`} language="tsx" dark />
+<Title type="h2">Usage</Title>
+<Source code={`import { Grid } from "@backstage/canon";
 
-<Title type="h2">Anatomy</Title>
-<Text>
-  The grid component is made of two parts: the grid container and the grid item. Import all parts and piece them together.
-</Text>
-<Source
-  code={`import { Grid } from "@backstage/canon/grid";
-
-export default () => (
-  <Grid>
-    <Grid.Item />
-  </Grid>
-);`}
-  language="tsx"
-  dark
-/>
+<Grid>
+  <Grid.Item>Hello World</Grid.Item>
+</Grid>
+`} language="tsx" dark />
 
 <Title type="h2">API reference</Title>
 
diff --git a/packages/canon/src/components/Heading/Docs.mdx b/packages/canon/src/components/Heading/Docs.mdx
index 489c023bda..dd64bd59b2 100644
--- a/packages/canon/src/components/Heading/Docs.mdx
+++ b/packages/canon/src/components/Heading/Docs.mdx
@@ -13,7 +13,11 @@ import { PropsTable } from '../../../docs/components/PropsTable/PropsTable';
 
 <Canvas of={HeadingStories.Title1} />
 
-<Source of={HeadingStories.Title1} dark />
+<Title type="h2">Usage</Title>
+<Source code={`import { Heading } from "@backstage/canon";
+
+<Heading variant="title1">Hello World!</Heading>
+`} language="tsx" dark />
 
 <Title type="h2" style={{ marginBottom: '16px' }}>
   API reference
diff --git a/packages/canon/src/components/Icon/Docs.mdx b/packages/canon/src/components/Icon/Docs.mdx
new file mode 100644
index 0000000000..463fe60133
--- /dev/null
+++ b/packages/canon/src/components/Icon/Docs.mdx
@@ -0,0 +1,48 @@
+import { Canvas, Meta, Unstyled, Source } from '@storybook/blocks';
+import * as IconStories from './Icon.stories';
+import { Title, Text } from '../../../docs/components';
+import { PropsTable } from '../../../docs/components/PropsTable/PropsTable';
+import { defaultIcons } from './icons';
+
+<Meta of={IconStories} />
+
+<Unstyled>
+
+<Title type="h1">Icon</Title>
+
+<Text>Icons are used to represent an action or a state.</Text>
+
+<Canvas of={IconStories.Primary} />
+
+<Title type="h2">Usage</Title>
+<Source code={`import { Icon } from "@backstage/canon";
+
+<Icon name="icon-name" />
+`} language="tsx" dark />
+
+<Title type="h2" style={{ marginBottom: '16px' }}>
+  API reference
+</Title>
+
+<PropsTable
+  data={{
+    name: {
+      type: Object.keys(defaultIcons),
+      responsive: false,
+    },
+    size: {
+      type: 'number',
+      responsive: false,
+    },
+    className: {
+      type: 'string',
+      responsive: false,
+    },
+    style: {
+      type: 'CSSProperties',
+      responsive: false,
+    },
+  }}
+/>
+
+</Unstyled>
diff --git a/packages/canon/src/components/Icon/Icon.tsx b/packages/canon/src/components/Icon/Icon.tsx
index 587e3c0a23..a45cd6f27e 100644
--- a/packages/canon/src/components/Icon/Icon.tsx
+++ b/packages/canon/src/components/Icon/Icon.tsx
@@ -16,10 +16,10 @@
 
 import React from 'react';
 import { useTheme } from '../../theme/context';
-import type { IconNames } from './types';
+import type { IconProps } from './types';
 
 /** @public */
-export const Icon = (props: { name: IconNames; size?: number }) => {
+export const Icon = (props: IconProps) => {
   const { name, size = 16 } = props;
   const { icons } = useTheme();
 
diff --git a/packages/canon/src/components/Icon/types.ts b/packages/canon/src/components/Icon/types.ts
index bac853257b..a65a9f0913 100644
--- a/packages/canon/src/components/Icon/types.ts
+++ b/packages/canon/src/components/Icon/types.ts
@@ -36,3 +36,9 @@ export type IconNames =
 
 /** @public */
 export type IconMap = Partial<Record<IconNames, React.ComponentType>>;
+
+/** @public */
+export type IconProps = {
+  name: IconNames;
+  size?: number;
+};
diff --git a/packages/canon/src/components/Inline/Docs.mdx b/packages/canon/src/components/Inline/Docs.mdx
index 9850dedf7a..8ff19747f0 100644
--- a/packages/canon/src/components/Inline/Docs.mdx
+++ b/packages/canon/src/components/Inline/Docs.mdx
@@ -16,12 +16,16 @@ import { inlineProperties } from './sprinkles.css';
   responsively.
 </Text>
 
-<Title type="h2">Installation</Title>
+<Title type="h2">Usage</Title>
 <Source
-  code={`import { Inline } from "@backstage/canon";`}
-  language="tsx"
-  dark
-/>
+  code={`import { Inline } from "@backstage/canon";
+
+<Inline>
+  <Box>Hello World</Box>
+  <Box>Hello World</Box>
+  <Box>Hello World</Box>
+</Inline>
+`} language="tsx" dark />
 
 <Title type="h2" style={{ marginBottom: '16px' }}>
   API reference
diff --git a/packages/canon/src/components/Stack/Docs.mdx b/packages/canon/src/components/Stack/Docs.mdx
index d5bdb0fc82..f1776e0262 100644
--- a/packages/canon/src/components/Stack/Docs.mdx
+++ b/packages/canon/src/components/Stack/Docs.mdx
@@ -15,12 +15,16 @@ import { spacingProperties } from '../../layout/sprinkles.css';
   columns. All values are responsive.
 </Text>
 
-<Title type="h2">Installation</Title>
+<Title type="h2">Usage</Title>
 <Source
-  code={`import { Stack } from "@backstage/canon";`}
-  language="tsx"
-  dark
-/>
+  code={`import { Stack } from "@backstage/canon";
+
+<Stack>
+  <Box>Hello World</Box>
+  <Box>Hello World</Box>
+  <Box>Hello World</Box>
+</Stack>
+`} language="tsx" dark />
 
 <Title type="h2" style={{ marginBottom: '16px' }}>
   API reference
diff --git a/packages/canon/src/components/Text/Docs.mdx b/packages/canon/src/components/Text/Docs.mdx
index 0daf16891b..685a00a33f 100644
--- a/packages/canon/src/components/Text/Docs.mdx
+++ b/packages/canon/src/components/Text/Docs.mdx
@@ -13,7 +13,10 @@ import { PropsTable } from '../../../docs/components/PropsTable/PropsTable';
 
 <Canvas of={TextStories.Default} />
 
-<Source of={TextStories.Default} dark />
+<Title type="h2">Usage</Title>
+<Source code={`import { Text } from "@backstage/canon";
+
+<Text>Hello World!</Text>`} language="tsx" dark />
 
 <Title type="h2" style={{ marginBottom: '16px' }}>
   API reference

From efad846e9a7d508eccc269f10b743d4508f3f69c Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Sun, 15 Dec 2024 23:29:58 +0000
Subject: [PATCH 3/3] Update report.api.md

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 packages/canon/report.api.md | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/packages/canon/report.api.md b/packages/canon/report.api.md
index cba0983972..247965bc05 100644
--- a/packages/canon/report.api.md
+++ b/packages/canon/report.api.md
@@ -267,10 +267,7 @@ export interface GridProps extends SpaceProps, ColorProps {
 }
 
 // @public (undocumented)
-export const Icon: (props: {
-  name: IconNames;
-  size?: number;
-}) => React_2.JSX.Element;
+export const Icon: (props: IconProps) => React_2.JSX.Element;
 
 // @public (undocumented)
 export type IconMap = Partial<Record<IconNames, React.ComponentType>>;
@@ -295,6 +292,12 @@ export type IconNames =
   | 'plus'
   | 'trash';
 
+// @public (undocumented)
+export type IconProps = {
+  name: IconNames;
+  size?: number;
+};
+
 // @public (undocumented)
 export const Inline: ForwardRefExoticComponent<
   InlineProps & RefAttributes<HTMLElement>