docs: improve font sizes

.eslintignore

@@ -10,3 +10,4 @@
 /showcases/nuxt-showcase/**
 build-outputs/
 build-showcases/
+/output/vue/scripts/fix-any-types.ts

.xo-config.cjs

@@ -1,8 +1,6 @@
 module.exports = {
 	prettier: true,
-	ignores: [
-		'./showcases/nuxt-showcase/**'
-	],
+	ignores: ['./showcases/nuxt-showcase/**'],
 	overrides: [
 		{
 			files: ['./showcases/angular-showcase/**'],

packages/foundations/docs/FontsSizes.md

@@ -1,10 +1,35 @@
-# Font-Sizes
+# DB Font Sizes
 
--   You should use our provided **Font-Sizes** to change the size of text elements like `<p>` etc.
+The font sizes of foundations consist of [two different sets](./overview) (9 sizes each) for general texts (**Body Font Sizes**) and headlines (**Headline Font Sizes**).
+All sizes of both sets are automatically adjusted by the selected [density](./../densities/readme).
 
-> **_NOTE:_** Some sizes may stay the same because of screen-width or density.
+## Body Font Sizes
 
-## How to include colors
+-   By default, the Body Font Size `md` is set to the body tag.
+-   These 9 Body Font Sizes can also be explicitly set as classes on elements in order to change their font size.
+
+## Headline Font Sizes
+
+-   9 Headline Sizes are available and are usable by custom properties
+-   6 Headline Sizes are mapped to native headline tags (`h1` to `h6`) by default. Headlines can therefore be used directly.
+
+## Available variants / sizes
+
+`3xl` | `2xl` | `xl` | `lg` | `md` | `sm` | `xs` | `2xs` | `3xs`
+
+## When to use
+
+-   Use our provided **Body Font Sizes** to explicitly change the size of text elements like `<p>`, `<span>` etc.
+-   Use a **Body Font Size** for a container and all text elements in it (does not affect components font-sizes) .
+-   **Headline Font Sizes** can be used to override the default mapping of the `h1` - `h6` tags.
+-   _Advanced: use standardised *custom properties* to define `font-size` and `line-height` in your own components._
+
+### Notes
+
+> -   Some sizes may stay the same because of screen width or density.
+> -   Elements such as `<p>` and all headings (`h1` - `h6`) as well as **DB UI components** have font sizes assigned by default so that they can be used without further customisation.
+
+### How to include
 
 For **CSS** and **Tailwind** you need to use the import `@import "@db-ui/foundations/build/css/fonts/classes/all.css";` in your root `.css` file.
 
@@ -23,12 +48,37 @@ Then you can use e.g. `sm` font-size by extending our SCSS placeholders like thi
 
 ### How to use
 
-We're providing an [overview for all possible font-sizes](./overview).
+The following options are recommended for applying **Body Font Sizes**:
+
+-   CSS classes
+-   CSS `data-`attributes
+-   SCSS placeholders
+-   Tailwind classes
 
-There are several variants: `3xl`, `2xl`, `xl`, `lg`, `md`, `sm`, `xs`, `2xs`, `3xs`.
+All options (except the last one) set `font-size`, `line-height` and some **CSS Custom Properties** for an element. These custom properties are internally required by some components to be displayed correctly.
 
-**We use `XX` here you should replace it with a variant from above.**
+> All available variants / sizes, [see also the detailed overview](./overview):
+>
+> `3xl` | `2xl` | `xl` | `lg` | `md` | `sm` | `xs` | `2xs` | `3xs`
 
-| Variant | CSS                       | SCSS                                 | Tailwind                  |
-| :-----: | ------------------------- | ------------------------------------ | ------------------------- |
-|  `XX`   | `class="db-font-size-XX"` | `@extend %db-overwrite-font-size-XX` | `class="db-font-size-XX"` |
+**Note: We use `XX` here. You should replace it with a size from above.**
+
+|         CSS class         | CSS data-attribute    | SCSS                                 | Tailwind                  |
+| :-----------------------: | --------------------- | ------------------------------------ | ------------------------- |
+| `class="db-font-size-XX"` | `data-font-size="XX"` | `@extend %db-overwrite-font-size-XX` | `class="db-font-size-XX"` |
+
+#### Advanced use: CSS Custom Properties
+
+> **_Note:_** The direct use of custom properties to set font sizes should be avoided if possible. If this is unavoidable, existing restrictions should be taken into account.
+
+All of the above options are available for applying the **Body Font Sizes** to HTML elements within custom components.
+In some cases it may make sense to set the `font-size` and `line-height` manually in the css.
+
+**Please replace `XX` in the custom-properties with one of the sizes:**
+
+```css
+.text-element {
+	font-size: var(--db-type-body-font-size-XX);
+	line-height: var(--db-type-body-line-height-XX);
+}
+```

showcases/patternhub/pages/foundations/font-sizes/overview.tsx

@@ -1,24 +1,266 @@
+import { useState } from 'react';
 import DefaultPage from '../../../components/default-page';
-import { DBInfotext } from '../../../../../output/react/src';
+import {
+	DBInfotext,
+	DBSwitch,
+	DBIcon,
+	DBSection
+} from '../../../../../output/react/src';
+
+const overwriteHeadlineMarkdown = `/* Select a headline tag to be overwritten */
+h1 {
+	font-size: var(--db-type-headline-font-size-XX);
+	line-height: var(--db-type-headline-line-height-XX);
+
+	/* spacings may vary depending on the project */
+	margin-block: var(--db-spacing-fixed-XX);
+}
+`;
+
+const getCodeExampleBodyFontSize = (size: string) => `.db-font-size-${size} {
+	font-size: var(--db-type-body-font-size-${size});
+	line-height: var(--db-type-body-line-height-${size});
+
+	/* custom properties only for components */
+	--db-icon-font-weight: var(--db-base-body-icon-weight-${size});
+	--db-icon-font-size: var(--db-base-body-icon-font-size-${size});
+	--db-base-line-height: var(--db-type-body-line-height-${size});
+	--db-base-font-size: var(--db-type-body-font-size-${size});
+}
+`;
+const getCodeExampleHeadlineTag = (tag: string, size: string) => `${tag} {
+    line-height: var(--db-type-headline-line-height-${size});
+    font-size: var(--db-type-headline-font-size-${size});
+    margin-block: var(--db-spacing-fixed-${size});
+}
+`;
+
+const getCodeExampleHeadlineSizes = (
+	size: string
+) => `.custom-headline-selector {
+    line-height: var(--db-type-headline-line-height-${size});
+    font-size: var(--db-type-headline-font-size-${size});
+    margin-block: var(--db-spacing-fixed-${size});
+}
+`;
 
 const ColorOverview = () => {
+	const [showCodeBody, setShowCodeBody] = useState(false);
+	const [showCodeHeadlines, setShowCodeHeadlines] = useState(false);
+	const [showCodeHeadlineSizes, setShowCodeHeadlineSizes] = useState(false);
+
 	return (
 		<DefaultPage>
-			<h1>FontsSizes Overview</h1>
-			<h2>Body</h2>
-			<DBInfotext semantic="warning">
-				Some font-sizes are the same for a specific device type. For
-				example in mobile all `xl` sizes are the same.
+			<h1>Font Sizes Overview</h1>
+			<ol>
+				<li>
+					<b>Body Font Sizes</b>
+				</li>
+				<li>
+					<b>Default Headlines H1 - H6</b>
+				</li>
+				<li>
+					<b>Available Headline Font Sizes</b>
+				</li>
+			</ol>
+			<DBInfotext data-font-size="md" semantic="informational">
+				<strong>Note: </strong>Some font sizes are the same for a
+				specific device type. For example in mobile all <code>xl</code>{' '}
+				sizes are the same.
 			</DBInfotext>
+			<h2>Body Font Sizes</h2>
+			<p>
+				All <strong>9 body font sizes</strong> provided by foundations
+				can be set via <strong>css class</strong>,{' '}
+				<strong>data-attribute</strong>,{' '}
+				<strong>scss placeholder</strong> or{' '}
+				<strong>Tailwind class</strong> (
+				<a href="./readme">How to use</a>). This ensures that all custom
+				properties are defined by the class to match the font size, so
+				that certain child components fit correctly. For example, this
+				allows DBIcon component to display its icon in the correct
+				height and weight according to the chosen font-size.
+			</p>
+			<p>
+				Therefore, if possible, these <b>db-font-size</b> classes should
+				be used to change the font size of certain text elements such as{' '}
+				<code>p</code> or containers with other texts.
+			</p>
+			<DBInfotext data-font-size="md" semantic="informational">
+				The display of icons works correctly in all sizes except{' '}
+				<code>3xl</code> and <code>3xs</code>. That is why they are
+				hidden there.
+			</DBInfotext>
+			<br />
 			<div>
+				<DBSwitch
+					change={(event) => {
+						setShowCodeBody(event.target.checked);
+					}}>
+					Show CSS applied by using <b>db-font-size-XX</b> classes
+				</DBSwitch>
+			</div>
+			<br />
+			<DBSection spacing="small" className="db-neutral-bg-lvl-2">
 				{['3xl', '2xl', 'xl', 'lg', 'md', 'sm', 'xs', '2xs', '3xs'].map(
 					(size) => (
-						<p className={`db-font-size-${size}`}>
-							I am size: <strong>{size}</strong>
-						</p>
+						<>
+							<p className={`db-font-size-${size}`}>
+								I am size: <strong>{size}</strong>{' '}
+								{size !== '3xl' && size !== '3xs' && (
+									<DBIcon icon="download" />
+								)}
+							</p>
+							<pre
+								style={{
+									display: showCodeBody ? 'block' : 'none'
+								}}>
+								<code className="language-css">
+									{getCodeExampleBodyFontSize(size)}
+								</code>
+							</pre>
+						</>
 					)
 				)}
+			</DBSection>
+
+			<h2>Default Headlines H1 - H6</h2>
+			<p>
+				Certain <strong>Headline Font Sizes</strong> are mapped to the{' '}
+				<strong>headline tags (H1 - H6)</strong> by default.
+				Accordingly, it is sufficient to use the native headline tags,
+				as in this example.
+			</p>
+			<DBInfotext data-font-size="md" semantic="informational">
+				There are currently no CSS classes or data-attributes to set a
+				predefined headline size for a specific element.
+			</DBInfotext>
+			<br />
+			<div>
+				<DBSwitch
+					change={(event) => {
+						setShowCodeHeadlines(event.target.checked);
+					}}>
+					Show CSS applied by using <strong>H1 - H6 tags</strong>
+				</DBSwitch>
 			</div>
+			<br />
+			<DBSection spacing="small" className="db-neutral-bg-lvl-2">
+				{(
+					[
+						{ Tag: 'h1', size: 'xl' },
+						{ Tag: 'h2', size: 'lg' },
+						{ Tag: 'h3', size: 'md' },
+						{ Tag: 'h4', size: 'sm' },
+						{ Tag: 'h5', size: 'xs' },
+						{ Tag: 'h6', size: '2xs' }
+					] as Array<{
+						Tag: keyof JSX.IntrinsicElements;
+						size: string;
+					}>
+				).map(({ Tag, size }) => (
+					<>
+						<Tag>
+							{Tag.toUpperCase()} - default mapped size is:{' '}
+							<u>{size}</u>
+						</Tag>
+						<pre
+							style={{
+								display: showCodeHeadlines ? 'block' : 'none'
+							}}>
+							<code className="language-css">
+								{getCodeExampleHeadlineTag(Tag, size)}
+							</code>
+						</pre>
+					</>
+				))}
+			</DBSection>
+
+			<h2>Available Headline Font Sizes</h2>
+			<p>
+				This overview shows all <strong>9 headline sizes</strong> that
+				are available in foundations. These can be used, for example, to
+				(globally) overwrite the default mapping. Instructions on how
+				overwriting works are below.
+			</p>
+
+			<br />
+			<div>
+				<DBSwitch
+					change={(event) => {
+						setShowCodeHeadlineSizes(event.target.checked);
+					}}>
+					Show CSS for custom usage of headline sizes
+				</DBSwitch>
+			</div>
+			<br />
+
+			<DBSection spacing="small" className="db-neutral-bg-lvl-2">
+				{['3xl', '2xl', 'xl', 'lg', 'md', 'sm', 'xs', '2xs', '3xs'].map(
+					(size) => (
+						<>
+							<h3
+								style={{
+									fontSize: `var(--db-type-headline-font-size-${size})`,
+									lineHeight: `var(--db-type-headline-line-height-${size})`,
+									marginBlock: `var(--db-spacing-fixed-${size})`
+								}}>
+								Headline with size: <u>{size}</u>
+							</h3>
+							<pre
+								style={{
+									display: showCodeHeadlineSizes
+										? 'block'
+										: 'none'
+								}}>
+								<code className="language-css">
+									{getCodeExampleHeadlineSizes(size)}
+								</code>
+							</pre>
+						</>
+					)
+				)}
+			</DBSection>
+
+			<h3>How to overwrite headlines default mapping</h3>
+			<p>
+				To overwrite the default mapping of the foundations, a suitable
+				selector (H1 - H6 or css class) is used to set{' '}
+				<code>font-size</code> and <code>line-height</code> (and{' '}
+				<code>margin-block</code> if necessary) to the desired size
+				using the supplied <strong>custom properties</strong>.
+			</p>
+
+			<DBInfotext data-font-size="md" semantic="warning">
+				In order to maintain a uniform typography, custom properties for{' '}
+				<code>font-size</code> and <code>line-height</code> <u>must</u>{' '}
+				be selected with the same size (e.g. <code>md</code>).
+			</DBInfotext>
+			<br />
+			<DBSection spacing="small" className="db-neutral-bg-lvl-2">
+				<p>
+					<b>These custom properties must be used for overwrites:</b>
+				</p>
+				<code>--db-type-headline-font-size-XX</code>
+				<br />
+				<code>--db-type-headline-line-height-XX</code>
+				<br />
+				<code>--db-spacing-fixed-XX</code> (optional e.g. for margin)
+				<p>
+					<strong>They are available in the following sizes:</strong>
+				</p>
+				<p>
+					<code>3xl</code> | <code>2xl</code> | <code>xl</code> |{' '}
+					<code>lg</code> | <code>md</code> | <code>sm</code> |{' '}
+					<code>xs</code> | <code>2xs</code> | <code>3xs</code>
+				</p>
+			</DBSection>
+			<br />
+			<pre>
+				<code className="language-css">
+					{overwriteHeadlineMarkdown}
+				</code>
+			</pre>
 		</DefaultPage>
 	);
 };