Merge pull request #631 from buildo/typography-docs

Author: gabro

packages/bento-design-system/src/Typography/Title/Title.tsx

@@ -28,7 +28,12 @@ export function Title({
   ...boxProps
 }: Props) {
   return (
-    <Box {...boxProps} className={titleRecipe({ size, color, ellipsis })} textAlign={align}>
+    <Box
+      as="span"
+      {...boxProps}
+      className={titleRecipe({ size, color, ellipsis })}
+      textAlign={align}
+    >
       {children}
     </Box>
   );

packages/website/docs/04-Components/Body.mdx

@@ -0,0 +1,9 @@
+import ComponentDoc from "./_ComponentDoc.mdx";
+
+<ComponentDoc
+  name="Body"
+  examplePath="Typography/Body"
+  storybookStoryId="foundations-typography-body"
+  alternativeNames={["Text"]}
+  relatedComponents={["Display", "Headline", "Title", "Label"]}
+/>

packages/website/docs/04-Components/Display.mdx

@@ -0,0 +1,9 @@
+import ComponentDoc from "./_ComponentDoc.mdx";
+
+<ComponentDoc
+  name="Display"
+  examplePath="Typography/Display"
+  storybookStoryId="foundations-typography-display"
+  alternativeNames={[]}
+  relatedComponents={["Headline", "Title", "Label", "Body"]}
+/>

packages/website/docs/04-Components/Headline.mdx

@@ -0,0 +1,9 @@
+import ComponentDoc from "./_ComponentDoc.mdx";
+
+<ComponentDoc
+  name="Headline"
+  examplePath="Typography/Headline"
+  storybookStoryId="foundations-typography-headline"
+  alternativeNames={[]}
+  relatedComponents={["Display", "Title", "Label", "Body"]}
+/>

packages/website/docs/04-Components/Label.mdx

@@ -0,0 +1,9 @@
+import ComponentDoc from "./_ComponentDoc.mdx";
+
+<ComponentDoc
+  name="Label"
+  examplePath="Typography/Label"
+  storybookStoryId="foundations-typography-label"
+  alternativeNames={[]}
+  relatedComponents={["Display", "Headline", "Title", "Body"]}
+/>

packages/website/docs/04-Components/Title.mdx

@@ -0,0 +1,9 @@
+import ComponentDoc from "./_ComponentDoc.mdx";
+
+<ComponentDoc
+  name="Title"
+  examplePath="Typography/Title"
+  storybookStoryId="foundations-typography-title"
+  alternativeNames={[]}
+  relatedComponents={["Display", "Headline", "Label", "Body"]}
+/>

packages/website/docs/05-Guides/typography.mdx

@@ -0,0 +1,63 @@
+import { Canvas } from "@site/src/components/Canvas";
+
+# Typography
+
+Bento type scale organizes styles into five roles, semantically named to describe their purposes:
+
+- [Display](../components/Display): reserved for short, important text or numerals. Usually, they work best on large screens.
+- [Headline](../components/Headline): best suited for short, high-emphasis text. These styles can be suitable for marking primary text passages or important content regions.
+- [Title](../components/Title): used to divide secondary text passages or content regions.
+- [Body](../components/Body): used for longer passages of text and paragraphs.
+- [Label](../components/Label): utilitarian styles used for text inside of components or very small supporting text in the content body, like captions.
+
+## Usage
+
+You can use any of the typography components like this:
+
+<Canvas path="Typography/All" />
+
+## Font weight
+
+All typography components support a single (configurable) font weight, with the exception of `Body`, which has two weights: `"default"` and `"strong"`.
+
+`"default"` is the default weight, and `"strong"` is a heavier weight that can be used to emphasize certain parts of the text.
+
+<Canvas path="Typography/BodyWeights" />
+
+## Truncation
+
+All typography components support an optional `ellipsis` prop (defaulted to `false`), which causes the text to be truncated with an ellipsis when it overflows its container.
+
+<Canvas path="Typography/Ellipsis" />
+
+This feature uses standard CSS, so the truncation will be accessible (the entire text is still visible in the DOM node) and standard browser feature work as expected (e.g. try copy-pasting the truncated text and you'll see you'll get the full text).
+
+## Semantic HTML
+
+All typography components render as `<span>` by default. This behavior can be customized using the optional `as` prop.
+
+For example, you may want to render `Body` as a `<p>`:
+
+<Canvas path="Typography/BodyP" />
+
+Another example is using `Title` as a `<h2>`:
+
+<Canvas path="Typography/TitleH2" />
+
+## Localization and rich formatting
+
+Typography components accept either a `LocalizedString` (see [Type-safe localization](../Advanced/strict-localization)) or a complex React Node as children.
+
+If you need rich formatting, you can typically rely on the localization library you are using to create a React children node.
+
+For example, if you are using [react-i18next](https://react.i18next.com/), you can use the `Trans` component to create a React node:
+
+```tsx
+<Body size="medium">
+  <Trans i18nKey="My.Localization.Key" />
+</Body>
+```
+
+where the string matching `My.Localization.Key` can be along the lines of `Hello <b>World</b>!`
+
+You can read more about `Trans` component in the official [react-i18next documentation](https://react.i18next.com/latest/trans-component)

packages/website/src/snippets/Typography/All.tsx

@@ -0,0 +1,16 @@
+import * as React from "react";
+import { Body, Display, Headline, Label, Stack, Title } from "..";
+
+export default function AllExample() {
+  return (
+    <Stack space={16}>
+      <Display size="large">Hello, world! (Display)</Display>
+      <Headline size="large">Hello, world! (Headline)</Headline>
+      <Title size="large">Hello, world! (Title)</Title>
+      <Label size="large" color="primary">
+        Hello, world! (Label)
+      </Label>
+      <Body size="large">Hello, world! (Body)</Body>
+    </Stack>
+  );
+}

packages/website/src/snippets/Typography/Body.tsx

@@ -0,0 +1,6 @@
+import * as React from "react";
+import { Body } from "..";
+
+export default function BodyExample() {
+  return <Body size="large">The quick brown fox jumped over the lazy dog</Body>;
+}

packages/website/src/snippets/Typography/BodyP.tsx

@@ -0,0 +1,14 @@
+import * as React from "react";
+import { Body } from "..";
+
+export default function BodyExample() {
+  return (
+    <Body as="p" size="large" align="center">
+      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
+      labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
+      laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in
+      voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat
+      non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+    </Body>
+  );
+}

packages/website/src/snippets/Typography/BodyWeights.tsx

@@ -0,0 +1,13 @@
+import * as React from "react";
+import { Body, Stack } from "..";
+
+export default function BodyWeightsExample() {
+  return (
+    <Stack space={16}>
+      <Body size="large">Hello, world! (Body default)</Body>
+      <Body size="large" weight="strong">
+        Hello, world! (Body strong)
+      </Body>
+    </Stack>
+  );
+}

packages/website/src/snippets/Typography/Display.tsx

@@ -0,0 +1,6 @@
+import * as React from "react";
+import { Display } from "..";
+
+export default function DisplayExample() {
+  return <Display size="large">The quick brown fox jumped over the lazy dog</Display>;
+}

packages/website/src/snippets/Typography/Ellipsis.tsx

@@ -0,0 +1,17 @@
+import * as React from "react";
+import { Body, Box, Stack } from "..";
+
+export default function EllipsisExample() {
+  return (
+    <Stack space={16}>
+      <Box style={{ width: 200 }} background="softIndigo" padding={8}>
+        <Body size="large">Very long string which will NOT be truncated.</Body>
+      </Box>
+      <Box style={{ width: 200 }} background="softIndigo" padding={8}>
+        <Body size="large" ellipsis>
+          Very long string which WILL be truncated.
+        </Body>
+      </Box>
+    </Stack>
+  );
+}

packages/website/src/snippets/Typography/Headline.tsx

@@ -0,0 +1,6 @@
+import * as React from "react";
+import { Headline } from "..";
+
+export default function HeadlineExample() {
+  return <Headline size="large">The quick brown fox jumped over the lazy dog</Headline>;
+}

packages/website/src/snippets/Typography/Label.tsx

@@ -0,0 +1,10 @@
+import * as React from "react";
+import { Label } from "..";
+
+export default function LabelExample() {
+  return (
+    <Label size="large" color="primary">
+      The quick brown fox jumped over the lazy dog
+    </Label>
+  );
+}

packages/website/src/snippets/Typography/Title.tsx

@@ -0,0 +1,6 @@
+import * as React from "react";
+import { Title } from "..";
+
+export default function TitleExample() {
+  return <Title size="large">The quick brown fox jumped over the lazy dog</Title>;
+}

packages/website/src/snippets/Typography/TitleH2.tsx

@@ -0,0 +1,6 @@
+import * as React from "react";
+import { Title } from "..";
+
+export default function TitleExample() {
+  return <Title as="h2" size="large">{`A title which is rendered as <h2>`}</Title>;
+}