Updated documentation for Typography (#2324)

apps/website/src/content/docs/typography.mdx

@@ -1,17 +1,63 @@
 ---
 title: Typography
-description:
+description: Typography components provide consistency in text styling across the application.
 thumbnail: Typography
 ---
 
 <p>{frontmatter.description}</p>
 
-<Placeholder componentPageName='text--basic' />
-
 ## Text
 
-<LiveExample src='Text.main.jsx' truncate={false}>
-  <AllExamples.TextMainExample client:load />
+`Text` is a [polymorphic](#polymorphic-only-semantics-and-not-size) typography component that can be used to render any kind of text as any kind of element.
+
+```jsx
+<Text>This is a text.</Text>
+```
+
+By default, the `Text` component renders a `<div>` element with the regular `"body"` size. The visuals of this component are completely separate from its semantics, which helps ensure proper [heading structure](https://www.w3.org/WAI/tutorials/page-structure/headings/).
+
+- **Visuals**: The `variant` prop can be used to customize the the size (e.g. `variant="subheading"`).
+- **Semantics**: The polymorphic `as` prop can be used to render a different element (e.g. `as="h2"`).
+
+### Variant (Only size and not semantics)
+
+The `variant` prop can be used to determine the size of the text. The available variants are (from largest to smallest):
+
+1. `"headline"`.
+2. `"title"`.
+3. `"subheading"`.
+4. `"leading"`.
+5. `"body"` (default).
+6. `"smaller"`.
+
+<LiveExample src='Text.variant.jsx'>
+  <AllExamples.TextVariantExample client:load />
+</LiveExample>
+
+Please note that the `variant` prop only affects the visual size and is completely decoupled from the semantics, which can be controlled using the `as` prop (see below).
+
+### Polymorphic (Only semantics and not size)
+
+The `Text` component supports the polymorphic `as` prop, which can be used to change the underlying HTML element. This is useful when you want to render the text as a specific heading level while maintaining a desired size.
+
+<LiveExample src='Text.polymorphic.jsx' truncate={false}>
+  <AllExamples.TextPolymorphicExample client:load />
+</LiveExample>
+
+### Muted
+
+To achieve a muted or desaturated text effect, the `isMuted` prop can be passed into the component. Muted text helps differentiating less important information as well as enhancing the overall readability.
+
+<LiveExample src='Text.muted.jsx' truncate={false}>
+  <AllExamples.TextMutedExample client:load />
+</LiveExample>
+
+### Skeleton
+
+To indicate that content is loading and will be available soon, you can use the `isSkeleton` prop along with the `variant` prop. This will display a placeholder for any text that is still loading. If no `variant` is specified, the skeleton will default to the size of `"body"` text.
+
+<LiveExample src='Text.skeleton.jsx'>
+  <AllExamples.TextSkeletonExample client:load />
 </LiveExample>
 
 ### Props
@@ -20,12 +66,31 @@ thumbnail: Typography
 
 ## Label
 
-<Placeholder componentPageName='label--basic' />
+`Label` corresponds to an HTML `<label>` and can be linked to an `Input` by matching `Label`'s `htmlFor` with `Input`'s `id` for better accessibility, ensuring assistive technologies correctly identify their relationship.
 
-<LiveExample src='Label.main.jsx' truncate={false}>
+<LiveExample src='Label.main.jsx'>
   <AllExamples.LabelMainExample client:load />
 </LiveExample>
 
+### Required
+
+To make the form field required, you can pass the `required` prop. This also adds the `*` next to the label.
+
+<LiveExample src='Label.required.jsx'>
+  <AllExamples.LabelRequiredExample client:load />
+</LiveExample>
+
+### Display style
+
+There are two available display styles:
+
+- `"block"` (default): places the label and the other fields on separate lines without adding any extra spacing.
+- `"inline"`: displays the label inline with other elements by adding a right margin to it.
+
+<LiveExample src='Label.displayStyles.jsx'>
+  <AllExamples.LabelDisplayStylesExample client:load />
+</LiveExample>
+
 ### Props
 
 <PropsTable path='@itwin/itwinui-react/esm/core/Label/Label.d.ts' />

examples/Label.displayStyles.css

@@ -0,0 +1,6 @@
+.demo-container {
+  display: flex;
+  flex-direction: column;
+  gap: var(--iui-size-xs);
+  width: 300px;
+}

examples/Label.displayStyles.jsx

@@ -0,0 +1,21 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { InputGrid, Input, Label, LabeledSelect } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <div className='demo-container'>
+      <InputGrid>
+        <Label displayStyle='block'>Block label</Label>
+        <Input />
+      </InputGrid>
+      <InputGrid labelPlacement='inline'>
+        <Label displayStyle='inline'>Inline label</Label>
+        <Input />
+      </InputGrid>
+    </div>
+  );
+};

examples/Label.main.css

@@ -0,0 +1,3 @@
+.demo-container {
+  width: 300px;
+}

examples/Label.main.jsx

@@ -3,8 +3,13 @@
  * See LICENSE.md in the project root for license terms and full copyright notice.
  *--------------------------------------------------------------------------------------------*/
 import * as React from 'react';
-import { Label } from '@itwin/itwinui-react';
+import { Flex, Input, Label } from '@itwin/itwinui-react';
 
 export default () => {
-  return <Label>This is label.</Label>;
+  return (
+    <>
+      <Label htmlFor='text-input'>Name:</Label>
+      <Input id='text-input' placeholder='Enter name' />
+    </>
+  );
 };

examples/Label.required.jsx

@@ -0,0 +1,17 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { Input, Label } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <div className='demo-container'>
+      <Label htmlFor='text-input' required>
+        Name:
+      </Label>
+      <Input id='text-input' placeholder='Enter name' />
+    </div>
+  );
+};

