@ceed/cds 1.22.3 → 1.22.4

package/dist/components/data-display/Typography.md

@@ -4,6 +4,8 @@
 
 The Typography component is a core component for displaying text. It is based on Joy UI Typography and provides a variety of text levels and styles. You can apply consistent typography across all text elements such as headings, body text, and labels.
 
+CDS extends the default typography system with **marketing levels** (`marketing-lg`, `marketing-md`, `marketing-sm`) for landing pages and promotional content, and uses **Poppins** as the display font family.
+
 ```tsx
 <Typography children="Typography" />
 ```
@@ -16,7 +18,7 @@ The Typography component is a core component for displaying text. It is based on
 ## Usage
 
 ```tsx
-import { Typography } from '@ceed/ads';
+import { Typography } from '@ceed/cds';
 
 function MyComponent() {
   return (
@@ -33,20 +35,126 @@ function MyComponent() {
 
 ## Typography Levels
 
+### Overview
+
+Typography levels are divided into four groups: **Headings**, **Titles**, **Body**, and **Marketing**. The default level is `body-md`.
+
+- **Headings** (`h1`–`h4`): Used for page and section headings. Uses the display font family (Poppins).
+- **Titles** (`title-lg`, `title-md`, `title-sm`): Used for UI labels, card titles, and emphasized text. Uses the body font family (Inter).
+- **Body** (`body-lg`, `body-md`, `body-sm`, `body-xs`): Used for readable content and descriptions. Uses the body font family (Inter).
+- **Marketing** (`marketing-lg`, `marketing-md`, `marketing-sm`): Used for landing pages, hero banners, and promotional content. Uses the display font family (Poppins).
+
+```tsx
+<>
+  <Stack direction="row" spacing={2}>
+    <Typography level="h1">h1</Typography>
+    <Typography {...args} level="h1" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="h2">h2</Typography>
+    <Typography {...args} level="h2" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="h3">h3</Typography>
+    <Typography {...args} level="h3" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="h4">h4</Typography>
+    <Typography {...args} level="h4" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="title-lg">title-lg</Typography>
+    <Typography {...args} level="title-lg" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="title-md">title-md</Typography>
+    <Typography {...args} level="title-md" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="title-sm">title-sm</Typography>
+    <Typography {...args} level="title-sm" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="body-lg">body-lg</Typography>
+    <Typography {...args} level="body-lg" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="body-md">body-md</Typography>
+    <Typography {...args} level="body-md" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="body-sm">body-sm</Typography>
+    <Typography {...args} level="body-sm" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="body-xs">body-xs</Typography>
+    <Typography {...args} level="body-xs" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="marketing-lg">marketing-lg</Typography>
+    <Typography {...args} level="marketing-lg" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="marketing-md">marketing-md</Typography>
+    <Typography {...args} level="marketing-md" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="marketing-sm">marketing-sm</Typography>
+    <Typography {...args} level="marketing-sm" />
+  </Stack>
+</>
+```
+
+### Style Reference
+
+| Level        | Font Family       | Font Size       | Font Weight    | Line Height | Letter Spacing | Default Color  | HTML Tag |
+| ------------ | ----------------- | --------------- | -------------- | ----------- | -------------- | -------------- | -------- |
+| h1           | display (Poppins) | 2.25rem (36px)  | 700 (Bold)     | 1.333       | -0.025em       | text.primary   | `<h1>`   |
+| h2           | display (Poppins) | 1.875rem (30px) | 700 (Bold)     | 1.333       | -0.025em       | text.primary   | `<h2>`   |
+| h3           | display (Poppins) | 1.5rem (24px)   | 600 (SemiBold) | 1.333       | -0.025em       | text.primary   | `<h3>`   |
+| h4           | display (Poppins) | 1.25rem (20px)  | 600 (SemiBold) | 1.5         | -0.025em       | text.primary   | `<h4>`   |
+| title-lg     | body (Inter)      | 1.125rem (18px) | 600 (SemiBold) | 1.333       | -              | text.primary   | `<p>`    |
+| title-md     | body (Inter)      | 1rem (16px)     | 500 (Medium)   | 1.5         | -              | text.primary   | `<p>`    |
+| title-sm     | body (Inter)      | 0.875rem (14px) | 500 (Medium)   | 1.429       | -              | text.primary   | `<p>`    |
+| body-lg      | body (Inter)      | 1.125rem (18px) | inherit        | 1.5         | -              | text.secondary | `<p>`    |
+| body-md      | body (Inter)      | 1rem (16px)     | inherit        | 1.5         | -              | text.secondary | `<p>`    |
+| body-sm      | body (Inter)      | 0.875rem (14px) | inherit        | 1.5         | -              | text.tertiary  | `<p>`    |
+| body-xs      | body (Inter)      | 0.75rem (12px)  | 500 (Medium)   | 1.5         | -              | text.tertiary  | `<span>` |
+| marketing-lg | display (Poppins) | 2.625rem (42px) | 600 (SemiBold) | 1.333       | -0.025em       | text.primary   | `<div>`  |
+| marketing-md | display (Poppins) | 2rem (32px)     | 600 (SemiBold) | 1.333       | -0.025em       | text.primary   | `<div>`  |
+| marketing-sm | display (Poppins) | 1.5rem (24px)   | 500 (Medium)   | 1.333       | -0.025em       | text.primary   | `<div>`  |
+
 ### Headings
 
-Levels for headings. Use them to clearly define page structure.
+Heading levels define page structure and hierarchy. In CDS, they use the **Poppins** display font family with heavier weights for visual prominence.
+
+```tsx
+<>
+  <Typography level="h1">h1 - Main page heading</Typography>
+  <Typography level="h2">h2 - Section heading</Typography>
+  <Typography level="h3">h3 - Subsection heading</Typography>
+  <Typography level="h4">h4 - Detail heading</Typography>
+</>
+```
 
 ```tsx
 <Typography level="h1">H1 - Main page heading</Typography>
 <Typography level="h2">H2 - Section heading</Typography>
 <Typography level="h3">H3 - Subsection heading</Typography>
