@recursica/mantine-adapter 0.50.6 → 0.52.0

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mantine-adapter"
   },
-  "version": "0.50.6",
+  "version": "0.52.0",
   "type": "module",
   "main": "./dist/mantine-adapter.cjs",
   "module": "./dist/mantine-adapter.js",
@@ -95,7 +95,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@recursica/adapter-common": "^0.25.1",
+    "@recursica/adapter-common": "^0.26.0",
     "@recursica/official-release": "^2.8.0"
   },
   "peerDependencies": {

package/src/Introduction.stories.tsx

@@ -6,7 +6,7 @@ import {
   Container,
   Stack,
   Group,
-  Title,
+  Heading,
   Text,
   Link,
   Button,
@@ -21,9 +21,9 @@ function IntroductionContent() {
       <Group gap="rec-md" mb="rec-xl" align="flex-start" wrap="nowrap">
         <MantineLogo width={80} height={80} />
         <Stack gap={0}>
-          <Title order={1} m={0}>
+          <Heading order={1} m={0}>
             Recursica Design System (Mantine Adapter)
-          </Title>
+          </Heading>
           <Link href="https://mantine.dev" target="_blank" rel="noreferrer">
             mantine.dev
           </Link>
@@ -36,9 +36,9 @@ function IntroductionContent() {
       </Text>
 
       <Stack mb="rec-xl">
-        <Title order={2} mb="rec-md">
+        <Heading order={2} mb="rec-md">
           Looking for another UI Kit?
-        </Title>
+        </Heading>
         <Text mb="rec-md">
           Are you using a different UI Kit (like Material UI)? Recursica
           provides multiple adapters for different frameworks.
@@ -56,9 +56,9 @@ function IntroductionContent() {
       </Stack>
 
       <Stack mb="rec-xl">
-        <Title order={2} mb="rec-md">
+        <Heading order={2} mb="rec-md">
           Installation
-        </Title>
+        </Heading>
         <Text mb="rec-md">
           To install the Mantine adapter in your project, run:
         </Text>
@@ -78,9 +78,9 @@ function IntroductionContent() {
       </Stack>
 
       <Stack mb="rec-xl">
-        <Title order={2} mb="rec-md">
+        <Heading order={2} mb="rec-md">
           Tokens
-        </Title>
+        </Heading>
         <Text mb="rec-md">
           Raw design tokens (colors, sizes, font weights, opacities, etc.) that
           feed the theme and components. These are the primitive values defined
@@ -89,9 +89,9 @@ function IntroductionContent() {
       </Stack>
 
       <Stack mb="rec-xl">
-        <Title order={2} mb="rec-md">
+        <Heading order={2} mb="rec-md">
           Theme
-        </Title>
+        </Heading>
         <Text mb="rec-md">
           Brand and theme layer built on top of tokens. Typography types,
           dimensions, and layout grids are defined here. Theme uses the tokens
@@ -101,9 +101,9 @@ function IntroductionContent() {
       </Stack>
 
       <Stack mb="rec-xl">
-        <Title order={2} mb="rec-md">
+        <Heading order={2} mb="rec-md">
           Configuring Recursica
-        </Title>
+        </Heading>
         <Text mb="rec-md">
           To modify the Recursica configuration (tokens, brand, theme), go to{" "}
           <Link href={FORGE_URL} target="_blank" rel="noopener noreferrer">
@@ -114,9 +114,9 @@ function IntroductionContent() {
       </Stack>
 
       <Stack mb="rec-xl">
-        <Title order={2} mb="rec-md">
+        <Heading order={2} mb="rec-md">
           Documentation
-        </Title>
+        </Heading>
         <Text mb="rec-md">
           For full documentation, guides, and API reference, visit{" "}
           <Link href={DOCS_URL} target="_blank" rel="noopener noreferrer">

package/src/OverStyling.tsx

@@ -3,7 +3,7 @@ import { TypographyStylesProvider } from "@mantine/core";
 import {
   Container,
   Card,
-  Title,
+  Heading,
   Text as RawText,
   Group,
   Stack,
@@ -36,9 +36,9 @@ export const OverStylingInfo = () => {
             my="rec-xl"
           />
 
-          <Title order={3} mb="rec-md">
+          <Heading order={3} mb="rec-md">
             Try It Yourself
-          </Title>
+          </Heading>
 
           <Group mb="rec-xl">
             <Switch

package/src/components/Accordion/ACCORDION_IMPLEMENTATION_NOTES.md

@@ -60,3 +60,13 @@ and silently override the `leftIcon`-derived element (spread order would let it
 to set that slot is through `leftIcon`. Mantine's separate, per-control `chevron` override
 is _not_ omitted — nothing here computes it, so it still passes through safely if a caller
 wants to override the cascaded container-level chevron for a single item.
+
+---
+
+## `.label` descender clipping (Matt Massey, 2026-08-28)
+
+`.label` used plain `overflow: hidden` to make `text-overflow: ellipsis` work, which also clips
+descenders (e.g. the "g" in a long title) whenever `text_line-height` is tighter than the font's
+natural ascent+descent. Switched to `overflow: clip; overflow-clip-margin: 0.35em;` — same
+truncation, but ink can bleed slightly past the line box before it's actually clipped. Project-wide
+fix; see Chip's `CHIP_IMPLEMENTATION_NOTES.md` for the original discovery.

package/src/components/Accordion/Accordion.module.css

@@ -211,7 +211,11 @@
   text-align: left;
   color: inherit;
   padding: 0; /* Clear Mantine inner padding */
-  overflow: hidden;
+  overflow: clip; /* HARDCODE: `hidden` clipped descenders (e.g. "g") whenever the text_line-height
+    token is tighter than the font's natural ascent+descent; `overflow-clip-margin` gives ink a
+    small bleed allowance while still clipping genuinely overflowing text — same fix project-wide,
+    see Chip/FileInput's IMPLEMENTATION_NOTES.md for the original discovery. */
+  overflow-clip-margin: 0.35em;
   white-space: nowrap;
   text-overflow: ellipsis;
 }

package/src/components/AutoComplete/AUTOCOMPLETE_IMPLEMENTATION_NOTES.md

@@ -34,4 +34,9 @@ rendering with our own value comparison.
 
 ## `wrapItemText`
 
-`label`/`supportingText` default to single-line truncation with an ellipsis (`.optionText > *` — `overflow: hidden; text-overflow: ellipsis; white-space: nowrap`). Passing `wrapItemText` adds `.optionTextWrap` alongside `.optionText`, which re-enables wrapping (`white-space: normal; overflow-wrap: anywhere`) for both children — same later-cascade-wins mechanism (`.optionTextWrap > *` declared after `.optionText > *`, equal specificity) as the rest of this file's overrides. `renderRichOption`/`renderRichOptionContent` (shared util, both adapters) take `wrapItemText` as a third parameter and combine the two class names when it's true.
+`label`/`supportingText` default to single-line truncation with an ellipsis (`.optionText > *` — `overflow: clip; overflow-clip-margin: 0.35em; text-overflow: ellipsis; white-space: nowrap`). Passing `wrapItemText` adds `.optionTextWrap` alongside `.optionText`, which re-enables wrapping (`white-space: normal; overflow-wrap: anywhere`) for both children — same later-cascade-wins mechanism (`.optionTextWrap > *` declared after `.optionText > *`, equal specificity) as the rest of this file's overrides. `renderRichOption`/`renderRichOptionContent` (shared util, both adapters) take `wrapItemText` as a third parameter and combine the two class names when it's true.
+
+`.optionText > *` used plain `overflow: hidden` until 2026-08-28 (Matt Massey) — it clipped
+descenders (e.g. "g") whenever `text_line-height` is tighter than the font's natural
+ascent+descent. `overflow-clip-margin` gives ink a small bleed allowance while still clipping
+genuinely overflowing text; same project-wide fix as Chip's `CHIP_IMPLEMENTATION_NOTES.md`.

package/src/components/AutoComplete/AutoComplete.module.css

@@ -304,7 +304,10 @@
 
 /* Default: label/supportingText each truncate to a single line with an ellipsis. */
 .optionText > * {
-  overflow: hidden;
+  overflow: clip; /* HARDCODE: `hidden` clips descenders (e.g. "g") when text_line-height is
+    tighter than the font's natural ascent+descent; overflow-clip-margin gives ink a small bleed
+    allowance while still clipping genuinely overflowing text (see Chip's IMPLEMENTATION_NOTES.md). */
+  overflow-clip-margin: 0.35em;
   text-overflow: ellipsis;
   white-space: nowrap;
 }

package/src/components/Button/Button.module.css

@@ -72,7 +72,10 @@
 .labelText {
   display: block;
   min-width: 0;
-  overflow: hidden;
+  overflow: clip; /* HARDCODE: `hidden` clips descenders (e.g. "g") when text_line-height is
+    tighter than the font's natural ascent+descent; overflow-clip-margin gives ink a small bleed
+    allowance while still clipping genuinely overflowing text (see Chip's IMPLEMENTATION_NOTES.md). */
+  overflow-clip-margin: 0.35em;
   text-overflow: ellipsis;
   white-space: nowrap;
   font-size: inherit;

package/src/components/Button/IMPLEMENTATION_NOTES.md

@@ -69,3 +69,15 @@ Mantine's `.mantine-Button-label` flex centering breaks primitive truncation log
 **Bug:** with `overStyled` and a custom `className` (surfaced by Tree embedding a `Button` for its expand chevron — see `Tree/IMPLEMENTATION_NOTES.md`), `finalClass` (`` `${styles.root} ${classNameProp}` ``) was set explicitly on `<MantineButton>`, but `{...sanitizedProps}` was spread _after_ it — and `sanitizedProps` still contained the original, unmodified `className` key, since it had only been _read_, never deleted. The later spread would silently overwrite `finalClass` with just the caller's own class. Same bug class as `Dropdown.tsx`/`BareDropdown.tsx` had.
 
 **Why it wasn't visible here:** `classNames={{root: mergedClassNames.root, ...}}` is a _separate_ Mantine prop from the plain `className` string, unaffected by the overwrite, and `mergedClassNames.root` always includes `styles.root` independently — so the root element kept its Recursica styling regardless of the bug. mui-adapter's equivalent `Button.tsx` has no such secondary path (`@mui/material` only has a plain `className`), so the identical mistake there was fully visible (chevron rendered in MUI's own default color). Fixed in both regardless, since this is a real latent bug independent of whether it happens to be masked today.
+
+---
+
+## `.labelText` descender clipping (Matt Massey, 2026-08-28)
+
+`.labelText` used plain `overflow: hidden` to make `text-overflow: ellipsis` work, which also
+clips descenders (e.g. the "g" in a long label) whenever `text_line-height` is tighter than the
+font's natural ascent+descent. Switched to `overflow: clip; overflow-clip-margin: 0.35em;` — same
+truncation, but ink can bleed slightly past the line box before it's actually clipped. `.root`'s
+own `overflow: hidden` (the max-width truncation bounding box) is untouched — it has padding
+around the label so it isn't tight against the glyphs the way `.labelText` is. Project-wide fix;
+see Chip's `CHIP_IMPLEMENTATION_NOTES.md` for the original discovery.

package/src/components/Card/USAGE.md

@@ -22,7 +22,7 @@ export default function Demo() {
   return (
     <Card>
       <Card.Header>
-        <Title order={3}>Card Title</Title>
+        <Heading order={3}>Card Title</Heading>
       </Card.Header>
       <Card.Content>
         <Text>

package/src/components/Dropdown/DROPDOWN_IMPLEMENTATION_NOTES.md

@@ -8,5 +8,5 @@ The `Dropdown` component is mapped explicitly to Mantine's `<Select>` following
 4. **Popup Vertical Padding:** The gap above/below the option list inside `.dropdown` is explicitly set from the same `--recursica_..._dropdown_properties_vertical-padding` token the closed control uses — it was previously left to Mantine's own untokenized `--combobox-padding` (4px) default.
 5. **Clear Button Styling:** Mantine's native clear button (`clearButtonProps`, shown when `clearable` + a value are both present) is a bare `CloseButton` with its own hardcoded gray icon/hover styling by default. `Dropdown.tsx` merges in a `.clearButton` class (Dropdown.module.css) that overrides it with the same icon-size/trailing-icon-color/focus-ring tokens as the rest of the right section, using the double-class-selector specificity trick (same as Chip.module.css's `.root.root`) to beat Mantine's own CSS module rule without `!important`.
 6. **Rich Option Content (`leadingIcon`/`supportingText`):** `data` items now accept optional `leadingIcon`/`supportingText` fields, via the shared `RecursicaComboboxItem` type in `@recursica/adapter-common` (see `MANTINE_ADAPTER_RICH_OPTION_DATA.md` at the repo root) — the same type `AutoComplete` and both `mui-adapter` components use, so it's declared once and not redeclared per component/adapter. `label` on that shared type is optional, falling back to `value` (matches Mantine's own runtime default for both `Select` and `Autocomplete`). `Dropdown.tsx` installs a default `renderOption` (`../../utils/renderRichOption.tsx`, shared with `AutoComplete`) that reads `leadingIcon`/`supportingText` straight off Mantine's own parsed `option` — no separate lookup-by-value map is needed, since Mantine's `getParsedComboboxData` passes extra fields on an item through untouched whenever the item already has both `value` and `label`. Because `label` is now optional, `data` is first run through adapter-common's `normalizeComboboxData` (backfilling `label` from `value`) before being handed to Mantine, so items missing `label` don't have their `leadingIcon`/`supportingText` silently dropped by that same parser (see `AutoComplete.tsx`'s identical, longer-standing use of this — `Dropdown`'s `label` used to be required, which is why it didn't need this before). A caller-supplied `renderOption` always wins over the default. New CSS classes (`.optionContent`/`.optionIcon`/`.optionText`/`.optionSupportingText`) reuse the menu-item component's icon/supporting-text tokens — no dedicated dropdown-option tokens exist for either, same reasoning as the `.option[data-selected]` reuse above. The icon is only rendered when `leadingIcon` is present (a conditional child, not a hidden reserved slot), so label/supportingText shift left when there's no icon; `.optionContent`'s `align-items: center` keeps the label vertically centered when there's no `supportingText` to stack under it.
-7. **`wrapItemText`:** `label`/`supportingText` default to single-line truncation with an ellipsis (`.optionText > *` — `overflow: hidden; text-overflow: ellipsis; white-space: nowrap`). Passing `wrapItemText` adds `.optionTextWrap` alongside `.optionText`, re-enabling wrapping (`white-space: normal; overflow-wrap: anywhere`) for both children — later-cascade-wins, equal specificity, same mechanism as this file's other CSS overrides. `renderRichOption`/`renderRichOptionContent` take `wrapItemText` as a third parameter and combine the two class names when it's true.
+7. **`wrapItemText`:** `label`/`supportingText` default to single-line truncation with an ellipsis (`.optionText > *` — `overflow: clip; overflow-clip-margin: 0.35em; text-overflow: ellipsis; white-space: nowrap`). Passing `wrapItemText` adds `.optionTextWrap` alongside `.optionText`, re-enabling wrapping (`white-space: normal; overflow-wrap: anywhere`) for both children — later-cascade-wins, equal specificity, same mechanism as this file's other CSS overrides. `renderRichOption`/`renderRichOptionContent` take `wrapItemText` as a third parameter and combine the two class names when it's true. `.optionText > *` used plain `overflow: hidden` until 2026-08-28 (Matt Massey) — it clipped descenders (e.g. "g") whenever `text_line-height` is tighter than the font's natural ascent+descent; `overflow-clip-margin` gives ink a small bleed allowance while still clipping genuinely overflowing text, same project-wide fix as Chip's `CHIP_IMPLEMENTATION_NOTES.md`.
 8. **Selected Option Highlight (bug fix):** The `.option[data-selected="true"], .option[data-combobox-active="true"]` background/text-color rule (and the matching `.optionIcon`/`.optionSupportingText` color rules) used to key off `data-combobox-selected` instead of `data-combobox-active`. Despite the name, `data-combobox-active` is what Mantine sets when an option's value matches the current field value (`OptionsDropdown.mjs`: `active: checked`, consumed by `ComboboxOption.mjs`'s `mod` map); `data-combobox-selected` is an unrelated, transient keyboard-navigation highlight that Mantine sets/clears imperatively via `element.setAttribute` outside React (`use-combobox.mjs`'s `selectOption`/`clearSelectedItem`), not tied to the chosen value at all. The bug: the real selected option only showed the brand background while being arrow-key-navigated, and lost it entirely on a normal open/close (matches Playwright verification — `data-combobox-active="true"` is present and gets the token background after a plain click-select-reopen, with no keyboard involved).

package/src/components/Dropdown/Dropdown.module.css

@@ -408,7 +408,10 @@
 
 /* Default: label/supportingText each truncate to a single line with an ellipsis. */
 .optionText > * {
-  overflow: hidden;
+  overflow: clip; /* HARDCODE: `hidden` clips descenders (e.g. "g") when text_line-height is
+    tighter than the font's natural ascent+descent; overflow-clip-margin gives ink a small bleed
+    allowance while still clipping genuinely overflowing text (see Chip's IMPLEMENTATION_NOTES.md). */
+  overflow-clip-margin: 0.35em;
   text-overflow: ellipsis;
   white-space: nowrap;
 }

package/src/components/Heading/HEADING_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,18 @@
+# Heading – Implementation Notes
+
+## Renamed from `Title` (Matt Massey, 2026-08-28)
+
+**Decision:** Renamed the component from `Title` to `Heading` — designers refer to semantic tags
+(`h1`-`h6`, `span`, `p`), and "Title" wasn't part of that vocabulary. `Heading` + `Text` are now
+Recursica's common typography component names across all adapters. No behavior change.
+
+## `.root` `text-wrap: balance` (Matt Massey, 2026-08-28)
+
+**Decision:** Added `text-wrap: balance` via a new `Heading.module.css` `.root` class, merged onto
+the typography class for every `order` (h1–h6), alongside the caller's own `className`.
+
+**Implementation:** UX asked for more evenly balanced multi-line wrapping instead of a ragged last
+line — headings are the primary intended use case for this property. Not a design token — it's a
+layout algorithm choice, so it's hardcoded rather than pulled from `recursica_variables_scoped.css`.
+Chromium/Firefox only balance up to ~6 lines, which comfortably covers heading text. No fallback
+needed — browsers that don't support the value just ignore the declaration.

package/src/components/Heading/Heading.module.css

@@ -0,0 +1,13 @@
+/*
+ * HARDCODED VALUES
+ * - `.root` `text-wrap: balance` — not a design token; a layout algorithm choice requested by
+ *   UX (Matt Massey, 2026-08-28) to even out wrapped line lengths. See HEADING_IMPLEMENTATION_NOTES.md.
+ */
+
+.root {
+  /* HARDCODE: balances wrapped line lengths instead of leaving a ragged short last line. Most
+     effective on short text; browsers cap balancing at ~6 lines, so long paragraphs silently
+     fall back to normal wrapping past that point — no fallback needed, unsupported browsers
+     just ignore the declaration. */
+  text-wrap: balance;
+}

package/src/components/{Title/Title.stories.tsx → Heading/Heading.stories.tsx}

@@ -1,15 +1,15 @@
 import type { Meta, StoryObj } from "@storybook/react";
-import { Title } from "./Title";
+import { Heading } from "./Heading";
 
-const meta: Meta<typeof Title> = {
-  title: "UI-Kit/Title",
-  component: Title,
+const meta: Meta<typeof Heading> = {
+  title: "UI-Kit/Heading",
+  component: Heading,
   tags: ["autodocs"],
   parameters: {
     docs: {
       description: {
         component:
-          "The semantic `<Title>` abstraction intrinsically links pure `h1-h6` tag generation with exact Recursica design boundaries to preserve SEO and screen reader trees uniformly globally.",
+          "The semantic `<Heading>` abstraction intrinsically links pure `h1-h6` tag generation with exact Recursica design boundaries to preserve SEO and screen reader trees uniformly globally.",
       },
     },
   },
@@ -25,26 +25,26 @@ const meta: Meta<typeof Title> = {
 
 export default meta;
 
-type Story = StoryObj<typeof Title>;
+type Story = StoryObj<typeof Heading>;
 
 export const Default: Story = {
   args: {
     order: 1,
     children: "Semantic H1 Document Boundary",
   },
-  render: ({ ...args }) => <Title {...args} />,
+  render: ({ ...args }) => <Heading {...args} />,
 };
 
 export const StaticVariations: Story = {
   args: {},
   render: () => (
     <div style={{ display: "flex", flexDirection: "column", gap: "24px" }}>
-      <Title order={1}>H1 Title</Title>
-      <Title order={2}>H2 Title</Title>
-      <Title order={3}>H3 Title</Title>
-      <Title order={4}>H4 Title</Title>
-      <Title order={5}>H5 Title</Title>
-      <Title order={6}>H6 Title</Title>
+      <Heading order={1}>H1 Heading</Heading>
+      <Heading order={2}>H2 Heading</Heading>
+      <Heading order={3}>H3 Heading</Heading>
+      <Heading order={4}>H4 Heading</Heading>
+      <Heading order={5}>H5 Heading</Heading>
+      <Heading order={6}>H6 Heading</Heading>
     </div>
   ),
 };

package/src/components/Heading/Heading.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Heading component tests. Add tests here if/when needed.

package/src/components/Heading/Heading.tsx

@@ -0,0 +1,52 @@
+import { forwardRef } from "react";
+import {
+  Title as MantineTitle,
+  type TitleProps as MantineTitleProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  omitUnsupportedProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+
+import { type RecursicaHeadingProps } from "@recursica/adapter-common";
+import styles from "./Heading.module.css";
+
+export type HeadingProps = RecursicaOverStyled<
+  Omit<MantineTitleProps, "size"> & RecursicaHeadingProps
+>;
+
+/**
+ * Enforces highly accessible structural markup utilizing semantic `<h1>` through `<h6>` tags securely bound directly to Recursica typographic scales.
+ */
+export const Heading = forwardRef<HTMLHeadingElement, HeadingProps>(
+  function Heading({ overStyled = false, order = 1, ...rest }, ref) {
+    // Props this component intentionally doesn't support — deleted at runtime so they can't leak
+    // through even if a caller forces them via plain JavaScript, bypassing the `Omit<>` above.
+    const UNSUPPORTED_PROPS = [
+      "size", // Recursica controls Heading sizing via the `order` prop + typography tokens, not Mantine's native `size`.
+    ] as const satisfies readonly (keyof MantineTitleProps)[];
+
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled),
+      UNSUPPORTED_PROPS,
+    );
+    const classNameProp = (sanitizedProps as Record<string, unknown>)
+      .className as string | undefined;
+
+    const typographyClass = `recursica_brand_typography_h${order}`;
+    const mergedClassName = [typographyClass, styles.root, classNameProp]
+      .filter(Boolean)
+      .join(" ");
+
+    return (
+      <MantineTitle
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineTitleProps)}
+        order={order}
+        className={mergedClassName}
+      />
+    );
+  },
+);
+Heading.displayName = "Heading";

package/src/components/{Title → Heading}/USAGE.md

@@ -1,13 +1,13 @@
-# Title - Usage Guide
+# Heading - Usage Guide
 
-This document describes how to integrate and use the `Title` component in your projects using `@recursica/mantine-adapter`.
+This document describes how to integrate and use the `Heading` component in your projects using `@recursica/mantine-adapter`.
 
 ---
 
 ## 1. Import Reference
 
 ```tsx
-import { Title } from "@recursica/mantine-adapter";
+import { Heading } from "@recursica/mantine-adapter";
 ```
 
 ---
@@ -16,10 +16,10 @@ import { Title } from "@recursica/mantine-adapter";
 
 ```tsx
 import React from "react";
-import { Title } from "@recursica/mantine-adapter";
+import { Heading } from "@recursica/mantine-adapter";
 
 export default function Demo() {
-  return <Title order={1}>This is a Heading 1</Title>;
+  return <Heading order={1}>This is a Heading 1</Heading>;
 }
 ```
 

package/src/components/Modal/MODAL_IMPLEMENTATION_NOTES.md

@@ -16,7 +16,12 @@ Mantine internally handles scroll state natively, dynamically showing/hiding a d
 
 ### 3. Title truncation
 
-`.title` truncates with an ellipsis (`overflow: hidden`, `white-space: nowrap`, `text-overflow: ellipsis`) rather than wrapping. It also needs `flex: 1 1 auto; min-width: 0;` since it's a flex child of `.header` alongside the close button — without `min-width: 0`, a flex item won't shrink below its content's intrinsic width, so ellipsis never engages. `.header`'s `display: flex` is likewise explicit rather than relied upon from Mantine's own header class, so the mui-adapter's plain-`<div>` header gets identical layout.
+`.title` truncates with an ellipsis (`overflow: clip; overflow-clip-margin: 0.35em`, `white-space: nowrap`, `text-overflow: ellipsis`) rather than wrapping. It also needs `flex: 1 1 auto; min-width: 0;` since it's a flex child of `.header` alongside the close button — without `min-width: 0`, a flex item won't shrink below its content's intrinsic width, so ellipsis never engages. `.header`'s `display: flex` is likewise explicit rather than relied upon from Mantine's own header class, so the mui-adapter's plain-`<div>` header gets identical layout.
+
+`.title` used plain `overflow: hidden` until 2026-08-28 (Matt Massey) — it clipped descenders
+(e.g. "g" in a long title) whenever `text_line-height` is tighter than the font's natural
+ascent+descent. `overflow-clip-margin` gives ink a small bleed allowance while still clipping
+genuinely overflowing text, same project-wide fix as Chip's `CHIP_IMPLEMENTATION_NOTES.md`.
 
 ### 4. Width was pinned to Mantine's `md` size, not content-driven
 

package/src/components/Modal/Modal.module.css

@@ -78,7 +78,10 @@
 .title {
   flex: 1 1 auto; /* HARDCODE: let the title claim the space between the header edge and the close button */
   min-width: 0; /* HARDCODE: required for text-overflow ellipsis to take effect on a flex child */
-  overflow: hidden;
+  overflow: clip; /* HARDCODE: `hidden` clips descenders (e.g. "g") when text_line-height is
+    tighter than the font's natural ascent+descent; overflow-clip-margin gives ink a small bleed
+    allowance while still clipping genuinely overflowing text (see Chip's IMPLEMENTATION_NOTES.md). */
+  overflow-clip-margin: 0.35em;
   white-space: nowrap;
   text-overflow: ellipsis;
 

package/src/components/Panel/PANEL_IMPLEMENTATION_NOTES.md

@@ -104,3 +104,13 @@ Mantine's Drawer content does not set `border-style` natively. Without this, the
 - **Scrollable** — Internal scrollbar enabled when content exceeds the panel height. Header and footer CTAs remain pinned.
 
 Mantine's Drawer handles this automatically — the `body` section scrolls when content overflows, while the `header` remains fixed. The `Panel.Footer` uses `margin-top: auto` to stay at the bottom.
+
+---
+
+## `.titleTruncate` descender clipping (Matt Massey, 2026-08-28)
+
+`.titleTruncate` used plain `overflow: hidden` to make `text-overflow: ellipsis` work, which also
+clips descenders (e.g. the "g" in a long title) whenever `text_line-height` is tighter than the
+font's natural ascent+descent. Switched to `overflow: clip; overflow-clip-margin: 0.35em;` — same
+truncation, but ink can bleed slightly past the line box before it's actually clipped.
+Project-wide fix; see Chip's `CHIP_IMPLEMENTATION_NOTES.md` for the original discovery.

package/src/components/Panel/Panel.module.css

@@ -96,7 +96,10 @@
 .titleTruncate {
   composes: title;
   white-space: nowrap;
-  overflow: hidden;
+  overflow: clip; /* HARDCODE: `hidden` clips descenders (e.g. "g") when text_line-height is
+    tighter than the font's natural ascent+descent; overflow-clip-margin gives ink a small bleed
+    allowance while still clipping genuinely overflowing text (see Chip's IMPLEMENTATION_NOTES.md). */
+  overflow-clip-margin: 0.35em;
   text-overflow: ellipsis;
   display: block;
   flex: 1;

package/src/components/Text/TEXT_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,12 @@
+# Text – Implementation Notes
+
+## `.root` `text-wrap: balance` (Matt Massey, 2026-08-28)
+
+**Decision:** Added `text-wrap: balance` via a new `Text.module.css` `.root` class, merged onto the
+typography class alongside the caller's own `className`.
+
+**Implementation:** UX asked for more evenly balanced multi-line wrapping instead of a ragged last
+line. Not a design token — it's a layout algorithm choice, so it's hardcoded rather than pulled
+from `recursica_variables_scoped.css`. Chromium/Firefox only balance up to ~6 lines; longer
+paragraphs silently fall back to normal wrapping past that point. No fallback needed — browsers
+that don't support the value just ignore the declaration.

package/src/components/Text/Text.module.css

@@ -0,0 +1,13 @@
+/*
+ * HARDCODED VALUES
+ * - `.root` `text-wrap: balance` — not a design token; a layout algorithm choice requested by
+ *   UX (Matt Massey, 2026-08-28) to even out wrapped line lengths. See TEXT_IMPLEMENTATION_NOTES.md.
+ */
+
+.root {
+  /* HARDCODE: balances wrapped line lengths instead of leaving a ragged short last line. Most
+     effective on short text; browsers cap balancing at ~6 lines, so long paragraphs silently
+     fall back to normal wrapping past that point — no fallback needed, unsupported browsers
+     just ignore the declaration. */
+  text-wrap: balance;
+}

package/src/components/Text/Text.stories.tsx

@@ -9,7 +9,7 @@ const meta: Meta<typeof Text> = {
     docs: {
       description: {
         component:
-          "The standard `<Text>` component controls common body sizing scales and implicit paragraphs governed by the active theme layer. For semantic headings (`h1` through `h6`), use `<Title>` instead.",
+          "The standard `<Text>` component controls common body sizing scales and implicit paragraphs governed by the active theme layer. For semantic headings (`h1` through `h6`), use `<Heading>` instead.",
       },
     },
   },

package/src/components/Text/Text.tsx

@@ -10,6 +10,7 @@ import {
 } from "../../utils/filterStylingProps";
 
 import { type RecursicaTextProps } from "@recursica/adapter-common";
+import styles from "./Text.module.css";
 
 export type TextProps = RecursicaOverStyled<
   Omit<MantineTextProps, "variant"> & RecursicaTextProps
@@ -24,9 +25,9 @@ const _Text = forwardRef<HTMLDivElement, TextProps>(function Text(
     .className as string | undefined;
 
   const typographyClass = `recursica_brand_typography_${variant}`;
-  const mergedClassName = classNameProp
-    ? `${typographyClass} ${classNameProp}`
-    : typographyClass;
+  const mergedClassName = [typographyClass, styles.root, classNameProp]
+    .filter(Boolean)
+    .join(" ");
 
   return (
     <MantineText
@@ -40,7 +41,7 @@ _Text.displayName = "Text";
 
 /**
  * A generalized typographical wrapper limiting text properties to bounded Recursica UI-kit tokens inherently.
- * Do not use for semantic headings; use the explicit `<Title>` component for `<h1>` - `<h6>`.
+ * Do not use for semantic headings; use the explicit `<Heading>` component for `<h1>` - `<h6>`.
  *
  * Supports polymorphism via the `component` prop or `renderRoot` for custom element rendering.
  * @example

package/src/components/index.ts

@@ -18,6 +18,7 @@ export * from "./Flex/Flex";
 export * from "./FormControlLayout/FormControlLayout";
 export * from "./Grid/Grid";
 export * from "./Group/Group";
+export * from "./Heading/Heading";
 export * from "./HoverCard/HoverCard";
 export * from "./Link/Link";
 export * from "./Loader/Loader";
@@ -45,7 +46,6 @@ export * from "./TextField/TextField";
 export * from "./TimePicker/TimePicker";
 export * from "./Timeline/Timeline";
 export * from "./Timeline/TimelineItem";
-export * from "./Title/Title";
 export * from "./Toast";
 export * from "./Tooltip/Tooltip";
 export * from "./TransferList/TransferList";

package/src/index.ts

@@ -72,6 +72,9 @@ export const FileUpload = wrapComponent(
 export const FormControlLayout = wrapComponent(
   rawComponents.FormControlLayout,
 ) as typeof rawComponents.FormControlLayout;
+export const Heading = wrapComponent(
+  rawComponents.Heading,
+) as typeof rawComponents.Heading;
 export const HoverCard = wrapComponent(
   rawComponents.HoverCard,
 ) as typeof rawComponents.HoverCard;
@@ -147,9 +150,6 @@ export const Timeline = wrapComponent(
 export const TimelineItem = wrapComponent(
   rawComponents.TimelineItem,
 ) as typeof rawComponents.TimelineItem;
-export const Title = wrapComponent(
-  rawComponents.Title,
-) as typeof rawComponents.Title;
 export const Toast = wrapComponent(
   rawComponents.Toast,
 ) as typeof rawComponents.Toast;

package/src/components/Title/Title.test.tsx

@@ -1 +0,0 @@
-// Placeholder for future Title component tests. Add tests here if/when needed.