examples/Text.muted.jsx

@@ -0,0 +1,15 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { Flex, Text } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <Flex flexDirection='column'>
+      <Text>This is a regular text</Text>
+      <Text isMuted>This is a muted text</Text>
+    </Flex>
+  );
+};

examples/Text.main.jsx → examples/Text.polymorphic.jsx

@@ -6,5 +6,9 @@ import * as React from 'react';
 import { Text } from '@itwin/itwinui-react';
 
 export default () => {
-  return <Text variant='body'>This is text</Text>;
+  return (
+    <Text variant='subheading' as='h1'>
+      This is a subheading rendered as an h1.
+    </Text>
+  );
 };

examples/Text.skeleton.jsx

@@ -0,0 +1,29 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { Flex, Text } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <Flex flexDirection='column'>
+      <Text isSkeleton variant='headline'>
+        This is a skeleton text
+      </Text>
+      <Text isSkeleton variant='title'>
+        This is a skeleton text
+      </Text>
+      <Text isSkeleton variant='subheading'>
+        This is a skeleton text
+      </Text>
+      <Text isSkeleton variant='leading'>
+        This is a skeleton text
+      </Text>
+      <Text isSkeleton>This is a skeleton text</Text>
+      <Text isSkeleton variant='small'>
+        This is a skeleton text
+      </Text>
+    </Flex>
+  );
+};

examples/Text.variant.jsx

@@ -0,0 +1,19 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { Flex, Text } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <Flex flexDirection='column'>
+      <Text variant='headline'>This is a headline</Text>
+      <Text variant='title'>This is a title</Text>
+      <Text variant='subheading'>This is a subheading</Text>
+      <Text variant='leading'>This is a leading</Text>
+      <Text>This is a body</Text>
+      <Text variant='small'>This is a small text</Text>
+    </Flex>
+  );
+};

examples/index.tsx

@@ -777,6 +777,16 @@ import { default as LabelMainExampleRaw } from './Label.main';
 const LabelMainExample = withThemeProvider(LabelMainExampleRaw);
 export { LabelMainExample };
 
+import { default as LabelRequiredExampleRaw } from './Label.required';
+const LabelRequiredExample = withThemeProvider(LabelRequiredExampleRaw);
+export { LabelRequiredExample };
+
+import { default as LabelDisplayStylesExampleRaw } from './Label.displayStyles';
+const LabelDisplayStylesExample = withThemeProvider(
+  LabelDisplayStylesExampleRaw,
+);
+export { LabelDisplayStylesExample };
+
 // ----------------------------------------------------------------------------
 
 import { default as LinkActionMainExampleRaw } from './LinkAction.main';
@@ -1306,9 +1316,21 @@ export { TextareaInlineExample };
 
 // ----------------------------------------------------------------------------
 
-import { default as TextMainExampleRaw } from './Text.main';
-const TextMainExample = withThemeProvider(TextMainExampleRaw);
-export { TextMainExample };
+import { default as TextVariantExampleRaw } from './Text.variant';
+const TextVariantExample = withThemeProvider(TextVariantExampleRaw);
+export { TextVariantExample };
+
+import { default as TextMutedExampleRaw } from './Text.muted';
+const TextMutedExample = withThemeProvider(TextMutedExampleRaw);
+export { TextMutedExample };
+
+import { default as TextSkeletonExampleRaw } from './Text.skeleton';
+const TextSkeletonExample = withThemeProvider(TextSkeletonExampleRaw);
+export { TextSkeletonExample };
+
+import { default as TextPolymorphicExampleRaw } from './Text.polymorphic';
+const TextPolymorphicExample = withThemeProvider(TextPolymorphicExampleRaw);
+export { TextPolymorphicExample };
 
 // ----------------------------------------------------------------------------