-<Typography level="h4">H4 - Detailed heading</Typography>
+<Typography level="h4">H4 - Detail heading</Typography>
 ```
 
 ### Titles
 
-Used for important titles or emphasized text.
+Title levels are used for UI labels, card titles, and other emphasized text that is not a document heading.
+
+```tsx
+<>
+  <Typography level="title-lg">title-lg - Large title</Typography>
+  <Typography level="title-md">title-md - Medium title</Typography>
+  <Typography level="title-sm">title-sm - Small title</Typography>
+</>
+```
 
 ```tsx
 <Typography level="title-lg">Large Title</Typography>
@@ -56,7 +164,16 @@ Used for important titles or emphasized text.
 
 ### Body Text
 
-Levels for body text. Use these for most readable content.
+Body levels are used for readable content and descriptions. The default level `body-md` is suitable for most body text. Use `body-xs` sparingly for auxiliary information like timestamps or counters.
+
+```tsx
+<>
+  <Typography level="body-lg">body-lg - Large body text</Typography>
+  <Typography level="body-md">body-md - Regular body text</Typography>
+  <Typography level="body-sm">body-sm - Small body text</Typography>
+  <Typography level="body-xs">body-xs - Extra small text</Typography>
+</>
+```
 
 ```tsx
 <Typography level="body-lg">Large body text</Typography>
@@ -65,6 +182,221 @@ Levels for body text. Use these for most readable content.
 <Typography level="body-xs">Extra small text</Typography>
 ```
 
