@juwel-development/design-system 3.9.1 → 3.11.0

package/src/Display/Typography/H3/H3.tsx

@@ -6,7 +6,7 @@ import type { FunctionComponent, ReactNode } from 'react';
 // inherits - Tailwind's preflight resets h1-h6 to font-weight: inherit, so the sized levels carry no
 // weight class. Colour is a semantic token re-pointed by `.dark`, so no variant carries a `dark:`
 // class.
-const h3 = cva('font-primary text-subtitle leading-subtitle', {
+const h3 = cva('font-heading text-subtitle leading-subtitle', {
   variants: {
     color: {
       foreground: 'text-foreground',
@@ -31,7 +31,8 @@ interface IH3Props extends VariantProps<typeof h3> {
  *
  * @Guarantees — enforced on every render
  * - Renders an `h3`; its outline level and the subtitle role are one choice, not two (docs/adr/0005).
- * - Reads `--font-primary`, sized by `--text-subtitle` and led by `--leading-subtitle`.
+ * - Reads `--font-heading`, the heading family that follows `--font-primary` until a theme
+ *   re-points it (#120), sized by `--text-subtitle` and led by `--leading-subtitle`.
  * - `color` selects `foreground`, `muted`, `success`, `warning`, `error` or `info`; nothing else
  *   paints text. A status tone changes colour only and adds no announcement semantics.
  *

package/src/Display/Typography/H4/H4.tsx

@@ -6,7 +6,7 @@ import type { FunctionComponent, ReactNode } from 'react';
 // (docs/adr/0005). The `font-bold` is load-bearing - Tailwind's preflight resets h1-h6 to
 // font-weight: inherit, so without it an h4 renders identically to a paragraph. Colour is a semantic
 // token re-pointed by `.dark`, so no variant carries a `dark:` class.
-const h4 = cva('font-primary text-body leading-body font-bold', {
+const h4 = cva('font-heading text-body leading-body font-bold', {
   variants: {
     color: {
       foreground: 'text-foreground',
@@ -30,7 +30,8 @@ interface IH4Props extends VariantProps<typeof h4> {
  *
  * @Guarantees — enforced on every render
  * - Renders an `h4`; its outline level and the body role are one choice, not two (docs/adr/0005).
- * - Reads `--font-primary`, sized by `--text-body`, and is bold so it stands apart from a paragraph.
+ * - Reads `--font-heading`, the heading family that follows `--font-primary` until a theme
+ *   re-points it (#120), sized by `--text-body`, and is bold so it stands apart from a paragraph.
  * - `color` selects `foreground`, `muted`, `success`, `warning`, `error` or `info`; nothing else
  *   paints text. A status tone changes colour only and adds no announcement semantics.
  *

package/src/Display/Typography/H5/H5.tsx

@@ -6,7 +6,7 @@ import type { FunctionComponent, ReactNode } from 'react';
 // (docs/adr/0005). The `font-semibold` is load-bearing - Tailwind's preflight resets h1-h6 to
 // font-weight: inherit, so without it an h5 renders identically to a paragraph. Colour is a semantic
 // token re-pointed by `.dark`, so no variant carries a `dark:` class.
-const h5 = cva('font-primary text-body leading-body font-semibold', {
+const h5 = cva('font-heading text-body leading-body font-semibold', {
   variants: {
     color: {
       foreground: 'text-foreground',
@@ -31,7 +31,8 @@ interface IH5Props extends VariantProps<typeof h5> {
  *
  * @Guarantees — enforced on every render
  * - Renders an `h5`; its outline level and the body role are one choice, not two (docs/adr/0005).
- * - Reads `--font-primary`, sized by `--text-body`, semibold so it stands apart from a paragraph.
+ * - Reads `--font-heading`, the heading family that follows `--font-primary` until a theme
+ *   re-points it (#120), sized by `--text-body`, semibold so it stands apart from a paragraph.
  * - `color` selects `foreground`, `muted`, `success`, `warning`, `error` or `info`; nothing else
  *   paints text. A status tone changes colour only and adds no announcement semantics.
  *

package/src/Display/Typography/H6/H6.tsx

@@ -6,7 +6,7 @@ import type { FunctionComponent, ReactNode } from 'react';
 // (docs/adr/0005). The `font-medium` is load-bearing - Tailwind's preflight resets h1-h6 to
 // font-weight: inherit, so without it an h6 renders identically to a paragraph. Colour is a semantic
 // token re-pointed by `.dark`, so no variant carries a `dark:` class.
-const h6 = cva('font-primary text-body leading-body font-medium', {
+const h6 = cva('font-heading text-body leading-body font-medium', {
   variants: {
     color: {
       foreground: 'text-foreground',
@@ -31,7 +31,8 @@ interface IH6Props extends VariantProps<typeof h6> {
  *
  * @Guarantees — enforced on every render
  * - Renders an `h6`; its outline level and the body role are one choice, not two (docs/adr/0005).
- * - Reads `--font-primary`, sized by `--text-body`, medium so it stands apart from a paragraph.
+ * - Reads `--font-heading`, the heading family that follows `--font-primary` until a theme
+ *   re-points it (#120), sized by `--text-body`, medium so it stands apart from a paragraph.
  * - `color` selects `foreground`, `muted`, `success`, `warning`, `error` or `info`; nothing else
  *   paints text. A status tone changes colour only and adds no announcement semantics.
  *

package/src/Display/Typography/P/P.tsx

@@ -5,7 +5,7 @@ import type { FunctionComponent, ReactNode } from 'react';
 // The body role, shared with h4-h6 which add a weight to stand apart from it (docs/adr/0005). Weight
 // inherits. Colour is a semantic token re-pointed by `.dark`, so no variant carries a `dark:` class.
 // P owns no reading measure - that belongs to whatever owns the reading column (Prose #21).
-const p = cva('font-primary text-body leading-body', {
+const p = cva('font-body text-body leading-body', {
   variants: {
     color: {
       foreground: 'text-foreground',
@@ -29,7 +29,8 @@ interface IPProps extends VariantProps<typeof p> {
  * table cell — because the reading measure belongs to whatever owns the reading column (Prose #21).
  *
  * @Guarantees — enforced on every render
- * - Renders a `p`, reading `--font-primary`, sized by `--text-body` and led by `--leading-body`.
+ * - Renders a `p`, reading `--font-body` (the body family, which follows `--font-primary` until a
+ *   theme re-points it, #120), sized by `--text-body` and led by `--leading-body`.
  * - `color` selects `foreground`, `muted`, `success`, `warning`, `error` or `info`; nothing else
  *   paints text. A status tone changes colour only and adds no announcement semantics.
  *

package/src/Display/Typography/Prose/Prose.tsx

@@ -13,12 +13,12 @@ const proseRoot = cva(
 
 // The opening paragraph, at the new lede role: larger than body and led tighter (docs/adr/0004), but
 // still running-text leading, not a heading's. Colour is the foreground token, re-pointed by `.dark`.
-const proseLede = cva('font-primary text-lede leading-lede text-foreground');
+const proseLede = cva('font-body text-lede leading-lede text-foreground');
 
 // The body role inside the column - the same utilities P emits, restated because the no-cross-import
 // rule forbids reusing P's recipe. A test pins the two equal so they cannot drift. Colour is a
 // semantic token re-pointed by `.dark`, so no variant carries a `dark:` class.
-const proseBody = cva('font-primary text-body leading-body', {
+const proseBody = cva('font-body text-body leading-body', {
   variants: {
     color: {
       foreground: 'text-foreground',
@@ -33,7 +33,7 @@ const proseBody = cva('font-primary text-body leading-body', {
 });
 
 // The stepped-down closing note: the small role, always muted. small carries the enforced 15px floor.
-const proseTail = cva('font-primary text-small text-muted');
+const proseTail = cva('font-body text-small text-muted');
 
 interface IProseRootProps {
   children?: ReactNode;

package/src/Interaction/Button/Button.tsx

@@ -5,25 +5,33 @@ import type { Subject } from 'rxjs';
 
 // No `dark:` classes here by design: every colour below is a semantic token whose value is
 // re-pointed by the `.dark` class in tokens.css, so one set of classes serves both themes.
-// The colour transition is stated once in the base, on the motion token, so no variant can
-// disagree with it - see docs/adr/0001-motion-token-contract.md. The one focus ring is in the
-// base too: identical across variants, drawn with outline, colour at rest so it never fades in -
-// see docs/adr/0002-focus-ring-token-contract.md. The corner is in the base as well, one radius
-// token every variant shares, so none can disagree - see docs/adr/0003-radius-token-contract.md.
-// The face is in the base for the same reason - see docs/adr/0004-typography-token-contract.md (#90).
-// The size is in the base for the same reason, and here it is load-bearing: the recipe fixes
-// vertical padding and sets no height, so the font-size is what drives it (docs/adr/0004, #92).
+// Every variant shares colour motion and the focus ring. Faced controls share their typography,
+// radius and label arrangement; plain inherits its surrounding text. Long words wrap within the
+// available width without clipping, and faced minimum widths yield to a narrower holder (#119).
+const face =
+  'font-control text-body text-balance wrap-anywhere rounded-[var(--radius-control)] select-none inline-flex flex-row items-center justify-center gap-2';
 const button = cva(
-  'font-primary text-body transition-colors duration-[var(--motion-duration-color)] rounded-[var(--radius-control)] py-2 sm:py-2 disabled:bg-disabled disabled:hover:bg-disabled-hover cursor-pointer disabled:cursor-not-allowed select-none text-nowrap inline-flex flex-row items-center justify-center gap-2 outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)]',
+  'transition-colors duration-[var(--motion-duration-color)] cursor-pointer disabled:cursor-not-allowed outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)]',
   {
     variants: {
       variant: {
-        primary:
-          'px-4 sm:px-6 min-w-[var(--control-min-width)] bg-primary text-primary-foreground hover:bg-primary-hover',
-        secondary:
-          'px-4 sm:px-6 min-w-[var(--control-min-width)] bg-secondary text-secondary-foreground hover:bg-secondary-hover',
-        ghost:
-          'px-2 min-w-0 bg-transparent text-foreground hover:underline hover:decoration-[length:var(--underline-thickness)] hover:underline-offset-[var(--underline-offset)]',
+        // The four faced variants share one floor, `--control-min-width`, so a row of them aligns,
+        // and the floor yields to a holder narrower than it (#119): `min()` against the holder's
+        // width lets the button shrink and its label wrap instead of forcing the holder to overflow.
+        // A holder sized to its content (an auto track, a table cell) has no width to yield to, so
+        // there the button takes its content width. Measured: a filled button in forced colours has
+        // no boundary at all - the UA forces the fill to ButtonFace, which can equal Canvas, and
+        // preflight zeroes the border - so the filled variants draw one there and nowhere else.
+        primary: `${face} px-4 sm:px-6 py-2 min-w-[min(var(--control-min-width),100%)] bg-primary text-primary-foreground hover:bg-primary-hover disabled:bg-disabled disabled:hover:bg-disabled-hover forced-colors:border`,
+        secondary: `${face} px-4 sm:px-6 py-2 min-w-[min(var(--control-min-width),100%)] bg-secondary text-secondary-foreground hover:bg-secondary-hover disabled:bg-disabled disabled:hover:bg-disabled-hover forced-colors:border`,
+        ghost: `${face} px-2 py-2 min-w-0 bg-transparent text-foreground hover:underline hover:decoration-[length:var(--underline-thickness)] hover:underline-offset-[var(--underline-offset)] disabled:bg-disabled disabled:hover:bg-disabled-hover`,
+        // Unfilled and identified by its edge (#119). The edge sits outside the inset, so each inset
+        // gives back the edge's pixel and the outlined button is exactly a filled one's height.
+        // Disabled follows Input: edge and ink go to the disabled tones and no fill appears.
+        outlined: `${face} px-[calc(1rem_-_1px)] sm:px-[calc(1.5rem_-_1px)] py-[calc(0.5rem_-_1px)] min-w-[min(var(--control-min-width),100%)] border border-solid border-secondary bg-transparent text-secondary hover:bg-backing disabled:border-disabled disabled:text-muted disabled:hover:bg-transparent`,
+        destructive: `${face} px-4 sm:px-6 py-2 min-w-[min(var(--control-min-width),100%)] bg-error text-error-foreground hover:bg-error-hover disabled:bg-disabled disabled:hover:bg-disabled-hover forced-colors:border`,
+        plain:
+          'inline p-0 min-w-0 max-w-full whitespace-normal wrap-anywhere bg-transparent [font:inherit] [letter-spacing:inherit] [color:inherit] [text-align:inherit] disabled:text-disabled',
       },
     },
     defaultVariants: {
@@ -51,10 +59,29 @@ interface IButtonProps extends VariantProps<typeof button> {
  *
  * @component
  *
+ * @Variants
+ * - `primary` and `secondary`: the filled actions
+ * - `outlined`: the quiet secondary - `secondary` text and edge on an unfilled surface, for an
+ *   action beside a primary one that must not compete with it
+ * - `destructive`: an action that removes or ends something, filled with the `error` status tone
+ *   and inked with `errorForeground`. The tone reinforces words it never replaces: the label, or
+ *   the `ariaLabel` of a symbol-only button, must say what the action does
+ * - `ghost`: the padded text action with a hover underline and no floor. With an `ariaLabel` and
+ *   the bin `Icon` as its only child it is the quiet delete: the unfilled form of a secondary
+ *   destructive action at the corner of a block of content, where `destructive` is the filled form
+ *
+ * The four faced variants share the control minimum width and inset, so a row of them aligns, and
+ * every one of them shrinks and wraps its label where its holder is narrower than that.
+ *
  * @UXGuidelines
  * - Use clear, action-oriented text (e.g., "Save" instead of "OK")
- * - Keep button text concise (1-3 words)
+ * - Keep button text short; a translated label that runs longer wraps where the layout constrains
+ *   it, so the words stay readable rather than overflowing
  * - Use primary buttons for main actions, secondary buttons for alternative actions
+ * - `plain` is a plain action (CONTEXT.md): an operable button in the typography and colour of the
+ *   text around it, with no face, padding, corner or hover underline of its own. Reach for it where
+ *   the action belongs to a line of content - a sortable column header composed with `Icon` - and
+ *   for `ghost` where a quiet but still button-shaped action is wanted
  * - Maintain consistent button styling throughout the application
  * - Provide visual feedback on hover/active states
  * - Ensure sufficient touch target size (minimum 44x44px) for mobile users
@@ -64,8 +91,11 @@ interface IButtonProps extends VariantProps<typeof button> {
  *
  * @Accessibility
  * - Ensure adequate color contrast (4.5:1 minimum ratio)
- * - Provide focus styles for keyboard navigation
+ * - Provide focus styles for keyboard navigation: every variant, `plain` included, draws the shared
+ *   focus ring and nothing else changes on focus
+ * - A disabled `plain` button is told apart by the `disabled` text tone and keeps native disabled semantics
  * - Use appropriate ARIA attributes when needed
+ * - Status colour never stands alone: a destructive action is named by its words or symbol
  */
 export const Button: FunctionComponent<IButtonProps> = ({
   children,

package/src/Interaction/Input/Input.tsx

@@ -12,7 +12,7 @@ import type { Subject } from 'rxjs';
 // control's face, and the placeholder that follows it, are docs/adr/0004's (#90); so is its size
 // (#92) - `body` is the role clearing the 16px below which iOS Safari zooms a focused control.
 const input = cva(
-  'block w-full rounded-[var(--radius-control)] border border-solid border-control-border bg-transparent px-3 py-2 font-primary text-body text-foreground transition-colors duration-[var(--motion-duration-color)] outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)] [&:user-invalid]:border-error aria-[invalid=true]:border-error disabled:cursor-not-allowed disabled:border-disabled disabled:text-muted',
+  'block w-full rounded-[var(--radius-control)] border border-solid border-control-border bg-transparent px-3 py-2 font-control text-body text-foreground transition-colors duration-[var(--motion-duration-color)] outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)] [&:user-invalid]:border-error aria-[invalid=true]:border-error disabled:cursor-not-allowed disabled:border-disabled disabled:text-muted',
   {
     variants: {
       // text/email/url are visually identical; the axis only selects the control's `type`

package/src/Interaction/MultiSelect/MultiSelect.tsx

@@ -43,7 +43,7 @@ const multiSelectRoot = cva('', {
       field: [
         'group/field relative flex items-center gap-1',
         'rounded-[var(--radius-control)] border border-solid border-control-border bg-transparent px-3 py-2',
-        'font-primary text-body text-foreground transition-colors duration-[var(--motion-duration-color)]',
+        'font-control text-body text-foreground transition-colors duration-[var(--motion-duration-color)]',
         'data-[disabled]:border-disabled data-[disabled]:text-muted',
       ].join(' '),
       trigger: `absolute inset-0 flex cursor-pointer items-center justify-end rounded-[var(--radius-control)] bg-transparent px-3 text-muted disabled:cursor-not-allowed ${FOCUS_RING}`,

package/src/Interaction/NumberInput/NumberInput.tsx

@@ -7,7 +7,7 @@ import type { Subject } from 'rxjs';
 // #number-state) - with `inputmode=decimal` as a keyboard hint only. The classes are Input's, for
 // Input's reasons: tokens re-pointed by `.dark`, the ring of docs/adr/0002, the faces of 0004.
 const numberInput = cva(
-  'block w-full rounded-[var(--radius-control)] border border-solid border-control-border bg-transparent px-3 py-2 font-primary text-body text-foreground transition-colors duration-[var(--motion-duration-color)] outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)] [&:user-invalid]:border-error aria-[invalid=true]:border-error disabled:cursor-not-allowed disabled:border-disabled disabled:text-muted',
+  'block w-full rounded-[var(--radius-control)] border border-solid border-control-border bg-transparent px-3 py-2 font-control text-body text-foreground transition-colors duration-[var(--motion-duration-color)] outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)] [&:user-invalid]:border-error aria-[invalid=true]:border-error disabled:cursor-not-allowed disabled:border-disabled disabled:text-muted',
 );
 
 export interface INumberInputProps {

package/src/Interaction/Select/Select.tsx

@@ -10,7 +10,7 @@ const selectRoot = cva(
     '[&>span]:font-secondary [&>span]:text-muted [&>span]:text-small',
     '[&>p]:font-secondary [&>p]:text-small [&>p]:text-muted [&>p[data-error]]:text-error',
     '[&>select]:block [&>select]:w-full [&>select]:rounded-[var(--radius-control)] [&>select]:border [&>select]:border-solid [&>select]:border-control-border [&>select]:bg-transparent [&>select]:px-3 [&>select]:py-2',
-    '[&>select]:font-primary [&>select]:text-body [&>select]:text-foreground [&>select]:transition-colors [&>select]:duration-[var(--motion-duration-color)]',
+    '[&>select]:font-control [&>select]:text-body [&>select]:text-foreground [&>select]:transition-colors [&>select]:duration-[var(--motion-duration-color)]',
     '[&>select]:outline-focus-ring [&>select]:outline-offset-[var(--focus-ring-offset)] [&>select]:focus-visible:outline [&>select]:focus-visible:outline-[length:var(--focus-ring-width)]',
     '[&>select:user-invalid]:border-error [&>select]:aria-[invalid=true]:border-error [&>select]:disabled:cursor-not-allowed [&>select]:disabled:border-disabled [&>select]:disabled:text-muted',
   ].join(' '),

package/src/Interaction/Tabs/Tabs.tsx

@@ -11,10 +11,10 @@ import {
 import type { Subject } from 'rxjs';
 import { TabsCompositionError } from './TabsCompositionError';
 
-// The row is a single scrolling line, never a wrap: overflow is an accommodation, not a strip. The
-// ring room is written from the two focus-ring tokens so it cannot drift from the ring it exists
-// for: padding holds the scroll clip off the outline, the negative margin hands the room back to
-// the page, and scroll-padding makes a nearest scrollIntoView stop with the ring inside the clip.
+// The row is one scrolling line of controls, never a second row. The ring room is written from the
+// two focus-ring tokens so it cannot drift from the ring it exists for: padding holds the scroll
+// clip off the outline, the negative margin hands the room back to the page, and scroll-padding
+// makes a nearest scrollIntoView stop with the ring inside the clip.
 const tabsList = cva(
   [
     'flex flex-row overflow-x-auto',
@@ -28,12 +28,14 @@ const tabsList = cva(
 // keyed on aria-selected, so the attribute the device reads is the one the paint follows. The
 // marker keeps one thickness and flips only colour on the shared motion token, so selection
 // shifts no geometry. The focus ring sits in the base with its colour at rest, as on Button.
+// The tab sets no flex-shrink and no white-space of its own (#121): as a flex item it shrinks
+// no further than its longest word, so a label wraps inside its tab before the row scrolls.
 const tabsTab = cva(
   [
     'font-secondary text-label tracking-label',
     'text-muted hover:text-foreground aria-selected:text-foreground',
     'border-b-[length:var(--tab-marker-thickness)] border-solid border-transparent aria-selected:border-foreground',
-    'shrink-0 cursor-pointer select-none text-nowrap px-[var(--tab-inset-inline)] py-[var(--tab-inset-block)]',
+    'cursor-pointer select-none px-[var(--tab-inset-inline)] py-[var(--tab-inset-block)]',
     'transition-colors duration-[var(--motion-duration-color)]',
     'outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)]',
   ].join(' '),
@@ -117,8 +119,10 @@ export interface ITabsTabProps {
   /** The stable identity connecting this tab to its panel and emitted by selection requests.
    *  Not React's `key`, and never inferred from the label or the position. */
   value: string;
-  /** The visible text label. Text only - no icons, no per-tab markup. */
-  children: string;
+  /** The label: visible text naming the view - a plain string still works - optionally with an
+   *  icon, a count or inline emphasis beside it. Decorative parts carry the consumer's own
+   *  `aria-hidden`; nothing in it is interactive, as the tab is the control. Rendered whole. */
+  children: ReactNode;
   testId?: string;
 }
 
@@ -252,15 +256,31 @@ const TabsPanel: FunctionComponent<ITabsPanelProps> = ({
  *   immediately; focus stays on the operated tab. Up/Down are left to the browser.
  * - Roving tabindex: Tab enters the list at the active tab, then the active panel - a consistent
  *   Tab stop whether or not its content is focusable. Inactive panels add no stop.
- * - The row scrolls horizontally on overflow - one line, no wrap, no shrink - and holds its own
- *   ring room, so the focused tab's ring survives the scroll clip.
+ * - A label is rendered whole, text and markup alike, however long its translation runs: never
+ *   clipped, shortened, elided or replaced by a hint. The tab's accessible name is computed from
+ *   its content, so what the device reads is what the viewer sees, less what the consumer marked
+ *   `aria-hidden`. A rich label and a plain string are one and the same control.
+ * - The row is one line of controls. As it narrows, a label's text wraps inside its tab, down to
+ *   the tab's longest word; only when the controls still cannot fit does the row scroll
+ *   horizontally - the row, never the page. The row holds its own ring room so the focused tab's
+ *   ring survives the scroll clip, and focus reveals a scrolled-off tab, so every tab is reachable
+ *   by keyboard without scrolling first.
+ * - The tabs on the row share one height, so every marker sits on one line whether or not a
+ *   neighbour's label wrapped.
  * - Selection is marked by a persistent line under the active tab: `--tab-marker-thickness` in
  *   `foreground`, constant thickness in both states, so switching shifts no widths and no weights.
  *   Keyboard focus is the separate shared focus ring. Colour moves on the one motion token.
  *
  * @CallerMustEnsure — the component cannot see these and does not check them
  * - One List with Tab elements as direct DOM children (arrays and fragments are supported),
- *   and sibling Panels under Root. Do not wrap tabs in host elements.
+ *   and the Panels under the same Root - as siblings of the List, or with it inside one
+ *   arrangement such as a `Stack` (see the separation guidance below). Do not wrap tabs in host
+ *   elements.
+ * - A label is a meaningful visible text name, with non-interactive decoration at most: no link,
+ *   button, input or other focusable descendant, since the tab is the one control and a nested
+ *   control inside a `button` is invalid. Decorative parts - an icon that repeats the text - carry
+ *   `aria-hidden` so they stay out of the name; the library does not guess which parts those are.
+ *   A count or an emphasis is meaning and stays in the name.
  * - At least two tabs, each `value` unique and stable, each with exactly one matching `Panel`
  *   under the same `Root`, and `active` naming a declared pair. Invalid input is a contract
  *   violation, not a request for a fallback.
@@ -271,10 +291,17 @@ const TabsPanel: FunctionComponent<ITabsPanelProps> = ({
  *
  * @UXGuidelines
  * - Labels are short names for views, not actions; the consuming app words and translates them.
+ *   A long translation wraps inside its tab and the row scrolls only when even the longest words
+ *   do not fit, so a label is never the reason to shorten a name.
  * - This is not a router: no location, no history, no deep links. Wire `onSelect$` to whatever
  *   owns the active key and pass that key back in.
+ * - Tabs sets no spacing between the row and the panel; the separation is a `Stack` between Root
+ *   and its members - `<Tabs.Root><Stack gap="region"><Tabs.List/>…<Tabs.Panel/>…</Stack>
+ *   </Tabs.Root>`. `gap="stack"` holds the row and its view together as one block; `gap="region"`
+ *   sets the view apart as a region of its own. Inactive panels are hidden, so the gap is exactly
+ *   one whichever panel is active, from the token the consumer's other groups already use.
  * - The panel is an opaque slot: compose the view's own rhythm inside it - a `Stack`, a `Prose` -
- *   as the view owns it; Tabs sets no spacing between the row and the panel.
+ *   as the view owns it.
  */
 export const Tabs = {
   Root: TabsRoot,

package/src/Interaction/TextArea/TextArea.tsx

@@ -12,7 +12,7 @@ import type { Subject } from 'rxjs';
 // docs/adr/0004's (#90); so is its size (#92) - `body` is the role clearing the 16px below which
 // iOS Safari zooms a focused control.
 const textArea = cva(
-  'block min-h-24 w-full rounded-[var(--radius-control)] border border-solid border-control-border bg-transparent px-3 py-2 font-primary text-body text-foreground transition-colors duration-[var(--motion-duration-color)] outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)] [&:user-invalid]:border-error aria-[invalid=true]:border-error disabled:cursor-not-allowed disabled:border-disabled disabled:text-muted',
+  'block min-h-24 w-full rounded-[var(--radius-control)] border border-solid border-control-border bg-transparent px-3 py-2 font-control text-body text-foreground transition-colors duration-[var(--motion-duration-color)] outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)] [&:user-invalid]:border-error aria-[invalid=true]:border-error disabled:cursor-not-allowed disabled:border-disabled disabled:text-muted',
 );
 
 interface ITextAreaProps {

package/src/Layout/Dialog/Dialog.tsx

@@ -347,11 +347,12 @@ const DialogTitle: FunctionComponent<IDialogTitleProps> = ({
       data-testid={testId}
     >
       {/* The independent Dialog h1 at its own type role - not the page's display role, and not a
-          generic heading primitive (docs/adr/0004 and 0005, Amendments). */}
+          generic heading primitive - in the heading face every heading reads (docs/adr/0004 and
+          0005, Amendments; #120). */}
       <h1
         id={titleId}
         className={
-          'font-primary text-dialog-title leading-dialog-title text-foreground'
+          'font-heading text-dialog-title leading-dialog-title text-foreground'
         }
       >
         {children}
@@ -374,7 +375,7 @@ const DialogDescription: FunctionComponent<IDialogDescriptionProps> = ({
     >
       <p
         id={descriptionId}
-        className={'font-primary text-body leading-body text-foreground'}
+        className={'font-body text-body leading-body text-foreground'}
       >
         {children}
       </p>