Improve docs for Text + Heading

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>

packages/canon/.storybook/preview.tsx

@@ -27,6 +27,7 @@ const preview: Preview = {
     options: {
       storySort: {
         method: 'alphabetical',
+        order: ['Core Concepts', 'Components'],
       },
     },
     viewport: {

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>

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>

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>

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>

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;

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

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;

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;
+  }
 }

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;

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>

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',
     },
   },

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>

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,

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

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 */