+### Marketing Levels
+
+Marketing levels are designed for landing pages, hero banners, and promotional content. They use the **Poppins** display font family for a distinctive marketing look.
+
+```tsx
+<>
+  <Typography level="marketing-lg">
+    marketing-lg - Large marketing text
+  </Typography>
+  <Typography level="marketing-md">
+    marketing-md - Medium marketing text
+  </Typography>
+  <Typography level="marketing-sm">
+    marketing-sm - Small marketing text
+  </Typography>
+</>
+```
+
+```tsx
+<Typography level="marketing-lg">Large marketing text</Typography>
+<Typography level="marketing-md">Medium marketing text</Typography>
+<Typography level="marketing-sm">Small marketing text</Typography>
+```
+
+## Design Token Reference
+
+### Font Size Scale
+
+| Token | Value           |
+| ----- | --------------- |
+| xs    | 0.75rem (12px)  |
+| sm    | 0.875rem (14px) |
+| md    | 1rem (16px)     |
+| lg    | 1.125rem (18px) |
+| xl    | 1.25rem (20px)  |
+| xl2   | 1.5rem (24px)   |
+| xl3   | 1.875rem (30px) |
+| xl4   | 2.25rem (36px)  |
+
+### Font Weight Scale
+
+| Token | Value          |
+| ----- | -------------- |
+| sm    | 300 (Light)    |
+| md    | 500 (Medium)   |
+| lg    | 600 (SemiBold) |
+| xl    | 700 (Bold)     |
+
+### Line Height Scale
+
+| Token | Value |
+| ----- | ----- |
+| xs    | 1.333 |
+| sm    | 1.429 |
+| md    | 1.5   |
+| lg    | 1.556 |
+| xl    | 1.667 |
+
+### Font Families
+
+- **body**: `"Inter"`, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif
+- **display**: `"Poppins"`, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif
+- **code**: `"Source Code Pro"`, ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace
+
+## Colors
+
+Typography supports five semantic colors via the `color` prop. Use `textColor` to apply any palette color directly.
+
+```tsx
+<>
+  <Typography color="primary">Primary color</Typography>
+  <Typography color="neutral">Neutral color</Typography>
+  <Typography color="danger">Danger color</Typography>
+  <Typography color="success">Success color</Typography>
+  <Typography color="warning">Warning color</Typography>
+</>
+```
+
+```tsx
+<Typography color="primary">Primary color</Typography>
+<Typography color="neutral">Neutral color</Typography>
+<Typography color="danger">Danger color</Typography>
+<Typography color="success">Success color</Typography>
+<Typography color="warning">Warning color</Typography>
+
+{/* Use textColor for specific palette values */}
+<Typography textColor="neutral.600">Custom palette color</Typography>
+```
+
+## Component Prop
+
+Use the `component` prop to render Typography as a different HTML element or React component. Each level has a default HTML tag mapping shown below.
+
+```tsx
+<>
+  <Typography level="h1" component="h2">
+    h1 style rendered as h2 tag
+  </Typography>
+  <Typography level="body-md" component="span">
+    body-md rendered as span
+  </Typography>
+  <Typography level="title-md" component="label">
+    title-md rendered as label
+  </Typography>
+</>
+```
+
+```tsx
+<Typography level="h1" component="h2">
+  h1 style rendered as an h2 tag
+</Typography>
+
+<Typography level="body-md" component="span">
+  Inline text
+</Typography>
+
+<Typography level="title-md" component="label">
+  Rendered as a label element
+</Typography>
+```
+
+**Default HTML tag mapping:**
+
+| Level        | Default HTML Tag |
+| ------------ | ---------------- |
+| h1           | `<h1>`           |
+| h2           | `<h2>`           |
+| h3           | `<h3>`           |
+| h4           | `<h4>`           |
+| title-lg     | `<p>`            |
+| title-md     | `<p>`            |
+| title-sm     | `<p>`            |
+| body-lg      | `<p>`            |
+| body-md      | `<p>`            |
+| body-sm      | `<p>`            |
+| body-xs      | `<span>`         |
+| marketing-lg | `<div>`          |
+| marketing-md | `<div>`          |
+| marketing-sm | `<div>`          |
+
+## Decorators
+
+Use `startDecorator` and `endDecorator` to add icons or other elements before or after the text.
+
+```tsx
+<>
+  <Typography startDecorator={<InfoOutlined />}>
+    Text with start decorator
+  </Typography>
+  <Typography endDecorator={<ArrowForward />}>
+    Text with end decorator
+  </Typography>
+  <Typography startDecorator={<InfoOutlined />} endDecorator={<ArrowForward />}>
+    Text with both decorators
+  </Typography>
+</>
+```
+
+```tsx
+import InfoOutlined from '@mui/icons-material/InfoOutlined';
+import ArrowForward from '@mui/icons-material/ArrowForward';
+
+<Typography startDecorator={<InfoOutlined />}>
+  Text with start decorator
+</Typography>
+
+<Typography endDecorator={<ArrowForward />}>
+  Text with end decorator
+</Typography>
+
+<Typography startDecorator={<InfoOutlined />} endDecorator={<ArrowForward />}>
+  Text with both decorators
+</Typography>
+```
+
+## Text Overflow (noWrap)
+
+Use the `noWrap` prop to truncate overflowing text with an ellipsis. Pair it with a `maxWidth` to constrain the text width.
+
+```tsx
+<Typography noWrap sx={{
+  maxWidth: 200
+}}>
+This is a long text that will be truncated with an ellipsis when it
+exceeds the maximum width of the container.
+</Typography>
+```
+
+```tsx
+<Typography noWrap sx={{ maxWidth: 200 }}>
+  This is a long text that will be truncated with an ellipsis when it exceeds
+  the maximum width.
+</Typography>
+```
+
+## Responsive Typography
+
+You can pass a responsive object to the `level` prop, or use `sx` to set responsive font sizes.
+
+```tsx
+{/* Responsive level */}
+<Typography level={{ xs: 'h3', sm: 'h2', md: 'h1' }}>
+  Responsive Heading
+</Typography>
+
+{/* Responsive font size via sx */}
+<Typography
+  sx={{
+    fontSize: { xs: '1rem', sm: '1.25rem', md: '1.5rem' },
+  }}
+>
+  Responsive text
+</Typography>
+```
+
 ## Common Use Cases
 
 ### Page Structure
@@ -82,14 +414,17 @@ function ArticlePage() {
       </Typography>
 
       <Typography level="body-md" sx={{ mb: 2 }}>
-        The main content of the article goes here. This text uses a readable size and line spacing.
+        The main content of the article goes here. This text uses a readable size
+        and line spacing.
       </Typography>
 
       <Typography level="h2" sx={{ mt: 4, mb: 2 }}>
         Section Title
       </Typography>
 
-      <Typography level="body-md">The section content continues here.</Typography>
+      <Typography level="body-md">
+        The section content continues here.
+      </Typography>
     </article>
   );
 }
@@ -207,56 +542,9 @@ function ArticlePage() {
 </Stack>
 ```
 
-## Colors
-
-Typography supports various colors:
-
-```tsx
-<Stack spacing={1}>
-  <Typography color="primary">Primary color</Typography>
-  <Typography color="neutral">Neutral color</Typography>
-  <Typography color="danger">Danger color</Typography>
-  <Typography color="success">Success color</Typography>
-  <Typography color="warning">Warning color</Typography>
-</Stack>
-```
-
-## Component Prop
-
-You can render it as a different HTML element or React component:
-
-```tsx
-<Typography level="h1" component="h2">
-  h1 style rendered as an h2 tag
-</Typography>
-
-<Typography level="body-md" component="span">
-  Inline text
-</Typography>
-
-<Typography level="title-md" component={Link} href="/page">
-  Rendered as a Link component
-</Typography>
-```
-
-## Responsive Typography
-
-You can use responsive levels:
-
-```tsx
-<Typography
-  level={{ xs: 'h3', sm: 'h2', md: 'h1' }}
-  sx={{
-    fontSize: { xs: '1.5rem', sm: '2rem', md: '2.5rem' },
-  }}
->
-  Responsive Heading
-</Typography>
-```
-
 ## Best Practices
 
-1. **Semantic Structure**: Use heading levels in order to create a clear document structure.
+1. **Semantic Structure**: Use heading levels in order (`h1` → `h2` → `h3`) to create a clear document hierarchy.
 
 ```tsx
 // ✅ Correct order
@@ -264,22 +552,34 @@ You can use responsive levels:
 <Typography level="h2">Section heading</Typography>
 <Typography level="h3">Subsection</Typography>
 
-// ❌ Incorrect order
+// ❌ Incorrect order — skipping h2
 <Typography level="h1">Main heading</Typography>
 <Typography level="h3">Section heading</Typography>
 ```
 
-2. **Consistency**: Use the same level for text serving the same purpose.
+2. **Consistency**: Use the same level for text serving the same purpose across the application.
 
 3. **Readability**: Provide proper line spacing and paragraph separation for body text.
 
 4. **Color Contrast**: Maintain sufficient color contrast to ensure accessibility.
 
-## Accessibility
+5. **Level Selection Guide**:
+   - **Headings** (`h1`–`h4`): Use for document structure and section titles.
+   - **Titles** (`title-lg/md/sm`): Use for UI labels, card headers, and emphasized text.
+   - **Body** (`body-lg/md/sm/xs`): Use for content, descriptions, and supporting text.
+   - **Marketing** (`marketing-lg/md/sm`): Use exclusively for marketing and landing pages — not for general UI.
+
+6. **Avoid inline style overrides**: Prefer the `level` prop over `sx` for font sizing. Use `level` for consistent design tokens.
 
-- Use appropriate semantic HTML tags
-- Support screen readers
-- Ensure keyboard navigation (when used as a link or button)
-- Maintain sufficient color contrast
+7. **Use `textColor` for custom colors**: When the five semantic colors are insufficient, use `textColor` to apply any palette value directly.
+
+8. **Use `body-xs` sparingly**: Reserve `body-xs` (12px) for auxiliary information such as timestamps, counters, and footnotes — not for primary content.
+
+9. **Marketing vs Heading levels**: Marketing levels are intended for landing pages and promotional content only. For standard application UI, use heading and title levels instead. Be aware that `h1`–`h4` and `marketing-*` levels use the Poppins display font, while `title-*` and `body-*` use Inter.
+
+## Accessibility
 
-Typography plays a key role in effectively conveying information and creating visual hierarchy in user interfaces. By choosing appropriate levels and styles, you can create content that is easy to read and accessible.
+- Use sequential heading levels (`h1` → `h2` → `h3`). Do not skip levels.
+- Use the `component` prop to separate visual style from semantic meaning (e.g., `level="h1" component="h2"` when you need h1 styling but h2 semantics).
+- Avoid using `body-xs` (12px) for essential content — the small size may be difficult to read.
+- Maintain sufficient color contrast ratios (WCAG AA: 4.5:1 for normal text, 3:1 for large text).